Hermes Agent 知识库搭建教程：文档上传、分段、检索和问答测试

如果你正在用 Hermes Agent 做 AI Agent 项目，知识库是绕不开的一环。文档怎么上传、分段策略怎么调、检索能不能命中、问答测试是否准确——这几个步骤踩坑的人不少。这篇就手把手走一遍 Hermes Agent 知识库搭建流程，从原始文档到可检索问答，所有命令和配置都实测过。

Hermes Agent 知识库搭建教程：文档上传与分段

准备环境：确保 Hermes Agent 已部署并运行

先确认你的 Hermes Agent 服务在 VPS 上跑起来了。如果还没部署，参考官方仓库用 Docker 快速启动（这里不赘述）。启动后，通过 `docker ps` 检查容器状态，确保 `hermes-agent` 和对应的向量数据库服务（如 Qdrant 或 Chroma）都在运行。

docker ps | grep hermes

知识库功能依赖向量数据库，默认配置通常用 Qdrant。检查 `.env` 或 `config.yaml` 里 `VECTOR_DB` 的地址和端口是否正确，比如 `localhost:6333`。

上传文档：支持格式与路径

Hermes Agent 知识库支持常见文本格式：`.txt`、`.md`、`.pdf`、`.docx` 等。上传方式有两种：

1.API 上传：通过 HTTP 请求将文档内容 POST 到知识库端点。
2.本地目录挂载：在 Docker 启动时挂载一个包含文档的目录，代理会自动扫描并导入。

推荐用目录挂载方式，批量导入更高效。在 `docker-compose.yml` 的 `volumes` 下添加映射：

yaml
volumes:
– ./docs:/app/docs # 把本地 ./docs 目录映射到容器内

重启容器后，Hermes Agent 会自动读取 `/app/docs` 下的文件并入库。如果没自动触发，检查日志：

docker logs hermes-agent –tail 50 | grep -i "ingest"

老鸟叮嘱：PDF 文件如果扫描版（图片型），Hermes Agent 默认不支持 OCR，需要先转成文本。建议用 `pdftotext` 预处理一下。

分段策略：控制块大小与重叠

文档入库前会按 chunk 分割，分段参数直接影响检索质量。默认分段大小是 512 tokens，重叠 64 tokens。如果你文档是技术手册（长段落多），建议调大 chunk 到 1024，重叠 128；如果是问答型短文本，保持 256 更精准。

修改 `config.yaml` 中的 `chunking` 部分：

yaml
knowledge_base:
chunk_size: 512 # 每个块的最大 token 数
chunk_overlap: 64 # 相邻块重叠 token 数
separator: "\n" # 分段分隔符，默认换行

改完重启容器生效。注意：chunk 太小会导致上下文断裂，太大则检索时容易混入无关内容。

老鸟叮嘱：不要一次把整个技术文档当一个大块。分段后务必检查实际切分效果。可以用调试模式打印每个 chunk 的前 100 字符：

curl -X POST http://localhost:8000/knowledge/debug -H "Content-Type: application/json" -d '{"file":"docs/manual.pdf"}'

检索配置：向量模型与相似度阈值

选择嵌入模型

Hermes Agent 支持多种嵌入模型，默认用 `all-MiniLM-L6-v2`（轻量，适合 VPS）。如果你 VPS 内存小于 4GB，别换大模型，否则 OOM 频繁。在 `config.yaml` 中指定：

yaml
embedding:
model: "all-MiniLM-L6-v2" # 或 "text-embedding-ada-002"（需 API Key）
device: "cpu" # 无 GPU 就用 cpu

老鸟叮嘱：如果用 OpenAI 的 `text-embedding-ada-002`，必须配好 `OPENAI_API_KEY`，且每次检索会消耗 token 计费。个人实验建议本地模型，免费且可控。

设置检索相似度阈值

检索时，知识库会返回与 query 向量最相似的 chunk，默认 top_k=5，相似度阈值 0.7。如果文档内容专业性强，调低阈值到 0.5 能召回更多相关片段；如果噪音多，调高到 0.85 提高精准度。

