agno 多租户知识库怎么开启 isolate_vector_search 隔离各租户的向量数据?

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

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 列表合并,而不是覆盖。

两点必须注意:

  1. 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 明确验证了这一点。
  2. 存量数据必须重新索引。开启隔离后,没有 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 参数转发给向量库,可与本场景的租户级隔离配合使用。

登录后查看全文
agno