第 13 期 | 知识库构建：RAG 与长期文档管理 — Hermes Agent Hands-On Guide

好的，这是为 Hermes Agent 教程撰写的第 13 期文章。

副标题：整合向量数据库，利用 RAG (检索增强生成) 构建私人知识库，增强 AI 回答的事实准确度。

学习目标

在本期课程中，你将深入学习 Hermes Agent 的一项核心高级功能：知识库管理。完成本章后，你将能够：

理解 RAG 的工作原理：掌握 Retrieval-Augmented Generation (检索增强生成) 的核心思想，并理解它为何是解决大型语言模型 (LLM) 知识局限性的关键技术。
配置向量数据库：学会在 Hermes Agent 中配置并集成一个向量数据库 (Vector Database)，例如 ChromaDB，作为知识的持久化存储。
创建和管理知识库：通过 Hermes Agent CLI (命令行工具) 创建、索引、管理你的私有文档集合，构建一个或多个专属知识库。
赋能 Agent：将创建的知识库与特定的 Agent 实例关联，使其能够基于你的私有数据进行回答，显著提升回答的准确性和相关性。
验证 RAG 效果：通过实际对话，对比启用知识库前后 Agent 回答的差异，直观感受 RAG 带来的能力跃升。

核心概念讲解

在深入实战之前，我们必须理解驱动知识库功能的核心技术——RAG，以及它在 Hermes Agent 架构中的位置。

1. LLM 的困境：知识的“静止”与“遗忘”

标准的大型语言模型，如 GPT-4 或 Llama 3，尽管能力强大，但存在两个固有缺陷：

知识截止 (Knowledge Cutoff)：模型的知识被“冻结”在训练数据截止的那个时间点。它无法获知此后发生的新闻、发布的产品或更新的内部文档。
事实幻觉 (Hallucination)：在被问及不确定或其知识库中不存在的信息时，LLM 可能会“编造”听起来合理但完全错误的答案。
缺乏私有上下文 (Lack of Private Context)：模型对你的公司内部流程、项目文档、个人笔记等私有信息一无所知。直接向其提问这些内容，无法得到有效回答。

为了克服这些问题，业界提出了多种方案，而 RAG (Retrieval-Augmented Generation) 已被证明是其中最高效、最灵活的解决方案之一。

2. RAG (Retrieval-Augmented Generation) 工作流解析

RAG 的核心思想非常直观：不要只依赖模型“记忆”中的知识，而是在回答问题前，先让它“开卷查书”。这里的“书”就是我们为它准备的私有知识库。

整个 RAG 流程可以分为两个阶段：数据索引 (Indexing) 和 检索与生成 (Retrieval & Generation)。

阶段一：数据索引 (离线处理)

这个阶段的目标是将你的文档（如 .txt, .md, .pdf 文件）转化为可被机器高效检索的格式。

加载 (Load)：系统读取你指定的文档源。
切分 (Chunk/Split)：将长文档切分成更小的、有意义的文本块 (Chunks)。为什么要切分？因为：
- LLM 的上下文窗口 (Context Window) 有限，无法一次处理整本书。
- 更小的文本块能提供更精确的检索结果，避免无关信息干扰。
嵌入 (Embed)：使用一个 Embedding 模型将每个文本块转换为一个高维向量 (Vector)。这个向量可以被看作是文本块在“语义空间”中的数学坐标。语义上相似的文本块，其向量在空间中的距离也更近。
存储 (Store)：将所有文本块及其对应的向量存储到一个专门的数据库——向量数据库 (Vector Database) 中。这个数据库被高度优化，可以极速地进行向量相似度搜索。

阶段二：检索与生成 (在线处理)

当用户向 Agent 提问时，系统会执行以下步骤：

查询嵌入 (Embed Query)：使用与索引阶段相同的 Embedding 模型，将用户的提问也转换为一个向量。
检索 (Retrieve)：在向量数据库中，以用户问题的向量为基准，执行相似度搜索，找出与问题语义最相关的 Top-K 个文本块（例如，最相关的 3 个）。

增强 (Augment)：将检索到的这些文本块作为“上下文 (Context)”与用户的原始问题一起，组合成一个新的、更丰富的提示 (Prompt)。

原始 Prompt: "请问凤凰项目的负责人是谁？"

增强后 Prompt:

请根据以下上下文信息回答问题。如果信息不足，请说你不知道。
上下文:
- "文档A片段：...凤凰项目 (Project Phoenix) 的项目经理是 Alice Johnson，项目目标是在 Q4 2024 完成..."
- "文档B片段：...关于项目预算，请联系 Alice Johnson..."

问题:
请问凤凰项目的负责人是谁？

生成 (Generate)：将这个增强后的 Prompt 发送给 LLM。由于 LLM 得到了明确、相关的上下文，它就能像“开卷考试”一样，准确地回答出 "凤凰项目的负责人是 Alice Johnson"。

3. Hermes Agent 中的 RAG 架构

