【Agno系列七】手把手教你用Agno构建RAG：从零打造你的专属知识问答引擎！

1. RAG 概念与原理

1.1 什么是 RAG

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

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

1.2 RAG 工作原理

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

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

详细步骤：

1. 文档预处理阶段：

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

2. 2查询检索阶段：

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

3. 生成回答阶段：

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

1.3 传统 RAG vs Agentic RAG

传统 RAG

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

# 传统 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 自主决定：

• 是否需要检索知识库
• 何时检索知识库
• 如何检索（选择检索策略）
• 是否需要多次检索

# 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 系统由以下核心组件构成：

┌─────────────────────────────────────────────────────────┐│                    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 知识流转过程

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

┌─────────────────┐│  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 类来创建和管理。创建知识库的基本步骤：

from agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom 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 知识库配置

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

from agno.knowledge.knowledge import Knowledgefrom agno.vectordb.lancedb import LanceDbfrom agno.vectordb.search import SearchTypefrom agno.knowledge.reranker.cohere import CohereRerankerknowledge = 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 添加内容

# 同步添加knowledge.add_content(    name="Thai Recipes",                     # 内容名称    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",  # 文档 URL    metadata={"category": "recipes", "cuisine": "thai"}  # 元数据（可选）)# 异步添加（推荐用于高并发场景）import asyncioasync def load_knowledge():    await knowledge.add_content_async(        url="https://docs.agno.com/introduction/agents.md"    )asyncio.run(load_knowledge())

方式2：从本地路径添加

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 知识库管理

删除内容

# 按名称删除knowledge.vector_db.delete_by_name("Thai Recipes")# 按元数据删除knowledge.vector_db.delete_by_metadata(    {"category": "recipes"})

检查内容是否存在

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

知识库过滤

from agno.agent import Agent# 创建带过滤器的 Agentagent = 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 选择合适的向量数据库

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

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

4.3 向量数据库配置

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

# 通用配置参数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）

from agno.vectordb.pgvector import PgVectorfrom agno.vectordb.search import SearchTypefrom 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"""# 配置 PgVectorvector_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（本地持久化）

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

示例3：ChromaDB（Chroma Cloud）

from chromadb.config import Settingsfrom 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（混合搜索）

from agno.vectordb.weaviate import Weaviate, VectorIndex, Distancefrom 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（开发测试）

from agno.vectordb.lancedb import LanceDbfrom 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（高性能、高精度）

from agno.vectordb.lightrag import LightRagimport osvector_db = LightRag(    api_key=os.getenv("LIGHTRAG_API_KEY"),)

示例7：Qdrant（高性能）

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 对象结构：

{    "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 支持以下分块策略：

# 1. 文档分块（尊重文档结构）from agno.knowledge.chunking.document import DocumentChunkingknowledge.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 FixedSizeChunkingknowledge.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 SemanticChunkingknowledge.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 AgenticChunkingknowledge.add_content(    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",    reader=PDFReader(        name="Agentic Chunking Reader",        chunking_strategy=AgenticChunking(),    ),)

Reader 配置示例

from agno.knowledge.reader.pdf_reader import PDFReaderfrom 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 文档）

from agno.knowledge.reader.pdf_reader import PDFReaderfrom agno.knowledge.knowledge import Knowledge# 创建 PDF Readerpdf_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（网站爬取）

from agno.knowledge.reader.website_reader import WebsiteReader# 创建 Website Readerwebsite_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 文件）

from agno.knowledge.reader.csv_reader import CSVReader# 创建 CSV Readercsv_reader = CSVReader(    delimiter=",",                       # 分隔符    encoding="utf-8",                    # 编码    chunk=True,    chunk_size=500)# 加载 CSVknowledge.add_content(    path="data/products.csv",    reader=csv_reader)

4. JSONReader（JSON 文件）

from agno.knowledge.reader.json_reader import JSONReader# 创建 JSON Readerjson_reader = JSONReader(    chunk=True,    chunk_size=600)# 加载 JSONknowledge.add_content(    path="data/config.json",    reader=json_reader)

ReaderFactory（智能选择）

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

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

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

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

Sentence Transformer（本地模型）

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

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

Ollama Embedder（本地运行）

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 枚举配置：

from agno.vectordb.search import SearchType# 向量搜索（语义相似度）SearchType.vector# 关键词搜索（传统全文搜索）SearchType.keyword# 混合搜索（结合向量和关键词）SearchType.hybrid

向量搜索

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

from agno.vectordb.pgvector import PgVectorfrom agno.vectordb.search import SearchTypevector_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个结果)

关键词搜索

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

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

6.2 混合搜索

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

混合搜索的工作原理：

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

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

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

混合搜索示例

from agno.vectordb.lancedb import LanceDbfrom agno.vectordb.search import SearchTypefrom agno.knowledge.embedder.cohere import CohereEmbedderfrom 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 参数调整向量搜索和关键词搜索的权重：

from agno.vectordb.pinecone import Pineconevector_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）

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

from agno.knowledge.reranker.cohere import CohereRerankerfrom agno.vectordb.lancedb import LanceDbfrom 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 支持自定义检索器函数。

自定义检索器函数签名

from typing import Optionalfrom agno.agent import Agentdef 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

同步自定义检索器示例

from typing import Optionalfrom agno.agent import Agentfrom agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.qdrant import Qdrantfrom 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：使用自定义检索器创建 Agentdef 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()

异步自定义检索器示例

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

import asynciofrom typing import Optionalfrom agno.agent import Agentfrom agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.qdrant import Qdrantfrom 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())

自定义检索器的高级用法

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

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 时传入知识库：

from agno.agent import Agentfrom agno.knowledge.knowledge import Knowledgefrom 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 拥有主动搜索知识库的能力。

from agno.agent import Agentfrom agno.models.openai import OpenAILikefrom dotenv import load_dotenvload_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 的工作流程：

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

7.3 传统 RAG

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

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 知识过滤器

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

静态过滤器

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 自主选择过滤器：

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

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

# 添加内容时设置元数据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"    })

元数据过滤搜索

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

7.5 Agent 更新知识库

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

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

---

8. 实战示例

8.1 基础 RAG 示例

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

"""基础 RAG 示例功能：创建一个能够回答泰式食谱问题的 Agent"""import osfrom agno.agent import Agentfrom agno.models.openai import OpenAILikefrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.lancedb import LanceDbfrom agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.vectordb.search import SearchTypedef 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()

运行输出示例：

正在加载知识库...知识库加载完成！============================================================示例查询 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 的示例

"""ChromaDB RAG 示例使用 ChromaDB 本地持久化存储"""import osfrom agno.agent import Agentfrom agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.models.openai import OpenAILikefrom agno.vectordb.chroma import ChromaDbembedder = 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 的示例

"""PgVector RAG 示例使用 PostgreSQL + PgVector 扩展，支持混合搜索"""import osfrom agno.agent import Agentfrom agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.pgvector import PgVectorfrom agno.vectordb.search import SearchTypefrom agno.models.openai import OpenAILikefrom dotenv import load_dotenvload_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    """    passdef 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 自定义检索器示例

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

