企业官网建设流程全解析

1. 从一次检索翻车说起：Hermes 知识库到底该怎么选

如果你正在用 Hermes 搭本地知识库，大概率卡在同一个岔路口：检索侧到底用 qmd 这套开箱即用的混合搜索，还是自己拿 bge-m3 拼一套 Dense + Sparse 的经典 RAG？我最初也是两边都试，结果一次查询把两个方案的差异暴露得很彻底——问“SSH 配置审计怎么做”，bge-m3 自组方案召回了一堆讲“远程登录安全”的泛泛文档，而 qmd 直接把sshd_config、authorized_keys、端口检查那几篇精准推到了前面。原因不复杂：qmd 内部把 BM25 全文检索、向量语义检索、查询扩展、LLM 重排四件事打包成了一条固定流水线，而 bge-m3 只负责其中“向量”这一环，剩下的全靠你自己接。

这篇就围绕 Hermes 本地 RAG 全栈选型展开，重点拆 qmd 与 bge-m3 在 GGUF 量化下的检索性能与资源占用差异，并给出一套可复制的config.toml与settings.json配置骨架。适合谁看：正在自建知识库、机器没有独显、又不想把文档外发的开发者。全文会落到具体命令、参数和排障动作，你照着改路径就能跑。检索侧我最终选了 qmd 本地闭环，生成侧走远程 API，中间用 TaoToken 统一 Key 通道收口，下面一步步来。

2. 前置准备：TaoToken 统一 Key 与本地环境骨架

在动检索之前，先把“生成侧”的通道理顺，否则你调完检索还得回头补 API 配置。TaoToken 在这里的角色是统一入口：一个 Key 覆盖多家模型，省得你在 Hermes 的config.yaml里为每个 provider 维护一套 base_url 和密钥。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个地址不加 UTM，直接填进配置）。

你需要先拿到 Key，再去控制台确认模型可用性。拿 Key 的路径是 API Keys 页面，接入文档在 doc 里，模型可用性可以在模型对话里先手动验证一轮。这三步做完，再回到本地环境。

本地环境这边，Hermes 的检索侧依赖 Node 运行时和 qmd 的 MCP server。先确认版本：

node -v # 期望 v22.x，qmd 的 cli 依赖较新的 node-llama-cpp npm ls -g @tobilu/qmd # 没装的话 npm install -g @tobilu/qmd

qmd 的三个 GGUF 模型默认落在~/.cache/qmd/models/，首次索引会自动拉取。如果你网络环境拉取慢，可以提前手动放到该目录，文件名必须严格匹配：embeddinggemma-300M-Q8_0.gguf、qmd-query-expansion-1.7B-q4_k_m.gguf、qwen3-reranker-0.6b-q8_0.gguf。这三个文件加起来约 2.1GB，是后面所有性能数字的基础。

注意：qmd 的检索链路完全本地，不经过任何远程 API。生成侧才走 TaoToken 通道，两者互不影响，排障时先分清是哪一侧的问题。

3. 可复制配置：config.toml 与 settings.json 骨架

Hermes 的配置分两层：~/.hermes/config.yaml管 MCP server 注册和模型 provider，项目侧的config.toml和settings.json管检索参数与运行时行为。先给 MCP 注册骨架，把 qmd 挂上去：

# ~/.hermes/config.yaml mcp_servers: qmd: command: /home/yourname/.nvm/versions/node/v22.22.2/bin/node args: - /home/yourname/.nvm/versions/node/v22.22.2/lib/node_modules/@tobilu/qmd/dist/cli/qmd.js - mcp timeout: 300 model: provider: taotoken name: MiniMax-M2.7-highspeed base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY}

timeout: 300是给 reranker 留的余量，纯 CPU 上重排 40 个候选文档确实要几秒，超时设小了会偶发中断。api_key用环境变量注入，别硬编码进文件。

接着是检索侧的config.toml，控制索引与切分行为：

# ~/.hermes/qmd/config.toml [index] collections = ["hermes-kb", "hermes-topics"] db_path = "~/.cache/qmd/index.db" chunk_size = 800 chunk_overlap = 80 respect_headings = true protect_code_blocks = true [search] top_k = 5 fusion_candidates = 30 rerank = true rerank_context = 1024 [models] embedding = "embeddinggemma-300M-Q8_0.gguf" expansion = "qmd-query-expansion-1.7B-q4_k_m.gguf" reranker = "qwen3-reranker-0.6b-q8_0.gguf"

respect_headings = true是按标题层级切分，避免把“执行步骤”和“注意事项”切进同一个 chunk；protect_code_blocks = true保证代码块不被拦腰截断。fusion_candidates = 30是进入 reranker 的候选数，这个值直接决定重排耗时。

最后是settings.json，管运行时和自动维护：

