生产级向量数据库 (Milvus)

Catalogue
  1. 1. Milvus 保存什么,检索什么
  2. 2. 用 Docker 启动服务
  3. 3. 创建集合并写入文档
    1. 连接数据库,生成向量
    2. 定义字段、索引并加载集合
    3. 批量写入
  4. 4. 用问题向量检索
  5. 5. 读取、更新与删除
    1. get 按 ID 读取,query 按字段筛选
    2. upsert 替换记录,正文与向量一起更新
    3. delete 按 ID 删除
  6. 6. 验证重建容器后数据仍在

在前文的向量化与存储示例中,FAISS 索引和 Chroma 数据保存在应用本地,适合单个程序使用。当知识库中的文档会不断新增或修改,同时又有多个问答服务需要读取它时,如果每个服务都维护一份本地副本,就要自行同步数据,并让每个服务重新生成或加载本地索引。

Milvus 以独立服务的方式提供存储和检索:一个程序负责把文档写入数据库,多个问答服务通过 SDK 查询同一份数据,减少应用维护副本的工作。代价是需要额外运行和维护数据库服务;单个脚本的小规模检索可以继续用本地方案。这里比较的是前文使用的本地模式,Chroma 也支持服务部署。

本文用 Docker 启动 Milvus 单机版,再用 Python 完成写入、检索、更新和删除。

1. Milvus 保存什么,检索什么

Embedding(向量化)模型把文本转换成向量;Milvus 保存向量及其对应的原文、来源,并根据问题向量寻找相关文档:

1
2
入库:原文 → Embedding 模型 → 向量 + 原文 + 来源 → Milvus
检索:问题 → 同一套模型 → 问题向量 → Milvus → 相关原文与分数

记录存放在 Collection(集合) 中,可以把它理解成一张数据库表;Schema(结构定义) 规定字段类型和向量维度。本例每条记录包含 id(主键)、text(原文)、vector(向量)、topic(分类)和 source(来源)。向量用于比较相似度,原文与来源用于展示检索结果、核对出处。

2. 用 Docker 启动服务

准备 Docker、Compose V2 和 Python 3.12。Docker 运行环境至少分配 8 GB 内存。官方安装要求

Compose 可以一次启动 Milvus 及其依赖,并统一配置网络和数据目录。下载完整示例包,解压并进入 milvus-sdk-example 目录。包内使用官方 Compose 配置,固定 Milvus 3.0.2,端口仅绑定本机:

1
2
3
docker compose up -d
docker compose ps -a
curl -f http://127.0.0.1:9091/healthz

首次启动需要下载镜像。Milvus 接收请求,etcd 保存集合结构等管理信息,MinIO 保存数据文件;这三个服务应持续运行。健康接口返回 OK 后再运行 Python;启动失败可用 docker compose logs --tail=100 standalone 查看日志。

安装依赖,运行完整示例:

1
2
3
4
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python demo.py

依赖固定为 pymilvus==3.0.2、sentence-transformers==6.1.0,分别用于访问 Milvus 和生成向量。首次下载模型需要联网,向量在本机生成,无需 API Key。

以下按执行顺序节选 demo.py。它已包含由三条虚构文档组成的 docs 列表;common.py 提供集合名、模型加载和查询指令。重复运行遇到同名集合时,脚本会停止,换集合名的方法见 README。

示例已在 macOS Apple Silicon、Python 3.12.7 上验证增删改查和容器重建,具体环境保存在包内 VALIDATION.md。

3. 创建集合并写入文档

连接数据库,生成向量

docs 保存以下三条文档。每条文档还带有 source 来源标记,例如 refund.md#到账时间,方便检索后定位原文。

ID 分类 原文
1 refund 退款审核通过后,款项通常会在三个工作日内原路退回,节假日顺延。
2 refund 显示已退款表示平台已发起操作,银行卡到账还需要支付渠道处理。
3 invoice 电子发票可以在订单详情页下载,修改抬头需要联系客服。

Python 通过 19530 端口连接 Milvus,再用中文向量模型 BAAI/bge-small-zh-v1.5 编码原文,每条生成 512 维向量:

1
2
3
4
5
6
7
8
9
10
from pymilvus import MilvusClient, DataType
from common import COLLECTION, load_model, QUERY_PREFIX

client = MilvusClient(uri="http://127.0.0.1:19530", timeout=30)
model = load_model()

texts = []
for doc in docs:
texts.append(doc["text"])
vectors = model.encode(texts, normalize_embeddings=True)

load_model() 加载包内固定版本的 BGE 模型,在 CPU 上运行。三条文档编码后,vectors.shape 为 (3, 512),第 i 条向量对应第 i 条原文。normalize_embeddings=True 将向量长度调整为 1,便于比较向量的方向。

定义字段、索引并加载集合

COLLECTION 是包内定义的集合名 rag_milvus_demo_512。创建集合时,让字段与待写入的记录一致:

1
2
3
4
5
6
7
8
9
10
11
12
schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="text", datatype=DataType.VARCHAR, max_length=4096)
schema.add_field(field_name="topic", datatype=DataType.VARCHAR, max_length=64)
schema.add_field(field_name="source", datatype=DataType.VARCHAR, max_length=256)
schema.add_field(field_name="vector", datatype=DataType.FLOAT_VECTOR, dim=512)

client.create_collection(
collection_name=COLLECTION,
schema=schema,
consistency_level="Strong",
)

id 是整数主键,auto_id=False 表示由应用提供;更新文档时沿用同一主键,才能定位原记录。字符串的 max_length 按 UTF-8 字节数计;关闭动态字段后,只接受已声明的字段,能及时发现字段名拼错。向量的 dim=512 必须与模型输出一致。Schema 说明

