ewoooc/docs/adr/ADR-003-local-embedding-on-ollama.md

ADR-003：Embedding 本地化到 Ollama 主機

• Status: Accepted
• Date: 2026-04-18
• Decision Maker: 統帥（顧問補充建議第 1 條）
• Author: Claude

Context

ADR-001 把 embedding 工作分配給 Hermes（採集層）。但 embedding 引擎本身有兩個選項：

• 雲端 API（OpenAI text-embedding-3、Gemini embedding-001、Cohere）
• 本地（Ollama 上跑 embedding 模型）

目前 Hermes 已在 Ollama 上跑 hermes3:latest，主機（192.168.0.111 / 192.168.0.188）有 GPU 算力閒置。

Decision

Embedding 模型也跑在 Ollama 本地，禁用雲端 embedding API。

候選模型（擇一）：

• bge-m3（推薦）：1024 維、多語言、繁中表現好、上下文 8192 token
• nomic-embed-text：768 維、英文強、繁中弱
• mxbai-embed-large：1024 維、英文最強

首選 bge-m3（理由：繁中是 MOMO Pro 主要語言）。

Alternatives Considered

方案	拒絕原因
OpenAI text-embedding-3-small	$0.02/1M tokens，量大時也燒錢；資料外洩風險
Gemini embedding-001	配額限制、需要 API key 管理
Cohere embed-multilingual-v3	付費、外部依賴

Consequences

Positive

• 絕對零成本：embedding 量再大都 0 元
• 資料隱私：商品/業績/客戶相關資訊永不離開內網
• 零延遲：本地呼叫 < 100ms vs 雲端 500ms+
• 無配額限制：可一次跑大量 batch（半夜重新 embedding 整個 KM）

Negative / Trade-offs

• Ollama 主機 RAM/GPU 壓力增加（需確認硬體容量）
• 若想換模型，需先 pull 到 Ollama 再切換（雲端 API 換模型只改 model_name）
• 模型品質可能略低於最新雲端模型（但 bge-m3 已是業界一流）

Implementation Notes

# 在 Ollama 主機 pull 模型
ollama pull bge-m3:latest

# Hermes 服務內呼叫
curl http://192.168.0.111:11434/api/embeddings \
  -d '{"model":"bge-m3","prompt":"商品策略矩陣分析"}'

# services/openclaw_learning_service.py 內
def embed_text(text: str) -> list[float]:
    r = requests.post(
        f"{OLLAMA_HOST}/api/embeddings",
        json={"model": "bge-m3", "prompt": text},
        timeout=30,
    )
    return r.json()["embedding"]  # 1024 dim

對應 pgvector 表設計：

ALTER TABLE ai_insights ADD COLUMN embedding vector(1024);

Related ADRs

• ADR-001：三 Agent 分工（Hermes 採集層）
• ADR-002：pgvector 儲存層