Hermes Agent 将上述复杂的 RAG 流程进行了优雅的封装，通过 config.yml 文件和 CLI 工具，让开发者可以轻松构建和使用知识库。

Knowledge Component: Hermes Agent 内置了知识库管理模块，负责处理文档的加载、切分、嵌入和存储。
Vector DB Provider: 通过配置文件，你可以指定使用的向量数据库类型。Hermes Agent 支持多种实现，例如本地文件型数据库 ChromaDB（适合快速原型和个人使用）和服务器型数据库 Qdrant（适合生产环境）。
Embedding Provider: 同样在配置中指定，你可以选择使用 OpenAI 的 text-embedding-ada-002，或者其他本地部署的 Embedding 模型来生成向量。
CLI 工具: hermes knowledge 命令集提供了创建、添加文档、列出和删除知识库的便捷操作。

现在，让我们通过实战来体验这一切。

💻 实战演示

我们将构建一个关于“凤凰项目 (Project Phoenix)”的内部知识库，并让 Agent 成为该项目的专家。

第一步：环境准备

首先，确保你已经安装了 Hermes Agent (参考第 01 期)。本次实战我们将使用 ChromaDB 作为向量数据库，因为它无需额外安装服务，可以直接通过 pip 包使用。

打开你的终端，激活 Hermes Agent 的 Python 环境，并安装 chromadb 依赖。

# 激活你的 Python 环境 (例如 venv 或 conda)
# source .venv/bin/activate

pip install chromadb

第二步：配置向量数据库与 Embedding 模型

打开 Hermes Agent 的核心配置文件 config.yml。我们需要配置两个部分：embedding 和 vector_db。

我们将使用 OpenAI 的 Embedding 模型，并指定 ChromaDB 作为向量数据库，数据将存储在本地的 ./data/chroma_db 目录中。

# config.yml

# ... 其他配置 ...

# Embedding Provider 配置
embedding:
  provider: openai
  # 确保你的环境变量 OPENAI_API_KEY 已设置
  # model: text-embedding-3-small # 或者其他 embedding 模型

# Vector Database 配置
vector_db:
  provider: chromadb
  # ChromaDB 的数据持久化路径
  path: ./data/chroma_db

# ... agents 和其他配置 ...

说明：

embedding.provider: openai：告诉 Hermes Agent 使用 OpenAI 的 API 来生成文本向量。请确保你的环境变量 OPENAI_API_KEY 已正确设置。
vector_db.provider: chromadb：指定使用 ChromaDB。
vector_db.path: 指定 ChromaDB 数据库文件的存储位置。Hermes Agent 启动时会自动创建这个目录。

第三步：准备知识库文档

创建一个用于存放知识库源文件的目录。

mkdir -p my_knowledge/project_phoenix

现在，在该目录中创建两个 markdown 文件，模拟项目文档。

文件 1: my_knowledge/project_phoenix/overview.md

# 凤凰项目 (Project Phoenix) 总览

凤凰项目是一个旨在重构公司核心交易系统的内部计划。

- **项目代号**: Phoenix
- **项目负责人**: Alice Johnson
- **技术栈**: Python, Go, Kubernetes
- **预计上线日期**: 2024年第四季度 (Q4 2024)

文件 2: my_knowledge/project_phoenix/qa.md

# 凤凰项目常见问题解答 (FAQ)

**Q: 项目的主要风险是什么？**
A: 主要风险在于数据迁移的复杂性以及与旧系统的兼容性问题。团队正在制定详细的回滚计划。

**Q: 如何获取项目状态更新？**
A: 每周五下午3点，Alice Johnson 会在 #project-phoenix 频道发布周报。

这些文件包含的信息是公开 LLM 不可能知道的，是验证我们知识库是否生效的完美测试用例。

第四步：创建与索引知识库

现在，我们使用 Hermes Agent CLI 来处理这些文档。

创建一个新的知识库

在终端中运行以下命令，创建一个名为 project_phoenix_kb 的知识库。
```
hermes knowledge create --name project_phoenix_kb --description "All internal documents related to Project Phoenix."
```
你会看到成功创建的提示。--name 是知识库的唯一标识符，--description 是一个方便人类阅读的描述。
向知识库中添加文档

接下来，我们将刚才创建的 my_knowledge/project_phoenix 目录下的所有文档添加到知识库中。
```
hermes knowledge add --name project_phoenix_kb --path ./my_knowledge/project_phoenix --recursive
```
命令解析:
- --name project_phoenix_kb: 指定要向哪个知识库添加文档。
- --path ./my_knowledge/project_phoenix: 指定文档所在的路径。
- --recursive: 如果目录中还有子目录，此选项会递归地添加所有文件。
执行此命令后，Hermes Agent 会在后台执行我们之前讨论的数据索引流程：
- 加载 overview.md 和 qa.md 文件。
- 将文件内容切分成合适的文本块。
- 调用 OpenAI API 将每个文本块转换为 Embedding 向量。
- 将文本块和向量存入 ChromaDB 中。
(可选) 查看已有的知识库