yaml
retrieval:
top_k: 5
similarity_threshold: 0.7

测试时可以用 API 直接查：

curl -X POST http://localhost:8000/knowledge/query -H "Content-Type: application/json" -d '{"query":"如何配置反向代理","top_k":3}'

如果返回为空，先检查文档是否已索引，再降低阈值试试。

问答测试：对接 Agent 对话

配置知识库作为 Agent 的上下文

在 Hermes Agent 的 `agent` 配置中，启用 `knowledge_base` 插件：

yaml
agent:
plugins:
– knowledge_base
knowledge_base:
enabled: true
retrieval_mode: "hybrid" # 混合检索（向量+关键词），推荐

重启后，Agent 在回答用户问题时会自动查询知识库，把相关 chunk 拼入 prompt。测试一个常见问题：

curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" -d '{"message":"Hermes Agent 如何部署？"}'

观察返回的 `answer` 里是否包含了知识库中的内容。如果 Agent 回答“我不知道”，说明检索失败或 chunk 不相关。

老鸟叮嘱：知识库问答的准确性高度依赖文档质量和分段粒度。建议先用 2-3 个典型问题做回归测试，反复调整 chunk 和阈值，直到满意再正式使用。

老鸟叮嘱：Hermes Agent 知识库避坑清单

1.文档乱码：上传的文档编码必须是 UTF-8，GBK 或 ISO-8859-1 会导致分段异常。用 `file -i 文档.md` 查看编码。
2.内存不足：向量模型加载和文档索引都很吃内存。4GB 内存的 VPS 最多处理 50MB 纯文本，超过建议换更大配置或分批导入。
3.端口放行：如果知识库 API 需要外部访问，务必在防火墙放行 8000 端口，但不要暴露到公网——用 Nginx 反向代理加 IP 白名单。
4.向量数据库持久化：Docker 重启后向量数据会丢失，务必挂载持久化卷。Qdrant 默认数据在 `/qdrant/storage`，在 `docker-compose.yml` 里映射出来。
5.不要用 root 跑服务：创建专用用户 `hermes`，避免权限漏洞。

FAQ

Q1：Hermes Agent 知识库支持哪些文件格式？
A：支持 .txt、.md、.pdf、.docx、.csv 等常见文本格式。图片型 PDF 需先 OCR 转文本。

Q2：上传文档后多久能检索到？
A：文档入库是异步的，通常几秒到几十秒（取决于文件大小和 VPS 性能）。查看日志确认 `Ingest complete` 后再测试。

Q3：分段大小设多少合适？
A：技术文档建议 512 tokens，问答类文档 256 tokens。重叠设为 chunk_size 的 12.5%-25%。

Q4：检索结果不准确怎么办？
A：先检查 chunk 是否切碎了关键信息，然后调低相似度阈值或增大 top_k。如果还是不行，考虑更换更强的嵌入模型。

Q5：知识库能对接外部 API 吗？
A：Hermes Agent 知识库是内置模块，不支持直接对接外部知识库 API。但可以通过自定义插件扩展，需要修改源码。

Q6：VPS 配置最低多少能跑知识库？
A：2 核 4GB 内存可稳定运行本地嵌入模型和 50MB 以内的文档库。超过 100MB 建议 8GB 内存。

知识库搭建完成后，记得定期更新文档并重新索引。别等到用户问出过时信息才去排查检索逻辑。Hermes Agent 的灵活度很高，但知识库质量最终还是取决于你喂进去的内容和分段策略。多测几轮，找到适合你场景的参数组合。

—

**相关阅读：**

– [Hermes Agent VPS 部署教程：Docker Compose 安装和初始化配置](https://www.zhujixuan.com/jishujiaocheng/9872.html)
– [VPS部署AI工具100讲：AI Agent、Codex、Claude Code、Hermes Agent、Ollama与自动化工作流实战教程](https://www.zhujixuan.com/jishujiaocheng/9606.html)
– [VPS 部署 AI 工具需要哪些基础？Linux、Docker、Nginx 和域名配置入门](https://www.zhujixuan.com/jishujiaocheng/9747.html)