Agno 知识库每用户隔离实战:基于 17 个向量数据库后端的用户级 RAG 数据边界实现与测试验证
Agno 知识库每用户隔离实战:基于 17 个向量数据库后端的用户级 RAG 数据边界实现与测试验证
在 Agno 中,一个知识库可以被多个用户共享,同时为每个用户保留严格的私有视图:文档写入时携带 user_id 即归属该用户,不携带 user_id 即成为全量共享内容,检索时通过 Knowledge.asearch(user_id=...) 限定数据边界。本文以 cookbook/07_knowledge/04_advanced/07_per_user_isolation 目录下的 17 个示例与 TEST_LOG.md 的实测记录为骨架,讲解每用户隔离的设计语义、各后端不同的隔离原语(列过滤、集合拆分、哨兵值等)、源码级实现机制,以及可复现的验证方法与测试结论,帮助你为多租户 RAG 应用建立可靠的数据边界。
隔离模型:一个知识库,三种可见性
整个演示围绕一个固定的业务场景展开:Alice 与 Bob 各上传一份私有薪资文档,第三方上传的节假日文档不指定所有者因而全员共享,随后验证三类调用者的检索结果。
| 角色 | 检索时传入的 user_id |
可见内容 |
|---|---|---|
| Alice | "alice" |
Alice 的私有文档 + 共享文档(2 条结果) |
| Bob | "bob" |
Bob 的私有文档 + 共享文档(2 条结果) |
| 管理员 | None |
全部文档(3 条结果,admin view) |
这一语义在 README.md 中有明确说明:文档上传时带 user_id 仅该用户可见,不带的与所有人共享,而 user_id=None 会丢弃作用域,等于管理员视角。关键在于"丢弃 user_id 变成 None"是一个静默行为——它不会报错,而是直接退化为管理员视图,返回所有用户的文档。这正是所有示例在末尾都用断言(assert)验证隔离而非依赖异常的原因:作用域一旦在调用链中丢失,系统不会主动告警,只有检查检索结果才能发现泄漏。
核心 API:user_id 如何贯穿写入与检索
隔离能力由 Agno 知识库层的 user_id 参数贯穿全程。在 libs/agno/agno/knowledge/knowledge.py 中,ainsert 的文档字符串明确写有:user_id 是"Owner of this content. None writes to the shared bucket, which everyone [sees]"(该内容的所有者,None 写入共享桶,所有人可见);而 asearch 中的 user_id 则被"forwarded to vector_db.search()",None 表示搜索全部。
写入侧,三种插入方式统一支持所有者标注:
knowledge.ainsert(name=..., text_content=..., user_id="alice"):单文档插入,指定所有者;knowledge.ainsert_many([...], user_id="bob"):批量插入,调用级统一指定所有者,也支持逐项覆盖;- 省略
user_id:写入共享桶(shared bucket)。
检索侧,asearch(query=..., user_id="alice") 会把作用域原样转交给底层 vector_db.search(),由各向量数据库适配器翻译成自己的过滤语法。从源码看,Knowledge 层还有一道 strict_user_id_kwarg 防线(见 knowledge.py 中 asearch 的实现),用于校验 user_id 确实被传递给了向量库而非中途丢失。
Agent 场景中,user_id 同样挂在 Agent(user_id="alice", ...) 上,与 knowledge=knowledge、search_knowledge=True 组合使用。当 Agent 回答问题时,所有者信息需要从运行上下文一路传递到向量库检索,这正是"handoff"环节最容易出问题的地方。
五种隔离原语:17 个后端如何落地"我的 + 共享"边界
不同向量数据库表达"所属用户或共享"这一条件的能力各不相同。每个示例文件都选用该后端最自然的机制来实现,大致可分为五类:
1. 可空列 + OR 条件(关系型)
PgVector 与 SingleStore 使用可空的 user_id 列,检索条件为 WHERE user_id = X OR user_id IS NULL,共享文档的 user_id 列保持 NULL。pgvector_db.py 中即如此实现,且建表时对 user_id 列建立索引(见源码 libs/agno/agno/vectordb/pgvector/pgvector.py 中 Column("user_id", String, nullable=True) 与 Index(f"idx_{self.table_name}_user_id", ...) 的定义)。需要注意的是,隔离是基于 v3 表结构的:源码中 _require_owner_column 会在表不存在 user_id 列且传入非空 user_id 时明确报错,要求先迁移旧表。
2. 列/字段预过滤(列式与文档数据库)
LanceDB 使用 user_id 列配合 .where("user_id = X OR user_id IS NULL", prefilter=True),先过滤再做 top-K 相似度排序;ClickHouse 因列不可空,改用非空 String 列加 "" 空串哨兵;MongoDB 在 $vectorSearch 之前先执行 $match {$in: [X, null]};OpenSearch 用 keyword 字段的 term OR must_not exists 表达同一含义。
3. 元数据过滤(向量原生与云服务)
Pinecone 在向量 metadata 中保存 user_id,过滤条件为 $or [{$eq: X}, {$exists: false}];Upstash 使用 user_id = X OR HAS NOT FIELD user_id;Qdrant 使用索引化的 payload 字段,以 should 匹配加 is-empty 表达。
4. 哨兵值(要求字段非空的系统)
Milvus、Cassandra、Redis、Valkey、Couchbase 采用 __shared__ 哨兵:系统要求字段必须存在时,共享文档写入 __shared__,检索匹配"调用者 OR 哨兵"。milvus_db.py 中明确说明 Milvus 的 user_id 字段非空,因此共享块携带 __shared__ 哨兵;Redis 与 Valkey 则将所有者存为 hash 的 user_id TAG 字段,在 FT.SEARCH 内部完成过滤。
5. 集合/命名空间拆分
Chroma 不给文档打 owner 标签,而是为每个用户建立独立集合({base}__{user_id}),基础集合充当共享桶,检索时查询调用者集合加基础集合并按距离合并结果。SurrealDB 走专用绑定:user_id 字段通过 $scope_user_id bind 注入查询。
完整对应关系如下表(来自 README.md):
| 示例文件 | 隔离原语 |
|---|---|
| pgvector_db.py | 可空 user_id 列,WHERE user_id = X OR user_id IS NULL |
| lance_db.py | user_id 列,.where("user_id = X OR user_id IS NULL", prefilter=True) |
| chroma_db.py | 每用户一个集合({base}__{user_id}),基础集合 = 共享桶 |
| qdrant_db.py | 索引化 user_id payload 字段,should 匹配 + is-empty |
| milvus_db.py | user_id 标量字段,__shared__ 哨兵 |
| mongo_db.py | 顶层 user_id 字段,$vectorSearch 前 $match {$in: [X, null]} |
| weaviate_db.py | user_id text 属性,where OR is_none |
| opensearch_db.py | user_id keyword 字段,term OR must_not exists |
| redis_db.py | user_id TAG 字段,__shared__ 哨兵标签 |
| valkey_db.py | user_id TAG 字段,__shared__ 哨兵标签 |
| clickhouse_db.py | 非空 String 列,"" 哨兵表示共享 |
| cassandra_db.py | user_id 元数据,__shared__ 哨兵 |
| couchbase_db.py | keyword 索引的 FTS user_id 字段,__shared__ 哨兵 |
| singlestore_db.py | 可空 user_id 列,WHERE user_id = X OR user_id IS NULL |
| surreal_db.py | user_id 字段,专用 $scope_user_id bind |
| pinecone_db.py | 向量 metadata 中的 user_id,$or [{$eq: X}, {$exists: false}] 过滤 |
| upstash_db.py | metadata 中的 user_id,user_id = X OR HAS NOT FIELD user_id |
端到端示例:一次完整的隔离验证
以 pgvector_db.py 为例,整个验证流程分为四步,其余 16 个示例遵循完全相同的结构,仅替换向量库适配器。
第一步:准备数据。 固定三份文本——ALICE_SALARY($180,000)、BOB_SALARY($215,000)与 HOLIDAYS(共享节假日),并声明连接参数:
db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
TABLE_NAME = "per_user_isolation_demo"
vector_db = PgVector(table_name=TABLE_NAME, db_url=db_url)
# 每次启动清空重建,确保表带有 user_id 列:
# 对隔离前遗留的旧表做作用域读取会直接报错,
# Knowledge.search 会把它转成空结果,导致验证失真。
if vector_db.exists():
vector_db.drop()
vector_db.create()
knowledge = Knowledge(
name="per_user_demo",
description="Per-user RAG isolation demo (PgVector)",
vector_db=vector_db,
)
第二步:按所有者写入。 前两份文档指定 user_id,第三份省略即共享:
await knowledge.ainsert(name="alice_salary", text_content=ALICE_SALARY, user_id="alice")
await knowledge.ainsert(name="bob_salary", text_content=BOB_SALARY, user_id="bob")
await knowledge.ainsert(name="company_holidays", text_content=HOLIDAYS) # 无 owner,全员共享
第三步:作用域检索并断言。 对三个角色分别执行 asearch(query="salary", user_id=...),用 in / not in 检查文本内容:
- Alice 的视角必须包含
"180,000"与"January 1",绝不包含"215,000"; - Bob 的视角必须包含
"215,000"与"January 1",绝不包含"180,000"; - 管理员(
user_id=None)必须三者俱全,且必须是任何作用域结果的超集。
第四步:Agent 检索的隔离验证。 这是最容易出问题的环节——所有者信息要从 Agent 运行上下文传递到向量库:
alice_agent = Agent(
name="Alice's Assistant",
model=OpenAIResponses(id="gpt-5.5"),
knowledge=knowledge,
search_knowledge=True,
user_id="alice",
instructions=[
"Answer questions using ONLY the knowledge you can retrieve.",
"If you don't know, say so - do not invent salary figures.",
],
markdown=True,
)
response = await alice_agent.arun("What is Bob's salary?")
# 关键:断言检索结果,而不是模型措辞
retrieved = " ".join(
item["content"]
for ref in (response.references or [])
for item in (ref.references or [])
if isinstance(item, dict) and item.get("content")
)
assert retrieved, "Retrieval returned no documents, so the isolation check below would pass on nothing"
assert "215,000" not in retrieved, (
"Isolation broken: Alice's agent retrieved Bob's salary. The owner was "
"dropped between the run context and the vector DB, so retrieval ran "
"unscoped (user_id=None, the admin view)."
)
这里有两个工程要点值得注意。其一,验证对象是 RunOutput.references(即检索实际返回的文档集合)而非模型生成的散文——模型可能在无证据时自行编造或回避,只有 references 才忠实反映向量库返回了什么;其二,断言空结果也会导致隔离检查"通过",所以先断言 retrieved 非空,再断言其中不含他人内容,两步缺一不可。
环境准备与运行方式
运行任意示例前需要满足前置条件(详见 README.md):
- 设置
OPENAI_API_KEY(示例使用OpenAIResponses模型); - LanceDB、Chroma、Qdrant 为嵌入式运行,无需额外启动服务;
- 服务型后端需先启动对应脚本,仓库已提供:
./cookbook/scripts/run_pgvector.sh、run_weaviate.sh、run_opensearch.sh、run_redis.sh、run_valkey.sh、run_clickhouse.sh、run_cassandra.sh、run_couchbase.sh、run_surrealdb.sh、run_singlestore.sh; - Milvus 需要独立服务端(
bash standalone_embed.sh start),因为 Milvus Lite 会在检索读路径上丢弃标量字段,导致内容返回为空; - MongoDB 需要 Atlas-Local 容器(
docker run -d -p 27017:27017 mongodb/mongodb-atlas-local:latest),普通 MongoDB 没有$vectorSearch; - 云后端需要各自凭据:Pinecone 用
PINECONE_API_KEY,Upstash 用UPSTASH_VECTOR_REST_URL与UPSTASH_VECTOR_REST_TOKEN(1536 维索引),SingleStore 与 Couchbase 使用各自的凭据环境变量。
运行方式为逐个执行(多个示例共享默认端口,禁止并行):
.venvs/demo/bin/python cookbook/07_knowledge/04_advanced/07_per_user_isolation/pgvector_db.py
每个示例在启动时都会 drop 并重建自己的集合/表,因此重复运行是安全的;Chroma 的 drop() 会连带清理所有以该基础名命名的每用户集合。
测试验证:17 个后端全部通过隔离断言
cookbook/07_knowledge/TEST_LOG.md 记录了这套场景在全部 17 个后端上的实测结果,统一结论为:Alice 2 条结果、Bob 2 条、admin 3 条,所有断言通过,Agent 从未说出 Bob 的薪资。各后端的具体运行环境与额外注意点如下:
| 后端 | 运行环境 | 关键注意点 |
|---|---|---|
| PgVector | localhost:5532,可空索引列 | 隔离依赖 v3 表结构,旧表需迁移 |
| LanceDB | 嵌入式 tmp/per_user_isolation_lancedb |
预过滤后 top-K 只对允许的行排序 |
| Chroma | 嵌入式 tmp/per_user_isolation_chromadb |
每用户集合 + 共享基础集合 |
| Qdrant | 嵌入式 | 索引化 payload 字段 + is-empty |
| Milvus | 独立 2.5.4,localhost:19530 | Milvus Lite 不可用,会丢弃标量字段 |
| MongoDB | Atlas Local,$match 先于 $vectorSearch |
索引构建需等 10 秒;普通 mongo:7 会报 no such command: 'createSearchIndexes' |
| Weaviate | localhost:8080,text 属性 | owner 属性随集合创建,无法事后追加 |
| OpenSearch | localhost:9200,keyword 字段 | term OR must_not exists |
| Redis | Redis Stack,TAG 字段 | 需要 RediSearch 模块;同端口换 Valkey 会得到 0 条结果 |
| Valkey | localhost:6379 | 必须用 valkey-bundle 镜像,普通 valkey/valkey 无搜索模块 |
| ClickHouse | localhost:8123,库 ai |
非空列用 "" 哨兵 |
| Cassandra | localhost:9042,keyspace per_user_demo |
嵌入维度固定 1024,__shared__ 哨兵 |
| Couchbase | localhost,FTS 索引 | keyword 映射字段,等待 FTS 索引 3 秒 |
| SingleStore | SINGLESTORE_* 环境变量 |
可空列 + OR 条件 |
| SurrealDB | ws://localhost:8000/rpc,namespace agno |
专用 $scope_user_id bind |
| Pinecone | serverless 索引 | metadata 过滤 + 等待最终一致 5 秒 |
| Upstash | UPSTASH_VECTOR_REST_URL/_TOKEN |
1536 维 cosine 索引;重置后等 2 秒、写入后等 5 秒 |
工程结论与踩坑清单
从 17 个后端的实测中可以提炼出几条可复用的工程结论:
- 共享语义要显式建模:无论用
NULL、""还是__shared__哨兵,关键是所有后端都能区分"共享"与"某用户的私有"两种状态;Milvus/Redis/Valkey/Cassandra/Couchbase 这类要求字段存在的系统,哨兵是唯一选择。 - 静默降级比报错更危险:
user_id一旦丢失就变成None(管理员视图),系统不抛异常。生产代码必须对检索结果做断言或校验,而不是指望错误暴露泄漏。 - 验证对象应是
references而非模型输出:模型措辞不可作为隔离是否成立的证据,只有检索实际返回的文档集合才算数。 - 注意后端的特殊限制:Milvus Lite 丢标量字段、普通 MongoDB 无
$vectorSearch、普通valkey/valkey无搜索模块、Redis 与 Valkey 同占 6379 端口且过滤行为不互通——这些都是在 TEST_LOG 中实际踩过并记录在案的坑。 - 异步索引/最终一致性需要显式等待:MongoDB 等 10 秒、Couchbase 等 3 秒、Pinecone 等 5 秒、Upstash 写入后等 5 秒,都是保证断言可靠性的必要条件。
若想继续深入,可对照 knowledge.py 中 user_id 的传递链路与 pgvector.py 中 _scope_by_user_id(OR (user_id = X, user_id IS NULL) 的 SQLAlchemy 实现)阅读源码,理解作用域在知识库层与向量库层的分工:知识库层负责语义(shared bucket、admin view),向量库层负责把语义翻译成每个数据库自己的过滤语法。