Embedding 模型选型
与 Milvus 从部署到检索

本专题目录

阅读过程中可按 Ctrl + Z 快速返回当前页面的本章目录；也可以点击右下角按钮。

知识流思维导图

顺序不能倒：先确定 Embedding 模型和输出维度，再创建 Milvus 向量字段。数据库字段是 1024 维，模型却返回 1536 维时，数据写不进去。

M01Embedding 模型分类

Embedding 不是一个固定品牌，而是一类“把输入内容编码成向量”的模型。工程上最实用的分法是先看调用方式和擅长的数据。

M02Embedding 模型选型与评测

明确默认方案：第一版先用成熟的托管多语言 Embedding API，减少模型运维，把精力放在切块、metadata 和召回评测；如果政策禁止文本出网，再选 BGE-M3 或 Qwen3-Embedding 等多语言开源模型在内网运行。最后让候选模型在同一份真实评测集上比赛。

选择时检查 8 件事

M03模型版本、维度与迁移约束

文档向量与查询向量必须位于兼容坐标系。换模型、重要版本、预处理方式或维度，通常要新建字段或 Collection，重新向量化全部文档，评测后再切流量。

不要原地混写：一半数据用模型 A、一半用模型 B，再用 B 搜整个 Collection，即使数据库成功返回，也没有可靠语义。

embedding_provider = "your-provider"
embedding_model = "exact-model-name"
embedding_version = "固定版本或内部发布号"
embedding_dim = 1024
preprocess_version = "chunk-clean-v3"

D01Milvus 数据层级与核心对象

向量数据库服务 Milvus 接收向量、普通字段和过滤条件，建立近邻搜索索引并返回相似记录。它不负责把文字变向量，也不生成最终答案。

D02向量写入与搜索链路

应用不用直接调用内部节点：后端只连统一 URI。理解内部结构是为了排查写入、对象存储、索引和查询内存问题。

D03退款知识库的字段设计

默认设计：一个 Entity 存一个 Chunk；正文放 Milvus 方便取回，原始 PDF 放对象存储。权限、租户、状态、版本和有效期使用独立标量字段，便于搜索前过滤。

高频过滤字段不要全塞进一个大 JSON：tenant、status、时间等建议独立建字段和索引，类型、权限逻辑和性能更清楚。

P01Milvus 部署模式选型

你的默认选择：Windows + Docker Desktop + Milvus Standalone。真正需要多节点、高可用和更大规模时，再评估 Distributed 或托管服务。

P02Windows 用 Docker 部署 Standalone

Docker 容器部署 Docker 把 Milvus 及依赖装进隔离容器。Python 后端可在容器外通过 localhost:19530 连接。

# PowerShell
New-Item -ItemType Directory -Path D:\milvus-local
Set-Location D:\milvus-local

# 2026-09 官方安装页示例为 3.0.1；未来安装前先核对官方页面
Invoke-WebRequest https://github.com/milvus-io/milvus/releases/download/v3.0.1/milvus-standalone-docker-compose.yml -OutFile docker-compose.yml

docker compose up -d
docker compose ps

当前官方 Compose 会启动 Milvus、MinIO 和 etcd 等容器。客户端地址通常为 http://localhost:19530，数据映射到当前目录的 volumes/。

# 停服务，保留数据
docker compose down

# 再启动
docker compose up -d

# 查看日志
docker compose logs milvus-standalone

停容器不等于删数据：删除 volumes 或删除 Docker 卷可能造成不可恢复的数据丢失。删除前先备份并确认路径。

C01连接、建 Collection 和索引

pip install -U pymilvus sentence-transformers

from pymilvus import MilvusClient, DataType

URI = "http://localhost:19530"
TOKEN = "root:Milvus"       # 仅本地演示；生产必须改默认凭据
COLLECTION = "refund_policy_chunks_v1"
DIM = 1024                  # 必须与真实模型输出长度一致

client = MilvusClient(uri=URI, token=TOKEN)

schema = MilvusClient.create_schema(
    auto_id=False,
    enable_dynamic_field=False,
)
schema.add_field("chunk_id", DataType.VARCHAR,
                 is_primary=True, max_length=128)
