> ## Documentation Index
> Fetch the complete documentation index at: https://ikun.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 知识库

**知识库**是 Agent 在运行时可以**搜索**的领域特定信息，用于做出更好的决策（动态少样本学习）和提供准确的响应（Agentic RAG）。知识存储在向量数据库中，这种**按需搜索**模式称为 Agentic RAG。

<Accordion title="动态少样本学习：Text2Sql Agent" icon="database">
  示例：如果我们正在构建一个 Text2Sql Agent，我们需要提供表架构、列名、数据类型、示例查询以及常见的“陷阱”来帮助它生成最佳的 SQL 查询。

  我们显然不会将所有这些信息都放入系统提示中，而是将这些信息存储在向量数据库中，并在运行时让 Agent 查询它。

  利用这些信息，Agent 就可以生成最佳的 SQL 查询。这被称为动态少样本学习。
</Accordion>

**Agno Agents 默认使用 Agentic RAG**，这意味着当我们向 Agent 提供 `knowledge` 时，它将在运行时搜索这个知识库，以获取完成任务所需的特定信息。

为 Agent 添加知识的伪步骤如下：

```python theme={null}
from agno.agent import Agent, AgentKnowledge

# 为 Agent 创建知识库
knowledge_base = AgentKnowledge(vector_db=...)

# 向知识库添加信息
knowledge_base.load_text("The sky is blue")

# 将知识库添加到 Agent 并为其提供一个工具以按需搜索知识库
agent = Agent(knowledge=knowledge_base, search_knowledge=True)
```

我们可以通过以下方式让 Agent 访问知识库：

* 我们可以设置 `search_knowledge=True` 来向 Agent 添加一个 `search_knowledge_base()` 工具。如果您向 Agent 添加了 `knowledge`，`search_knowledge` **默认情况下**为 `True`。
* 我们可以设置 `add_references=True` 来自动将知识库中的引用添加到 Agent 的提示中。这是传统的 2023 RAG 方法。

<Tip>
  如果您需要完全控制知识库搜索，可以通过以下签名传递您自己的 `retriever` 函数：

  ```python theme={null}
  def retriever(agent: Agent, query: str, num_documents: Optional[int], **kwargs) -> Optional[list[dict]]:
    ...
  ```

  该函数在调用 `search_knowledge_base()` 时被调用，Agent 使用它从知识库检索引用。
</Tip>

## 向量数据库

虽然任何类型的存储都可以充当知识库，但向量数据库提供了快速从密集信息中检索相关结果的最佳解决方案。以下是向量数据库在 Agent 中的使用方式：

<Steps>
  <Step title="分块信息">
    将知识分解成更小的块，以确保我们的搜索查询只返回相关结果。
  </Step>

  <Step title="加载知识库">
    将这些块转换为嵌入向量，并将其存储在向量数据库中。
  </Step>

  <Step title="搜索知识库">
    当用户发送消息时，我们将输入消息转换为嵌入，并在向量数据库中“搜索”最近邻。
  </Step>
</Steps>

<Note>
  知识过滤器目前支持以下知识库类型：<b>PDF</b>、<b>PDF\_URL</b>、<b>Text</b>、<b>JSON</b> 和 <b>DOCX</b>。
  有关更多详细信息，请参阅 [Knowledge Filters 文档](/filters/introduction)。
</Note>

## 示例：带 PDF 知识库的 RAG Agent

让我们构建一个 **RAG Agent**，它可以回答 PDF 中的问题。

### 步骤 1：运行 PgVector

我们将使用 `PgVector` 作为我们的向量数据库，因为它也可以为我们的 Agent 提供存储。