"""自定义检索器示例实现高级检索逻辑：多阶段检索、自定义评分、结果融合"""from typing import Optional, List, Dictfrom agno.agent import Agentfrom agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.models.openai import OpenAILikefrom dotenv import load_dotenvfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.qdrant import Qdrantfrom qdrant_client import QdrantClientimport osload_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 Nonedef 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 如何协作，各自使用不同的知识库：

"""多 Agent RAG 协作示例场景：RAG论文分析系统- LightRAG 论文分析师- GraphRAG 论文分析师- Coordinator Agent：协调者，决定咨询哪位专家"""import osfrom agno.agent import Agentfrom agno.knowledge.knowledge import Knowledgefrom agno.team import Teamfrom agno.vectordb.lancedb import LanceDbfrom agno.vectordb.qdrant import Qdrantfrom agno.vectordb.search import SearchTypefrom agno.knowledge.embedder.openai import OpenAIEmbedderfrom agno.models.openai import OpenAILikefrom dotenv import load_dotenvload_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 knowledgedef 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协作输出示例：

====================================================================多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 提供了完整的异步支持。

异步加载知识库

import asynciofrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.pgvector import PgVectorasync 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 查询

import asynciofrom agno.agent import Agentfrom agno.models.openai import OpenAILikeasync 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())

批量异步查询

import asynciofrom agno.agent import Agentasync def batch_queries(agent: Agent, queries: list):    """批量异步查询"""        tasks = [        agent.arun(query)        for query in queries    ]        responses = await asyncio.gather(*tasks)        return responsesasync 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 知识库动态更新

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

from agno.agent import Agentfrom agno.knowledge.knowledge import Knowledge# 创建知识库和 Agentknowledge = 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 有哪些新特性？")

增量更新策略

from agno.knowledge.knowledge import Knowledgedef 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 元数据过滤

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

加载时设置元数据

# 为不同类型的文档设置不同的元数据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"    })

基于元数据搜索

# 只搜索教程类文档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 动态元数据过滤

from agno.agent import Agent# 创建支持动态过滤的 Agentagent = 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 的思考过程：

import osfrom agno.agent import Agentfrom agno.models.openai import OpenAILikefrom agno.tools.reasoning import ReasoningTools# 创建带透明推理的 Agentagent = 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 的优缺点，并推荐适合生产环境的选择")

透明推理输出示例：

====================================================================透明推理示例====================================================================[Reasoning Step 1] 分析问题问题要求我比较两个向量数据库并给出生产环境推荐。我需要：1. 搜索知识库了解 PgVector 和 ChromaDB2. 比较它们的特性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. 合理的文档分块

from agno.knowledge.reader.pdf_reader import PDFReaderfrom 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. 有效的元数据设计

# ✅ 好的元数据设计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. 知识库组织策略

# ✅ 推荐：按主题分离知识库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", ...))# 为不同用途创建不同的 Agentapi_agent = Agent(    knowledge=api_docs_kb,    instructions="回答 API 使用问题")tutorial_agent = Agent(    knowledge=tutorials_kb,    instructions="提供教程和示例")

10.2 检索优化

