Agno 知识库每用户隔离实战:基于 17 个向量数据库后端的用户级 RAG 数据边界实现与测试验证

原创2026-09-09 19:40:142,307 阅读
文章标签:人工智能AI AgentAgent 框架多智能体Agent 工作流工具调用RAGAI 评测后端MCP 服务可观测性

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):

  1. 设置 OPENAI_API_KEY(示例使用 OpenAIResponses 模型);
  2. LanceDB、Chroma、Qdrant 为嵌入式运行,无需额外启动服务;
  3. 服务型后端需先启动对应脚本,仓库已提供:./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;
  4. Milvus 需要独立服务端(bash standalone_embed.sh start),因为 Milvus Lite 会在检索读路径上丢弃标量字段,导致内容返回为空;
  5. MongoDB 需要 Atlas-Local 容器(docker run -d -p 27017:27017 mongodb/mongodb-atlas-local:latest),普通 MongoDB 没有 $vectorSearch;
  6. 云后端需要各自凭据: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 个后端的实测中可以提炼出几条可复用的工程结论:

  1. 共享语义要显式建模:无论用 NULL、"" 还是 __shared__ 哨兵,关键是所有后端都能区分"共享"与"某用户的私有"两种状态;Milvus/Redis/Valkey/Cassandra/Couchbase 这类要求字段存在的系统,哨兵是唯一选择。
  2. 静默降级比报错更危险:user_id 一旦丢失就变成 None(管理员视图),系统不抛异常。生产代码必须对检索结果做断言或校验,而不是指望错误暴露泄漏。
  3. 验证对象应是 references 而非模型输出:模型措辞不可作为隔离是否成立的证据,只有检索实际返回的文档集合才算数。
  4. 注意后端的特殊限制:Milvus Lite 丢标量字段、普通 MongoDB 无 $vectorSearch、普通 valkey/valkey 无搜索模块、Redis 与 Valkey 同占 6379 端口且过滤行为不互通——这些都是在 TEST_LOG 中实际踩过并记录在案的坑。
  5. 异步索引/最终一致性需要显式等待: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),向量库层负责把语义翻译成每个数据库自己的过滤语法。

登录后查看全文
agno