ewoooc/docs/adr/ADR-002-pgvector-as-sole-km-store.md

ADR-002：pgvector 作為唯一 KM 向量庫

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

Context

KM（知識管理）需要向量化檢索能力來支援 RAG（Retrieval-Augmented Generation）。市面選項：pgvector、ChromaDB、Qdrant、Weaviate、Milvus。

現況：MOMO Pro 已使用 PostgreSQL，且生產環境的 PG 實例（192.168.0.188）映像為 pgvector/pgvector:pg14 —— 即 pgvector 擴充已內建。

Decision

KM 唯一向量庫 = pgvector。禁用任何其他向量資料庫（ChromaDB、Qdrant、Weaviate、Milvus）。

Alternatives Considered

方案	拒絕原因
ChromaDB（輕量獨立）	必須在兩個 DB 之間 JOIN，「結構化篩選 + 語意檢索」要兩階段，痛苦
Qdrant（性能最好）	需獨立部署、運維成本、與現有 PG 切割記憶
Weaviate / Milvus	過度工程化，超出當前需求量

Consequences

Positive

• 零部署：pgvector 已在 192.168.0.188 PG 實例上運行

• 零維運：沿用既有備份/監控/擴容機制

• 單條 SQL 同時做語意檢索 + 結構化篩選：

  SELECT insight_text, generated_at, ai_model
  FROM ai_insights
  WHERE insight_type = 'monthly'
    AND created_at > NOW() - INTERVAL '90 days'
    AND status = 'approved'
  ORDER BY embedding <-> :query_vector
  LIMIT 5;
  

• 事務一致性：洞察寫入 + embedding 寫入同一 transaction，原子性

Negative / Trade-offs

• pgvector 在百萬向量量級時，HNSW 索引需要調優（IVFFlat or HNSW）
• 與專業向量庫相比，cluster 化方案較少（但短中期不需要）

Implementation Notes

-- 1. 確認擴充
CREATE EXTENSION IF NOT EXISTS vector;

-- 2. ai_insights 表加 embedding 欄
ALTER TABLE ai_insights
  ADD COLUMN embedding vector(1024);  -- bge-m3 維度（見 ADR-003）

-- 3. HNSW 索引（v0.5.0+）
CREATE INDEX ON ai_insights
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

Related ADRs

• ADR-001：三 Agent 分工
• ADR-003：embedding 模型選型決定向量維度