Docker 安装配置 Milvus 向量数据库与基本使用

对齐token
51 阅读6分钟

一、环境说明

本文基于以下环境编写：

项目内容
云平台腾讯云
操作系统Ubuntu Server 24.04 LTS
Docker已安装（Docker Engine 19.03+ / Docker Compose 1.25.1+）
部署模式Milvus Standalone（Docker Compose）
客户端本机通过公网 IP 访问

二、安装部署

2.1 下载 Docker Compose 配置文件

Milvus 官方提供了 Standalone 模式的 Docker Compose 配置文件，包含 Milvus 核心服务、etcd（元数据存储）和 MinIO（对象存储）三个组件。

在腾讯云服务器上执行：

# 创建 Milvus 工作目录
mkdir -p /opt/milvus && cd /opt/milvus

# 下载 Milvus Standalone Docker Compose 配置文件（以 v2.5 稳定版为例）
wget https://github.com/milvus-io/milvus/releases/download/v2.5.14/milvus-standalone-docker-compose.yml -O docker-compose.yml

img

配置文件默认包含以下关键端口映射：

  • 19530（RPC 数据端口，客户端连接核心通道）
  • 9091（RESTful API / 健康检查端口）

2.2 启动 Milvus 服务

# 后台启动 Milvus Standalone
sudo docker compose up -d

# 查看容器运行状态
sudo docker compose ps

预期输出中包含三个容器：milvus-standalone、milvus-etcd、milvus-minio，状态均为 running。

img

其中会报错：

img

**原因是：**MinIO 官方在 2025 年 10 月主动从 Docker Hub 撤下了 minio/minio 镜像，这个仓库现在已经被归档，任何地方拉取都会返回 pull access denied

**修复方式：**修改docker-compose.yml MinIO 的镜像地址从 Docker Hub 换成官方仍在维护的 quay.io 即可

sed -i 's|minio/minio:|quay.io/minio/minio:|' /opt/milvus/docker-compose.yml

2.3 配置腾讯云安全组（关键步骤）

由于需要从本机访问腾讯云服务器上的 Milvus，必须在腾讯云安全组中放行以下端口：

端口协议用途
19530TCPgRPC 数据端口（客户端连接）
9091TCPRESTful API / 健康检查

在腾讯云控制台 → 安全组 → 入站规则中，添加上述两条规则

img

2.4 验证服务可用性

# 在腾讯云服务器上验证 Milvus 健康状态
curl http://localhost:9091/healthz

# 返回 {"status":"ok"} 表示服务正常

img

三、结构与架构

3.1 Milvus 整体架构

Milvus 遵循数据平面与控制平面分解的原则，采用存储/计算分离的架构，整体分为四个层次，各层在可扩展性和灾难恢复方面相互独立。

img

各层职责简述：

  • 接入层：由无状态 Proxy 组成，负责验证客户端请求、聚合中间结果并返回最终结果。由于 Milvus 采用大规模并行处理（MPP）架构，Proxy 会对中间结果进行聚合和后处理。
  • 协调服务：集群的“大脑”，负责 DDL/DCL 管理、流服务管理、查询管理和历史数据管理，维护集群拓扑结构与一致性。
  • 工作节点：包括流节点（碎片级一致性保证与故障恢复）、查询节点（加载历史数据并提供查询）和数据节点（离线压缩与索引构建）。

  • 存储层：etcd 存储元数据快照（Schema、检查点），MinIO 存储索引文件和查询结果，WAL 存储保证数据持久性与一致性。

3.2 Standalone 模式组件关系

在 Standalone 部署模式下，Milvus 的所有组件 MixCoord、Proxy、QueryNode、DataNode、StreamingNode运行在同一个进程内，无需 Pod 间通信。

Docker Compose 部署包含三个容器：

img

四、基本使用（基于 pymilvus）

以下操作均在本机（客户端）通过 pymilvus 连接腾讯云服务器上的 Milvus 执行。

首先安装 Python SDK：

pip install pymilvus>=2.4.0

4.1 连接 Milvus

from pymilvus import MilvusClient

# 替换为你的腾讯云服务器公网 IP
MILVUS_URI = "http://<你的公网IP>:19530"

client = MilvusClient(uri=MILVUS_URI)

# 验证连接
print(client.list_collections())

Milvus 使用 19530 端口作为 gRPC 数据服务的唯一入口，所有数据操作（增删改查、索引创建、向量搜索）均通过此端口进行。

img

