基于Python的Milvus完整使用案例

这份教程是Milvus 2.4.x + Python 的开箱即用实战案例，覆盖连接服务、创建集合、建索引、插入数据、向量检索、混合检索、数据管理全流程，适合新手快速上手。

一、环境准备

1. 启动Milvus服务

推荐用Docker一键启动（最简单，无需复杂配置）：

bash 复制代码

# 下载Milvus 2.4.x 配置文件
wget https://github.com/milvus-io/milvus/releases/download/v2.4.4/milvus-standalone-docker-compose.yml -O docker-compose.yml

# 启动服务
docker-compose up -d

启动后，Milvus默认地址：localhost:19530

2. 安装Python客户端

bash 复制代码

pip install pymilvus>=2.4.0  # 安装官方Python SDK
pip install numpy           # 用于生成模拟向量

二、完整实战代码

核心场景：向量数据库的基础CRUD + 相似度检索（模拟文本/图像特征向量存储与搜索）

python 复制代码

# 1. 导入依赖包
from pymilvus import (
    connections,  # 连接Milvus
    Collection,   # 集合操作
    FieldSchema,  # 字段定义
    CollectionSchema,  # 集合结构
    DataType,     # 数据类型
    utility       # 工具函数（检查集合、删除集合等）
)
import numpy as np

# ====================== 2. 连接Milvus服务 ======================
# 默认连接本地Milvus，参数：host(地址)、port(端口)、alias(连接别名)
connections.connect(
    alias="default", 
    host="localhost", 
    port="19530"
)
print("✅ 成功连接Milvus服务")

# ====================== 3. 定义集合结构（Schema） ======================
# 集合 = 表，字段 = 列，必须包含：主键字段 + 向量字段
# 字段1：主键ID（自增整数，唯一标识）
primary_field = FieldSchema(
    name="id", 
    dtype=DataType.INT64, 
    is_primary=True,  # 主键
    auto_id=True      # 自动生成ID，无需手动插入
)
# 字段2：向量字段（核心！存储特征向量，512维）
vector_field = FieldSchema(
    name="embedding", 
    dtype=DataType.FLOAT_VECTOR, 
    dim=512  # 向量维度：必须和你的数据一致
)
# 字段3：标量字段（辅助过滤，比如分类标签）
tag_field = FieldSchema(
    name="tag", 
    dtype=DataType.INT64
)

# 定义集合整体结构
schema = CollectionSchema(
    fields=[primary_field, vector_field, tag_field],
    description="Milvus基础案例：特征向量存储与检索"
)

# ====================== 4. 创建集合 ======================
collection_name = "milvus_demo"
# 如果集合已存在，先删除（避免重复创建报错）
if utility.has_collection(collection_name):
    utility.drop_collection(collection_name)

# 创建集合
collection = Collection(
    name=collection_name,
    schema=schema,
    using="default"  # 使用默认连接
)
print(f"✅ 成功创建集合：{collection_name}")

# ====================== 5. 创建向量索引（必须！） ======================
# Milvus必须建索引才能检索，索引决定检索速度和精度
# 入门推荐：IVF_FLAT（平衡速度和精度）
index_params = {
    "index_type": "IVF_FLAT",      # 索引类型
    "metric_type": "L2",           # 相似度计算方式：L2(欧氏距离)、IP(内积)、COSINE(余弦)
    "params": {"nlist": 128}       # 索引参数（聚类数量）
}

# 为向量字段创建索引
collection.create_index(
    field_name="embedding",
    index_params=index_params
)
print("✅ 成功创建向量索引")

# ====================== 6. 加载集合到内存（必须！） ======================
# 集合创建后默认在磁盘，必须加载到内存才能读写
collection.load()
print("✅ 集合已加载到内存")

# ====================== 7. 插入模拟数据 ======================
# 生成1000条512维随机向量（模拟文本/图像特征）
num_entities = 1000
vectors = np.random.rand(num_entities, 512).tolist()  # 转列表格式
# 生成标量标签（0-9随机分类）
tags = np.random.randint(0, 10, num_entities).tolist()