{ "knowledge_dirs": [ "/home/yourname/Hermes/knowledge_base", "/home/yourname/.hermes/skills" ], "auto_reindex": { "enabled": true, "size_delta_mb": 20 }, "generation": { "provider": "taotoken", "fallback_model": "kimi-k2.6", "max_output_tokens": 300 } }

size_delta_mb: 20是自动重建索引的阈值，对应几十篇新增或大改文档，既不会因小改动频繁重建，也不会让新文档长期未索引。max_output_tokens: 300是给纯 CPU 场景留的响应余量，生成阶段控制在 300 token 内，端到端延迟才稳。

4. 验证请求：跑通一次完整检索链路

配置写完别急着信，先验证。第一步看索引状态：

qmd status # 期望输出类似： # 总文档数: 1972 # 向量索引: 已启用 # 需要嵌入: 0 # 集合: hermes-kb (986 docs) / hermes-topics (986 docs)

需要嵌入不为 0 说明还有文档没入库，等索引跑完再继续。第二步直接调一次混合检索，验证三层流水线是否都活着：

qmd query "SSH 安全配置审计" --top-k 5 --rerank true

正常返回应该包含sshd_config、authorized_keys相关片段，且顺序合理。如果返回结果里全是泛泛的“远程登录安全”，说明向量检索或重排没生效，回到第 5 节排查。

第三步验证生成侧通道。用 TaoToken 的模型对话先手动确认模型可用，再在 Hermes 里发一条需要检索的任务：

# 在 Hermes 会话中 /harness status # 触发一次需要知识库的任务，观察是否先检索后生成

成功的结果是：检索侧 1–1.5 秒返回候选（不含 reranker），含 reranker 约 3–6 秒；生成侧 1–3 秒返回。端到端 3–6 秒属于正常区间。如果生成侧报 401 或模型不存在，去 API Keys 和接入文档核对 Key 与 base_url；如果检索侧超时，先看qmd status的待嵌入数量。

提示：MiniMax 这类远程 provider 偶尔会“缺斤少两”，某个模型实际不可用但不报错。我后来校验时才发现qwen3-reranker-0.6b没被正确加载，重排一直静默跳过。养成习惯：每次改完配置，用qmd status加一次真实查询双重确认。

5. 本篇常见错排查

报错一：name 'StdioServerParameters' is not defined。这是 MCP 依赖没装全，在 Hermes 里用 terminal 工具执行pip install mcp或对应包管理器补上。skill 文档里hermes-mcp-debug/SKILL.md有完整排查步骤，Agent 读到后会自动处理。

报错二：检索结果全是泛泛文档，精准术语召不回。先确认respect_headings和protect_code_blocks是否为 true，切分方式错了会破坏语义结构。再确认rerank是否真的生效——如果 reranker 模型文件缺失，qmd 可能静默降级。用qmd status看模型加载状态，缺文件就补到~/.cache/qmd/models/。

报错三：查询延迟暴涨到 10 秒以上。大概率是fusion_candidates设太大，或者误用了 7B 级别的模型做嵌入/重排。qmd 的平衡点是 300M 嵌入 + 1.7B 扩展 + 0.6B 重排，换大模型延迟会失控。把fusion_candidates压回 30，rerank_context保持 1024。

报错四：内存占用超过 4GB。检查是不是同时跑了 Ollama 和 qmd。qmd 检索侧约 2.5–3GB，如果还挂着本地生成模型，内存会叠加。我的做法是检索本地、生成远程，两者不在一台机器上抢内存。

报错五：自动重建索引不触发。确认settings.json里knowledge_dirs路径正确，且size_delta_mb阈值没设得过大。20MB 是个经验值，文档更新频繁可以降到 10MB。

6. 选型收口：检索本地化，生成云化

回到最初的问题：qmd 还是 bge-m3？我的结论是，如果你要的是“开箱即用、低维护、隐私可控”，qmd 的三层混合流水线在 2GB 内存内就完成了 bge-m3 自组方案需要嵌入 + 扩展 + 重排 + 向量库四套组件才能拼出的效果。bge-m3 的优势在于多语言和多粒度表示，适合你要自己掌控每一环、且愿意承担组合复杂度的场景；但每多一个外部组件，就多一层配置和一种故障模式，我折腾过 ollama+bge-m3、知识图谱，最后都回滚了。

生成侧我走 TaoToken 统一通道，一个 Key 覆盖 MiniMax 和 kimi 作为 fallback，省去多 provider 维护。如果你也在搭 Hermes 本地 RAG，建议先把检索侧用 qmd 跑通，再通过 API Keys 配好生成通道，接入文档里有完整的 base_url 和参数说明。长期做编码或 Agent 任务的，可以看 Coding Plan 把额度固定下来；只是想先验证模型可用性，模型对话里手动试一轮最快。检索本地、生成云化，这套组合在老破旧笔记本上跑下来，是当前最务实的平衡点。