4.2 DDL：创建集合与索引

快速创建集合

# 快速创建一个名为 demo_collection 的集合
# 维度 768，使用默认主键 id 和向量字段 vector
if client.has_collection(collection_name="demo_collection"):
    client.drop_collection(collection_name="demo_collection")

client.create_collection(
    collection_name="demo_collection",
    dimension=768,
)

此方式会自动启用 auto_id（主键自增）和 enable_dynamic_field（支持动态字段），适合快速原型验证。

自定义 Schema 与索引

from pymilvus import MilvusClient, DataType

# 创建 Schema
schema = client.create_schema(auto_id=False, enable_dynamic_field=True)

schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="vector", datatype=DataType.FLOAT_VECTOR, dim=768)
schema.add_field(field_name="text", datatype=DataType.VARCHAR, max_length=512)

# 准备索引参数
index_params = client.prepare_index_params()

index_params.add_index(
    field_name="vector",
    index_type="HNSW",
    metric_type="COSINE",
    params={"M": 16, "efConstruction": 200},
)

# 创建集合并同时建立索引
client.create_collection(
    collection_name="my_collection",
    schema=schema,
    index_params=index_params,
)

Milvus 支持多种索引类型，常用选项包括 FLAT（精确搜索）、IVF_FLAT、HNSW（基于图的近似搜索）等。

img

4.3 DML：数据插入、更新与删除

插入数据

import random

# 模拟生成向量数据
data = [
    {
        "id": i,
        "vector": [random.uniform(-1, 1) for _ in range(768)],
        "text": f"文档内容 {i}",
    }
    for i in range(100)
]

res = client.insert(collection_name="my_collection", data=data)
print(f"插入成功，数量：{res['insert_count']}")

img

Upsert（更新或插入）

# Upsert 操作：存在则更新，不存在则插入
upsert_data = [
    {
        "id": 0,
        "vector": [random.uniform(-1, 1) for _ in range(768)],
        "text": "更新后的文档内容 0",
    }
]

res = client.upsert(collection_name="my_collection", data=upsert_data)

注意：更新数据时建议使用 upsert() 而非 delete() + insert()，因为 upsert 是原子操作。

删除数据

# 按主键删除
client.delete(collection_name="my_collection", ids=[0, 1, 2])

# 按过滤条件删除
client.delete(
    collection_name="my_collection",
    filter="id > 50",
)

img

4.4 DQL：查询与向量检索

标量过滤查询（Query）

# 查询 id 在 10 到 20 之间的记录
res = client.query(
    collection_name="my_collection",
    filter="id >= 10 and id <= 20",
    output_fields=["id", "text"],
    limit=10,
)

for row in res:
    print(row)

img

向量相似度搜索（Search）

# 生成一个查询向量
query_vector = [random.uniform(-1, 1) for _ in range(768)]

search_res = client.search(
    collection_name="my_collection",
    data=[query_vector],
    limit=5,
    output_fields=["id", "text"],
    search_params={
        "metric_type": "COSINE",
        "params": {"ef": 64},
    },
)

for hits in search_res:
    for hit in hits:
        print(f"id={hit['id']}, distance={hit['distance']:.4f}, text={hit['entity']['text']}")

search 使用 ANN（近似最近邻）算法找到与查询向量最相似的向量；query 则基于标量条件进行过滤检索。

img

混合检索（Hybrid Search）

img

五、DQL 操作流程总结

img

六、常用运维命令

# 查看 Milvus 容器日志
sudo docker compose logs -f milvus-standalone

# 重启 Milvus 服务
sudo docker compose restart

# 停止服务（保留数据）
sudo docker compose down

# 停止服务并删除所有数据
sudo docker compose down -v

七、注意事项

  1. 端口安全：生产环境中建议将安全组来源限制为具体 IP，避免 19530 端口暴露在公网。
  2. 数据持久化：Docker Compose 默认使用 volumes 存储数据，执行 docker compose down -v 会删除所有数据，操作前请确认。
  3. 资源要求：Milvus Standalone 建议至少分配 4 个 vCPU 和 8 GB 内存。
  4. 一致性级别：Milvus 支持 Strong、Bounded（默认）、Session、Eventually 四种一致性级别，可通过 search 或 query 的 consistency_level 参数调节。
  5. 版本选择：本文示例使用 Milvus v2.5 稳定版，如使用其他版本请注意 docker-compose 文件中的镜像标签和端口配置差异。
avatar
文章
阅读
粉丝