2026年9月17日

hermes-memory-pgvector v0.5.3：使用你自己的嵌入模型

hermes-memory-pgvector v0.5.3：使用你自己的嵌入模型

hermes-memory-pgvector 是开源插件，为一组 hermes-agent 代理在 PostgreSQL 和 pgvector 上提供共享、持久的记忆。0.5.3 版本已在 PyPI 发布，并移除了插件中最后一个硬编码假设：由哪种嵌入模型将你的记忆转换为可搜索向量。

为什么会有这个版本

直到现在，嵌入模型实际上都是固定的。插件会将每个向量与字面量 768 维进行检查，这正是默认 nomic-embed-text 模型的大小，而且它没有办法传递 API 密钥，因此托管嵌入服务一直无法使用。

这对我们自己的部署来说已经成为一个实际限制。我们把记忆数据库迁移到了 OpenAI 的 text-embedding-3-small，通过 OpenRouter 提供服务，因为托管端点始终保持可用，而自托管模型可能需要几秒钟才能唤醒。数据库列改为了 1536 维，而插件没有能够跟随这一变化的设置。v0.5.3 增加了这些设置。

三个新设置

  • embed_dim 是你的模型返回的向量长度。默认值是 768，因此现有部署不受影响。现在每个嵌入仍会被检查，只是改为依据这个值，因此不匹配会立即失败，而不会一直到数据库层面才出错。
  • embed_api_key_env 是一个环境变量的名称，其中保存着 bearer token，例如 OPENROUTER_API_KEY。密钥不会写入配置文件；它会在调用时读取，并且永远不会被记录日志。
  • embed_protocol 是 openai、ollama 或 auto。默认值 auto 会先尝试 OpenAI 兼容路径，然后回退到 Ollama 的原生 API。对于托管服务，选择 openai 意味着认证或模型错误会按原样报告，而不会被 fallback 伪装成一个 404。

通过 OpenRouter 将插件指向 text-embedding-3-small 现在看起来是这样的：

plugins:
  pgvector:
    embed_url: "https://openrouter.ai/api"
    embed_model: "openai/text-embedding-3-small"
    embed_dim: 1536
    embed_api_key_env: "OPENROUTER_API_KEY"
    embed_protocol: "openai"

两个即使你什么都不改也很重要的修复

  • hermes-agent 插件加载器下的嵌入。 在加载插件后，宿主的加载器会把每个子模块重新附加到包上，其中包括一个名为 embed 的模块。这替换了插件所调用的函数，因此嵌入会因 TypeError: 'module' object is not callable 而失败，记忆写入也不会被存储为文本，而是被丢弃。现在插件改为调用一个加载器永远不会触碰的私有别名。
  • 慢速端点。 服务器虽然接受了连接，但在超时之后才返回响应，这会抛出一个裸 TimeoutError，从而绕过插件的错误处理：没有 fallback，没有重试，并且写入会丢失。现在它会像其他所有端点失败一样被处理。

升级

默认值没有变化：768 维、没有认证头、auto 协议，并且没有新的数据库迁移。使用以下命令升级：

pip install -U hermes-memory-pgvector

切换到具有不同向量大小的模型是一次数据库迁移，而不仅仅是修改配置，因为来自两个不同模型的向量不可比较。README 中详细说明了流程：修改列类型，使用 hermes-pgvector backfill 重新嵌入现有行，然后重建 HNSW 索引。

源代码和完整配置参考在 GitHub 上：

👉 github.com/andreab67/hermes-memory-pgvector

← 返回博客