Hermes Bridge 嵌入模型离线部署：解决反复重启的联网依赖

问题

Hermes 启动时，Bridge 模块（负责嵌入向量生成）会自动下载嵌入模型。如果网络不通或下载慢，Bridge 就会反复重启：

[bridge] Downloading embedding model...
[bridge] Connection timeout, retrying...
[bridge] Retry 1/3 failed...
[bridge] Bridge restarting...

循环往复，最后 Hermes 的 Bridge 功能不可用。

原因

Bridge 使用 @xenova/transformers.js（Node.js 版的 transformers）加载嵌入模型。首次启动时，它会从 HuggingFace Hub 下载模型文件。

默认的下载源是 HuggingFace（huggingface.co），国内访问慢、且经常不稳定。

解决方案

方案一：设置镜像源（最简单）

通过环境变量指定 HuggingFace 镜像：

export HF_ENDPOINT=https://hf-mirror.com

然后重启 Hermes。首次启动时 Bridge 会从镜像站下载模型，速度快很多。

方案二：预下载模型到本地缓存

先手动把嵌入模型下载到 transformers.js 的缓存目录：

# 找到 transformers.js 的缓存路径
# 通常是 ~/.cache/huggingface/hub/ 或 ~/.cache/transformers/

# 预下载 all-MiniLM-L6-v2（Hermes 默认嵌入模型）
npx -y @xenova/transformers-cli download Xenova/all-MiniLM-L6-v2

下载完成后，Bridge 启动时检测到本地已有缓存，不会再联网下载。

方案三：完全离线模式

在配置文件中指定本地模型路径：

bridge:
  embedding:
    model: /path/to/local/embedding/model
    local: true

注意：这种方式需要确认 Hermes 版本是否支持 local 参数，部分版本需要通过环境变量或代码修改来实现。

验证 Bridge 状态

Bridge 正常工作时的日志：

[bridge] Embedding model loaded: all-MiniLM-L6-v2
[bridge] Bridge ready on port 7188
[bridge] Memory system initialized

如果看到 Downloading embedding model... 后卡住或报错，说明网络有问题。

推荐方案

对于大多数场景，方案一（镜像源） 就够了：

# 加到启动脚本或 systemd 配置中
export HF_ENDPOINT=https://hf-mirror.com
hermes

如果网络条件特别差，用方案二预下载。

嵌入模型的作用

Bridge 的嵌入模型主要用于：

1. 记忆检索：将输入文本转为向量，从记忆库中搜索相关内容
2. 技能匹配：将用户请求转为向量，匹配最相关的技能
3. 上下文压缩：压缩历史消息时保留语义信息

没有 Bridge，Hermes 的长期记忆和智能匹配功能就会失效。

缓存占用

嵌入模型 all-MiniLM-L6-v2 的大小：

占用不大，不用担心磁盘空间。

注意事项

1. 缓存位置：transformers.js 的缓存默认在 ~/.cache/huggingface/，删除后 Bridge 会重新下载。
2. 模型版本：Hermes 不同版本可能使用不同的嵌入模型，检查日志中的模型名称。
3. Node.js 版本：transformers.js 需要 Node.js 18+，确认版本兼容。
4. 内存占用：加载嵌入模型后额外占用 ~200MB 内存，对 20GB+ 内存的服务器不是问题。

总结

Bridge 的联网下载是单次问题，解决方法：

临时：export HF_ENDPOINT=https://hf-mirror.com（最快）
永久：预下载到本地缓存（一次搞定）
终极：本地模型路径配置（完全离线）

配好之后，Bridge 启动秒过，Hermes 的记忆和检索功能正常运作。