安装 [docker desktop](https://docs.docker.com/desktop/install/mac-install/) 并使用以下命令在端口 **5532** 上运行 **PgVector**：

```bash theme={null}
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 \
  agnohq/pgvector:16
```

### 步骤 2：传统 RAG

检索增强生成 (RAG) 是指 **“将相关信息塞入提示中”** 以改善模型的响应。这是一个包含 2 个步骤的过程：

1. 从知识库中检索相关信息。
2. 增强提示以向模型提供上下文。

让我们构建一个**传统 RAG** Agent，它能回答食谱 PDF 中的问题。

<Steps>
  <Step title="安装库">
    使用 pip 安装所需的库

    <CodeGroup>
      ```bash Mac theme={null}
      pip install -U pgvector pypdf "psycopg[binary]" sqlalchemy
      ```

      ```bash Windows theme={null}
      pip install -U pgvector pypdf "psycopg[binary]" sqlalchemy
      ```
    </CodeGroup>
  </Step>

  <Step title="创建传统 RAG Agent">
    创建一个名为 `traditional_rag.py` 的文件，其中包含以下内容

    ```python traditional_rag.py theme={null}
    from agno.agent import Agent
    from agno.models.openai import OpenAIChat
    from agno.knowledge.pdf_url import PDFUrlKnowledgeBase
    from agno.vectordb.pgvector import PgVector, SearchType

    db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
    knowledge_base = PDFUrlKnowledgeBase(
        # 从此 URL 读取 PDF
        urls=["https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"],
        # 将嵌入存储在 `ai.recipes` 表中
        vector_db=PgVector(table_name="recipes", db_url=db_url, search_type=SearchType.hybrid),
    )
    # 加载知识库：首次运行后注释掉
    knowledge_base.load(upsert=True)

    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        knowledge=knowledge_base,
        # 通过将 AgentKnowledge 中的引用添加到用户提示来启用 RAG。
        add_references=True,
        # 设置为 False，因为 Agent 默认设置为 `search_knowledge=True`
        search_knowledge=False,
        markdown=True,
        # debug_mode=True,
    )
    agent.print_response("How do I make chicken and galangal in coconut milk soup")
    ```
  </Step>

  <Step title="运行 Agent">
    运行 Agent（加载知识库需要几秒钟）。

    <CodeGroup>
      ```bash Mac theme={null}
      python traditional_rag.py
      ```

      ```bash Windows theme={null}
      python traditional_rag.py
      ```
    </CodeGroup>

    <br />
  </Step>
</Steps>

<Accordion title="如何使用本地 PDF" icon="file-pdf" iconType="duotone">
  如果您想使用本地 PDF，请改用 `PDFKnowledgeBase`

  ```python agent.py theme={null}
  from agno.knowledge.pdf import PDFKnowledgeBase

  ...
  knowledge_base = PDFKnowledgeBase(
      path="data/pdfs",
      vector_db=PgVector(
          table_name="pdf_documents",
          db_url=db_url,
      ),
  )
  ...
  ```
</Accordion>

### 步骤 3：Agentic RAG

对于上面的传统 RAG，无论信息是否与问题相关或有帮助，`add_references=True` 始终会将知识库中的信息添加到提示中。

而通过 Agentic RAG，我们让 Agent 决定**是否**需要访问知识库以及需要使用何种搜索参数来查询知识库。

设置 `search_knowledge=True` 和 `read_chat_history=True`，为 Agent 提供按需搜索其知识库和聊天记录的工具。

<Steps>
  <Step title="创建 Agentic RAG Agent">
    创建一个名为 `agentic_rag.py` 的文件，其中包含以下内容

    ```python agentic_rag.py theme={null}
    from agno.agent import Agent
    from agno.models.openai import OpenAIChat
    from agno.knowledge.pdf_url import PDFUrlKnowledgeBase
    from agno.vectordb.pgvector import PgVector, SearchType

    db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
    knowledge_base = PDFUrlKnowledgeBase(
        urls=["https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"],
        vector_db=PgVector(table_name="recipes", db_url=db_url, search_type=SearchType.hybrid),
    )
    # 加载知识库：首次运行后注释掉
    knowledge_base.load(upsert=True)

    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        knowledge=knowledge_base,
        # 添加一个搜索知识库的工具，以启用 Agentic RAG。
        search_knowledge=True,
        # 添加一个读取聊天记录的工具。
        read_chat_history=True,
        show_tool_calls=True,
        markdown=True,
        # debug_mode=True,
    )
    agent.print_response("How do I make chicken and galangal in coconut milk soup", stream=True)
    agent.print_response("What was my last question?", markdown=True)
    ```
  </Step>

  <Step title="运行 Agent">
    运行 Agent

    <CodeGroup>
      ```bash Mac theme={null}
      python agentic_rag.py
      ```

      ```bash Windows theme={null}
      python agentic_rag.py
      ```
    </CodeGroup>

    <Note>
      注意它何时搜索知识库和聊天记录
    </Note>
  </Step>
</Steps>

## 属性

| 参数                         | 类型                                    | 默认值     | 描述                                                                |
| -------------------------- | ------------------------------------- | ------- | ----------------------------------------------------------------- |
| `knowledge`                | `AgentKnowledge`                      | `None`  | 提供 Agent 使用的知识库。                                                  |
| `search_knowledge`         | `bool`                                | `True`  | 添加一个允许模型搜索知识库（即 Agentic RAG）的工具。在提供 `knowledge` 时默认启用。            |
| `add_references`           | `bool`                                | `False` | 通过将 AgentKnowledge 中的引用添加到用户提示来启用 RAG。                            |
| `retriever`                | `Callable[..., Optional[list[dict]]]` | `None`  | 获取上下文以添加到用户消息的函数。在 `add_references` 为 True 时调用此函数。                |
| `context_format`           | `Literal['json', 'yaml']`             | `json`  | 指定 RAG 的格式，可以是 "json" 或 "yaml"。                                   |
| `add_context_instructions` | `bool`                                | `False` | 如果为 True，则将使用上下文的说明添加到系统提示中（如果也提供了知识库）。例如：添加一个优先使用知识库信息而非训练数据的说明。 |

## 开发者资源

* 查看 [Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/agent_concepts/knowledge)