如何高效安装部署向量数据库Milvus？

1 概述：Milvus 向量数据库之安装部署篇 前置知识: Milvus 向量数据库 [向量数据库/AI] Milvus: 开源向量数据库 - 博客园/千千寰宇 硬件要求 Milvus Standalone 部署模式的最低硬件要求为 4 核 CPU 和 8 GB 内存 端口占用情况 端口占用情况 Milvus (Standalone / Distributed ) 支持 19530 和 9091 两个端口 端口 19530 : 用于 gRPC 和 RESTful API。 这是您使用不同 Milvus SDK 或 HTTP 客户端连接到 Milvus 服务器时的默认端口。 端口 9091 : 作为管理端口，用于 Kubernetes 内的指标收集、pprof 分析和运行状况探测。 部署模式 部署模式 维护状态 适用场景 数据规模 Milvus Lite ✅ 活跃维护 快速原型开发、Jupyter Notebook、边缘设备 数百万向量以内 Milvus Standalone ✅ 活跃维护 中小规模生产环境、早期产品阶段 最高可达1亿向量 Milvus Distributed ✅ 活跃维护 大规模生产、企业级部署 数亿至数百亿向量 Milvus Lite：作为 Python 库集成在 pymilvus 中，持续更新。最新版本可通过 pip install pymilvus 直接安装使用，无需额外启动服务端，数据持久化通过本地文件实现。 仅适用于小规模原型设计（通常少于 100 万个矢量）或边缘设备。 适合场景: Jupyter Notebook / 谷歌 Colab; 笔记本 电脑; 边缘设备 Milvus Standalone：所有组件打包在单个 Docker 镜像中，支持主备模式实现高可用，适合生产环境部署。官方文档明确说明该模式仍在持续维护，并支持扩展到1亿向量的规模。 Milvus Distributed：采用云原生架构，支持 Kubernetes 部署。最新版本（如 v2.5.x）仍在积极开发和维护中，社区讨论显示用户正在使用 v2.5.2-gpu 等较新版本进行部署测试 Milvus Lite Milvus Lite 是 Milvus 的轻量级版本 Milvus 是一个高性能矢量数据库，通过矢量相似性搜索为 AI 应用程序提供支持。 该存储库包含 Milvus Lite 的核心组件。 使用 Milvus Lite，您可以在几分钟内开始构建具有向量相似性搜索的 AI 应用程序！Milvus Lite 适合在以下环境中运行： Jupyter Notebook / 谷歌 Colab 笔记本 电脑 边缘设备 Milvus Lite 可以导入到您的 Python 应用程序中，提供 Milvus 的核心矢量搜索功能。 Milvus Lite 已经包含在 Milvus 的 Python SDK 中。 要使用它，您只需要: pip install pymilvus Milvus Lite 使用与 Milvus Standalone 和 Distributed 相同的 API，提供跨环境的一致体验。 只需开发一次 GenAI 应用程序，即可在任何地方运行它们： 在笔记本电脑或 Jupyter Notebook 上使用 Milvus Lite， 在 Docker 容器中使用 Milvus Standalone， 或者在 K8s 集群上使用 Milvus Distributed 进行大规模生产。 Milvus Lite 仅适用于小规模原型设计（通常少于 100 万个矢量）或边缘设备。 对于大规模生产，我们建议使用 Milvus Standalone 或 Milvus Distributed。 您还可以考虑 Zilliz Cloud 上的完全托管的 Milvus。 Milvus-Lite https://pypi.org/project/milvus-lite/ Milvus Lite 目前支持以下环境： Ubuntu >= 20.04（x86_64 和 arm64） MacOS >= 11.0（Apple Silicon M1/M2 和 x86_64） 注意：尚不支持 Windows。 Milvus Standalone Milvus Distributed Milvus Lite + Pip 安装方式 (Milvue-Lite:2.2.16) 【不推荐/未亲测成功】 Step0 安装 conda 虚拟环境管理器，并创建、启用虚拟环境 安装 conda 虚拟环境管理器 参考文献 [Python/虚拟环境/包管理] conda：多环境管理与包管理器 - 博客园/千千寰宇 [Python] Miniforge: 开源版conda环境管理器 - 博客园/千千寰宇 创建、启用虚拟环境 例如: ai-env //添加第三方源，避免 python=3.12 及部分依赖包不支持、下载官方源的速度太慢等问题 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/bioconda/ conda create --name ai-env python=3.12 conda activate ai-env C:\Users\xxx\.conda\envs\ai-env\python.exe 环境验证 (ai-env) C:\Users\Xxx> python --version Python 3.12.11 (ai-env) C:\Users\Xxx> pip --version pip 25.2 from C:\Users\EDY\.conda\envs\ai-env\Lib\site-packages\pip (python 3.12) Step1 基于 pip 安装 milvus-lite 本地任意位置新建一个空文件夹作为服务器的存储位置 例如: D:\data\milvus-server\ 基于 pip 安装 milvus 服务端 其一，会默认安装较低版本的 2.2.16；其二, pip的milvus项目已被弃用(https://pypi.org/project/milvus/)，其建议使用milvus-lite项目(https://pypi.org/project/milvus-lite/) 不建议使用此命令 (ai-env) C:\Users\Xxx> pip install milvus Looking in indexes: https://mirrors.aliyun.com/pypi/simple Collecting milvus Downloading https://mirrors.aliyun.com/pypi/packages/ab/8f/2a24d629f194c1bc83725652a9341794fbab09d0de978d5e5ec72e1f80e4/milvus-2.2.16-py3-none-win_amd64.whl (38.6 MB) ---------------------------------------- 38.6/38.6 MB 13.0 MB/s 0:00:03 Installing collected packages: milvus Successfully installed milvus-2.2.16 【补充】卸载命令 pip uninstall milvus 卸载完成后，上一步创建的 milvus-server(即 milvus-lite) 的数据目录不会自动删除，需要自己手动移除。 Step2 启动 milvus-server (ai-env) C:\Users\Xxx> milvus-server --data D:\code\serve\milvus Milvus 数据库服务已正常启用（如图） Step3 Milvus客户端(应用程序): 连接、验证 安装依赖包: pymilvus 安装Python应用程序的Milvus客户端依赖包 (ai-env) C:\Users\Xxx> pip install pymilvus 查看详情 (ai-env) C:\Users\Xxx> pip install pymilvus Looking in indexes: https://mirrors.aliyun.com/pypi/simple Collecting pymilvus Downloading https://mirrors.aliyun.com/pypi/packages/d9/78/ab628de53ae36c2a4519e8d56e09604b2ff6e8084538cb058cdbff42a564/pymilvus-2.6.2-py3-none-any.whl (258 kB) Requirement already satisfied: setuptools>69 in c:\users\edy\.conda\envs\ai-env\lib\site-packages (from pymilvus) (80.9.0) Collecting grpcio!=1.68.0,!=1.68.1,!=1.69.0,!=1.70.0,!=1.70.1,!=1.71.0,!=1.72.1,!=1.73.0,>=1.66.2 (from pymilvus) Downloading https://mirrors.aliyun.com/pypi/packages/ff/14/e1309a570b7ebdd1c8ca24c4df6b8d6690009fa8e0d997cb2c026ce850c9/grpcio-1.75.0-cp312-cp312-win_amd64.whl (4.6 MB) ---------------------------------------- 4.6/4.6 MB 11.2 MB/s 0:00:00 Collecting protobuf>=5.27.2 (from pymilvus) Downloading https://mirrors.aliyun.com/pypi/packages/8c/f3/6f58f841f6ebafe076cebeae33fc336e900619d34b1c93e4b5c97a81fdfa/protobuf-6.32.1-cp310-abi3-win_amd64.whl (435 kB) Requirement already satisfied: python-dotenv<2.0.0,>=1.0.1 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pymilvus) (1.0.1) Collecting ujson>=2.0.0 (from pymilvus) Downloading https://mirrors.aliyun.com/pypi/packages/44/1b/27c05dc8c9728f44875d74b5bfa948ce91f6c33349232619279f35c6e817/ujson-5.11.0-cp312-cp312-win_amd64.whl (43 kB) Requirement already satisfied: pandas>=1.2.4 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pymilvus) (2.2.3) Requirement already satisfied: typing-extensions~=4.12 in c:\users\edy\appdata\roaming\python\python312\site-packages (from grpcio!=1.68.0,!=1.68.1,!=1.69.0,!=1.70.0,!=1.70.1,!=1.71.0,!=1.72.1,!=1.73.0,>=1.66.2->pymilvus) (4.12.2) Requirement already satisfied: numpy>=1.26.0 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2.2.4) Requirement already satisfied: python-dateutil>=2.8.2 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2.9.0.post0) Requirement already satisfied: pytz>=2020.1 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2024.2) Requirement already satisfied: tzdata>=2022.7 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2024.2) Requirement already satisfied: six>=1.5 in c:\users\edy\appdata\roaming\python\python312\site-packages (from python-dateutil>=2.8.2->pandas>=1.2.4->pymilvus) (1.17.0) Installing collected packages: ujson, protobuf, grpcio, pymilvus Successfully installed grpcio-1.75.0 protobuf-6.32.1 pymilvus-2.6.2 ujson-5.11.0 连接与验证 另开一窗口，进入 python 环境 (ai-env) C:\Users\Xxx> python 代码验证 import logging from pymilvus import connections, Collection, CollectionSchema, FieldSchema, DataType # 配置日志记录 logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') # 连接到 Milvus 服务 try: connections.connect(alias="default", uri="http://localhost:19530") logging.info("成功连接到Milvus服务") except Exception as e: logging.error(f"连接Milvus服务失败: {e}") raise 出现"成功连接到Milvus服务"，即说明连接/验证成功 Milvue Lite + Pip 安装方式 (Milvue-Lite:2.5.1) 【不推荐/亲测未成功】 操作系统: CENTOS 7.9 (亲测: 尚不支持 Windows) Step0 安装 conda 虚拟环境管理器，并创建、启用虚拟环境 参考 : Pip 安装方式 (Milvue-Lite:2.2.16) Step1 基于 pip 安装 milvus-lite (ai-env) [root@xxx ~]# pip install milvus-lite>=2.5.1 (ai-env) [root@xxx ~]# pip list | grep "milvus" milvus-lite 2.5.1 Step2 启动 milvus-server(milvus-lite) 【无需此步骤】 Step2 Milvus客户端(应用程序): 连接、验证 Milvus Standalone + Docker 容器方式 【推荐/亲测成功】 以 ubuntu 24 (阿里云ECS, 4c 8gb)为例 step1 安装 Docker 和 Docker Compose # 更新系统 sudo apt update && sudo apt upgrade -y # 安装必要依赖 sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release # 添加阿里云 Docker 镜像源 curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 启动 Docker sudo systemctl start docker sudo systemctl enable docker # 配置阿里云镜像加速（重要） ## 解释: https://<你的阿里云镜像加速器地址>.mirror.aliyuncs.com 的获取方法: ### 方法1: 登录阿里云容器镜像服务控制台获取专属镜像加速器地址 #### 访问 https://cr.console.aliyun.com/cn-hangzhou/instances/mirrors ### 方法2: 通过阿里云CLI命令获取相关信息 #### aliyun cr GetInstance endpoint=<your-region-id> sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json <<-'EOF' { "registry-mirrors": [ "https://<你的阿里云镜像加速器地址>.mirror.aliyuncs.com", "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com", "https://swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io" ] } EOF # 注：这样 docker pull milvusdb/milvus:v2.5.21 会自动走华为云镜像等指定的第三方镜像仓库，而无需修改 Compose 文件或手动打标签。 sudo systemctl daemon-reload sudo systemctl restart docker 💡 获取阿里云镜像加速器：登录阿里云控制台 → 容器镜像服务 → 镜像加速器 补充: 基于国内服务器安装完成 docker 后，如何验证能够正常下载国外镜像？ # step1 直接拉取镜像 ## 注: 成功标志：看到 `Status: Downloaded newer image for xxx` 或 `Status: Image is up to date for xxx` # 拉取一个轻量级国外官方镜像进行测试 docker pull hello-world # 或拉取 Alpine Linux（体积小，速度快） docker pull alpine:latest # 或拉取 Nginx 官方镜像 docker pull nginx:latest # step2 验证镜像是否成功下载 docker images | grep alpine # step3 运行测试容器验证完整性 docker run --rm alpine:latest echo "镜像运行正常" step2 下载 Milvus 配置文件（使用国内代理） milvus https://milvus.io/ GitHub - milvus-io/milvus: Milvus is a high-performance, cloud-native vector database built for scalable vector ANN search · GitHub GitHub - zilliztech/attu: The Best GUI for Milvus · GitHub # 创建工作目录 mkdir -p ~/milvus && cd ~/milvus # 下载 docker-compose.yml（使用 GitHub 代理或手动下载） # 方案A：使用 ghproxy 代理 wget https://ghproxy.com/https://github.com/milvus-io/milvus/releases/download/v2.5.21/milvus-standalone-docker-compose.yml -O docker-compose.yml # 如果上面失败，使用方案B：手动创建 cat > docker-compose.yml << 'EOF' version: '3.5' services: etcd: container_name: milvus-etcd image: quay.io/coreos/etcd:v3.5.18 environment: - ETCD_AUTO_COMPACTION_MODE=revision - ETCD_AUTO_COMPACTION_RETENTION=1000 - ETCD_QUOTA_BACKEND_BYTES=4294967296 - ETCD_SNAPSHOT_COUNT=50000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd healthcheck: test: ["CMD", "etcdctl", "endpoint", "health"] interval: 30s timeout: 20s retries: 3 minio: container_name: milvus-minio image: minio/minio:RELEASE.2024-05-28T17-19-04Z environment: MINIO_ACCESS_KEY: minioadmin MINIO_SECRET_KEY: minioadmin ports: - "9001:9001" - "9000:9000" volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data command: minio server /minio_data --console-address ":9001" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"] interval: 30s timeout: 20s retries: 3 standalone: container_name: milvus-standalone image: milvusdb/milvus:v2.5.21 command: ["milvus", "run", "standalone"] security_opt: - seccomp:unconfined environment: MINIO_REGION: us-east-1 ETCD_ENDPOINTS: etcd:2379 MINIO_ADDRESS: minio:9000 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus healthcheck: test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"] interval: 30s start_period: 90s timeout: 20s retries: 3 ports: #- "127.0.0.1:19530:19530" # 仅本地回环接口 #- "127.0.0.1:9091:9091" # 仅本地回环接口 #- "0.0.0.0:19530:19530" # 接收所有来源IP（同下） #- "0.0.0.0:9091:9091" # 接收所有来源IP（同下） - "19530:19530" - "9091:9091" depends_on: - "etcd" - "minio" networks: default: name: milvus EOF step3 启用 账号密码认证（可选） 编辑 docker-compose.yml 在 standalone.volumes 下编辑，新增 volumes: - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus # 新增如下4行配置项: # 挂载自定义配置文件（关键步骤） # - ${DOCKER_VOLUME_DIRECTORY:-.}/milvus.yaml:/milvus/configs/milvus.yaml # 官方配置模板: https://raw.githubusercontent.com/milvus-io/milvus/master/configs/milvus.yaml # 或使用额外的用户配置 - ${DOCKER_VOLUME_DIRECTORY:-.}/user.yaml:/milvus/configs/user.yaml 新增并编辑user.yaml cat > ~/milvus/user.yaml << 'EOF' common: security: authorizationEnabled: true EOF 重启 milvus # 重启 Milvus 服务 docker compose restart standalone # 或完全重新创建容器 docker compose down docker compose up -d 连接方式变更 启用认证后，默认账户信息为： 用户名: root / 密码: Milvus python sdk 示例 from pymilvus import MilvusClient # 方式1：使用 token（推荐） client = MilvusClient( uri="http://localhost:19530", token="root:Milvus" # 格式：用户名:密码 ) # 方式2：使用 user/password 参数 client = MilvusClient( uri="http://localhost:19530", user="root", password="Milvus" ) 密码错误时将报错: "auth check failure, please check username and password are correct" 修改默认密码 from pymilvus import connections, utility # 使用默认账户连接 connections.connect( alias='default', host='localhost', port='19530', user='root', password='Milvus' ) # 修改 root 密码 utility.reset_password('root', 'Milvus', 'YourNewStrongPassword', using='default') 创建新用户（可选） 以 root 身份登录后，可以创建更多用户： # 创建新用户 client.create_user( user_name="user_1", password="P@ssw0rd", ) # 验证用户 client.describe_user("user_1") step4 启动 Milvus 基于 docker-compose.yaml 拉取指定镜像 # 拉取镜像（国内环境可能需要多次尝试） sudo docker compose pull # 注：可仅拉取指定服务，跳过 milvus 等镜像 （了解即可） # docker compose pull etcd minio # 注：可仅拉取指定服务，跳过 milvus 等镜像 （了解即可） # docker compose up -d --no-deps --pull never milvus docker images 若 minio 镜像拉取失败，可尝试: docker pull quay.io/minio/minio:RELEASE.2024-05-28T17-19-04Z # 新增镜像标签 docker tag quay.io/minio/minio:RELEASE.2024-05-28T17-19-04Z minio/minio:RELEASE.2024-05-28T17-19-04Z 注： MinIO 官方主要将镜像发布在 Quay.io 仓库，而非 Docker Hub 根本原因：RELEASE.2024-05-28T17-19-04Z 这个特定标签在 Docker Hub 上可能已被删除或从未推送，MinIO 官方主要维护 quay.io 仓库。 若 milvus 镜像拉取失败，可尝试: docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/milvusdb/milvus:v2.5.21 # 新增镜像标签 docker tag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/milvusdb/milvus:v2.5.21 docker.io/milvusdb/milvus:v2.5.21 从华为云等处拉取（但可能最新版镜像是缺乏的） 启动服务 # 启动服务 ## 启动方式1: 默认行为/本地存在目标镜像，则不再从远程仓库拉取 sudo docker compose up -d ## 启动方式2: 明确指定不从远程仓库拉取镜像 ### always：总是拉取（默认行为） missing / if_not_present：本地不存在时才拉取 ⭐推荐 / never：永远不拉取，必须本地已存在 / build：优先使用本地构建的镜像 # sudo docker compose up -d --pull missing 查看运行状态/日志等 # 查看状态 sudo docker compose ps docker compose ls > out: NAME STATUS CONFIG FILES milvus running(3) /root/milvus/docker-compose.yml # 查看日志 sudo docker logs milvus-standalone -f step5 验证/使用 端口验证 curl http://127.0.0.1:19530 -v 数据库服务验证 by python # 安装 Python 客户端测试 pip3 install pymilvus # 测试连接 python3 << 'EOF' from pymilvus import MilvusClient, connections, utility # 连接 Milvus client = MilvusClient("http://localhost:19530") # 检查版本 print(f"Milvus 版本: {client.get_server_version()}") # 创建测试集合 client.create_collection( collection_name="test_collection", dimension=128, metric_type="COSINE" ) print("集合创建成功！") # 查看集合 print(f"集合列表: {client.list_collections()}") EOF Milvus Distributed + Kubernetes 安装方式（未亲测/适用于生产环境） # 安装 kubectl 和 helm curl -LO "https://dl.k8s/release/$(curl -L -s https://dl.k8s/release/stable.txt)/bin/linux/amd64/kubectl" sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash # 添加 Milvus Helm 仓库 helm repo add milvus https://zilliztech.github.io/milvus-helm/ helm repo update # 安装 Milvus（指定国内镜像） helm install my-milvus milvus/milvus --set cluster.enabled=false --set etcd.replicaCount=1 --set minio.mode=standalone --set image.repository=registry.cn-hangzhou.aliyuncs.com/milvusdb/milvus 2 WEB 管理工具: Attu / Milvus WEB-UI(9091) [AI/向量数据库/GUI] Attu : Milvus 的图形化与一体化管理工具 - 博客园/千千寰宇 https://github.com/zilliztech/attu/releases/download/v2.4.5/attu-docker-compose.yml -O attu-docker-compose.yml Z FAQ for Milvus 安装部署 常见问题解决 问题 解决方案 镜像拉取失败 确认 Docker 镜像加速器配置正确，或手动 docker pull 替代镜像 端口被占用 sudo lsof -i :19530 查看占用，或修改 docker-compose.yml 端口映射 内存不足 Milvus 建议至少 8GB 内存，修改 docker-compose.yml 限制资源使用 防火墙问题 sudo ufw allow 19530/tcp 开放端口 Y 推荐文献 Milvus https://milvus.io 快速入门 Milvus Lite - Milvus https://github.com/milvus-io/milvus https://github.com/milvus-io/milvus/releases 阿里云 容器镜像服务 - Aliyun https://your-mirror-url.mirror.aliyuncs.com 华为云 https://mirrors.huaweicloud.com/home X 参考文献