ewoooc/docs/adr/ADR-009-embedding-retry-queue-persistence.md

ADR-009：Embedding Retry Queue 持久化（DB-backed）

• Status: Accepted
• Date: 2026-04-19
• Decision Maker: 統帥
• Author: Claude

Context

ADR-007（AI 學習雙寫規範）要求 store_insight() 必須同時寫入 ai_insights DB 表與 embedding 欄位。 初版實作（2026-04-18）使用 Python queue.Queue() 記憶體佇列 + daemon thread worker：

_embedding_queue = Queue()                    # 記憶體
threading.Thread(target=_embedding_worker, daemon=True).start()

破洞：

• Python 進程重啟（K8s Pod 滾動重啟、gunicorn reload、OOM kill）→ queue 全部遺失
• Ollama 主機 192.168.0.111 短暫斷線 → 該筆 insight 永遠沒 embedding
• 違反 ADR-007「雙寫必達」精神：DB 有寫但 KM 沒寫 → RAG 永遠找不到這筆洞察

Decision

Embedding queue 改為 DB 持久化（embedding_retry_queue 表），worker 改為輪詢批次處理。

面向	記憶體 Queue（舊）	DB Queue（新）
持久化	❌ 重啟遺失	✅ 持久化
Retry	❌ 無	✅ attempts 欄位 + 上限 5 次
觀測性	❌ 無法查詢	✅ SQL 即可
跨進程	❌ 每 Pod 各自一份	✅ 多 Pod 共享同一 queue
吞吐	✅ 最快	✅ 批次 10 筆/分鐘已足夠

Schema（Migration 011）

CREATE TABLE embedding_retry_queue (
    id SERIAL PRIMARY KEY,
    target_table VARCHAR(50) NOT NULL,     -- ai_insights / conversations
    target_id INTEGER NOT NULL,
    text_content TEXT NOT NULL,
    model VARCHAR(50) DEFAULT 'bge-m3:latest',
    status VARCHAR(20) DEFAULT 'pending',  -- pending / processing / done / failed
    attempts INTEGER DEFAULT 0,
    last_error TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    processed_at TIMESTAMP
);

Worker 流程

Worker Loop (每 60 秒):
    SELECT * FROM embedding_retry_queue
      WHERE status='pending' AND attempts < 5
      ORDER BY created_at LIMIT 10
    ↓
    對每筆：
      UPDATE status='processing'
      呼叫 Ollama bge-m3 生成 embedding
      ↓
      成功 → UPDATE target SET embedding = vec;
             UPDATE retry_queue SET status='done', processed_at=NOW()
      失敗 → UPDATE retry_queue SET attempts=attempts+1, last_error=...
             若 attempts ≥ 5 → status='failed'（人工處理）

Consequences

Positive

• 即使 Pod 重啟也不會丟 embedding 任務
• 失敗累積可視化（可寫 Grafana 面板監控 status='failed' 數量）
• 多 Pod 共用同一 queue，不重複處理（processing 狀態互斥）

Negative

• 延遲從「毫秒」拉長到「最多 60 秒」（輪詢間隔）
  • 緩解：AI 洞察不需要即時 embedding，RAG 查詢 < 1 分鐘延遲可接受
• DB 需多一張表（小幅維運成本）

Related ADRs

• ADR-007（雙寫規範）：本 ADR 是其 Step 4 的持久化實作
• ADR-003（本地 embedding）：worker 呼叫的後端