【Milvus】Milvus 快速入门指南

本教程将提供了一个 Milvus 快速入门指南，帮助快速上手 Milvus 向量数据库。教程基于 Milvus 2.x（截至 2025 年 4 月的最新版本），使用 Docker 部署 Milvus 和 Python SDK（pymilvus）进行操作。从安装开始，逐步完成创建集合、插入向量、构建索引、执行搜索等核心操作，最后展示一个简单的语义搜索示例。教程适合初学者，代码和步骤都经过简化，确保能快速上手。

---

1. 前提条件

确保你的环境满足以下要求：

• 操作系统：Linux（推荐 Ubuntu）、macOS 或 Windows（需要 WSL2）。
• 工具：
  • Docker（19.03+）：用于运行 Milvus。
  • Python 3.7+ 和 pip：用于安装 pymilvus。
• 硬件：至少 8GB 内存、4 核 CPU、50GB 磁盘空间。
• 网络：确保可以访问 Docker Hub 和 PyPI。

---

2. 安装 Milvus

我们将使用 Docker 部署 Milvus 单机模式，因为这是最简单的方式。

步骤：

1. 安装 Docker（如果尚未安装）：

   • Ubuntu：

     sudo apt update
     sudo apt install -y docker.io
     sudo systemctl start docker
     sudo systemctl enable docker
     

   • macOS/Windows：安装 Docker Desktop。

2. 拉取 Milvus 镜像：

   docker pull milvusdb/milvus:latest
   

3. 创建数据目录：

   mkdir -p ~/milvus/data ~/milvus/logs ~/milvus/configs
   

4. 运行 Milvus 容器：

   docker run -d --name milvus_standalone \
     -p 19530:19530 \
     -p 9091:9091 \
     -v ~/milvus/data:/var/lib/milvus \
     -v ~/milvus/logs:/var/lib/milvus/logs \
     -v ~/milvus/configs:/var/lib/milvus/configs \
     milvusdb/milvus:latest
   

5. 验证 Milvus 运行：

   docker ps
   

   确保 milvus_standalone 容器状态为 Up。

---

3. 安装 Milvus Python SDK

Milvus 的 Python SDK（pymilvus）用于与 Milvus 服务交互。

步骤：

1. 安装 pymilvus：

   pip3 install pymilvus
   

2. 验证安装：

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

   如果返回版本号（如 2.4.x），说明安装成功。

---

4. 快速入门：核心操作

以下是一个完整的 Milvus 操作流程，包括创建集合、插入向量、构建索引和执行搜索。我们将使用随机生成的向量作为示例数据。

步骤：

1. 创建 Python 脚本：
   创建一个文件 milvus_quickstart.py，并添加以下代码：

   from pymilvus import MilvusClient, DataType, FieldSchema, CollectionSchema
   import random
   
   from pymilvus.milvus_client import IndexParams
   
   # 1. 连接 Milvus 服务
   client = MilvusClient(uri="http://localhost:19530")
   print("Connected to Milvus")
   
   # 2. 创建集合
   collection_name = "quickstart_collection"
   client.drop_collection(collection_name)  # 删除旧集合（如果存在）
   fields = [
       FieldSchema(name="id", dtype=DataType.INT64, is_primary=True),
       FieldSchema(name="vector", dtype=DataType.FLOAT_VECTOR, dim=128)
   ]
   schema = CollectionSchema(fields=fields, enable_dynamic_field=True)
   client.create_collection(collection_name=collection_name, schema=schema, metric_type="L2")
   print(f"Collection '{collection_name}' created")
   
   # 3. 插入随机向量
   data = [
       {
           "id": i,
           "vector": [random.random() for _ in range(128)],
           "metadata": {"category": f"cat_{i % 3}"}
       }
       for i in range(1000)
   ]
   client.insert(collection_name=collection_name, data=data)
   print("Inserted 1000 vectors")
   
   # 4. 构建索引
   index_params = {
       "field_name":"vector",
       "index_type": "HNSW",
       "metric_type": "L2",
       "params": {"M": 16, "efConstruction": 200}
   }
   client.create_index(
       collection_name=collection_name,
       index_params=IndexParams(**index_params)
   )
   print("Index created")
   
   client.load_collection(collection_name)
   
   # 5. 执行搜索
   query_vector = [random.random() for _ in range(128)]
   results = client.search(
       collection_name=collection_name,
       data=[query_vector],
       limit=5,  # 返回 Top-5 结果
       output_fields=["id", "metadata"],
       filter="metadata['category'] == 'cat_0'"  # 过滤条件
   )
   print("Search results:")
   for result in results[0]:
       print(f"ID: {result['id']}, Distance: {result['distance']}, Metadata: {result['entity']['metadata']}")
   
   # 6. 清理
   client.drop_collection(collection_name)
   print("Collection dropped")
   

2. 运行脚本：

   python3 milvus_quickstart.py
   

