快速开始

本章节用 5 分钟带你跑通 Milvus 向量数据库的完整链路：启动服务 → 建表 → 插入数据 → 建索引 → 向量搜索 → 清理。跑通后，你可以再阅读后续章节深入每个主题。

前置说明

在开始之前，请确认本机已具备以下环境：

依赖	最低版本	说明
Docker	20.10+	用于启动 Milvus 单机版容器
Docker Compose	v2+	编排 Milvus 及其依赖（etcd / MinIO）
Python	3.8+	运行 pymilvus 客户端脚本
pip	21+	安装 pymilvus

提示：可通过 docker --version、docker compose version、python --version 逐一核对。

步骤 1：启动 Milvus

Milvus 单机版以 docker-compose 方式运行，包含 milvus、etcd、minio 三个容器。把下面的内容保存为 docker-compose.yml：

version: '3.5'

services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.5
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - etcd_data:/etcd
    command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd

  minio:
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    volumes:
      - minio_data:/minio_data
    command: minio server /minio_data

  milvus:
    image: milvusdb/milvus:v2.4.0
    command: ["milvus", "run", "standalone"]
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - milvus_data:/var/lib/milvus
    ports:
      - "19530:19530"   # gRPC 端口
      - "9091:9091"     # Metrics 端口
    depends_on:
      - etcd
      - minio

volumes:
  etcd_data:
  minio_data:
  milvus_data:

也可以直接下载官方编排文件：

# 官方精简版
curl -L -o docker-compose.yml https://github.com/milvus-io/milvus/releases/download/v2.4.0/milvus-standalone-docker-compose.yml

启动服务：

docker compose up -d

查看容器状态，三个容器均为 Up 即说明启动成功：

docker compose ps

预期输出：

NAME                IMAGE                                  STATUS
milvus-standalone   milvusdb/milvus:v2.4.0                 Up
milvus-minio        minio/minio:RELEASE.2023-03-20...      Up
milvus-etcd         quay.io/coreos/etcd:v3.5.5             Up

步骤 2：安装 pymilvus

pip install pymilvus

验证安装版本（应输出 2.4.x）：

python -c "import pymilvus; print(pymilvus.__version__)"

步骤 3：完整示例脚本

把下面这段约 60 行的脚本保存为 quick_start.py，可直接 python quick_start.py 运行。它串起了连接 → 创建 Collection（含 Schema）→ 插入 10 条 128 维向量 → 创建 IVF_FLAT 索引 → load → 搜索 → 打印结果 → 清理的完整链路，使用推荐的 MilvusClient 新 API：

import random
from pymilvus import MilvusClient, DataType

# 1. 连接 Milvus
client = MilvusClient(uri="http://localhost:19530")
print("已连接 Milvus")

COLLECTION_NAME = "quick_start_demo"

# 清理同名的旧集合，保证脚本可重复运行
if client.has_collection(COLLECTION_NAME):
    client.drop_collection(COLLECTION_NAME)

# 2. 定义 Schema：主键 + 128 维向量 + 类别字段
schema = MilvusClient.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=128)
schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=64)

# 3. 准备索引（IVF_FLAT），建表时一并下发
index_params = client.prepare_index_params()
index_params.add_index(
    field_name="vector",
    index_type="IVF_FLAT",
    metric_type="L2",
    params={"nlist": 128},
)

client.create_collection(
    collection_name=COLLECTION_NAME,
    schema=schema,
    index_params=index_params,
)
print(f"已创建集合 {COLLECTION_NAME}")

# 4. 插入 10 条随机向量
data = [
    {"id": i, "vector": [random.random() for _ in range(128)], "category": f"cat_{i % 3}"}
    for i in range(10)
]
client.insert(collection_name=COLLECTION_NAME, data=data)
print(f"已插入 {len(data)} 条数据")

# 5. 加载集合到内存，使其可被搜索
client.load_collection(COLLECTION_NAME)
print("集合已 load")

# 6. 执行向量搜索，取 top 3
query_vector = [random.random() for _ in range(128)]
results = client.search(
    collection_name=COLLECTION_NAME,
    data=[query_vector],
    limit=3,
    output_fields=["category"],
)

# 7. 打印搜索结果
print("\n搜索结果（top 3）：")
for hit in results[0]:
    print(f"  id={hit['id']}, distance={hit['distance']:.4f}, category={hit['entity']['category']}")

# 8. 清理
client.drop_collection(COLLECTION_NAME)
client.close()
print("\n已清理集合并关闭连接，快速开始演示完成。")

步骤 4：预期输出

运行脚本后，输出形如：

已连接 Milvus
已创建集合 quick_start_demo
已插入 10 条数据
集合已 load

搜索结果（top 3）：
  id=4, distance=12.3456, category=cat_1
  id=7, distance=13.2109, category=cat_1
  id=2, distance=14.0567, category=cat_2

已清理集合并关闭连接，快速开始演示完成。

说明：distance 是 L2 距离，越小越相似；向量是随机的，因此每次运行的数值会不同，但流程一致。

常见问题

端口 19530 被占用

报错形如 Bind port failed: 19530。可释放占用端口，或修改 docker-compose.yml 中的端口映射（例如 19531:19530），并在脚本里把 uri 改成 http://localhost:19531。

# 查看占用 19530 的进程
# Windows PowerShell
netstat -ano | findstr :19530
# Linux / macOS
lsof -i :19530

连接被拒绝（Connection refused）

可能原因及排查：

原因	排查方式	解决办法
Milvus 容器未启动	docker compose ps	执行 docker compose up -d
容器仍在初始化	查看日志 docker compose logs milvus	等待 10-30 秒后重试
端口映射错误	docker compose ps 中 PORTS 列	核对 docker-compose.yml 的 ports
防火墙拦截	关闭本机防火墙测试	放行 19530 端口

RPC error 或超时

通常是容器内存不足导致。可在 Docker Desktop 设置中给 Docker 至少分配 4GB 内存，然后重启容器：

docker compose down
docker compose up -d

查看实时日志定位问题

# 跟踪 milvus 容器日志
docker compose logs -f milvus

下一步

跑通快速开始后，你可以：

1. 阅读简介，了解 Milvus 全貌
2. 学习基础概念，理解 Collection / 向量 / 索引等术语
3. 掌握集合创建与 Schema 定义