# 插入数据：字段顺序和Schema定义一致
insert_result = collection.insert(
    data=[vectors, tags]  # 自动填充主键（auto_id=True）
)
print(f"✅ 成功插入 {num_entities} 条数据，主键ID：{insert_result.ids[:5]}...")

# 刷新数据（确保插入后立即可检索）
collection.flush()

# ====================== 8. 核心功能：向量相似度检索 ======================
# 生成1条查询向量（和插入数据同维度）
search_vector = np.random.rand(1, 512).tolist()

# 检索参数
search_params = {
    "metric_type": "L2",
    "params": {"nprobe": 10}  # 检索精度：值越大越准，速度越慢
}

# 执行检索
results = collection.search(
    data=search_vector,        # 查询向量
    anns_field="embedding",    # 要检索的向量字段
    param=search_params,       # 检索参数
    limit=5,                   # 返回Top5最相似的结果
    output_fields=["id", "tag"]# 同时返回的标量字段
)

# 打印检索结果
print("\n🔍 向量相似度检索结果（Top5）：")
for hits in results:
    for hit in hits:
        print(f"ID: {hit.id}, 相似度距离: {hit.distance:.4f}, 标签: {hit.entity.get('tag')}")

# ====================== 9. 进阶：标量过滤 + 向量检索 ======================
# 场景：只检索【标签=3】的向量中，最相似的Top3
filtered_results = collection.search(
    data=search_vector,
    anns_field="embedding",
    param=search_params,
    limit=3,
    expr="tag == 3",  # 标量过滤条件（SQL风格）
    output_fields=["id", "tag"]
)

print("\n🔍 过滤后检索结果（tag=3，Top3）：")
for hits in filtered_results:
    for hit in hits:
        print(f"ID: {hit.id}, 相似度距离: {hit.distance:.4f}, 标签: {hit.entity.get('tag')}")

# ====================== 10. 数据管理 ======================
# 1. 删除数据（根据主键ID）
if len(insert_result.ids) > 0:
    del_id = insert_result.ids[0]
    collection.delete(expr=f"id == {del_id}")
    print(f"\n✅ 成功删除ID={del_id}的数据")

# 2. 释放集合（从内存卸载）
collection.release()
print("✅ 集合已从内存释放")

# 3. 删除集合（清空所有数据）
# utility.drop_collection(collection_name)
# print("✅ 已删除集合")

# ====================== 11. 断开连接 ======================
connections.disconnect("default")
print("\n✅ 已断开Milvus连接")

三、关键知识点解释

1. 核心概念

概念	解释
集合(Collection)	相当于关系型数据库的表，用于存储向量数据
向量字段	存储特征向量（文本/图像/音频的数字化特征）
索引	加速向量检索的核心，无索引无法检索
相似度计算	`L2`（欧氏距离，越小越相似）、`IP`（内积，越大越相似）、`COSINE`（余弦相似度）

2. 必做操作

连接Milvus后才能操作
向量字段必须建索引
集合必须加载到内存才能读写
检索前建议flush()刷新数据

3. 检索参数说明

nprobe：检索精度，10-100 之间调整，越大越准、速度越慢
limit：返回最相似的TopN结果
expr：标量过滤，支持==、>、<、and、or等条件

四、常见问题

连接失败 ：检查Milvus服务是否启动（docker ps 查看容器）
维度不匹配 ：插入向量的dim必须和Schema定义一致
检索报错：未建索引/未加载集合到内存
数据不显示 ：插入后未执行flush()刷新

总结

本案例覆盖Milvus Python客户端全流程操作，可直接复制运行
核心能力是向量相似度检索，适用于AI大模型、图像搜索、推荐系统等场景
入门优先用IVF_FLAT索引+L2相似度，后续可根据业务优化索引类型