3. 输出示例：

   Connected to Milvus
   Collection 'quickstart_collection' created
   Inserted 1000 vectors
   Index created
   Search results:
   ID: 0, Distance: 12.345, Metadata: {'category': 'cat_0'}
   ID: 3, Distance: 12.678, Metadata: {'category': 'cat_0'}
   ...
   Collection dropped
   

代码说明：

• 连接：使用 MilvusClient 连接本地 Milvus 服务。
• 集合：创建一个名为 quickstart_collection 的集合，指定向量维度（128）和距离度量（L2）。
• 插入：插入 1000 个随机生成的 128 维向量，每个向量关联一个 ID 和元数据（category）。
• 索引：使用 HNSW 索引加速搜索，设置参数 M 和 efConstruction。
• 搜索：搜索与查询向量最相似的 5 个向量，过滤 category == 'cat_0'。
• 清理：删除集合以释放资源。

---

5. 简单应用：语义搜索

以下是一个更实际的示例，展示如何使用 Milvus 实现 文本语义搜索。我们将使用预训练的 Sentence-BERT 模型生成文本嵌入，并存储到 Milvus 中。

步骤：

1. 安装依赖*：安装 Sentence-BERT 模型库：

   pip3 install sentence-transformers
   

2. 创建语义搜索脚本：
   创建文件 milvus_semantic_search.py：

   from pymilvus import MilvusClient, FieldSchema, DataType, CollectionSchema
   from pymilvus.milvus_client import IndexParams
   from sentence_transformers import SentenceTransformer
   
   # 初始化 Milvus 和 Sentence-BERT
   client = MilvusClient(uri="http://localhost:19530")
   model = SentenceTransformer('all-MiniLM-L6-v2')  # 加载预训练模型
   
   # 准备文本数据
   texts = [
       "I love machine learning",
       "Deep learning is a subset of AI",
       "Natural language processing is fascinating",
       "Computer vision is transforming industries",
       "AI is the future"
   ]
   embeddings = model.encode(texts)  # 生成文本嵌入
   
   # 创建集合
   collection_name = "semantic_search"
   client.drop_collection(collection_name)
   fields = [
       FieldSchema(name="id", dtype=DataType.INT64, is_primary=True),
       FieldSchema(name="vector", dtype=DataType.FLOAT_VECTOR, dim=384)
   ]
   schema = CollectionSchema(fields=fields, enable_dynamic_field = True)
   client.create_collection(collection_name=collection_name, schema=schema, metric_type="COSINE")
   
   # 插入数据
   data = [
       {"id": i, "vector": embeddings[i].tolist(), "text": texts[i]}
       for i in range(len(texts))
   ]
   client.insert(collection_name=collection_name, data=data)
   
   # 构建索引
   index_params={"field_name":"vector", "index_type": "HNSW", "metric_type": "COSINE", "params": {"M": 16, "efConstruction": 200}}
   client.create_index(
       collection_name=collection_name,
       index_params = IndexParams(**index_params)
   )
   
   client.load_collection(collection_name)
   
   # 搜索
   query = "Artificial intelligence advancements"
   query_embedding = model.encode([query])[0].tolist()
   results = client.search(
       collection_name=collection_name,
       data=[query_embedding],
       limit=3,
       output_fields=["text"]
   )
   print("Query:", query)
   print("Top results:")
   for result in results[0]:
       print(f"Text: {result['entity']['text']}, Distance: {result['distance']}")
   
   # 清理
   client.drop_collection(collection_name)
   

   3. 运行脚本：

      python3 milvus_semantic_search.py
      

3. 输出示例：

   Query: Artificial intelligence advancements
   Top results:
   Text: AI is the future, Distance: 0.85
   Text: Deep learning is a subset of AI, Distance: 0.78
   Text: Natural language processing is fascinating, Distance: 0.65
   

说明：

• Sentence-BERT：将文本转换为 384 维嵌入，捕捉语义信息。
• COSINE 距离：用于衡量文本嵌入的相似性。
• 搜索：查找与查询文本语义最相近的文本。

---

6. 常见问题与解决

• Milvus 服务连接失败：
  • 确保 Docker 容器运行：docker ps。
  • 检查端口 19530 是否被占用或被防火墙阻止。
• 插入或搜索失败：
  • 确认集合已创建且索引已构建。
  • 检查向量维度是否匹配（例如，128 或 384）。
• 性能缓慢：
  • 调整索引参数（如 efConstruction 或 M）。
  • 增加硬件资源（内存、CPU）。
• Python 环境问题：
  • 使用虚拟环境避免依赖冲突：

    python3 -m venv milvus_env
    source milvus_env/bin/activate
    

---

7. 总结

本教程展示了如何通过 Docker 安装 Milvus、安装 pymilvus、执行核心操作，并实现简单的语义搜索。

• 部署 Milvus 并连接到服务。
• 创建集合、插入向量、构建索引和执行搜索。
• 使用 Sentence-BERT 实现语义搜索。

---

8. 参考资源：

• Milvus 官方文档
• pymilvus 示例
• Sentence-Transformers 文档