Agno RAG 知识管线与 Agentic 过滤

Agno RAG 知识管线与 Agentic 过滤

学习目标

本章将分析 Agno 的知识库/RAG 系统：

• KnowledgeProtocol 抽象与可插拔知识源
• 完整 RAG 管线：Loader → Chunking → Embedder → Reranker → VectorDB
• Agentic RAG：让 Agent 自主选择知识过滤器
• 自定义检索函数替换默认搜索

前置知识

建议先阅读：

• 记忆系统设计 — RAG 管线 — 检索增强生成的通用原理

下文假设你已理解上述概念，直接聚焦 Agno 的具体实现。

---

项目实践

KnowledgeProtocol 抽象

Agno 的知识系统围绕 KnowledgeProtocol 构建：

# 伪代码：KnowledgeProtocol
class KnowledgeProtocol(Protocol):
    def load(self, ...) -> None: ...
    def search(self, query: str, num_documents: Optional[int] = None, **filters) -> List[Document]: ...
    def get_references(self, query: str, ...) -> str: ...

核心设计：知识检索结果以 JSON 或 YAML 格式注入用户提示（references_format: Literal["json", "yaml"] = "json"），而非直接插入系统提示。这使得 Agent 可以结构化地理解和引用知识。

完整 RAG 管线

Agno 的 RAG 管线包含以下组件：

组件	源码位置	说明
Loader	knowledge/loaders/	从文件、URL、数据库等加载原始内容
Chunking	knowledge/chunking/	将长文档分块（固定大小、语义分块等）
Embedder	knowledge/embedder/	将文本块转为向量（FastEmbed、OpenAI、Cohere 等）
Reranker	knowledge/reranker/	对初检结果重排，提高相关性
VectorDB	vectordb/	15+ 向量数据库后端（pgvector、Qdrant、Pinecone 等）

Agentic RAG：Agent 自主过滤

Agno 支持让 Agent 自己选择知识过滤器：

# 伪代码：Agentic RAG
agent = Agent(
    model=OpenAIResponses(id="gpt-4o"),
    knowledge=my_knowledge,
    knowledge_filters={"category": ["engineering", "docs"]},  # 预定义过滤器
    enable_agentic_knowledge_filters=True,  # 让 Agent 自己选过滤器
    add_knowledge_to_context=True,  # 将检索结果注入上下文
)

当 enable_agentic_knowledge_filters=True 时，Agent 在运行时可以根据当前对话自主调整过滤条件，而不是依赖预设的固定过滤器。

自定义检索函数

可以完全替换默认的搜索逻辑：

# 伪代码：自定义检索函数
def custom_knowledge_retriever(agent: Agent, query: str, num_documents: Optional[int], **kwargs):
    # 自定义检索逻辑
    # 可以是外部 API 调用、缓存查询、启发式规则等
    return [{"content": "...", "source": "..."}]

agent = Agent(
    knowledge=my_knowledge,
    knowledge_retriever=custom_knowledge_retriever,  # 替换默认搜索
)

Agent 内置知识工具

# 伪代码：Agent 知识工具
agent = Agent(
    search_knowledge=True,           # 添加 search_knowledge 工具
    update_knowledge=False,          # 不添加 update_knowledge 工具
    add_search_knowledge_instructions=True,  # 在系统提示中添加使用指南
)

• search_knowledge=True：向 Agent 暴露一个搜索工具，Agent 可以自主查询知识库
• update_knowledge=False：默认不暴露更新工具（防止 Agent 误修改知识库）
• add_search_knowledge_instructions：在系统提示中说明如何使用知识工具

问题与规避

1. 知识库注入的上下文膨胀

将检索结果注入上下文时，可能占用大量 token。

规避：

• 使用 num_documents 限制返回文档数
• 使用 Reranker 提高相关性，减少无用文档
• references_format="yaml" 可能比 JSON 更节省 token（取决于内容）

2. 知识更新的权限控制

如果 Agent 有 update_knowledge 工具，可能误修改或污染知识库。

规避：默认 update_knowledge=False。生产环境中如需更新，建议通过审批流程（使用 @approval decorator）控制写入。

3. 向量数据库选型困惑

15+ 向量数据库后端选择困难。

规避：

• 开发环境：pgvector（与 PostgreSQL 共用）
• 生产环境：Qdrant / Pinecone（托管服务）
• 本地/离线：Chroma（轻量嵌入式）

设计取舍

为什么将知识检索结果注入用户提示而非系统提示？

优势：知识检索结果是针对当前查询的，放在用户提示中更符合语义（“基于以下知识回答用户问题”） 代价：系统提示的缓存边界不受影响（知识变化不需要重新编译系统提示）

为什么默认不暴露 update_knowledge？

优势：防止 Agent 污染知识库——知识更新通常需要人工审核 替代方案：默认暴露，由 Agent 自主决定——灵活性更高但风险更大

参考来源

• Agno knowledge/ 源码
• Agno vectordb/ 源码