给智能体接一个本地知识检索工具，可以先用 Milvus Lite 跑通“存向量 → 按条件检索 → 返回原文和编号”。这一步只负责取资料，生成回答仍由模型完成。本文先给出不需要 API 密钥的 Python 演示，验证数据库调用和过滤，再说明接入真实嵌入模型时要替换哪些部分。
示例中的文本和四维向量均为人工构造，不是实际嵌入模型输出，也不是语义检索效果测试。接口依据为 2026 年 10 月 1 日读取的官方项目资料；本文未在读者机器上运行 Milvus，不能据此承诺特定平台的安装或延迟表现。
准备一个独立的本地演示环境
Milvus Lite 官方项目说明将它定位为本地开发、原型和小规模应用。当前项目要求 Python 3.10 或更新版本；macOS、Linux、Windows 的可安装性还取决于 faiss-cpu、pyarrow 等依赖是否有兼容包。不要把旧文章中的平台限制直接套到当前版本。
下面的示例固定使用 pymilvus 3.0.2、milvus-lite 3.2.1。演示代码在 Windows、Python 3.11.15 的独立环境验证了创建、关闭后重开和检索；这只验证小规模接口，不代表语义效果或性能测评。Windows 请使用仅含 ASCII 字符的目录路径，避免当前依赖写索引时遇到中文路径问题。Windows 激活命令与 Linux/macOS 不同，选适合自己系统的一条执行：
python -m venv .venv
# Windows PowerShell：.\.venv\Scripts\Activate.ps1
# Linux/macOS：source .venv/bin/activate
python -m pip install "pymilvus[milvus-lite]==3.0.2" "milvus-lite==3.2.1"
python -m pip show pymilvus milvus-lite保存两项包版本及 Python 版本，后续排错时一并提供。官方说明提醒，新版纯 Python 存储引擎与原版 Milvus Lite 的数据库格式不兼容；旧数据库应在可打开它的环境中导出后重新导入。下面使用新建的 demo-agent.db，不连接已有业务库。
创建集合、插入片段并执行一次查询
把下面内容保存为 demo.py，再运行 python demo.py。代码只在集合不存在时插入初始数据，重复执行不会重新插入相同 ID。
import os
from pathlib import Path
from pymilvus import MilvusClient
db_path = Path("./demo-agent.db").resolve()
if os.name == "nt" and not str(db_path).isascii():
raise ValueError("请在仅含 ASCII 字符的目录运行本演示")
client = MilvusClient(str(db_path))
name = "agent_demo_docs"
if not client.has_collection(collection_name=name):
client.create_collection(
collection_name=name, dimension=4, metric_type="COSINE"
)
client.insert(collection_name=name, data=[
{"id": 1, "vector": [1.0, 0.0, 0.0, 0.0],
"text": "示例手册：设备 A 保修期为 12 个月。", "scope": "public"},
{"id": 2, "vector": [0.8, 0.2, 0.0, 0.0],
"text": "示例手册：设备 A 的包装内有一条充电线。", "scope": "public"},
{"id": 3, "vector": [1.0, 0.0, 0.0, 0.0],
"text": "内部演示片段，不应出现在公开检索中。", "scope": "internal"},
])
client.load_collection(collection_name=name)
def retrieve_demo_snippets(query_vector):
"""返回公开演示资料；输入为同一向量空间中的四维查询向量。"""
if len(query_vector) != 4:
raise ValueError("演示集合只接受四维向量")
batches = client.search(
collection_name=name,
data=[query_vector],
filter='scope == "public"',
limit=2,
output_fields=["text", "scope"],
)
return [
{"source_id": hit["id"], "text": hit["entity"]["text"],
"scope": hit["entity"]["scope"], "score": hit["distance"]}
for hit in batches[0]
]
snippets = retrieve_demo_snippets([1.0, 0.0, 0.0, 0.0])
print(snippets)
assert snippets and snippets[0]["source_id"] == 1
assert all(s["scope"] == "public" for s in snippets)
assert all(s["source_id"] != 3 for s in snippets)
client.close()官方 MilvusClient 实现可核对 create_collection 的 dimension、metric_type，以及 search 的 filter、limit、output_fields 参数。这里显式选择 COSINE；返回键虽然叫 distance，不能只凭键名判断越小越好，必须结合所选度量解释。
怎样判断这一步跑通了
输出应包含原文、source_id 和 scope；在这组人工向量中，ID 1 与查询方向完全相同，ID 2 与其相近，ID 3 被公开范围条件排除。三个断言分别检查结果存在、来源排序和过滤。若断言失败，先检查是否复用了此前改动过的演示库、集合度量及输入数据，不能继续把错误结果交给回答模型。
重开本地库后，已有集合可能处于 released 状态，所以代码在创建条件之外显式调用 load_collection；每次执行先加载再检索。如果遇到“call load() before search/get/query”，先核对这一步，不重新插入同一份数据。
本演示证明的是接口数据流和限定范围的检索调用，不能证明它理解“保修多久”。把“设备 A 保修多久”输入 Python 函数也不会自动变成向量，必须加入嵌入步骤。
接入真实智能体时，保留接口，替换人工向量
- 选择一个可用的文本嵌入模型，用它为全部片段生成文档向量。记录模型名、输出维度及分段版本；新集合的 dimension 与输出长度一致。
- 检索工具接收自然语言 query，在应用内部生成查询向量，然后调用 search。不要让回答模型凭空填写向量数值，也不要混用另一模型生成的查询向量。
- 工具返回片段文本、来源 ID 和必要版本信息。回答提示词要求据这些片段作答，引用 source_id；没有足够依据时说明无法确认。
- 访问范围由经过认证的应用上下文决定。演示固定 public 只用于公开资料，不能让模型或用户自由修改过滤表达式来扩大权限。
先用一组已知答案的问题检查是否命中正确原文，再测没有依据的问题；数据库返回 top-k 只说明拿到了候选，不能证明答案有依据。调用日志需能对应 query、返回 source_id 和最终引用，才能分清检索失败与生成失败。
常见失败与部署边界
- 安装依赖失败：核对 Python、系统架构和依赖包是否提供兼容 wheel；先在新环境安装，提供完整错误，不靠反复升级旧环境碰运气。
- Windows 报 FAISS could not open … for writing：本地验证在含中文路径加载索引时遇到该错误，改用 ASCII 路径后通过。先检查完整数据库路径、目录权限和索引目录是否存在；不要把“路径无法写入”误当作集合数据丢失，也不要为排错删除原业务库。
- 向量维度不一致：检查集合 dimension、文档向量和查询向量三者；改模型或维度时建立新集合并重新嵌入，不截断旧向量后混存。
- 旧数据库打不开：先确认文件由哪代引擎生成，保留原文件，在对应旧环境导出；不要把格式不兼容误判为需要删除原始资料。
- 多人并发写入：官方说明当前 Lite 单个 data_dir 由单进程占用，同集合写入应串行；它也没有完整认证、RBAC 或 TLS。需要网络服务、多租户和生产运维时，应评估 Standalone、Distributed 或托管服务。
这次可以先完成一个具体动作：在新目录运行演示，保存包版本、三个断言和返回原文。通过后才接入真实嵌入模型和回答模型，避免把安装、向量生成、检索和回答四类问题混在一起排查。
Ai菜鸟网。发布者：AI小管家，转载请注明出处：https://www.alyyhw.com/30264.html
