Agno开发教程系列（七）：Agno 与 RAG

思想的光芒2025-12-06 11:05

目录

  1. [RAG 概念与原理](#RAG 概念与原理 "#1-rag-%E6%A6%82%E5%BF%B5%E4%B8%8E%E5%8E%9F%E7%90%86")

    • 1.1 什么是 RAG
    • 1.2 RAG 工作原理
    • 1.3 传统 RAG vs Agentic RAG
    • 1.4 为什么需要 RAG

  2. [Agno 中的 RAG 架构](#Agno 中的 RAG 架构 "#2-agno-%E4%B8%AD%E7%9A%84-rag-%E6%9E%B6%E6%9E%84")

    • 2.1 核心组件概览
    • 2.2 知识流转过程
    • 2.3 Agno 的 RAG 特性

  3. [知识库（Knowledge Base）](#知识库（Knowledge Base） "#3-%E7%9F%A5%E8%AF%86%E5%BA%93knowledge-base")

    • 3.1 创建知识库
    • 3.2 知识库配置
    • 3.3 添加内容
    • 3.4 知识库管理

  4. 向量数据库集成

    • 4.1 支持的向量数据库
    • 4.2 选择合适的向量数据库
    • 4.3 向量数据库配置
    • 4.4 常用向量数据库示例

  5. 文档加载与处理

    • 5.1 文档加载器（Readers）
    • 5.2 支持的文件格式
    • 5.3 文档分块策略
    • 5.4 嵌入器配置

  6. 检索器实现

    • 6.1 内置检索方法
    • 6.2 混合搜索
    • 6.3 重排序（Reranking）
    • 6.4 自定义检索器

  7. [RAG 与 Agent 集成](#RAG 与 Agent 集成 "#7-rag-%E4%B8%8E-agent-%E9%9B%86%E6%88%90")

    • 7.1 基础集成
    • 7.2 Agentic RAG
    • 7.3 传统 RAG
    • 7.4 知识过滤器
    • 7.5 Agent 更新知识库

  8. 实战示例

    • 8.1 基础 RAG 示例
    • 8.2 使用 ChromaDB 的示例
    • 8.3 使用 PgVector 的示例
    • 8.4 自定义检索器示例
    • 8.5 多Agent RAG 协作示例

  9. 高级特性

    • 9.1 异步操作
    • 9.2 知识库动态更新
    • 9.3 元数据过滤
    • 9.4 透明推理

  10. 最佳实践与性能优化

    • 10.1 知识库设计最佳实践
    • 10.2 检索优化
    • 10.3 性能调优
    • 10.4 常见问题与解决方案

  11. 总结

1. RAG 概念与原理

1.1 什么是 RAG

RAG（Retrieval Augmented Generation，检索增强生成） 是一种结合了信息检索和文本生成的技术，它通过在生成回答之前先从外部知识源检索相关信息，来增强大型语言模型（LLM）的能力。

RAG 的核心思想是：让 LLM 不仅依赖其训练数据中的知识，还能够访问和利用外部、最新的信息源。

1.2 RAG 工作原理

RAG 系统的基本工作流程包括以下几个步骤：

markdown 复制代码 
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   用户查询   │────>│  查询嵌入化   │────>│  向量检索   │
└─────────────┘     └──────────────┘     └─────────────┘
                                                │
                                                ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  生成回答   │<────│  LLM 处理    │<────│  相关文档   │
└─────────────┘     └──────────────┘     └─────────────┘

详细步骤：

  1. 文档预处理阶段：

    • 将原始文档分解成较小的文本块（Chunking）
    • 使用嵌入模型将文本块转换为向量
    • 将向量及其元数据存储到向量数据库中

  2. 查询检索阶段：

    • 接收用户查询
    • 将查询转换为向量嵌入
    • 在向量数据库中进行相似度搜索
    • 检索最相关的文档块

  3. 生成回答阶段：

    • 将检索到的文档作为上下文
    • 结合用户查询和检索上下文
    • LLM 生成基于上下文的准确回答

1.3 传统 RAG vs Agentic RAG

传统 RAG

在传统 RAG 中，检索过程是被动的 和固定的：

python 复制代码 
# 传统 RAG 伪代码
def traditional_rag(query):
    # 1. 总是执行检索
    retrieved_docs = search_knowledge_base(query)
    
    # 2. 将检索结果添加到上下文
    context = format_context(retrieved_docs)
    
    # 3. 生成回答
    response = llm.generate(query + context)
    
    return response

特点：

  • 每次查询都会执行检索
  • 检索逻辑固定，不够灵活
  • 无法根据任务复杂度调整检索策略

Agentic RAG（Agno 的实现方式）

Agentic RAG 赋予 Agent 智能决策能力，让 Agent 自主决定：

  • 是否需要检索知识库
  • 何时检索知识库
  • 如何检索（选择检索策略）
  • 是否需要多次检索
python 复制代码 
# Agentic RAG 伪代码
def agentic_rag(query):
    # 1. Agent 分析查询
    if agent.needs_knowledge(query):
        # 2. 智能决定检索策略
        search_strategy = agent.choose_strategy(query)
        
        # 3. 执行检索（可能多次）
        retrieved_docs = agent.search_knowledge(query, strategy)
        
        # 4. 可能结合其他工具
        additional_info = agent.use_other_tools_if_needed()
        
        # 5. 综合生成回答
        response = agent.generate_with_reasoning(
            query, retrieved_docs, additional_info
        )
    else:
        # 直接回答，无需检索
        response = agent.generate(query)
    
    return response

Agentic RAG 的优势：

  • ✅ 智能决策：Agent 自主判断是否需要检索
  • ✅ 动态调整：根据任务复杂度调整检索策略
  • ✅ 多工具协同：可以结合网络搜索、API 调用等其他工具
  • ✅ 透明推理：可以看到 Agent 的思考和决策过程
  • ✅ 更高准确性：通过多轮检索和验证提高答案质量

1.4 为什么需要 RAG

RAG 解决了 LLM 的几个关键问题：

问题 描述 RAG 解决方案
知识过时 LLM 的知识截止于训练时间 检索最新的外部信息
幻觉问题 LLM 可能生成虚假信息 基于真实文档生成回答
缺乏专业知识 通用模型缺少特定领域知识 加载专业领域文档
无法访问私有数据 LLM 无法访问企业内部数据 连接私有知识库
可追溯性差 难以验证答案来源 提供文档引用和来源

2. Agno 中的 RAG 架构

2.1 核心组件概览

Agno 的 RAG 系统由以下核心组件构成：

python 复制代码 
┌─────────────────────────────────────────────────────────┐
│                    Agno RAG 架构                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────┐      ┌────────────┐      ┌───────────┐   │
│  │  Agent   │─────>│ Knowledge  │─────>│  Vector   │   │
│  │          │      │    Base    │      │  Database │   │
│  └──────────┘      └────────────┘      └───────────┘   │
│       │                   │                    │        │
│       │                   │                    │        │
│       ▼                   ▼                    ▼        │
│  ┌──────────┐      ┌────────────┐      ┌───────────┐   │
│  │ Search   │      │  Readers   │      │ Embedder  │   │
│  │ Tools    │      │            │      │           │   │
│  └──────────┘      └────────────┘      └───────────┘   │
│       │                   │                    │        │
│       │                   ▼                    │        │
│       │            ┌────────────┐              │        │
│       │            │  Chunking  │              │        │
│       │            │  Strategy  │              │        │
│       │            └────────────┘              │        │
│       │                   │                    │        │
│       └───────────────────┴────────────────────┘        │
│                           │                             │
│                           ▼                             │
│                    ┌────────────┐                       │
│                    │ Retriever  │                       │
│                    │  (Optional │                       │
│                    │  Reranker) │                       │
│                    └────────────┘                       │
│                                                          │
└─────────────────────────────────────────────────────────┘

各组件说明：

  1. Agent（智能体）：

    • 决策中心，控制何时、如何使用 RAG
    • 可配置为 Agentic RAG 或传统 RAG 模式

  2. Knowledge Base（知识库）：

    • 管理和组织文档内容
    • 连接向量数据库和嵌入器
    • 提供内容加载和检索接口

  3. Vector Database（向量数据库）：

    • 存储文档的向量嵌入
    • 执行相似度搜索
    • 支持混合搜索和元数据过滤

  4. Readers（文档加载器）：

    • 从各种来源加载文档
    • 支持 PDF、网页、CSV、JSON 等格式
    • 处理文档解析和提取

  5. Embedder（嵌入器）：

    • 将文本转换为向量表示
    • 支持 OpenAI、Cohere、本地模型等

  6. Chunking Strategy（分块策略）：

    • 将文档分解为合适的大小
    • 支持固定大小、语义分块、智能分块等

  7. Retriever（检索器）：

    • 执行向量搜索
    • 支持自定义检索逻辑
    • 可选的重排序优化

2.2 知识流转过程

完整的知识流转过程如下：

scss 复制代码 
┌─────────────────┐
│  1. 原始文档    │
│  (PDF/URL/文本) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  2. Reader      │
│  解析和提取     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  3. 文档对象    │
│  (Document)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  4. 分块处理    │
│  (Chunking)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  5. 嵌入转换    │
│  (Embedding)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  6. 向量存储    │
│  (Vector DB)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  7. 检索查询    │
│  (Retrieval)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  8. Agent 生成  │
│  (Generation)   │
└─────────────────┘

2.3 Agno 的 RAG 特性

Agno 提供了丰富的 RAG 特性，使其在众多框架中脱颖而出：

特性 描述 优势
Agentic RAG Agent 智能决策何时检索 更高效、更智能
混合搜索 结合向量搜索和关键词搜索 检索更准确
重排序 对检索结果进行二次排序 提高相关性
20+ 向量数据库 支持主流向量数据库 灵活选择
多种文档格式 PDF、CSV、网页等 覆盖广泛
自定义检索器 完全控制检索逻辑 高度灵活
异步操作 支持异步加载和检索 高性能
元数据过滤 基于元数据筛选文档 精确控制
透明推理 可视化 Agent 思考过程 易于调试
知识动态更新 运行时更新知识库 实时性强

3. 知识库（Knowledge Base）

3.1 创建知识库

在 Agno 中，知识库通过 Knowledge 类来创建和管理。创建知识库的基本步骤：

python 复制代码 
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

# 步骤1：配置向量数据库
vector_db = PgVector(
    table_name="my_knowledge",           # 表名
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",  # 数据库连接
    embedder=OpenAIEmbedder(             # 嵌入器
        id="text-embedding-3-small"
    )
)

# 步骤2：创建知识库实例
knowledge = Knowledge(
    name="My Knowledge Base",            # 知识库名称（可选）
    description="专业领域知识库",        # 描述（可选）
    vector_db=vector_db                  # 绑定向量数据库
)

3.2 知识库配置

知识库支持丰富的配置选项：

python 复制代码 
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.lancedb import LanceDb
from agno.vectordb.search import SearchType
from agno.knowledge.reranker.cohere import CohereReranker

knowledge = Knowledge(
    name="Advanced Knowledge Base",
    description="高级知识库配置示例",

    # 向量数据库配置
    vector_db=LanceDb(
        uri="tmp/lancedb",  # 存储路径
        table_name="advanced_kb",  # 表名
        search_type=SearchType.hybrid,  # 混合搜索
        embedder=CohereEmbedder(  # Cohere 嵌入器
            id="embed-v4.0",
            dimensions=1024
        ),
        reranker=CohereReranker(  # 重排序器
            model="rerank-v3.5"
        )
    )
)

配置参数说明：

参数 类型 说明 默认值
name str 知识库名称 可选
description str 知识库描述 可选
vector_db VectorDb 向量数据库实例 必需

3.3 添加内容

Agno 提供多种方式向知识库添加内容：

方式1：从 URL 添加内容

python 复制代码 
# 同步添加
knowledge.add_content(
    name="Thai Recipes",                     # 内容名称
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",  # 文档 URL
    metadata={"category": "recipes", "cuisine": "thai"}  # 元数据（可选）
)

# 异步添加（推荐用于高并发场景）
import asyncio

async def load_knowledge():
    await knowledge.add_content_async(
        url="https://docs.agno.com/introduction/agents.md"
    )

asyncio.run(load_knowledge())

方式2：从本地路径添加

python 复制代码 
from agno.knowledge.reader.pdf_reader import PDFReader

# 使用 Reader 加载本地文件
knowledge.add_content(
    path="data/documents",                   # 本地文件路径
    reader=PDFReader(                        # 指定 Reader
        chunk=True,                          # 启用分块
        chunk_size=1000                      # 块大小
    )
)

3.4 知识库管理

删除内容

python 复制代码 
# 按名称删除
knowledge.vector_db.delete_by_name("Thai Recipes")

# 按元数据删除
knowledge.vector_db.delete_by_metadata(
    {"category": "recipes"}
)

检查内容是否存在

python 复制代码 
# 检查内容哈希是否存在（避免重复）
exists = knowledge.vector_db.content_hash_exists(content_hash)

知识库过滤

python 复制代码 
from agno.agent import Agent

# 创建带过滤器的 Agent
agent = Agent(
    knowledge=knowledge,
    knowledge_filters={
        "category": "recipes",       # 只检索食谱类文档
        "cuisine": "thai"            # 只检索泰式料理
    }
)

# 动态过滤（让 Agent 自主选择过滤器）
agent = Agent(
    knowledge=knowledge,
    enable_agentic_knowledge_filters=True  # 启用智能过滤
)

4. 向量数据库集成

4.1 支持的向量数据库

Agno 支持 20+ 种向量数据库，包括：

数据库 类型 适用场景
PgVector PostgreSQL 扩展 生产环境、需要 SQL 功能
LanceDB 本地嵌入式 开发测试、快速原型
ChromaDB 本地/云端 开发和生产均可
Pinecone 托管服务 生产环境、无运维需求
Qdrant 本地/云端 高性能需求
Weaviate 本地/云端 复杂查询、GraphQL
Milvus 分布式向量库 大规模生产环境
MongoDB 文档数据库 已有 MongoDB 基础设施
SingleStore 分布式SQL 实时分析
Cassandra 分布式NoSQL 高可用性需求
Couchbase 文档数据库 移动和边缘计算
Clickhouse 列式数据库 分析型应用
Upstash Vector Serverless Serverless 应用
LightRAG 高性能高准确率的开源RAG 对检索精度、性能要求高的场景

4.2 选择合适的向量数据库

根据不同的使用场景，推荐以下选择：

sql 复制代码 
┌─────────────────────────────────────────────────────────┐
│                 向量数据库选择指南                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  开发和测试                                               │
│  ├─ 推荐：LanceDB                                        │
│  ├─ 优势：本地运行、快速启动、无需配置                    │
│  └─ 示例：快速原型、学习实验                              │
│                                                          │
│  生产环境（自托管）                                       │
│  ├─ 推荐：PgVector                                       │
│  ├─ 优势：可靠、可扩展、SQL支持、成熟生态                │
│  └─ 示例：企业级应用、需要 SQL 查询                       │
│                                                          │
│  生产环境（托管服务）                                     │
│  ├─ 推荐：Pinecone                                       │
│  ├─ 优势：完全托管、高可用、自动扩展                     │
│  └─ 示例：SaaS 应用、快速上线                            │
│                                                          │
│  高性能需求                                               │
│  ├─ 推荐：Qdrant                                         │
│  ├─ 优势：速度优化、高级特性、Rust实现                   │
│  └─ 示例：实时搜索、大规模检索                           │
│                                                          │
│  大规模分布式                                             │
│  ├─ 推荐：Milvus                                         │
│  ├─ 优势：分布式架构、水平扩展、高吞吐                   │
│  └─ 示例：海量数据、多租户系统                           │
│                                                          │
│  已有基础设施                                             │
│  ├─ MongoDB → MongoDB Atlas Vector Search               │
│  ├─ PostgreSQL → PgVector                                │
│  └─ 优势：复用现有基础设施、降低运维成本        
│
│  │  高精度、高性能                                         │
│  ├─ 推荐： LightRAG                                      │
│  ├─ 优势： 结合图数据库实现极高的准确率                       │
│  └─ 示例：企业内部文档，法律法规，医疗等行业                   │
└─────────────────────────────────────────────────────────┘

4.3 向量数据库配置

所有向量数据库都遵循一致的配置模式，主要参数包括：

python 复制代码 
# 通用配置参数
vector_db = VectorDatabase(
    collection="collection_name",        # 集合/表名
    embedder=EmbedderInstance,          # 嵌入器
    search_type=SearchType.hybrid,      # 搜索类型
    distance=Distance.COSINE,           # 距离度量
    reranker=RerankerInstance           # 重排序器（可选）
)

核心参数说明：

参数 说明 可选值
collection/table_name 存储容器标识符 字符串
embedder 嵌入生成器 OpenAIEmbedder, CohereEmbedder 等
search_type 搜索类型 vector, keyword, hybrid
distance 距离度量 COSINE, EUCLIDEAN, DOT_PRODUCT
reranker 重排序器 CohereReranker 等（可选）

4.4 常用向量数据库示例

示例1：PgVector（PostgreSQL）

python 复制代码 
from agno.vectordb.pgvector import PgVector
from agno.vectordb.search import SearchType
from agno.embedder.openai import OpenAIEmbedder

# Docker 启动 PostgreSQL with PgVector
"""
docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql/data/pgdata \
  -v pgvolume:/var/lib/postgresql/data \
  -p 5532:5432 \
  --name pgvector \
  agno/pgvector:16
"""

# 配置 PgVector
vector_db = PgVector(
    table_name="recipes",                              # 表名
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",  # 数据库连接
    search_type=SearchType.hybrid,                     # 混合搜索
    embedder=OpenAIEmbedder(
        id="text-embedding-3-small",
        dimensions=1536
    )
)

示例2：ChromaDB（本地持久化）

python 复制代码 
from agno.vectordb.chroma import ChromaDb

# 本地持久化配置
vector_db = ChromaDb(
    collection="my_collection",          # 集合名
    path="tmp/chromadb",                 # 本地存储路径
    persistent_client=True               # 启用持久化
)

示例3：ChromaDB（Chroma Cloud）

python 复制代码 
from chromadb.config import Settings
from agno.vectordb.chroma import ChromaDb

# Chroma Cloud 托管配置
vector_db = ChromaDb(
    collection="vectors",
    settings=Settings(
        chroma_api_impl="chromadb.api.fastapi.FastAPI",
        chroma_server_host="your-tenant-id.api.trychroma.com",
        chroma_server_http_port=443,
        chroma_server_ssl_enabled=True,
        chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider",
        chroma_client_auth_credentials="your-api-key"  # 你的 API 密钥
    )
)

示例4：Weaviate（混合搜索）

python 复制代码 
from agno.vectordb.weaviate import Weaviate, VectorIndex, Distance
from agno.vectordb.search import SearchType

# Weaviate 配置
vector_db = Weaviate(
    collection="recipes",                # 集合名
    search_type=SearchType.hybrid,       # 混合搜索
    vector_index=VectorIndex.HNSW,       # HNSW 索引
    distance=Distance.COSINE,            # 余弦距离
    local=True                           # 本地运行
)

示例5：LanceDB（开发测试）

python 复制代码 
from agno.vectordb.lancedb import LanceDb
from agno.vectordb.search import SearchType

# LanceDB 配置（推荐用于开发）
vector_db = LanceDb(
    uri="tmp/lancedb",                   # 本地存储路径
    table_name="knowledge_table",        # 表名
    search_type=SearchType.hybrid,       # 混合搜索
    embedder=CohereEmbedder(
        id="embed-v4.0",
        dimensions=1024
    )
)

示例6：LightRAG（高性能、高精度）

python 复制代码 
from agno.vectordb.lightrag import LightRag
import os

vector_db = LightRag(
    api_key=os.getenv("LIGHTRAG_API_KEY"),
)

示例7：Qdrant（高性能）

python 复制代码 
from agno.vectordb.qdrant import Qdrant

# Qdrant 本地配置
vector_db = Qdrant(
    collection="thai-recipes",           # 集合名
    url="http://localhost:6333",         # Qdrant 服务地址
    embedder=OpenAIEmbedder(
        id="text-embedding-3-small"
    )
)

# Qdrant Cloud 配置
vector_db = Qdrant(
    collection="thai-recipes",
    url="https://your-cluster.qdrant.io",
    api_key=os.getenv("QDRANT_API_KEY"),
    embedder=OpenAIEmbedder(
        id="text-embedding-3-small"
    )
)

5. 文档加载与处理

5.1 文档加载器（Readers）

Agno 提供了丰富的文档加载器（Readers），用于从各种来源加载和处理文档。

Reader 的作用：

  1. 从原始格式解析内容
  2. 提取有意义的文本和元数据
  3. 将内容结构化为 Document 对象
  4. 应用分块策略

Document 对象结构：

python 复制代码 
{
    "id": "unique_document_id",          # 唯一标识
    "name": "document_name",             # 文档名称
    "content": "extracted text...",      # 提取的文本内容
    "meta_data": {                       # 元数据
        "page_number": 1,
        "url": "https://...",
        "author": "..."
    },
    "size": 1024                         # 文档大小
}

5.2 支持的文件格式

Agno 支持多种文档格式的加载器：

Reader 支持格式 说明
PDFReader PDF 支持加密PDF、图像OCR
PDFImageReader PDF（图像） 专门处理基于图像的PDF
DocxReader DOCX Word 文档
CSVReader CSV 表格数据
JSONReader JSON 结构化数据
TextReader TXT 纯文本文件
MarkdownReader MD Markdown 文档
WebsiteReader 网页 爬取整个网站
WebSearchReader 搜索结果 网络搜索结果
WikipediaReader Wikipedia Wikipedia 文章
YouTubeReader YouTube 视频转录和元数据
ArxivReader arXiv 学术论文
FirecrawlReader 网页 通过Firecrawl API抓取

5.3 文档分块策略

文档分块是 RAG 中的关键步骤，影响检索的精度和上下文的完整性。

分块策略类型

Agno 支持以下分块策略：

python 复制代码 
# 1. 文档分块（尊重文档结构）
from agno.knowledge.chunking.document import DocumentChunking
knowledge.add_content(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
    reader=PDFReader(
        name="Document Chunking Reader",
        chunking_strategy=DocumentChunking(),
    ),
)

# 2. 固定大小分块
from agno.knowledge.chunking.fixed import FixedSizeChunking
knowledge.add_content(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
    reader=PDFReader(
        name="FixedSize Chunking Reader",
        chunking_strategy=FixedSizeChunking(),
    ),
)

# 3. 语义分块（基于语义边界）
from agno.knowledge.chunking.semantic import SemanticChunking
knowledge.add_content(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
    reader=PDFReader(
        name="Semantic Chunking Reader",
        chunking_strategy=SemanticChunking(),
    ),
)

# 4. 智能分块（AI驱动）
from agno.knowledge.chunking.agentic import AgenticChunking
knowledge.add_content(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
    reader=PDFReader(
        name="Agentic Chunking Reader",
        chunking_strategy=AgenticChunking(),
    ),
)

Reader 配置示例

python 复制代码 
from agno.knowledge.reader.pdf_reader import PDFReader
from agno.knowledge.chunking.semantic import SemanticChunking

# PDF Reader 完整配置
pdf_reader = PDFReader(
    # 分块配置
    chunk=True,  # 启用分块
    chunk_size=1000,  # 块大小（字符数）
    chunking_strategy=SemanticChunking(),  # 语义分块

    # PDF 特定配置
    split_on_pages=True,  # 按页分割
    password="optional_password",  # PDF 密码（如果加密）
    read_images=True,  # OCR 读取图像

    # 通用配置
    name="PDF Documents"  # Reader 名称
)

各种 Reader 的详细示例

1. PDFReader（PDF 文档）

python 复制代码 
from agno.knowledge.reader.pdf_reader import PDFReader
from agno.knowledge.knowledge import Knowledge

# 创建 PDF Reader
pdf_reader = PDFReader(
    chunk=True,
    chunk_size=1000,
    split_on_pages=True
)

# 加载 PDF 文档
knowledge = Knowledge(vector_db=vector_db)
knowledge.add_content(
    path="data/documents/report.pdf",
    reader=pdf_reader
)

2. WebsiteReader（网站爬取）

python 复制代码 
from agno.knowledge.reader.website_reader import WebsiteReader

# 创建 Website Reader
website_reader = WebsiteReader(
    max_depth=2,                         # 爬取深度
    max_links=50,                        # 最大链接数
    chunk=True,
    chunk_size=800
)

# 爬取网站
knowledge.add_content(
    url="https://docs.agno.com",
    reader=website_reader
)

3. CSVReader（CSV 文件）

python 复制代码 
from agno.knowledge.reader.csv_reader import CSVReader

# 创建 CSV Reader
csv_reader = CSVReader(
    delimiter=",",                       # 分隔符
    encoding="utf-8",                    # 编码
    chunk=True,
    chunk_size=500
)

# 加载 CSV
knowledge.add_content(
    path="data/products.csv",
    reader=csv_reader
)

4. JSONReader（JSON 文件）

python 复制代码 
from agno.knowledge.reader.json_reader import JSONReader

# 创建 JSON Reader
json_reader = JSONReader(
    chunk=True,
    chunk_size=600
)

# 加载 JSON
knowledge.add_content(
    path="data/config.json",
    reader=json_reader
)

ReaderFactory（智能选择）

Agno 提供 ReaderFactory 根据文件扩展名或 URL 自动选择合适的 Reader：

python 复制代码 
from agno.knowledge.reader.reader_factory import ReaderFactory

# 自动选择 Reader
# 根据文件后缀识别
reader = ReaderFactory.get_reader_for_extension(
    path="document.pdf"          # 自动识别为 PDFReader
)
# 根据URL地址识别
reader = ReaderFactory.get_reader_for_url(
    url="https://example.com"    # 自动识别为 WebsiteReader
)

5.4 嵌入器配置

嵌入器负责将文本转换为向量表示。Agno 支持多种嵌入模型：

OpenAI Embedder

python 复制代码 
from agno.knowledge.embedder.openai import OpenAIEmbedder

# OpenAI 嵌入器
embedder = OpenAIEmbedder(
    id="text-embedding-v4",  # 模型名称 这里我们使用千问的通用文本向量-v4
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DashScope API 地址
    dimensions=1536,  # 向量维度
    api_key=os.getenv("QWEN_API_KEY")  # API 密钥（可选，默认从环境变量读取）
)

Cohere Embedder

python 复制代码 
from agno.embedder.cohere import CohereEmbedder

# Cohere 嵌入器
embedder = CohereEmbedder(
    model="embed-v4.0",                  # 模型名称
    dimensions=1024,                     # 向量维度
    api_key="your_cohere_api_key"        # API 密钥
)

Sentence Transformer（本地模型）

python 复制代码 
from agno.knowledge.embedder.sentence_transformer import SentenceTransformerEmbedder

# 本地 Sentence Transformer
embedder = SentenceTransformerEmbedder(
    model="BAAI/bge-large-en-v1.5",      # Hugging Face 模型
    device="cuda"                        # 设备（cpu/cuda）
)

推荐： 对于 Hugging Face 模型，建议使用 SentenceTransformerEmbedder 而非 HuggingfaceCustomEmbedder，以避免潜在的 HTTP 错误。

Ollama Embedder（本地运行）

python 复制代码 
from agno.knowledge.embedder.ollama import OllamaEmbedder

# Ollama 本地嵌入器
embedder = OllamaEmbedder(
    id="nomic-embed-text",            # Ollama 模型
    host="http://localhost:11434"        # Ollama 服务地址
)

6. 检索器实现

6.1 内置检索方法

Agno 提供了多种内置的检索方法，通过 SearchType 枚举配置：

python 复制代码 
from agno.vectordb.search import SearchType

# 向量搜索（语义相似度）
SearchType.vector

# 关键词搜索（传统全文搜索）
SearchType.keyword

# 混合搜索（结合向量和关键词）
SearchType.hybrid

向量搜索

基于语义相似度的搜索，适合理解语义意图：

python 复制代码 
from agno.vectordb.pgvector import PgVector
from agno.vectordb.search import SearchType

vector_db = PgVector(
    table_name="documents",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    search_type=SearchType.vector        # 纯向量搜索
)

# 执行搜索
results = vector_db.search(
    query="如何制作泰式咖喱?",
    limit=5                              # 返回前5个结果
)

关键词搜索

基于关键词匹配的传统搜索：

python 复制代码 
vector_db = PgVector(
    table_name="documents",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    search_type=SearchType.keyword       # 关键词搜索
)

6.2 混合搜索

混合搜索是 Agno 的一大特色，它结合了向量相似度搜索和关键词搜索的优势。

混合搜索的工作原理：

arduino 复制代码 
┌─────────────────────────────────────────────────────┐
│              混合搜索流程                            │
├─────────────────────────────────────────────────────┤
│                                                      │
│  用户查询："如何制作泰式咖喱"                         │
│       │                                              │
│       ├──────────┬──────────────────┐                │
│       │          │                  │                │
│       ▼          ▼                  ▼                │
│  ┌────────┐ ┌─────────┐      ┌──────────┐           │
│  │ 向量   │ │ 关键词  │      │ 加权     │           │
│  │ 搜索   │ │ 搜索    │      │ 合并     │           │
│  └────┬───┘ └────┬────┘      └────┬─────┘           │
│       │          │                 │                 │
│       │  结果1   │   结果2         │  最终结果        │
│       └──────────┴─────────────────┘                 │
│                                                      │
└─────────────────────────────────────────────────────┘

支持混合搜索的向量数据库：

  • PgVector
  • Pinecone
  • LanceDB
  • Weaviate
  • MongoDB
  • Qdrant
  • Milvus

混合搜索示例

python 复制代码 
from agno.vectordb.lancedb import LanceDb
from agno.vectordb.search import SearchType
from agno.knowledge.embedder.cohere import CohereEmbedder
from agno.knowledge.knowledge import Knowledge

# 配置混合搜索
vector_db = LanceDb(
    uri="tmp/lancedb",
    table_name="hybrid_search_demo",
    search_type=SearchType.hybrid,       # 启用混合搜索
    embedder=CohereEmbedder(
        id="embed-v4.0",
        dimensions=1024
    )
)

# 创建知识库
knowledge = Knowledge(vector_db=vector_db)
knowledge.add_content(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"
)

# 搜索（自动使用混合搜索）
results = vector_db.search(
    query="Massaman curry ingredients",
    limit=10
)

Pinecone 混合搜索（带权重调整）

Pinecone 支持通过 hybrid_alpha 参数调整向量搜索和关键词搜索的权重：

python 复制代码 
from agno.vectordb.pinecone import Pinecone

vector_db = Pinecone(
    name="hybrid-index",
    dimension=1536,
    metric="cosine",
    search_type=SearchType.hybrid,
    hybrid_alpha=0.7                     # 0.7 = 70% 向量搜索 + 30% 关键词搜索
)

# hybrid_alpha 值说明：
# 0.0 = 100% 关键词搜索
# 0.5 = 50% 向量 + 50% 关键词
# 1.0 = 100% 向量搜索

6.3 重排序（Reranking）

重排序是对初步检索结果进行二次排序，进一步提高相关性。

python 复制代码 
from agno.knowledge.reranker.cohere import CohereReranker
from agno.vectordb.lancedb import LanceDb
from agno.vectordb.search import SearchType

# 配置重排序器
vector_db = LanceDb(
    uri="tmp/lancedb",
    table_name="reranked_search",
    search_type=SearchType.hybrid,
    reranker=CohereReranker(              # 添加重排序器
        model="rerank-v3.5",
        top_n=5                          # 重排后返回前5个
    )
)

重排序的优势：

  • ✅ 进一步提高检索结果的相关性
  • ✅ 减少噪音和不相关结果
  • ✅ 提升用户体验

6.4 自定义检索器

在某些场景下，你可能需要完全控制检索逻辑。Agno 支持自定义检索器函数。

自定义检索器函数签名

python 复制代码 
from typing import Optional
from agno.agent import Agent

def custom_retriever(
    query: str,                          # 搜索查询
    agent: Optional[Agent] = None,       # Agent 实例
    num_documents: int = 5,              # 要检索的文档数
    **kwargs                             # 其他参数
) -> Optional[list[dict]]:               # 返回文档列表
    """
    自定义检索器函数
    
    Args:
        query: 用户查询字符串
        agent: 发起查询的 Agent 实例
        num_documents: 返回的文档数量
        **kwargs: 其他关键字参数
    
    Returns:
        检索到的文档列表，如果失败返回 None
    """
    # 你的自定义检索逻辑
    pass

同步自定义检索器示例

python 复制代码 
from typing import Optional
from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.qdrant import Qdrant
from qdrant_client import QdrantClient

# 步骤1：定义嵌入器
embedder = OpenAIEmbedder(
    id="text-embedding-v4",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# 步骤2：初始化向量数据库
vector_db = Qdrant(
    collection="thai-recipes",
    url="http://localhost:6333",
    embedder=embedder
)

# 步骤3：加载知识库（如果尚未加载）
knowledge_base = Knowledge(vector_db=vector_db)
knowledge_base.add_content(
    url="https://arxiv.org/pdf/2410.05779"
)

# 步骤4：定义自定义检索器
def custom_retriever(
    query: str,
    agent: Optional[Agent] = None,
    num_documents: int = 5,
    **kwargs
) -> Optional[list[dict]]:
    """
    自定义检索器：使用 Qdrant 客户端直接查询
    """
    try:
        # 创建 Qdrant 客户端
        qdrant_client = QdrantClient(
            url="http://localhost:6333"
        )
        
        # 将查询转换为嵌入向量
        query_embedding = embedder.get_embedding(query)
        
        # 执行向量搜索
        results = qdrant_client.query_points(
            collection_name="thai-recipes",
            query=query_embedding,
            limit=num_documents,
        )
        
        # 转换结果为字典格式
        results_dict = results.model_dump()
        
        if "points" in results_dict:
            return results_dict["points"]
        else:
            return None
            
    except Exception as e:
        print(f"检索过程中发生错误: {str(e)}")
        return None

# 步骤5：使用自定义检索器创建 Agent
def main():
    agent = Agent(
        knowledge_retriever=custom_retriever,    # 传入自定义检索器
        search_knowledge=True,                   # 启用 Agentic RAG
        instructions="搜索知识库获取信息"
    )
    
    # 查询示例
    query = "列出制作LightRAG的主要作者"
    agent.print_response(query, markdown=True)

if __name__ == "__main__":
    main()

异步自定义检索器示例

对于高并发场景，推荐使用异步检索器：

python 复制代码 
import asyncio
from typing import Optional
from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.qdrant import Qdrant
from qdrant_client import AsyncQdrantClient

# 嵌入器和知识库配置（同上）
vector_db = Qdrant(
    collection="thai-recipes",
    url="http://localhost:6333",
    embedder=embedder
)
knowledge_base = Knowledge(vector_db=vector_db)
knowledge_base.add_content(
    url="https://arxiv.org/pdf/2410.05779"
)

# 定义异步自定义检索器
async def async_custom_retriever(
    query: str,
    agent: Optional[Agent] = None,
    num_documents: int = 5,
    **kwargs
) -> Optional[list[dict]]:
    """
    异步自定义检索器
    """
    try:
        # 创建异步 Qdrant 客户端
        qdrant_client = AsyncQdrantClient(
            url="http://localhost:6333"
        )
        
        # 获取查询嵌入
        query_embedding = embedder.get_embedding(query)
        
        # 异步执行向量搜索
        results = await qdrant_client.query_points(
            collection_name="thai-recipes",
            query=query_embedding,
            limit=num_documents,
        )
        
        results_dict = results.model_dump()
        
        if "points" in results_dict:
            return results_dict["points"]
        else:
            return None
            
    except Exception as e:
        print(f"检索过程中发生错误: {str(e)}")
        return None

# 异步主函数
async def async_main():
    agent = Agent(
        knowledge_retriever=async_custom_retriever,  # 异步检索器
        search_knowledge=True,
        instructions="搜索知识库获取信息"
    )
    
    query = "列出制作LightRAG的主要作者"
    await agent.aprint_response(query, markdown=True)

if __name__ == "__main__":
    asyncio.run(async_main())

自定义检索器的高级用法

你可以在自定义检索器中实现更复杂的逻辑：

python 复制代码 
def advanced_custom_retriever(
    query: str,
    agent: Optional[Agent] = None,
    num_documents: int = 5,
    **kwargs
) -> Optional[list[dict]]:
    """
    高级自定义检索器：
    1. 多数据源检索
    2. 结果融合
    3. 自定义评分
    """
    try:
        # 1. 从多个数据源检索
        results_db1 = search_database_1(query, num_documents)
        results_db2 = search_database_2(query, num_documents)
        
        # 2. 合并和去重
        all_results = merge_and_deduplicate(results_db1, results_db2)
        
        # 3. 自定义评分逻辑
        scored_results = apply_custom_scoring(all_results, query)
        
        # 4. 重排序
        reranked_results = rerank_by_score(scored_results)
        
        # 5. 返回前 N 个结果
        return reranked_results[:num_documents]
        
    except Exception as e:
        print(f"高级检索失败: {str(e)}")
        return None

7. RAG 与 Agent 集成

7.1 基础集成

将 RAG 集成到 Agent 非常简单，只需在创建 Agent 时传入知识库：

python 复制代码 
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

# 步骤1：创建知识库
vector_db = PgVector(
    table_name="my_knowledge",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"
)

knowledge = Knowledge(vector_db=vector_db)
knowledge.add_content(
    url="https://docs.agno.com/introduction/agents.md"
)

# 步骤2：创建 Agent 并关联知识库
agent = Agent(
    name="Knowledge Agent",
    knowledge=knowledge,                 # 关联知识库
    search_knowledge=True,               # 启用知识搜索（默认为 True）
    instructions="在回答问题前，总是先搜索你的知识库。包含来源引用。"
)

# 步骤3：查询
agent.print_response("什么是 Agno Agent?", markdown=True)

7.2 Agentic RAG

Agentic RAG 是 Agno 的默认模式，Agent 拥有主动搜索知识库的能力。

python 复制代码 
from agno.agent import Agent
from agno.models.openai import OpenAILike
from dotenv import load_dotenv

load_dotenv()
# Agentic RAG 配置
agent = Agent(
    model=OpenAILike(id="qwen3-max",
                     base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", 
                     api_key=os.getenv("QWEN_API_KEY")),
    knowledge=knowledge,

    # Agentic RAG 核心参数
    search_knowledge=True,  # 为 Agent 添加搜索知识库的工具

    # 指令引导
    instructions=[
        "你是一个专业的知识助手。",
        "在回答问题前，总是先搜索你的知识库。",
        "如果知识库中没有相关信息，再考虑使用其他工具或基于通用知识回答。",
        "在回答中包含来源引用。"
    ],

    # 显示工具调用（调试用）
    read_tool_call_history=True,

    # Markdown 输出
    markdown=True
)

# Agent 会自主决定何时搜索知识库
agent.print_response("如何在 Agno 中创建一个 Agent?")

Agentic RAG 的工作流程：

markdown 复制代码 
用户查询 → Agent 分析
           │
           ├─ 需要知识库信息？
           │  ├─ 是 → 调用 search_knowledge 工具
           │  │       │
           │  │       ├─ 检索相关文档
           │  │       ├─ 分析检索结果
           │  │       └─ 决定是否需要更多信息
           │  │           ├─ 需要 → 再次检索
           │  │           └─ 不需要 → 继续
           │  │
           │  └─ 否 → 直接基于通用知识回答
           │
           └─ 生成最终回答

7.3 传统 RAG

传统 RAG 将检索到的知识直接添加到上下文中：

python 复制代码 
from agno.agent import Agent

# 传统 RAG 配置
agent = Agent(
    knowledge=knowledge,
    
    # 传统 RAG 参数
    add_knowledge_to_context=True,       # 将知识添加到上下文
    search_knowledge=False,              # 不使用搜索工具（可选）
    
    # 引用格式
    references_format="json",            # 或 "yaml"
    
    # 其他配置
    instructions="使用提供的知识回答问题。",
    markdown=True
)

# 每次查询都会自动检索知识并添加到上下文
agent.print_response("Agno 支持哪些向量数据库?")

传统 RAG vs Agentic RAG 对比：

特性 传统 RAG Agentic RAG
检索时机 每次查询都检索 Agent 智能决定
控制方式 add_knowledge_to_context=True search_knowledge=True
灵活性 固定流程 高度灵活
性能 可能有不必要的检索 按需检索，更高效
适用场景 简单问答 复杂任务、多步推理
多轮检索 不支持 支持

7.4 知识过滤器

知识过滤器允许你基于元数据精确控制检索范围。

静态过滤器

python 复制代码 
from agno.agent import Agent

# 为 Agent 配置静态过滤器
agent = Agent(
    knowledge=knowledge,
    
    # 静态知识过滤器
    knowledge_filters={
        "category": "recipes",           # 只检索食谱类文档
        "cuisine": "thai",               # 只检索泰式料理
        "difficulty": "easy"             # 只检索简单食谱
    },
    
    search_knowledge=True
)

# Agent 只会在符合过滤条件的文档中检索
agent.print_response("推荐一个简单的泰式菜谱")

动态过滤器（Agentic Filters）

让 Agent 自主选择过滤器：

python 复制代码 
agent = Agent(
    knowledge=knowledge,
    
    # 启用智能过滤器
    enable_agentic_knowledge_filters=True,
    
    # 可用的过滤器选项（Agent 会自主选择）
    # 这些可以在知识库加载时设置
    
    search_knowledge=True,
    instructions="根据用户查询，智能选择合适的知识过滤器。"
)

在知识库加载时设置元数据

python 复制代码 
# 添加内容时设置元数据
knowledge.add_content(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
    metadata={
        "category": "recipes",
        "cuisine": "thai",
        "difficulty": "easy",
        "preparation_time": "30min"
    }
)

knowledge.add_content(
    url="https://agno-public.s3.amazonaws.com/recipes/ItalianRecipes.pdf",
    metadata={
        "category": "recipes",
        "cuisine": "italian",
        "difficulty": "medium",
        "preparation_time": "45min"
    }
)

元数据过滤搜索

python 复制代码 
# 在搜索时应用过滤器
results = vector_db.search(
    query="pasta recipe",
    filters={
        "cuisine": "italian",
        "difficulty": "easy"
    },
    limit=5
)

7.5 Agent 更新知识库

Agent 还可以具备更新知识库的能力：

python 复制代码 
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    
    # 启用知识库更新能力
    update_knowledge=True,
    
    instructions=[
        "你可以搜索和更新知识库。",
        "当发现新的有价值信息时，添加到知识库中。"
    ]
)

8. 实战示例

8.1 基础 RAG 示例

这是一个完整的基础 RAG 示例，展示从创建知识库到 Agent 查询的全过程。

python 复制代码 
"""
基础 RAG 示例
功能：创建一个能够回答泰式食谱问题的 Agent
"""
import os

from agno.agent import Agent
from agno.models.openai import OpenAILike
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.lancedb import LanceDb
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.vectordb.search import SearchType


def main():
    # 步骤1：配置嵌入器
    embedder = OpenAIEmbedder(
        id="text-embedding-v4",  # 模型名称 这里我们使用千问的通用文本向量-v4
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DashScope API 地址
        dimensions=1536,  # 向量维度
        api_key=os.getenv("QWEN_API_KEY")  # API 密钥（可选，默认从环境变量读取）
    )

    # 步骤2：配置向量数据库
    vector_db = LanceDb(
        uri="tmp/lancedb",  # 本地存储路径
        table_name="thai_recipes",  # 表名
        search_type=SearchType.vector,  # 向量搜索
        embedder=embedder
    )

    # 步骤3：创建知识库
    knowledge = Knowledge(
        name="Thai Recipes Knowledge Base",
        description="泰式食谱知识库",
        vector_db=vector_db
    )

    # 步骤4：加载内容（首次运行时执行）
    print("正在加载知识库...")
    knowledge.add_content(
        name="Thai Recipes PDF",
        url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
        metadata={
            "category": "recipes",
            "cuisine": "thai"
        }
    )
    print("知识库加载完成！\n")

    # 步骤5：创建 Agent
    agent = Agent(
        name="Thai Chef",
        model=OpenAILike(id="qwen3-max",
                 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                 api_key=os.getenv("QWEN_API_KEY")),
        knowledge=knowledge,
        search_knowledge=True,  # 启用 Agentic RAG
        instructions=[
            "你是一位专业的泰式料理厨师。",
            "在回答问题时，总是先搜索你的知识库。",
            "提供详细的食材清单和烹饪步骤。",
            "在回答中包含来源页码。"
        ],
        read_tool_call_history=True,  # 显示工具调用
        markdown=True
    )

    # 步骤6：查询示例
    print("=" * 60)
    print("示例查询 1：查询食材")
    print("=" * 60)
    agent.print_response(
        "制作 Massaman Gai（马沙文咖喱鸡）需要哪些食材？"
    )

    print("\n" + "=" * 60)
    print("示例查询 2：查询烹饪步骤")
    print("=" * 60)
    agent.print_response(
        "Massaman Gai 的详细烹饪步骤是什么？"
    )

    print("\n" + "=" * 60)
    print("示例查询 3：推荐菜品")
    print("=" * 60)
    agent.print_response(
        "推荐三道适合初学者的泰式菜品"
    )


if __name__ == "__main__":
    main()

运行输出示例：

diff 复制代码 
正在加载知识库...
知识库加载完成！

============================================================
示例查询 1：查询食材
============================================================
[Tool Call] search_knowledge(query="Massaman Gai ingredients")

# Massaman Gai（马沙文咖喱鸡）食材清单

根据泰式食谱，制作 Massaman Gai 需要以下食材：

**主要食材：**
- 鸡肉（切块） - 500克
- 椰奶 - 400毫升
- 马铃薯（切块） - 2个
- 洋葱（切块） - 1个
- 花生 - 1/2杯

**咖喱酱料：**
- Massaman 咖喱酱 - 3汤匙
- 罗望子酱 - 2汤匙
- 鱼露 - 2汤匙
- 棕榈糖 - 1汤匙

**香料：**
- 月桂叶 - 2片
- 肉桂棒 - 1根
- 豆蔻 - 3颗

来源：Thai Recipes PDF, 第 15 页

8.2 使用 ChromaDB 的示例

python 复制代码 
"""
ChromaDB RAG 示例
使用 ChromaDB 本地持久化存储
"""
import os

from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.models.openai import OpenAILike
from agno.vectordb.chroma import ChromaDb

embedder = OpenAIEmbedder(
    id="text-embedding-v4",  # 模型名称 这里我们使用千问的通用文本向量-v4
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DashScope API 地址
    dimensions=1536,  # 向量维度
    api_key=os.getenv("QWEN_API_KEY")  # API 密钥（可选，默认从环境变量读取）
)


def main():
    # 配置 ChromaDB（本地持久化）
    vector_db = ChromaDb(
        collection="agno_docs",  # 集合名
        path="tmp/chromadb",  # 本地存储路径
        persistent_client=True,  # 启用持久化
        embedder=embedder
    )

    # 创建知识库
    knowledge = Knowledge(
        name="Agno Documentation",
        description="Agno 官方文档知识库",
        vector_db=vector_db
    )

    # 加载多个文档
    docs_to_load = [
        {
            "name": "Agents Introduction",
            "url": "https://docs.agno.com/introduction/agents.md",
            "metadata": {"category": "intro", "topic": "agents"}
        },
        {
            "name": "Knowledge Base Guide",
            "url": "https://docs.agno.com/concepts/knowledge/overview.md",
            "metadata": {"category": "concepts", "topic": "knowledge"}
        },
        {
            "name": "Vector Databases",
            "url": "https://docs.agno.com/concepts/vectordb/overview.md",
            "metadata": {"category": "concepts", "topic": "vectordb"}
        }
    ]

    # 批量加载文档
    print("正在加载文档到 ChromaDB...")
    for doc in docs_to_load:
        print(f"  - 加载: {doc['name']}")
        knowledge.add_content(
            name=doc["name"],
            url=doc["url"],
            metadata=doc["metadata"]
        )
    print("文档加载完成！\n")

    # 创建 Agent
    agent = Agent(
        name="Agno Assistant",
        model=OpenAILike(id="qwen3-max",
                         base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                         api_key=os.getenv("QWEN_API_KEY")),
        knowledge=knowledge,
        search_knowledge=True,
        instructions=[
            "你是 Agno 框架的专家助手。",
            "回答关于 Agno 的问题时，先搜索知识库。",
            "提供准确的代码示例和详细解释。",
            "引用具体的文档来源。"
        ],
        markdown=True
    )

    # 查询示例
    queries = [
        "如何在 Agno 中创建一个 Agent？",
        "Agno 支持哪些向量数据库？",
        "什么是 Knowledge Base？"
    ]

    for i, query in enumerate(queries, 1):
        print(f"\n{'=' * 60}")
        print(f"查询 {i}: {query}")
        print(f"{'=' * 60}")
        agent.print_response(query)


if __name__ == "__main__":
    main()

8.3 使用 PgVector 的示例

python 复制代码 
"""
PgVector RAG 示例
使用 PostgreSQL + PgVector 扩展，支持混合搜索
"""
import os

from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector
from agno.vectordb.search import SearchType
from agno.models.openai import OpenAILike
from dotenv import load_dotenv

load_dotenv()


def setup_pgvector():
    """
    设置 PgVector

    首先需要启动 PostgreSQL + PgVector 容器：

    docker run -d \
      -e POSTGRES_DB=ai \
      -e POSTGRES_USER=ai \
      -e POSTGRES_PASSWORD=ai \
      -e PGDATA=/var/lib/postgresql/data/pgdata \
      -v pgvolume:/var/lib/postgresql/data \
      -p 5532:5432 \
      --name pgvector \
      agno/pgvector:16
    """
    pass


def main():
    embedder = OpenAIEmbedder(
        id="text-embedding-v4",  # 模型名称 这里我们使用千问的通用文本向量-v4
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DashScope API 地址
        dimensions=1536,  # 向量维度
        api_key=os.getenv("QWEN_API_KEY")  # API 密钥（可选，默认从环境变量读取）
    )
    # 配置 PgVector（混合搜索）
    vector_db = PgVector(
        table_name="job_descriptions",  # 表名
        db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        search_type=SearchType.hybrid,  # 混合搜索
        embedder=embedder
    )

    # 创建知识库
    knowledge = Knowledge(
        name="Job Descriptions",
        description="职位描述知识库",
        vector_db=vector_db
    )

    # 加载职位描述文档
    print("正在加载职位描述...")
    knowledge.add_content(
        name="Software Engineer JD",
        url="https://example.com/job-descriptions/software-engineer.pdf",
        metadata={
            "department": "engineering",
            "level": "mid-senior",
            "location": "remote"
        }
    )
    print("职位描述加载完成！\n")

    # 创建 Agent（使用知识过滤器）
    agent = Agent(
        name="HR Assistant",
        model=OpenAILike(id="qwen3-max",
                         base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                         api_key=os.getenv("QWEN_API_KEY")),
        knowledge=knowledge,

        # 知识过滤器（只检索工程部门的职位）
        knowledge_filters={
            "department": "engineering"
        },

        search_knowledge=True,
        instructions=[
            "你是一位 HR 助手。",
            "回答职位相关问题时，先搜索职位描述知识库。",
            "提供详细的技能要求和职责说明。"
        ],
        markdown=True
    )

    # 查询
    print("=" * 60)
    print("查询：软件工程师职位要求")
    print("=" * 60)
    agent.print_response(
        "应聘软件工程师需要具备哪些技能？"
    )


if __name__ == "__main__":
    main()

8.4 自定义检索器示例

完整的自定义检索器实现，包含高级过滤和评分逻辑：

python 复制代码 
"""
自定义检索器示例
实现高级检索逻辑：多阶段检索、自定义评分、结果融合
"""

from typing import Optional, List, Dict
from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.models.openai import OpenAILike
from dotenv import load_dotenv

from agno.knowledge.knowledge import Knowledge
from agno.vectordb.qdrant import Qdrant
from qdrant_client import QdrantClient
import os

load_dotenv()
# 配置
QDRANT_URL = "http://localhost:6333"
COLLECTION_NAME = "advanced-kb"

# 初始化组件
embedder = OpenAIEmbedder(
    id="text-embedding-v4",  # 模型名称 这里我们使用千问的通用文本向量-v4
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DashScope API 地址
    dimensions=1536,  # 向量维度
    api_key=os.getenv("QWEN_API_KEY")  # API 密钥（可选，默认从环境变量读取）
)

vector_db = Qdrant(
    collection=COLLECTION_NAME,
    url=QDRANT_URL,
    embedder=embedder
)

knowledge_base = Knowledge(vector_db=vector_db)

# 加载知识库（首次运行）
if not os.path.exists("tmp/knowledge_loaded.flag"):
    print("首次运行，加载知识库...")
    knowledge_base.add_content(
        url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"
    )
    # 创建标记文件
    with open("tmp/knowledge_loaded.flag", "w") as f:
        f.write("loaded")
    print("知识库加载完成！\n")


def advanced_custom_retriever(
    query: str,
    agent: Optional[Agent] = None,
    num_documents: int = 5,
    min_score: float = 0.7,  # 最小相似度分数
    apply_reranking: bool = True,  # 是否应用重排序
    **kwargs
) -> Optional[List[Dict]]:
    """
    高级自定义检索器

    特性：
    1. 多阶段检索（先粗检索，再精检索）
    2. 自定义评分和过滤
    3. 可选的重排序
    4. 结果去重和格式化

    Args:
        query: 搜索查询
        agent: Agent 实例
        num_documents: 返回文档数
        min_score: 最小相似度阈值
        apply_reranking: 是否应用重排序
        **kwargs: 其他参数

    Returns:
        检索到的文档列表
    """
    try:
        # 创建 Qdrant 客户端
        qdrant_client = QdrantClient(url=QDRANT_URL)

        # 阶段1：粗检索（检索更多文档）
        query_embedding = embedder.get_embedding(query)

        initial_results = qdrant_client.query_points(
            collection_name=COLLECTION_NAME,
            query=query_embedding,
            limit=num_documents * 3,  # 检索 3 倍数量
        )

        results_dict = initial_results.model_dump()

        if "points" not in results_dict or not results_dict["points"]:
            print("未找到相关文档")
            return None

        points = results_dict["points"]

        # 阶段2：过滤低分文档
        filtered_points = [
            point for point in points
            if point.get("score", 0) >= min_score
        ]

        print(f"粗检索: {len(points)} 个文档")
        print(f"过滤后: {len(filtered_points)} 个文档 (score >= {min_score})")

        # 阶段3：重排序（可选）
        if apply_reranking and len(filtered_points) > 1:
            # 这里可以集成外部重排序服务
            # 例如：Cohere Reranker, Cross-Encoder 等
            # 示例：简单的基于分数的重排序
            filtered_points = sorted(
                filtered_points,
                key=lambda x: x.get("score", 0),
                reverse=True
            )
            print("已应用重排序")

        # 阶段4：返回前 N 个结果
        final_results = filtered_points[:num_documents]

        print(f"最终返回: {len(final_results)} 个文档\n")

        return final_results

    except Exception as e:
        print(f"检索过程中发生错误: {str(e)}")
        return None


def main():
    """主函数"""

    # 创建使用自定义检索器的 Agent
    agent = Agent(
        name="Advanced Chef",
        model=OpenAILike(id="qwen3-max",
                         base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                         api_key=os.getenv("QWEN_API_KEY")),

        # 使用自定义检索器
        knowledge_retriever=advanced_custom_retriever,
        search_knowledge=True,

        instructions=[
            "你是一位专业厨师。",
            "使用自定义检索器搜索食谱知识库。",
            "提供详细的烹饪指导。"
        ],

        read_tool_call_history=True,
        markdown=True
    )

    # 测试查询
    queries = [
        "制作泰式绿咖喱的食材和步骤是什么？",
        "推荐一道适合晚餐的泰式菜品",
        "如何制作泰式芒果糯米饭？"
    ]

    for i, query in enumerate(queries, 1):
        print("=" * 70)
        print(f"查询 {i}: {query}")
        print("=" * 70)
        agent.print_response(query)
        print("\n")


if __name__ == "__main__":
    main()

8.5 多Agent RAG 协作示例

展示多个 Agent 如何协作，各自使用不同的知识库：

python 复制代码 
"""
多 Agent RAG 协作示例
场景：RAG论文分析系统
- LightRAG 论文分析师
- GraphRAG 论文分析师
- Coordinator Agent：协调者，决定咨询哪位专家
"""
import os

from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.team import Team
from agno.vectordb.lancedb import LanceDb
from agno.vectordb.qdrant import Qdrant
from agno.vectordb.search import SearchType
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.models.openai import OpenAILike
from dotenv import load_dotenv

load_dotenv()
embedder = OpenAIEmbedder(
    id="text-embedding-v4",  # 模型名称 这里我们使用千问的通用文本向量-v4
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DashScope API 地址
    api_key=os.getenv("QWEN_API_KEY"),  # API 密钥（可选，默认从环境变量读取）
    dimensions=1024,
)


def create_knowledge_base(name: str, table_name: str, pdf_path: str):
    """创建知识库的辅助函数"""
    vector_db = Qdrant(
        collection=table_name,
        url="http://localhost:6333",
        embedder=embedder,
        search_type=SearchType.hybrid,
    )

    knowledge = Knowledge(
        name=name,
        vector_db=vector_db
    )

    knowledge.add_content(
        name=f"{name} PDF",
        path=pdf_path,

    )

    return knowledge


def main():
    # 创建LightRAG论文知识库
    print("正在创建LightRAG论文知识库...")
    lightrag_thesis_knowledge = create_knowledge_base(
        name="LightRAG 原始论文",
        table_name="lightrag_thesis",
        pdf_path="/Volumes/Transcend/2410.05779v3.pdf",
    )

    # 创建GraphRAG论文知识库
    print("正在创建GraphRAG论文知识库...")
    graphrag_thesis_knowledge = create_knowledge_base(
        name="GraphRAG 论文",
        table_name="graphrag_thesis",
        pdf_path="/Volumes/Transcend/2404.16130v2.pdf"
    )

    print("知识库创建完成！\n")

    # Agent 1：LightRAG 论文分析师
    lightrag_thesis_analyst = Agent(
        name="LightRAG Thesis Analyst",
        role="LightRAG 论文分析师",
        model=OpenAILike(id="qwen3-max",
                         base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                         api_key=os.getenv("QWEN_API_KEY")),
        knowledge=lightrag_thesis_knowledge,
        search_knowledge=True,
        instructions=[
            "你是一位专业的论文分析师。",
            "只回答LightRAG的论文相关的问题。",
            "提供详细的论文分析结果。"
        ],
        markdown=True
    )

    # Agent 2：GraphRAG 论文分析师
    graphrag_thesis_analyst = Agent(
        name="GraphRAG Thesis Analyst",
        role="GraphRAG 论文分析师",
        model=OpenAILike(id="qwen3-max",
                         base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                         api_key=os.getenv("QWEN_API_KEY")),
        knowledge=graphrag_thesis_knowledge,
        search_knowledge=True,
        instructions=[
            "你是一位专业的论文分析师。",
            "只回答GraphRAG的论文相关的问题。",
            "提供详细的论文分析结果。"
        ],
        markdown=True
    )

    # Agent 3：协调者（决定咨询哪位专家）
    coordinator = Team(
        name="Thesis Analysis Coordinator",
        role="论文分析协调专家",
        model=OpenAILike(id="qwen3-max",
                         base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                         api_key=os.getenv("QWEN_API_KEY")),
        members=[lightrag_thesis_analyst, graphrag_thesis_analyst],  # 管理的团队
        instructions=[
            "你是一位论文分析协调专家。",
            "根据用户的问题，决定咨询 LightRAG Thesis Analyst 还是 GraphRAG Thesis Analyst。",
            "如果问题涉及LightRAG，咨询 LightRAG Thesis Analyst。",
            "如果问题涉及GraphRAG，咨询 GraphRAG Thesis Analyst。",
            "如果问题涉及两种论文，分别咨询两位专家。",
            "整合专家的回答，给用户一个完整的答复。"
        ],
        markdown=True
    )

    # 测试多 Agent 协作
    test_queries = [
        "LightRAG的作者有哪些？",
        "对比LightRAG和GraphRAG中使用的技术有什么不同？"
    ]

    for i, query in enumerate(test_queries, 1):
        print("\n" + "=" * 70)
        print(f"多Agent协作查询 {i}")
        print("=" * 70)
        print(f"问题: {query}\n")

        # 协调者处理查询（会自动调用相应的专家 Agent）
        coordinator.print_response(query)

        print("\n")


if __name__ == "__main__":
    main()

多Agent协作输出示例：

markdown 复制代码 
====================================================================
多Agent协作查询 3
====================================================================
问题: 对比LightRAG和GraphRAG中使用的技术有什么不同？

┏━ Response (152.6s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                                                                              ┃
┃ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃
┃ ┃                    LightRAG 与 GraphRAG 技术对比分析                     ┃ ┃
┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┃
┃                                                                              ┃
┃ 通过对两篇论文核心技术的深入分析，可以清晰地看到 LightRAG 和 GraphRAG        ┃
┃ 虽然都利用了图结构来增强 RAG                                                 ┃
┃ 系统，但在设计理念、技术实现和应用场景上存在显著差异。                       ┃
┃                                                                              ┃
┃                                                                              ┃
┃                                核心理念与目标                                ┃
┃                                                                              ┃
┃  • GraphRAG: 旨在解决全局性意义建构问题（global sensemaking                  ┃
┃    questions），如"整个数据集的主要主题是什么？"。它通过构建一个全面的知识图 ┃
┃    谱并进行社区摘要，为用户提供宏观、综合的视角。                            ┃
┃  • LightRAG:                                                                 ┃
┃    旨在在保持高检索效率的同时，解决传统RAG的上下文碎片化问题。它追求在回答复 ┃
┃    杂查询时的全面性与系统运行效率、可扩展性之间的平衡。                      ┃
┃                                                                              ┃
┃                                                                              ┃
┃                               图结构的利用方式                               ┃
┃                                                                              ┃
┃                                                                              ┃
┃   方面       GraphRAG                        LightRAG                        ┃
┃  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ┃
┃   图的作用   核心索引结构。整个系统围绕知...   增强型索引结构。图作为对原始...   ┃
┃   图的处理   进行复杂的社区检测（Leiden算...   直接利用原始图结构（节点和边...   ┃
┃   知识单元   社区摘要（Community             实体（Entities）是直接的检索...   ┃
┃              Summaries）是最终的问答单元。                                   ┃
┃                                                                              ┃
┃                                                                              ┃
┃                                                                              ┃
┃                                检索与生成机制                                ┃
┃                                                                              ┃
┃                                                                              ┃
┃   方面       GraphRAG                        LightRAG                        ┃
┃  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ┃
┃   检索范式   无传统检索。采用 Map-Reduce     双层检索范式（Dual-Level        ┃
┃              式的查询聚焦摘要（QFS），遍 ...   Retrieval）。结合向量搜索和 ...   ┃
┃   生成过程   两阶段生成：1)                  单阶段生成：将检索到的实体、...   ┃
┃              为每个社区生成部分答案；2)                                      ┃
┃              聚合所有部分答案生成全局答案...                                   ┃
┃   效率       查询开销大。需要为每个社区调...   查询效率高。检索目标明确（实...   ┃
┃                                                                              ┃
┃                                                                              ┃
┃                                                                              ┃
┃                              索引构建与更新策略                              ┃
┃                                                                              ┃
┃                                                                              ┃
┃   方面         GraphRAG                       LightRAG                       ┃
┃  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ┃
┃   构建复杂度   非常高。涉及实体关系抽取、 ...   相对较低。主要工作是实体关 ...   ┃
┃   增量更新     极其困难且低效。新数据加入 ...   高效便捷。采用增量更新算法 ...   ┃
┃   适用场景     静态或变化缓慢的语料库，适 ...   动态、频繁更新的数据环境， ...   ┃
┃                                                                              ┃
┃                                                                              ┃
┃                                                                              ┃
┃                                     总结                                     ┃
┃                                                                              ┃
┃  • GraphRAG                                                                  ┃
┃    是一种重量级、全面性优先的方案。它牺牲了效率和动态更新能力，换取了对整个  ┃
┃    知识库无与伦比的全局洞察力，特别适合探索性、总结性的宏观问题。            ┃
┃  • LightRAG                                                                  ┃
┃    是一种轻量级、效率与效果兼顾的方案。它通过巧妙的双层检索和增量更新机制，  ┃
┃    在显著优于传统RAG的同时，避免了GraphRAG的巨大开销，更适合需要快速响应和处 ┃
┃    理动态数据的实际应用场景。                                                ┃
┃                                                                              ┃
┃ 简而言之，GraphRAG                                                           ┃
┃ 像是一位博学的学者，能为你提供一份关于整个领域的详尽综述报告；而 LightRAG    ┃
┃ 则像是一位高效的侦探，能迅速从海量信息中精准定位并整合出你需要的关键事实。   ┃
┃                                                                              ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

9. 高级特性

9.1 异步操作

对于高并发场景，Agno 提供了完整的异步支持。

异步加载知识库

python 复制代码 
import asyncio
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

async def async_load_knowledge():
    """异步加载知识库"""
    
    vector_db = PgVector(
        table_name="async_kb",
        db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"
    )
    
    knowledge = Knowledge(vector_db=vector_db)
    
    # 异步添加多个文档
    urls = [
        "https://docs.agno.com/introduction.md",
        "https://docs.agno.com/concepts/agents.md",
        "https://docs.agno.com/concepts/knowledge.md"
    ]
    
    # 并发加载
    tasks = [
        knowledge.add_content_async(url=url)
        for url in urls
    ]
    
    results = await asyncio.gather(*tasks)
    
    print(f"异步加载完成，共 {len(results)} 个文档")
    
    return knowledge

# 运行异步函数
knowledge = asyncio.run(async_load_knowledge())

异步 Agent 查询

python 复制代码 
import asyncio
from agno.agent import Agent
from agno.models.openai import OpenAILike

async def async_agent_query():
    """异步 Agent 查询"""
    
    agent = Agent(
        model=OpenAILike(id="qwen3-max",
                 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                 api_key=os.getenv("QWEN_API_KEY")),
        knowledge=knowledge,
        search_knowledge=True
    )
    
    # 异步查询
    response = await agent.arun(
        "什么是 Agno Agent?"
    )
    
    print(response.content)
    
    # 异步流式输出
    async for chunk in agent.arun(
        "解释 RAG 的工作原理"
        , stream=True
    ):
        print(chunk.content, end="", flush=True)

# 运行
asyncio.run(async_agent_query())

批量异步查询

python 复制代码 
import asyncio
from agno.agent import Agent

async def batch_queries(agent: Agent, queries: list):
    """批量异步查询"""
    
    tasks = [
        agent.arun(query)
        for query in queries
    ]
    
    responses = await asyncio.gather(*tasks)
    
    return responses

async def main():
    agent = Agent(
        knowledge=knowledge,
        search_knowledge=True
    )
    
    queries = [
        "什么是向量数据库？",
        "如何创建知识库？",
        "Agno 支持哪些嵌入模型？"
    ]
    
    print("开始批量查询...")
    responses = await batch_queries(agent, queries)
    
    for i, (query, response) in enumerate(zip(queries, responses), 1):
        print(f"\n查询 {i}: {query}")
        print(f"回答: {response.content}\n")

asyncio.run(main())

9.2 知识库动态更新

在运行时动态更新知识库，无需重启应用：

python 复制代码 
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge

# 创建知识库和 Agent
knowledge = Knowledge(vector_db=vector_db)
knowledge.add_content(url="https://docs.agno.com/v1/intro.md")

agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    update_knowledge=True,          # 启用知识库更新能力
)

# 初始查询
print("=" * 60)
print("查询 1：基于初始知识库")
print("=" * 60)
agent.print_response("Agno 的核心特性是什么？")

# 动态添加新文档
print("\n正在添加新文档到知识库...")
knowledge.add_content(
    url="https://docs.agno.com/v2/new-features.md",
    metadata={"version": "v2", "type": "features"}
)
print("新文档添加完成！\n")

# 基于更新后的知识库查询
print("=" * 60)
print("查询 2：基于更新后的知识库")
print("=" * 60)
agent.print_response("Agno v2 有哪些新特性？")

增量更新策略

python 复制代码 
from agno.knowledge.knowledge import Knowledge

def incremental_update(knowledge: Knowledge, new_docs: list):
    """增量更新知识库"""
    
    for doc in new_docs:
        # 使用 upsert 模式（更新已存在的，插入新的）
        knowledge.add_content(
            url=doc["url"],
            metadata=doc["metadata"]
        )
        
        # 或者检查是否存在再决定
        content_hash = compute_content_hash(doc["url"])
        
        if not knowledge.vector_db.content_hash_exists(content_hash):
            knowledge.add_content(url=doc["url"])
            print(f"新增文档: {doc['url']}")
        else:
            print(f"跳过已存在的文档: {doc['url']}")

# 使用示例
new_documents = [
    {
        "url": "https://docs.agno.com/guides/rag.md",
        "metadata": {"category": "guide", "topic": "rag"}
    },
    {
        "url": "https://docs.agno.com/guides/agents.md",
        "metadata": {"category": "guide", "topic": "agents"}
    }
]

incremental_update(knowledge, new_documents)

9.3 元数据过滤

使用元数据实现精确的文档过滤和检索：

加载时设置元数据

python 复制代码 
# 为不同类型的文档设置不同的元数据
knowledge.add_content(
    url="https://docs.agno.com/api/agents.md",
    metadata={
        "doc_type": "api_reference",
        "category": "agents",
        "version": "2.0",
        "language": "en",
        "last_updated": "2024-01-15"
    }
)

knowledge.add_content(
    url="https://docs.agno.com/tutorials/rag-basics.md",
    metadata={
        "doc_type": "tutorial",
        "category": "rag",
        "difficulty": "beginner",
        "version": "2.0",
        "language": "en",
        "last_updated": "2024-01-20"
    }
)

基于元数据搜索

python 复制代码 
# 只搜索教程类文档
results = vector_db.search(
    query="如何使用 RAG",
    filters={
        "doc_type": "tutorial"
    },
    limit=5
)

# 组合多个过滤条件
results = vector_db.search(
    query="Agent 配置",
    filters={
        "doc_type": "api_reference",
        "category": "agents",
        "version": "2.0"
    },
    limit=5
)

Agent 动态元数据过滤

python 复制代码 
from agno.agent import Agent

# 创建支持动态过滤的 Agent
agent = Agent(
    knowledge=knowledge,
    
    # 启用 Agent 智能选择过滤器
    enable_agentic_knowledge_filters=True,
    
    search_knowledge=True,
    instructions=[
        "根据用户查询的性质，智能选择合适的知识过滤器。",
        "如果用户问 API 用法，优先搜索 doc_type='api_reference' 的文档。",
        "如果用户问教程或示例，优先搜索 doc_type='tutorial' 的文档。"
    ]
)

# Agent 会自动根据查询选择合适的过滤器
agent.print_response("Agent 类有哪些参数？")  # 自动选择 API 文档
agent.print_response("给我一个 RAG 的完整示例")  # 自动选择教程文档

9.4 透明推理

启用透明推理，可视化 Agent 的思考过程：

python 复制代码 
import os

from agno.agent import Agent
from agno.models.openai import OpenAILike
from agno.tools.reasoning import ReasoningTools

# 创建带透明推理的 Agent
agent = Agent(
    name="Transparent Reasoner",
    model=OpenAILike(id="qwen3-max",
                     base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                     api_key=os.getenv("QWEN_API_KEY")),
    knowledge=knowledge,

    # 添加推理工具
    tools=[ReasoningTools()],

    # 显示完整推理过程
    reasoning=True,

    # 流式输出中间步骤
    stream_intermediate_steps=True,

    # 显示工具调用
    read_tool_call_history=True,

    search_knowledge=True,

    instructions=[
        "一步一步思考问题。",
        "展示你的推理过程。",
        "说明为什么选择搜索知识库。",
        "解释如何得出最终答案。"
    ],

    markdown=True
)

# 查询
print("=" * 70)
print("透明推理示例")
print("=" * 70)

agent.print_response(
    "比较 PgVector 和 ChromaDB 的优缺点，并推荐适合生产环境的选择"
)

透明推理输出示例：

markdown 复制代码 
====================================================================
透明推理示例
====================================================================

[Reasoning Step 1] 分析问题
问题要求我比较两个向量数据库并给出生产环境推荐。
我需要：
1. 搜索知识库了解 PgVector 和 ChromaDB
2. 比较它们的特性
3. 基于生产环境需求给出推荐

[Tool Call] search_knowledge(query="PgVector features production")
[Tool Call] search_knowledge(query="ChromaDB features production")

[Reasoning Step 2] 分析检索结果
从知识库检索到：
- PgVector：PostgreSQL 扩展，SQL 支持，成熟稳定
- ChromaDB：轻量级，易用，本地/云端两用

[Reasoning Step 3] 比较分析
PgVector 优势：
- 完整的 SQL 功能
- PostgreSQL 生态成熟
- 高可靠性和可扩展性

ChromaDB 优势：
- 设置简单
- 开发友好
- 支持本地和云端

[Reasoning Step 4] 生产环境推荐
基于以下因素：
- 可靠性需求 → PgVector 更成熟
- 扩展性需求 → PgVector 更好
- 运维成本 → PgVector 可复用现有 PostgreSQL 基础设施

[Final Answer]
# PgVector vs ChromaDB 对比及生产环境推荐

## 对比分析
...（详细对比）

## 生产环境推荐
推荐使用 **PgVector**，原因如下：
1. 成熟稳定的 PostgreSQL 生态
2. 完整的 SQL 支持和事务保证
3. 易于集成到现有基础设施
4. 良好的可扩展性
...

10. 最佳实践与性能优化

10.1 知识库设计最佳实践

1. 合理的文档分块

python 复制代码 
from agno.knowledge.reader.pdf_reader import PDFReader
from agno.chunking import ChunkingStrategy

# ❌ 不推荐：块太小，上下文不完整
pdf_reader_too_small = PDFReader(
    chunk=True,
    chunk_size=100                     # 太小
)

# ❌ 不推荐：块太大，检索不精确
pdf_reader_too_large = PDFReader(
    chunk=True,
    chunk_size=5000                    # 太大
)

# ✅ 推荐：根据内容类型选择合适大小
pdf_reader_balanced = PDFReader(
    chunk=True,
    chunk_size=1000,                   # 平衡的大小
    chunking_strategy=ChunkingStrategy.SEMANTIC  # 语义分块
)

分块大小建议：

内容类型 推荐块大小 原因
技术文档 800-1200 字符 保持概念完整性
对话/问答 400-600 字符 快速精确检索
长篇文章 1000-1500 字符 平衡上下文和精度
代码文档 500-800 字符 保持代码块完整
法律文本 1200-1800 字符 保持条款完整

2. 有效的元数据设计

python 复制代码 
# ✅ 好的元数据设计
knowledge.add_content(
    url="https://docs.agno.com/guide/rag.md",
    metadata={
        # 文档分类
        "doc_type": "guide",
        "category": "rag",
        "subcategory": "basics",
        
        # 版本和更新
        "version": "2.0",
        "last_updated": "2024-01-15",
        
        # 受众和难度
        "audience": "developer",
        "difficulty": "intermediate",
        
        # 语言和地区
        "language": "en",
        "region": "global",
        
        # 业务标签
        "product": "agno",
        "feature": "rag"
    }
)

3. 知识库组织策略

python 复制代码 
# ✅ 推荐：按主题分离知识库
api_docs_kb = Knowledge(
    name="API Documentation",
    vector_db=PgVector(table_name="api_docs", ...)
)

tutorials_kb = Knowledge(
    name="Tutorials",
    vector_db=PgVector(table_name="tutorials", ...)
)

# 为不同用途创建不同的 Agent
api_agent = Agent(
    knowledge=api_docs_kb,
    instructions="回答 API 使用问题"
)

tutorial_agent = Agent(
    knowledge=tutorials_kb,
    instructions="提供教程和示例"
)

10.2 检索优化

1. 使用混合搜索

python 复制代码 
# ✅ 推荐：使用混合搜索提高准确性
from agno.vectordb.search import SearchType

vector_db = LanceDb(
    uri="tmp/lancedb",
    table_name="optimized_search",
    search_type=SearchType.hybrid,     # 混合搜索
    embedder=embedder
)

2. 配置重排序

python 复制代码 
# ✅ 推荐：添加重排序进一步优化
from agno.reranker.cohere import CohereReranker

vector_db = LanceDb(
    uri="tmp/lancedb",
    table_name="reranked_search",
    search_type=SearchType.hybrid,
    reranker=CohereReranker(
        model="rerank-v3.5",
        top_n=5                        # 重排后返回前5个
    )
)

3. 优化检索数量

python 复制代码 
# ❌ 不推荐：检索太多文档
def poor_retrieval(query):
    results = vector_db.search(
        query=query,
        limit=50                       # 太多，增加噪音和延迟
    )
    return results

# ✅ 推荐：根据需求调整
def optimized_retrieval(query, context_window_size):
    # 根据模型上下文窗口动态调整
    if context_window_size < 4000:
        limit = 3
    elif context_window_size < 8000:
        limit = 5
    else:
        limit = 10
    
    results = vector_db.search(
        query=query,
        limit=limit
    )
    return results

4. 实现缓存机制

python 复制代码 
from functools import lru_cache

# ✅ 推荐：缓存频繁查询
@lru_cache(maxsize=128)
def cached_search(query: str, limit: int = 5):
    """缓存搜索结果"""
    return vector_db.search(query=query, limit=limit)

# 使用
results = cached_search("常见问题查询")

10.3 性能调优

1. 使用异步操作

python 复制代码 
import asyncio

# ✅ 推荐：高并发场景使用异步
async def async_batch_load(urls: list):
    """异步批量加载"""
    tasks = [
        knowledge.add_content_async(url=url)
        for url in urls
    ]
    await asyncio.gather(*tasks)

# 使用
asyncio.run(async_batch_load(document_urls))

2. 批量处理

python 复制代码 
# ❌ 不推荐：逐个加载
for url in urls:
    knowledge.add_content(url=url)     # 慢

# ✅ 推荐：批量加载
knowledge.add_content_batch(urls=urls)  # 快

3. 优化向量数据库配置

python 复制代码 
# ✅ PgVector 索引优化
vector_db = PgVector(
    table_name="optimized_kb",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    
    # 使用 HNSW 索引（比 IVFFlat 更快）
    vector_index="hnsw",
    
    # 调整索引参数
    hnsw_ef_construction=200,          # 构建时的搜索范围
    hnsw_m=16                          # 每个节点的连接数
)

4. 连接池配置

python 复制代码 
from sqlalchemy.pool import QueuePool

# ✅ 推荐：配置数据库连接池
db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

vector_db = PgVector(
    table_name="pooled_kb",
    db_url=db_url,
    
    # 连接池配置
    pool_size=10,                      # 连接池大小
    max_overflow=20,                   # 最大溢出连接
    pool_timeout=30                    # 连接超时
)

5. 监控和日志

python 复制代码 
import logging

# ✅ 推荐：启用详细日志
logging.basicConfig(level=logging.INFO)

agent = Agent(
    knowledge=knowledge,
    
    # 启用调试模式
    debug_mode=True,
    
    # 显示工具调用
    show_tool_calls=True,
    
    # 监控性能
    log_performance=True
)

10.4 常见问题与解决方案

问题1：检索结果不相关

原因分析：

  • 嵌入模型不合适
  • 分块策略不当
  • 缺少混合搜索

解决方案：

python 复制代码 
# ✅ 解决方案
# 1. 使用更好的嵌入模型
from agno.embedder.cohere import CohereEmbedder

embedder = CohereEmbedder(
    model="embed-v4.0",                # 高质量嵌入
    dimensions=1024
)

# 2. 优化分块策略
reader = PDFReader(
    chunk=True,
    chunking_strategy=ChunkingStrategy.SEMANTIC,  # 语义分块
    chunk_size=1000
)

# 3. 启用混合搜索
vector_db = LanceDb(
    search_type=SearchType.hybrid,     # 混合搜索
    embedder=embedder
)

# 4. 添加重排序
from agno.reranker.cohere import CohereReranker

vector_db = LanceDb(
    search_type=SearchType.hybrid,
    embedder=embedder,
    reranker=CohereReranker(model="rerank-v3.5")
)

问题2：Agent 不搜索知识库

原因分析：

  • search_knowledge 未启用
  • 指令不够明确
  • 知识库为空

解决方案：

python 复制代码 
# ✅ 解决方案
# 1. 确保启用搜索
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,             # 必须启用
)

# 2. 明确的指令
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    instructions=[
        "在回答任何问题前，总是先搜索你的知识库。",
        "即使你认为知道答案，也要验证知识库中的信息。",
        "如果知识库中没有相关信息，明确告知用户。"
    ]
)