1. 使用混合搜索

# ✅ 推荐：使用混合搜索提高准确性from agno.vectordb.search import SearchTypevector_db = LanceDb(    uri="tmp/lancedb",    table_name="optimized_search",    search_type=SearchType.hybrid,     # 混合搜索    embedder=embedder)

2. 配置重排序

# ✅ 推荐：添加重排序进一步优化from agno.reranker.cohere import CohereRerankervector_db = LanceDb(    uri="tmp/lancedb",    table_name="reranked_search",    search_type=SearchType.hybrid,    reranker=CohereReranker(        model="rerank-v3.5",        top_n=5                        # 重排后返回前5个    ))

3. 优化检索数量

# ❌ 不推荐：检索太多文档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. 实现缓存机制

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. 使用异步操作

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. 批量处理

# ❌ 不推荐：逐个加载for url in urls:    knowledge.add_content(url=url)     # 慢# ✅ 推荐：批量加载knowledge.add_content_batch(urls=urls)  # 快

3. 优化向量数据库配置

# ✅ 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. 连接池配置

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. 监控和日志

import logging# ✅ 推荐：启用详细日志logging.basicConfig(level=logging.INFO)agent = Agent(    knowledge=knowledge,        # 启用调试模式    debug_mode=True,        # 显示工具调用    show_tool_calls=True,        # 监控性能    log_performance=True)

10.4 常见问题与解决方案

问题1：检索结果不相关

原因分析：

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

解决方案：

# ✅ 解决方案# 1. 使用更好的嵌入模型from agno.embedder.cohere import CohereEmbedderembedder = 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 CohereRerankervector_db = LanceDb(    search_type=SearchType.hybrid,    embedder=embedder,    reranker=CohereReranker(model="rerank-v3.5"))

问题2：Agent 不搜索知识库

原因分析：

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

解决方案：

# ✅ 解决方案# 1. 确保启用搜索agent = Agent(    knowledge=knowledge,    search_knowledge=True,             # 必须启用)# 2. 明确的指令agent = Agent(    knowledge=knowledge,    search_knowledge=True,    instructions=[        "在回答任何问题前，总是先搜索你的知识库。",        "即使你认为知道答案，也要验证知识库中的信息。",        "如果知识库中没有相关信息，明确告知用户。"    ])# 3. 验证知识库内容print(f"知识库文档数: {vector_db.count()}")

问题3：性能慢

原因分析：

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

解决方案：

# ✅ 解决方案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：内存占用高

原因分析：

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

解决方案：

# ✅ 解决方案# 1. 流式处理大文件reader = PDFReader(    chunk=True,    chunk_size=800,                    # 较小的块    stream=True                        # 流式处理)# 2. 定期清理import gcdef 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：知识库更新不生效

原因分析：

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

解决方案：

# ✅ 解决方案# 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. 生产部署

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

---

那么，如何系统的去学习大模型LLM？

作为一名深耕行业的资深大模型算法工程师，我经常会收到一些评论和私信，我是小白，学习大模型该从哪里入手呢？我自学没有方向怎么办？这个地方我不会啊。如果你也有类似的经历，一定要继续看下去！这些问题啊，也不是三言两语啊就能讲明白的。

所以我综合了大模型的所有知识点，给大家带来一套全网最全最细的大模型零基础教程。在做这套教程之前呢，我就曾放空大脑，以一个大模型小白的角度去重新解析它，采用基础知识和实战项目相结合的教学方式，历时3个月，终于完成了这样的课程，让你真正体会到什么是每一秒都在疯狂输出知识点。

由于篇幅有限，⚡️ 朋友们如果有需要全套 《2025全新制作的大模型全套资料》，扫码获取~

👉大模型学习指南+路线汇总👈

我们这套大模型资料呢，会从基础篇、进阶篇和项目实战篇等三大方面来讲解。

👉①.基础篇👈

基础篇里面包括了Python快速入门、AI开发环境搭建及提示词工程，带你学习大模型核心原理、prompt使用技巧、Transformer架构和预训练、SFT、RLHF等一些基础概念，用最易懂的方式带你入门大模型。

👉②.进阶篇👈

接下来是进阶篇，你将掌握RAG、Agent、Langchain、大模型微调和私有化部署，学习如何构建外挂知识库并和自己的企业相结合，学习如何使用langchain框架提高开发效率和代码质量、学习如何选择合适的基座模型并进行数据集的收集预处理以及具体的模型微调等等。

👉③.实战篇👈

实战篇会手把手带着大家练习企业级的落地项目（已脱敏），比如RAG医疗问答系统、Agent智能电商客服系统、数字人项目实战、教育行业智能助教等等，从而帮助大家更好的应对大模型时代的挑战。

👉④.福利篇👈

最后呢，会给大家一个小福利，课程视频中的所有素材，有搭建AI开发环境资料包，还有学习计划表，几十上百G素材、电子书和课件等等，只要你能想到的素材，我这里几乎都有。我已经全部上传到优快云，朋友们如果需要可以微信扫描下方优快云官方认证二维码免费领取【保证100%免费】

相信我，这套大模型系统教程将会是全网最齐全 最易懂的小白专用课！！