# 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

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

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

```python
# 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 表設計：
```sql
ALTER TABLE ai_insights ADD COLUMN embedding vector(1024);
```

## Related ADRs

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