在前文的向量化与存储示例中,FAISS 索引和 Chroma 数据保存在应用本地,适合单个程序使用。当知识库中的文档会不断新增或修改,同时又有多个问答服务需要读取它时,如果每个服务都维护一份本地副本,就要自行同步数据,并让每个服务重新生成或加载本地索引。
Milvus 以独立服务的方式提供存储和检索:一个程序负责把文档写入数据库,多个问答服务通过 SDK 查询同一份数据,减少应用维护副本的工作。代价是需要额外运行和维护数据库服务;单个脚本的小规模检索可以继续用本地方案。这里比较的是前文使用的本地模式,Chroma 也支持服务部署。
本文用 Docker 启动 Milvus 单机版,再用 Python 完成写入、检索、更新和删除。
1. Milvus 保存什么,检索什么
Embedding(向量化)模型把文本转换成向量;Milvus 保存向量及其对应的原文、来源,并根据问题向量寻找相关文档:
1 | 入库:原文 → Embedding 模型 → 向量 + 原文 + 来源 → 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 | docker compose up -d |
首次启动需要下载镜像。Milvus 接收请求,etcd 保存集合结构等管理信息,MinIO 保存数据文件;这三个服务应持续运行。健康接口返回 OK 后再运行 Python;启动失败可用 docker compose logs --tail=100 standalone 查看日志。
安装依赖,运行完整示例:
1 | python3.12 -m venv .venv |
依赖固定为 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 | from pymilvus import MilvusClient, DataType |
load_model() 加载包内固定版本的 BGE 模型,在 CPU 上运行。三条文档编码后,vectors.shape 为 (3, 512),第 i 条向量对应第 i 条原文。normalize_embeddings=True 将向量长度调整为 1,便于比较向量的方向。
定义字段、索引并加载集合
COLLECTION 是包内定义的集合名 rag_milvus_demo_512。创建集合时,让字段与待写入的记录一致:
1 | schema = client.create_schema(auto_id=False, enable_dynamic_field=False) |
id 是整数主键,auto_id=False 表示由应用提供;更新文档时沿用同一主键,才能定位原记录。字符串的 max_length 按 UTF-8 字节数计;关闭动态字段后,只接受已声明的字段,能及时发现字段名拼错。向量的 dim=512 必须与模型输出一致。Schema 说明
Strong 使用强一致性读取,便于立即检查刚完成的写入、更新和删除,代价是可能增加读取等待时间。
接着建立向量索引,让数据库准备好检索:
1 | index_params = client.prepare_index_params() |
向量索引用于加速相似检索,AUTOINDEX 让 Milvus 选择具体索引;COSINE 规定用余弦相似度比较向量方向。load_collection() 把所需数据与索引加载到服务端内存,集合中的数据才可供检索;加载后新增记录也能参与检索。集合加载说明
批量写入
将原文记录与对应向量合并,用一次请求写入三条,减少逐条调用:
1 | rows = [] |
rows 是字典列表,每个字典包含 Schema 中的五个字段。tolist() 将模型输出的数组转换为普通 Python 列表。
4. 用问题向量检索
问题必须使用与原文相同的模型,否则向量坐标的含义不同,即使维度相同也无法可靠比较。按 BGE 的输入规则,短查询添加检索指令,文档直接编码。包内 QUERY_PREFIX 就是这条指令:为这个句子生成表示以用于检索相关文章:。
1 | question = "退款什么时候到账?" |
filter 将范围限定在退款分类,避免其他分类混入结果;随后按 vector 的相似度最多返回两条。output_fields 指定带回原文、分类和来源。查询的 COSINE 必须与索引一致。
data 接收查询向量列表,所以即使只有一个问题,也要写成 [query_vector]。返回结果的外层对应问题,results[0] 就是第一个问题的命中列表。实测输出:
1 | 2 0.6664 显示已退款表示平台已发起操作,银行卡到账还需要支付渠道处理。 |
每条结果中,id 是主键,entity 保存要求返回的字段,distance 是分数。使用 COSINE 时分数越大越相似,字段名中的 distance 不代表越小越好。
本次检索中,排名第一的文档说明“已退款”不等于银行卡已到账;排名第二的文档补充,退款通常会在三个工作日内原路退回。排名依据是相似度分数,但分数不能当作答案正确率。
5. 读取、更新与删除
get 按 ID 读取,query 按字段筛选
已知 ID 或筛选条件时,不需要生成问题向量:
1 | by_id = client.get( |
by_id 包含 ID 为 1 的文档,by_filter 包含两条退款文档。这两种读取都返回记录列表,不计算相似度;需要相似度排序时才使用 search()。
upsert 替换记录,正文与向量一起更新
把 ID 为 1 的到账时间改为“一到三个工作日”,重新编码后写回:
1 | updated = dict(docs[0]) |
这里使用默认的整条记录替换:主键存在就替换,不存在就插入,因此提供全部字段。再次按 ID 1 读取,应得到新原文。只改原文、不更新向量,会让检索依据与返回内容不一致。
普通 insert() 不检查主键重复,更新已有记录应使用 upsert()。官方插入与更新说明
delete 按 ID 删除
删除 ID 为 3 的发票文档,再读取确认:
1 | client.delete(collection_name=COLLECTION, ids=[3]) |
空列表表示记录已不可读;需要恢复时重新写入原记录。close() 只关闭客户端连接。
6. 验证重建容器后数据仍在
要确认数据能在容器重建后保留,需要在重建后读回旧记录,而不重新写入。本例把三个服务的数据目录映射到示例目录下的 volumes/milvus、volumes/etcd 和 volumes/minio。完成 demo.py 后,在同一目录重建容器:
1 | docker compose down |
down 会暂时中断服务并移除容器,但会保留这些本地目录。等健康接口重新返回 OK,执行:
1 | python verify_saved.py |
脚本只读取和检索,不重新写入。应保留 ID 1、2,ID 1 包含更新后的“一到三个工作日”,ID 3 已删除,最后输出“已保存数据检查通过,仍能检索到两条退款文档”。这个流程已实测通过。
容器可以重建,数据靠这些本地目录保留;删除 volumes/ 会丢失本例数据。