# 3. 验证知识库内容
print(f"知识库文档数: {vector_db.count()}")

问题3：性能慢

原因分析：

  • 同步操作
  • 检索文档过多
  • 向量数据库配置不当

解决方案：

python 复制代码 
# ✅ 解决方案
import asyncio

# 1. 使用异步
async def async_query(agent, query):
    response = await agent.arun(query)
    return response

# 2. 限制检索数量
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    
    # 限制每次检索的文档数
    knowledge_limit=5                  # 默认值
)

# 3. 优化向量数据库
vector_db = PgVector(
    table_name="fast_kb",
    db_url=db_url,
    vector_index="hnsw",               # 使用 HNSW 索引
    pool_size=10                       # 连接池
)

# 4. 使用缓存
from functools import lru_cache

@lru_cache(maxsize=128)
def cached_agent_query(query: str):
    return agent.run(query)

问题4：内存占用高

原因分析：

  • 加载大量文档到内存
  • 缺少清理机制

解决方案：

python 复制代码 
# ✅ 解决方案
# 1. 流式处理大文件
reader = PDFReader(
    chunk=True,
    chunk_size=800,                    # 较小的块
    stream=True                        # 流式处理
)

# 2. 定期清理
import gc

def process_large_dataset(urls):
    for url in urls:
        knowledge.add_content(url=url)
        
        # 定期清理内存
        gc.collect()

