背景

我的Hermes Agent配置了多個 profile，記憶系統(tǒng)選擇了基于 Honcho，通過 Postgres + pgvector 存儲對話歷史，用 LLM 提取觀察、歸納人格畫像。

但是Honcho的提示詞是英文的，它的API服務(wù)也是英文環(huán)境。在全中文使用環(huán)境下，當(dāng)然是中文語料、中文提示詞、中文能力強的大模型最合適，避免中-英-中互譯的信息偏移。本文是完整本地部署全中文 Honcho 的坑。注意一般4G內(nèi)存的服務(wù)器本地部署的話，內(nèi)存可能會爆。

架構(gòu)總覽

┌─────────────────────────────────────────────┐
│  Hermes Gateway (5 profiles)                │
│  └─ plugins/memory/honcho/  ← 插件層        │
│     └─ session.py, client.py, ...           │
├─────────────────────────────────────────────┤
│  Honcho API (FastAPI, 127.0.0.1:8000)       │
│  ├─ Honcho Deriver (觀察提取, src.deriver)   │
│  ├─ Honcho Embedding (768-dim, :8080)        │
│  ├─ Dialectic (辨證推理層)                   │
│  ├─ Dream (離線畫像演繹)                     │
│  └─ Summarizer (會話壓縮)                    │
├─────────────────────────────────────────────┤
│  PostgreSQL + pgvector                       │
│  └─ honcho 數(shù)據(jù)庫                            │
└─────────────────────────────────────────────┘

三個 systemd 服務(wù)：

部署前置坑一：pip install honcho裝錯包

PyPI 上有一個叫 honcho 的包——但它是一個進(jìn)程管理器（類似 Foreman），不是 Plastic Labs 的記憶系統(tǒng)。如果直接 pip install honcho，導(dǎo)入后沒有 src.main 模塊，uvicorn 啟動直接報 ModuleNotFoundError。

正確做法：從 GitHub 克隆源碼，用 pip install -e . 安裝。

git clone https://github.com/plastic-labs/honcho.git /opt/honcho2
cd /opt/honcho2 && pip install -e .

部署前置坑二：pgvector 擴展需單獨安裝

apt install postgresql 不會自動帶 pgvector。建表時才報錯，新手容易卡在這一步。

apt install -y postgresql-16-pgvector
su - postgres -c "psql -c 'CREATE EXTENSION vector;' -d honcho"

部署前置坑三：數(shù)據(jù)庫遷移未執(zhí)行

Honcho 源碼安裝后，數(shù)據(jù)庫是空的——沒有表結(jié)構(gòu)，API 啟動報 Required vector columns missing。必須運行 alembic 遷移：

cd /opt/honcho2
HONCHO_CONFIG_PATH=/opt/honcho2/config.toml alembic upgrade head

這步在 Honcho 官方文檔里有，但很容易在"先配 config 再遷移"的順序中被跳過。

部署前置坑四：Embedding 維度與數(shù)據(jù)庫不匹配

alembic 默認(rèn)創(chuàng)建 1536 維向量列（適配 OpenAI embedding），但 bge-base-zh-v1.5 是 768 維。API 啟動時會校驗維度，報 documents.embedding dim (1536) does not match EMBEDDING_VECTOR_DIMENSIONS (768)。

必須運行 Honcho 自帶的配置腳本：

echo y | HONCHO_CONFIG_PATH=/opt/honcho2/config.toml python scripts/configure_embeddings.py

安裝第一坑：DeepSeek structured output 模式

Honcho 的 Deriver、Dialectic、Dream、Summarizer 全都需要 LLM 輸出結(jié)構(gòu)化 JSON。Honcho 代碼里默認(rèn)使用 json_schema 模式（嚴(yán)格模式），但 DeepSeek API 不支持，只支持 json_object（寬松模式）。

癥狀：Deriver 啟動后無報錯但靜默失敗，數(shù)據(jù)庫沒有任何新 observation。

解決：在 Honcho 的 config.toml 中，所有 model_config 塊都要顯式指定：

[deriver.model_config]
transport = "openai"
model = "deepseek-v4-pro"
structured_output_mode = "json_object"  # ← 關(guān)鍵配置

涉及 7 個 model_config 塊（deriver、dialectic × 5 levels、summary、dream × 2）。

安裝第二坑：Embedding 模型的國內(nèi)下載

Honcho 需要本地 embedding 模型做語義搜索。選的是 BAAI/bge-base-zh-v1.5（768 維中文模型）。

問題 1：HuggingFace 國內(nèi)無法直連。

解決：代理下載，保存到 /opt/models/bge-base-zh-v1.5/。然后寫一個自定義 embedding 服務(wù)：

