agno 多租户知识库怎么开启 isolate_vector_search 隔离各租户的向量数据?
agno 多租户知识库怎么开启 isolate_vector_search 隔离各租户的向量数据?
在多租户应用里,不同用户或部门往往共享同一个向量数据库集合,但彼此只能检索自己的文档。agno 的 Knowledge 提供 isolate_vector_search 参数来完成这件事:多个 Knowledge 实例共用同一个向量库时,开启该参数后每个实例只检索带有自己 name 标记的向量,避免租户 A 检索到租户 B 的内容。本文以仓库中的 03_multi_tenant.py 为例,给出完整配置、运行和验证方式。适用前提:本地已安装 agno 的 Python 环境,能启动一个 Qdrant 实例(默认 http://localhost:6333),并有 OpenAI API Key(示例中同时用于 OpenAIEmbedder 和 OpenAIResponses 模型)。
isolate_vector_search 的行为
根据 knowledge.py 中 isolate_vector_search 字段旁的注释与实现,该参数的行为如下:
isolate_vector_search=False(默认):检索该向量库中的全部向量。isolate_vector_search=True:只检索带有本实例name标记的向量。
实现机制分两步:写入时,agno 会在插入文档的 metadata 中写入 linked_to 字段,值为该 Knowledge 实例的 name(见 knowledge.py 中 _prepare_documents_for_insert,document.meta_data["linked_to"] = self.name or "");检索时,agno 自动把 {"linked_to": self.name} 合并进搜索过滤器(_inject_instance_scope_filter),并且会与你传入的 dict 过滤器或 FilterExpr 列表合并,而不是覆盖。
两点必须注意:
name是生效前提。_inject_instance_scope_filter的判空逻辑是if not (self.isolate_vector_search and self.name): return search_filters,即实例没有设置name时即使开启了isolate_vector_search也不会注入过滤条件,隔离不生效。单元测试test_search_without_name_no_filter明确验证了这一点。- 存量数据必须重新索引。开启隔离后,没有
linked_to元数据的旧数据检索不到,需要重新插入以补上该元数据。这是 knowledge.py 注释和 cookbook 文档字符串都明确写出的限制,默认值保持False也是出于对存量数据的向后兼容。
准备环境
按 cookbook/07_knowledge/README.md 的说明,先启动 Qdrant:
./cookbook/scripts/run_qdrant.sh
再设置示例用到的 OpenAI Key(示例中的 embedder 为 text-embedding-3-small,模型为 OpenAIResponses,两者都依赖这个 Key):
export OPENAI_API_KEY=your-key
配置两个租户共享同一向量集合
下面是最短可行主路径,代码来自 03_multi_tenant.py。两个 Knowledge 实例共享同一个 Qdrant 集合 multi_tenant,各自设置不同的 name 并开启 isolate_vector_search=True:
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.qdrant import Qdrant
from agno.vectordb.search import SearchType
qdrant_url = "http://localhost:6333"
# 两个 Knowledge 实例共享同一个向量集合
vector_db = Qdrant(
collection="multi_tenant",
url=qdrant_url,
search_type=SearchType.hybrid,
embedder=OpenAIEmbedder(id="text-embedding-3-small"),
)
# 租户 A:只能检索到自己的数据
tenant_a_knowledge = Knowledge(
name="Tenant A",
vector_db=vector_db,
isolate_vector_search=True,
)
# 租户 B:只能检索到自己的数据
tenant_b_knowledge = Knowledge(
name="Tenant B",
vector_db=vector_db,
isolate_vector_search=True,
)
配置要点:
name必须为每个租户设置且互相不同,它是linked_to元数据的取值,也是检索过滤的键值;vector_db传同一个对象(同一集合、同一 embedder),隔离完全靠linked_to元数据区分;- 如果你的业务里已经传了 dict 或
FilterExpr过滤器,linked_to过滤会自动合并进去,不需要手动拼接。
再为每个租户挂上独立的 Agent,开启 search_knowledge=True 让 Agent 通过工具检索该租户的 Knowledge:
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
agent_a = Agent(
model=OpenAIResponses(id="gpt-5.2"),
knowledge=tenant_a_knowledge,
search_knowledge=True,
markdown=True,
)
agent_b = Agent(
model=OpenAIResponses(id="gpt-5.2"),
knowledge=tenant_b_knowledge,
search_knowledge=True,
markdown=True,
)
运行并验证隔离效果
cookbook 的验证方式是:向两个租户各插入一条互不相同的内容,然后分别提问,确认每个 Agent 只依据自己那份内容作答。插入与提问部分如下(同样来自 03_multi_tenant.py):
import asyncio
async def main():
# 各租户插入不同内容
await tenant_a_knowledge.ainsert(
name="Tenant A Docs",
text_content="Tenant A uses PostgreSQL for their primary database.",
)
await tenant_b_knowledge.ainsert(
name="Tenant B Docs",
text_content="Tenant B runs their workloads on AWS with DynamoDB.",
)
print("\n" + "=" * 60)
print("TENANT A: Only sees its own data")
print("=" * 60 + "\n")
agent_a.print_response("What database do we use?", stream=True)
print("\n" + "=" * 60)
print("TENANT B: Only sees its own data")
print("=" * 60 + "\n")
agent_b.print_response("What cloud provider do we use?", stream=True)
asyncio.run(main())
完整脚本可直接运行(以 README 给出的 demo 虚拟环境为例):
.venvs/demo/bin/python cookbook/07_knowledge/03_production/03_multi_tenant.py
判断隔离是否生效的标准:agent_a 的回答只反映 "PostgreSQL" 这一份内容,agent_b 的回答只反映 "AWS / DynamoDB" 这一份内容——即各自检索时 linked_to 过滤器把另一租户的向量排除在结果之外。如果想直接确认过滤器,也可以脱离 Agent 调用 tenant_a_knowledge.search("What database do we use?"),单元测试 显示此时传给向量库的过滤器为 {"linked_to": "Test KB"}(Test KB 为实例名),未开启隔离时过滤器为 None。
边界与限制
- 存量数据不受保护:开启
isolate_vector_search=True后,此前插入、没有linked_to元数据的向量检索不到,必须重新索引。若你的集合已有数据,先完成重索引再切换,否则该租户会查不到旧文档。 - 未设置
name时隔离静默失效:不会报错,只是不注入linked_to过滤,等于回到全量检索。为每个租户显式设置name是必做步骤。 - 同租户多实例:
linked_to取的是实例name。同一租户下的多个Knowledge实例若共享数据,应使用相同name;不同租户必须使用不同name。 - 除
linked_to外的普通元数据检索(dict 过滤器与FilterExpr)不受影响,参考 04_filtering.py,可与isolate_vector_search叠加使用。
如果后续还需要按用户维度进一步收窄检索范围(例如同一租户内的 user_id 隔离),agno 的 search/asearch 支持单独的 user_id 参数转发给向量库,可与本场景的租户级隔离配合使用。