# 3. 使用向量数据库持久化
vector_db = PgVector(
    table_name="persistent_kb",
    db_url=db_url                      # 存储到数据库，不在内存
)

问题5：知识库更新不生效

原因分析：

  • 缓存未清除
  • 使用了错误的更新方法

解决方案：

python 复制代码 
# ✅ 解决方案
# 1. 使用 upsert 模式
knowledge.add_content(
    url="https://docs.agno.com/updated.md",
    upsert=True                        # 更新已存在的文档
)

# 2. 重建知识库
knowledge.load(
    recreate=True                      # 完全重建
)

# 3. 清除缓存（如果使用了缓存）
cached_search.cache_clear()

# 4. 验证更新
results = vector_db.search("测试查询")
print(f"更新后的结果: {results}")

11. 总结

11.1 核心要点回顾

通过本教程，我们全面学习了 Agno 中的 RAG 系统，核心要点包括：

1. RAG 概念

  • RAG 结合检索和生成，增强 LLM 能力
  • Agentic RAG 赋予 Agent 智能决策能力
  • 解决了 LLM 的知识过时、幻觉等问题

2. Agno RAG 架构

  • 核心组件：Knowledge、Vector DB、Embedder、Reader、Retriever
  • 知识流转：加载 → 分块 → 嵌入 → 存储 → 检索 → 生成
  • 特色功能：混合搜索、重排序、自定义检索器