Strong 使用强一致性读取,便于立即检查刚完成的写入、更新和删除,代价是可能增加读取等待时间。

接着建立向量索引,让数据库准备好检索:

1
2
3
4
5
6
index_params = client.prepare_index_params()
index_params.add_index(
field_name="vector", index_type="AUTOINDEX", metric_type="COSINE"
)
client.create_index(collection_name=COLLECTION, index_params=index_params)
client.load_collection(collection_name=COLLECTION)

向量索引用于加速相似检索,AUTOINDEX 让 Milvus 选择具体索引;COSINE 规定用余弦相似度比较向量方向。load_collection() 把所需数据与索引加载到服务端内存,集合中的数据才可供检索;加载后新增记录也能参与检索。集合加载说明

批量写入

将原文记录与对应向量合并,用一次请求写入三条,减少逐条调用:

1
2
3
4
5
6
7
8
rows = []
for i, doc in enumerate(docs):
row = dict(doc)
row["vector"] = vectors[i].tolist()
rows.append(row)

inserted = client.insert(collection_name=COLLECTION, data=rows)
print(inserted["insert_count"]) # 3

rows 是字典列表,每个字典包含 Schema 中的五个字段。tolist() 将模型输出的数组转换为普通 Python 列表。

4. 用问题向量检索

问题必须使用与原文相同的模型,否则向量坐标的含义不同,即使维度相同也无法可靠比较。按 BGE 的输入规则,短查询添加检索指令,文档直接编码。包内 QUERY_PREFIX 就是这条指令:为这个句子生成表示以用于检索相关文章:。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
question = "退款什么时候到账?"
query_vector = model.encode(
QUERY_PREFIX + question, normalize_embeddings=True
).tolist()

results = client.search(
collection_name=COLLECTION,
data=[query_vector],
anns_field="vector",
search_params={"metric_type": "COSINE", "params": {}},
filter='topic == "refund"',
limit=2,
output_fields=["text", "topic", "source"],
)
for hit in results[0]:
print(hit["id"], round(hit["distance"], 4), hit["entity"]["text"])

filter 将范围限定在退款分类,避免其他分类混入结果;随后按 vector 的相似度最多返回两条。output_fields 指定带回原文、分类和来源。查询的 COSINE 必须与索引一致。

data 接收查询向量列表,所以即使只有一个问题,也要写成 [query_vector]。返回结果的外层对应问题,results[0] 就是第一个问题的命中列表。实测输出:

1
2
2 0.6664 显示已退款表示平台已发起操作,银行卡到账还需要支付渠道处理。
1 0.613 退款审核通过后,款项通常会在三个工作日内原路退回,节假日顺延。

每条结果中,id 是主键,entity 保存要求返回的字段,distance 是分数。使用 COSINE 时分数越大越相似,字段名中的 distance 不代表越小越好。

本次检索中,排名第一的文档说明“已退款”不等于银行卡已到账;排名第二的文档补充,退款通常会在三个工作日内原路退回。排名依据是相似度分数,但分数不能当作答案正确率。

5. 读取、更新与删除

get 按 ID 读取,query 按字段筛选

已知 ID 或筛选条件时,不需要生成问题向量:

1
2
3
4
5
6
7
by_id = client.get(
collection_name=COLLECTION, ids=[1], output_fields=["text", "source"]
)
by_filter = client.query(
collection_name=COLLECTION, filter='topic == "refund"',
output_fields=["text", "source"], limit=10,
)

by_id 包含 ID 为 1 的文档,by_filter 包含两条退款文档。这两种读取都返回记录列表,不计算相似度;需要相似度排序时才使用 search()。

upsert 替换记录,正文与向量一起更新

把 ID 为 1 的到账时间改为“一到三个工作日”,重新编码后写回:

1
2
3
4
5
6
updated = dict(docs[0])
updated["text"] = "退款审核通过后,款项通常会在一到三个工作日内原路退回,节假日顺延。"
updated["vector"] = model.encode(
updated["text"], normalize_embeddings=True
).tolist()
client.upsert(collection_name=COLLECTION, data=[updated])

这里使用默认的整条记录替换:主键存在就替换,不存在就插入,因此提供全部字段。再次按 ID 1 读取,应得到新原文。只改原文、不更新向量,会让检索依据与返回内容不一致。

普通 insert() 不检查主键重复,更新已有记录应使用 upsert()。官方插入与更新说明

delete 按 ID 删除

删除 ID 为 3 的发票文档,再读取确认:

1
2
3
4
5
6
client.delete(collection_name=COLLECTION, ids=[3])
after_delete = client.get(
collection_name=COLLECTION, ids=[3], output_fields=["text"]
)
print(list(after_delete)) # []
client.close()

空列表表示记录已不可读;需要恢复时重新写入原记录。close() 只关闭客户端连接。

6. 验证重建容器后数据仍在

要确认数据能在容器重建后保留,需要在重建后读回旧记录,而不重新写入。本例把三个服务的数据目录映射到示例目录下的 volumes/milvus、volumes/etcd 和 volumes/minio。完成 demo.py 后,在同一目录重建容器:

1
2
docker compose down
docker compose up -d

down 会暂时中断服务并移除容器,但会保留这些本地目录。等健康接口重新返回 OK,执行:

1
python verify_saved.py

脚本只读取和检索,不重新写入。应保留 ID 1、2,ID 1 包含更新后的“一到三个工作日”,ID 3 已删除,最后输出“已保存数据检查通过,仍能检索到两条退款文档”。这个流程已实测通过。

容器可以重建,数据靠这些本地目录保留;删除 volumes/ 会丢失本例数据。