# /opt/embedding-server.py — 綁定本地模型文件
MODEL_NAME = "/opt/models/bge-base-zh-v1.5"
model = SentenceTransformer(MODEL_NAME)
@app.post("/v1/embeddings")
async def embed(req: EmbedRequest):
    vectors = model.encode(texts, normalize_embeddings=True)
    return {"data": [{"embedding": v.tolist(), "index": i} for i, v in enumerate(vectors)]}

Honcho 配置中指向此服務(wù)：

[embedding.model_config]
transport = "openai"
model = "bge-base-zh-v1.5"
[embedding.model_config.overrides]
base_url = "http://127.0.0.1:8080/v1"

問題 2 ：HF Hub 下載的模型目錄里大量使用 symlink。如果下載時經(jīng)過了代理中轉(zhuǎn)、或者復(fù)制目錄時沒帶 -L 參數(shù)，symlink 全部斷鏈。SentenceTransformer 加載時會報 file not found，但錯誤信息不直觀。

解決：不用 snapshot_download 緩存目錄，直接把模型文件平鋪到一個目錄下，json、safetensors、tokenizer 文件全部同級放置，零 symlink。

安裝第三坑：全鏈路 Prompt 中文化

Honcho 發(fā)布時默認(rèn) Prompt 全是英文。DeepSeek 對英文 Prompt 也能工作，但會產(chǎn)生中英混雜的輸出，在 dialectic（辨證推理）環(huán)節(jié)尤其嚴(yán)重——英文思考過程夾雜中文，最終 observation 質(zhì)量差。

發(fā)現(xiàn)的 9 處英文 Prompt：

改完之后重新跑。

安裝第四坑：Representation 緩存的幽靈數(shù)據(jù)

數(shù)據(jù)層干凈了，但 honcho_context 返回的還是舊的英文垃圾。

根因：Honcho 的 honcho_context/honcho_search 返回的是預(yù)計算并緩存的 representation。刪了舊 observation、跑了新 Dream 之后，這個緩存不會自動刷新。必須開新會話（/new）讓 Peer 對象重建，才會從數(shù)據(jù)庫重新拉取。

配置：Hermes 的 session_reset 有兩種觸發(fā)方式——每日凌晨 4 點自動重置，或空閑 1440 分鐘（24 小時）后自動重置。

安裝第五坑：Hermes Honcho 插件的 observer bug

開新會話之后，本以為一切正常，Dream 生成了純中文 observation，representation 也刷新了。但 honcho_context 仍然返回空。

定位：排查發(fā)現(xiàn) Honcho API 直接調(diào)用是正常的（observer=hermes, target=user 能查到數(shù)據(jù)），問題出在 Hermes 的 Honcho 插件層。

根因：plugins/memory/honcho/session.py第 736 行，_fetch_session_context 方法在調(diào)用 _fetch_peer_context 時，直接傳了 session.user_peer_id 作為 observer，而正確做法應(yīng)該是用 _resolve_observer_target 解析出真正的 observer（即 hermes 自身的 peer_id）。其他所有調(diào)用點（get_peer_card、honcho_search、honcho_reasoning）都正確使用了 _resolve_observer_target，唯獨這一處遺漏。

修復(fù)：

# Before（錯誤）:
user_ctx = self._fetch_peer_context(session.user_peer_id, ...)

# After（正確）:
observer_peer_id, target_peer_id = self._resolve_observer_target(session, "user")
user_ctx = self._fetch_peer_context(observer_peer_id, ...)

修復(fù)后已向上游 提交 PR #62982。

最終效果

honcho_context 返回：
├── Summary:     純中文會話摘要
├── Representation: 25 條中文用戶觀察
├── Card:        身份/屬性/偏好/關(guān)系（全中文）
└── Recent messages: 最近消息記錄

避坑清單

1. pip install honcho 裝的是錯誤包：PyPI 上的 honcho 是進(jìn)程管理器，必須從 GitHub 克隆
2. pgvector 擴展需單獨安裝：apt install postgresql 不帶 pgvector
3. 數(shù)據(jù)庫遷移必跑：alembic upgrade head，否則 API 直接拒啟動
4. Embedding 維度需適配：alembic 默認(rèn) 1536 維，bge 是 768 維，必須跑 configure_embeddings.py
5. DeepSeek 必須用 json_object，不能用默認(rèn)的 json_schema，涉及 7 個配置塊
6. Embedding 模型本地化：HF 不可直連，symlink 會斷鏈，平鋪目錄最可靠
7. Prompt 中文化是全局的：deriver + dreamer + dialectic + summarizer 共 9 處
8. Representation 緩存不會自動刷新：改完數(shù)據(jù)后要 /new
9. Hermes 插件的 observer 參數(shù)：必須走 _resolve_observer_target，不能直接傳 user_peer_id

到此這篇關(guān)于在Hermes Agent里搭建全中文 Honcho 記憶系統(tǒng)踩過的坑的文章就介紹到這了,更多相關(guān)Hermes 搭建全中文Honcho內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論