Hindsight¶
概述¶
Hindsight 是專為 AI Agent 設計的記憶系統，提供 recall、retain、operations、recover 四類 API，讓 Agent 可以寫入重要資訊、按情境召回舊記憶、管理記憶生命週期，以及在異常或遺漏時執行復原。系統部署於 cf_network 固定 IP 172.21.0.79，後端整合 LiteLLM、pg-main PostgreSQL、e5-large embeddings 與 RRF 排序，適合用於需要長期記憶的對話代理與自動化任務。
架構¶
Hindsight 主要由以下部分組成：
- Hindsight API：對外提供記憶操作介面，接收 Agent 請求。
- LiteLLM：作為 LLM gateway，統一處理模型呼叫、重試與 fallback。
- pg-main：主要 PostgreSQL 資料庫，負責儲存記憶、metadata 與操作日誌。
- e5-large embeddings：將記憶內容轉換為向量，支援語意檢索。
- RRF（Reciprocal Rank Fusion）：混合關鍵字與向量檢索結果，提升召回排序品質。
Hindsight 使用 172.21.0.79 作為內部固定 IP，相關服務需在同一 Docker network 內才能互相連線。
部署（Docker Compose 片段）¶
以下為精簡可用的 Compose 設定，假設 pg-main 與 litellm 已在 cf_network 內：
services:
hindsight:
image: ghcr.io/vectorize-io/hindsight:latest-slim
container_name: hindsight
networks:
cf_network:
ipv4_address: 172.21.0.79
environment:
TZ: Asia/Hong_Kong
HINDSIGHT_API_DATABASE_URL: postgresql://hindsight:${HINDSIGHT_DB_PASSWORD}@pg-main:5432/hindsight
HINDSIGHT_API_LLM_PROVIDER: litellm
HINDSIGHT_API_LLM_BASE_URL: http://litellm:4000
部署前請在 .env 設定 HINDSIGHT_DB_PASSWORD，並確保 pg-main 的 PostgreSQL 已建立 hindsight 資料庫與使用者。
配置與環境變數¶
常用環境變數：
HINDSIGHT_API_DATABASE_URL：PostgreSQL 連線字串，指向pg-main:5432/hindsight。HINDSIGHT_API_LLM_PROVIDER：設定為litellm，使 Hindsight 透過 LiteLLM 存取模型。HINDSIGHT_API_LLM_BASE_URL：LiteLLM 服務位址，例如http://litellm:4000。TZ：建議設定Asia/Hong_Kong，確保日誌與排程時區正確。
若需要調整 embedding 模型、RRF 權重或 API key，請參考 Hindsight 官方文件，並以環境變數或設定檔方式覆蓋。
維運與監控¶
日常維運可從以下方向著手：
- 使用
docker compose logs -f hindsight查看 API 日誌，確認是否有連線或模型呼叫錯誤。 - 從
cf_network內其他容器測試http://172.21.0.79是否可達，並檢查 Hindsight 健康端點。 - 監控
pg-main連線數與磁碟空間，記憶大量成長時需要調整 retention 策略。 - 檢查 LiteLLM 上游模型延遲與錯誤率，必要時設定 fallback model。
- 確認 e5-large embeddings 已成功載入；首次啟動需要較多時間下載模型，勿誤判為 hang。
常見問題¶
- API 無法連線 pg-main：檢查
HINDSIGHT_DB_PASSWORD是否正確，以及pg-main是否允許hindsight使用者從 Docker network 登入。 - LLM 回應逾時：可能是 LiteLLM 設定或上游模型不穩定；建議檢查 LiteLLM 日誌並加入 timeout 與 fallback。
- 檢索結果不佳：確認 e5-large embeddings 已正確載入，並檢查 RRF 排序參數；若記憶都是短文本，可考慮調整分塊或 metadata 索引。
- 容器重啟後 IP 變更：必須使用固定 IP
172.21.0.79並確保cf_network子網段包含該位址，否則其他服務無法穩定存取。