你可以随时使用 list 命令查看当前系统中存在的所有知识库。
```
hermes knowledge list
```

第五步：在 Agent 中启用知识库

知识库已经建好，但 Agent 默认并不会使用它。我们需要明确地将知识库与一个 Agent 关联起来。

再次编辑 config.yml，我们创建一个名为 phoenix_expert 的新 Agent，并为它配置 knowledge_bases 字段。

# config.yml

# ... 其他配置 ...

agents:
  - name: default
    # ... default agent 的配置 ...

  - name: phoenix_expert
    # 使用与 default 相同的 LLM provider 或自定义
    provider: openai_chat
    # 启用 RAG 功能
    enable_rag: true
    # 关联我们刚刚创建的知识库
    knowledge_bases:
      - project_phoenix_kb
    # 你可以为这个 Agent 设置一个特定的系统提示
    system_prompt: "你是一个凤凰项目 (Project Phoenix) 的专家，请根据提供的上下文信息准确回答问题。"

关键配置：

enable_rag: true: 显式开启该 Agent 的 RAG 功能。
knowledge_bases: ["project_phoenix_kb"]: 这是一个列表，将 project_phoenix_kb 知识库与 phoenix_expert 这个 Agent 绑定。一个 Agent 可以同时关联多个知识库。

第六步：测试与验证

一切准备就绪！现在启动 Hermes Agent，见证奇迹。

hermes start

待服务启动后，我们可以通过任何已配置的消息网关（如 Web UI、Telegram 等）进行测试。

测试场景 1: 对比实验 (询问默认 Agent)

首先，向没有配置知识库的 default Agent 提问。

你: Who is the project lead for Project Phoenix?

default Agent: I'm sorry, but I don't have access to real-time or private project information like the specific lead for "Project Phoenix." This information is likely internal to an organization.

这个回答是完全符合预期的。default Agent 没有任何关于这个项目的私有知识。

测试场景 2: 验证知识库 (询问专家 Agent)

现在，切换到我们精心打造的 phoenix_expert Agent，并提出同样的问题。

你: @phoenix_expert Who is the project lead for Project Phoenix?

phoenix_expert Agent: The project lead for Project Phoenix is Alice Johnson.

成功了！ Agent 准确地从我们提供的 overview.md 文件中检索到了信息并给出了正确答案。

让我们再试一个更复杂的问题。

你: @phoenix_expert When is the project expected to launch and how can I get status updates?

phoenix_expert Agent: Project Phoenix is expected to launch in Q4 2024. You can get status updates from the weekly report published by Alice Johnson every Friday at 3 PM in the #project-phoenix channel.

这个回答完美地融合了来自 overview.md (上线日期) 和 qa.md (获取更新的方式) 两个不同文档的信息。这充分证明了 RAG 流程的有效性：系统检索到了与问题最相关的多个文本块，并将它们一并提供给 LLM 作为上下文，从而生成了全面而准确的回答。

涉及命令

以下是本期教程中使用的核心命令汇总：

安装依赖:
```
pip install chromadb
```

创建知识库:

hermes knowledge create --name <knowledge_base_name> --description "<description>"

添加文档到知识库:

hermes knowledge add --name <knowledge_base_name> --path <path_to_docs> [--recursive]

列出所有知识库:
```
hermes knowledge list
```

删除知识库 (谨慎使用):

hermes knowledge delete --name <knowledge_base_name>

启动 Hermes Agent 服务:
```
hermes start
```

要点回顾

RAG 是关键：RAG 通过“检索-增强-生成”的模式，为 LLM 提供了外部、动态、私有的知识源，有效解决了知识截止和事实幻觉问题。
两阶段流程：RAG 的工作流分为离线的数据索引（加载、切分、嵌入、存储）和在线的检索生成（查询嵌入、检索、增强、生成）。
配置驱动：在 Hermes Agent 中，知识库功能是高度配置化的。你只需在 config.yml 中声明 embedding 和 vector_db 的提供者即可。
CLI 管理：Hermes Agent 提供了强大的 hermes knowledge 命令行工具，使得知识库的创建、文档添加和生命周期管理变得简单直观。
Agent 绑定：知识库必须与特定的 Agent 实例通过 knowledge_bases 字段进行关联，才能被该 Agent 使用，这提供了极大的灵活性。
效果显著：通过实战对比，我们可以清晰地看到，启用了 RAG 的 Agent 在处理特定领域或私有问题时，其事实准确性和信息相关性远超通用 LLM。

通过掌握 Hermes Agent 的知识库功能，你已经解锁了构建真正有用的、专家级 AI 助手的核心能力。无论是打造企业内部的智能问答机器人、个人的知识管理助手，还是特定领域的智能客服，RAG 都将是你手中最强大的工具之一。

参考资料

Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks - 原始 RAG 论文
Hermes Agent Official Documentation - (假设的) Hermes Agent 官方知识库文档
ChromaDB Documentation - ChromaDB 官方文档
What Are Embeddings? - 关于 Embeddings 的一篇优秀入门文章