3. 实践技能

  • 创建和管理知识库
  • 配置向量数据库（20+ 种选择）
  • 使用文档加载器处理多种格式
  • 实现自定义检索逻辑
  • 构建多 Agent RAG 系统

4. 最佳实践

  • 合理的文档分块策略
  • 有效的元数据设计
  • 性能优化技巧
  • 常见问题解决方案

11.2 Agno RAG 的优势

优势 说明
智能化 Agentic RAG 让 Agent 自主决策
灵活性 支持 20+ 向量数据库，多种嵌入器
高性能 混合搜索、重排序、异步操作
可扩展 自定义检索器、多 Agent 协作
易用性 简洁的 API，丰富的文档加载器
透明性 可视化推理过程，易于调试

11.3 下一步学习建议

  1. 深入实践

    • 构建自己的领域知识库
    • 尝试不同的向量数据库
    • 实验各种分块策略

  2. 性能优化

    • 基准测试不同配置
    • 优化检索准确性
    • 提升系统吞吐量

  3. 高级特性

    • 实现复杂的自定义检索器
    • 构建多 Agent RAG 系统
    • 集成实时数据源

  4. 生产部署

    • 选择合适的向量数据库
    • 设计可扩展架构
    • 监控和日志系统

教程系列

  • [Agno 开发教程系列（一）：框架介绍与基础智能体构建](#Agno 开发教程系列（一）：框架介绍与基础智能体构建 "#")
  • [Agno 开发教程系列（二）：赋予智能体超能力------工具的使用](#Agno 开发教程系列（二）：赋予智能体超能力——工具的使用 "#")
  • [Agno 开发教程系列（三）：Agent的记忆系统------让AI记住你](#Agno 开发教程系列（三）：Agent的记忆系统——让AI记住你 "#")
  • [Agno 开发教程系列（四）：多Agent协作系统（上）------ Team团队协作机制](#Agno 开发教程系列（四）：多Agent协作系统（上）—— Team团队协作机制 "#")
  • [Agno 开发教程系列（五）：多Agent协作系统（下）------ Workflow工作流机制](#Agno 开发教程系列（五）：多Agent协作系统（下）—— Workflow工作流机制 "#")
  • [Agno 开发教程系列（六）：工具系统详细教程](#Agno 开发教程系列（六）：工具系统详细教程 "#")
  • Agno 开发教程系列（七）：Agno 与 RAG（本篇）
  • [Agno 开发教程系列（八）：使用多模态大模型](#Agno 开发教程系列（八）：使用多模态大模型 "#")
相关推荐
吉吉安2 小时前
vercel ai sdk使用指南（Nextjs版本）
人工智能·大模型·llm·nodejs·vercel
带刺的坐椅3 小时前
Solon AI 开发学习16 - generate - 生成模型（图、音、视）
java·ai·llm·openai·solon
Baihai IDP3 小时前
用户体验与商业化的两难：Chatbots 的广告承载困境分析
人工智能·ai·chatgpt·llm
土豆125015 小时前
🚀 RAG系统构建指南：从「为什么」到「怎么做」
llm
智泊AI15 小时前
为什么说CLIP是多模态大模型的基石？
llm
鱼鱼块18 小时前
"从自然语言到数据库：AI First 时代的编程与开发革命"
sqlite·llm·openai
ohyeah20 小时前
AI First 时代：用大模型构建轻量级后台管理系统
前端·llm
Swizard21 小时前
Claude Opus 4.5 深度解构：当 AI 学会了“拒绝道歉”与“痛恨列表”
ai·llm·prompt·claude
企鹅侠客21 小时前
Ubuntu本地部署AnythingLLM实现本地文档RAG
linux·运维·ubuntu·llm
热门推荐
01GitHub 镜像站点02React CVE-2025-55182漏洞排查与修复指南03【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）04安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）05UV安装并设置国内源06BongoCat - 跨平台键盘猫动画工具07智能库存管理的需求预测模型：从业务痛点到落地代码的完整实践08本地部署阿里最新开源的Z-Image09Linux下V2Ray安装配置指南10论文阅读 - 深度学习端到端解决库存管理问题 - 有限时间范围内的多周期补货问题（Management Science）