schema.add_field("document_id", DataType.VARCHAR, max_length=128)
schema.add_field("text", DataType.VARCHAR, max_length=8192)
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=DIM)
schema.add_field("tenant_id", DataType.VARCHAR, max_length=64)
schema.add_field("access_level", DataType.INT16)
schema.add_field("version", DataType.INT32)
schema.add_field("status", DataType.VARCHAR, max_length=16)
schema.add_field("effective_at", DataType.INT64)
schema.add_field("expires_at", DataType.INT64)
schema.add_field("source_uri", DataType.VARCHAR, max_length=512)

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="embedding",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)
for field in ["tenant_id", "status", "effective_at", "expires_at"]:
    index_params.add_index(field_name=field, index_type="AUTOINDEX")

client.create_collection(
    collection_name=COLLECTION,
    schema=schema,
    index_params=index_params,
)

C02文本变向量并写入 Milvus

下面用开源 BAAI/bge-m3 演示。第一次会下载模型，CPU 能运行但可能较慢。生产可以替换为托管 API，Milvus 写入逻辑不变。

from sentence_transformers import SentenceTransformer

embedder = SentenceTransformer("BAAI/bge-m3")

chunks = [
    {
        "chunk_id": "refund-v4-p2-c1",
        "document_id": "refund-policy",
        "text": "退款审核通过后，款项通常在三个工作日内原路退回。",
        "tenant_id": "company-a",
        "access_level": 1,
        "version": 4,
        "status": "active",
        "effective_at": 1788192000,
        "expires_at": 4102444800,
        "source_uri": "s3://policies/refund-v4.pdf",
    },
    {
        "chunk_id": "refund-v4-p3-c1",
        "document_id": "refund-policy",
        "text": "生鲜商品拆封后不支持无理由退款。",
        "tenant_id": "company-a",
        "access_level": 1,
        "version": 4,
        "status": "active",
        "effective_at": 1788192000,
        "expires_at": 4102444800,
        "source_uri": "s3://policies/refund-v4.pdf",
    },
]

vectors = embedder.encode(
    [item["text"] for item in chunks],
    normalize_embeddings=True,
).tolist()

assert len(vectors[0]) == DIM, "模型输出维度与 Schema 不一致"
for item, vector in zip(chunks, vectors):
    item["embedding"] = vector

result = client.insert(collection_name=COLLECTION, data=chunks)
print(result)

在线与离线：文档在发布知识库时批量向量化；用户每次提问只向量化问题，不会重新处理全库。

C03带租户、权限和版本过滤搜索

import time

question = "退款审核通过了，钱什么时候回来？"
query_vector = embedder.encode(
    [question],
    normalize_embeddings=True,
)[0].tolist()

now_ts = int(time.time())
filter_expr = (
    'tenant_id == "company-a" '
    'and access_level <= 1 '
    'and status == "active" '
    f'and effective_at <= {now_ts} '
    f'and expires_at > {now_ts}'
)

hits = client.search(
    collection_name=COLLECTION,
    data=[query_vector],
    anns_field="embedding",
    filter=filter_expr,
    limit=5,
    output_fields=[
        "chunk_id", "document_id", "text",
        "version", "source_uri"
    ],
)

for hit in hits[0]:
    print(hit["distance"], hit["entity"]["text"])

hits[0] 是第一个查询的结果列表。每个结果含主键、距离/相似度和指定字段。这只是候选证据，后面还要去重、Rerank、冲突检查、引用和必要时拒答。

权限过滤由登录系统产生：不能让 LLM 猜 tenant_id，也不能信任浏览器随便提交的 tenant_id。

C04向量索引选型

数据库加速结构 索引不是数据本身，而是帮助 Milvus 少比较一些向量。速度、内存、构建时间和召回率需要权衡。

不要照抄参数：用固定真实查询集比较 Recall@k、P95、QPS、建索引时间、内存和磁盘。

C05更新政策如何避免新旧混淆

小规模可用 upsert 更新同一主键；需要审计的政策更适合保留版本记录，通过状态切换控制可见性。大量数据重建应研究批量导入。

P03生产环境保障

P04常见故障从哪里查

排错顺序：先服务健康，再确认数据存在，再检查过滤，最后才调相似度和索引。不要一错就换模型。