Hindsight

Hindsight（字面可譯作「後見之明」）係一套由 Vectorize 開源嘅自托管 AI 服務。佢嘅核心功能係將非結構化內容——例如網頁、筆記、對話記錄、文件——轉換成可以語意檢索嘅知識庫，再配合大型語言模型（LLM）做自然語言問答。同一般商業 SaaS AI 工具唔同，Hindsight 可以完全部署喺用戶自己控制嘅伺服器或雲端環境，例如 Oracle Cloud 上面嘅 VM。

呢篇百科主要講解 Hindsight 嘅架構、部署方法、配置要點、日常操作，以及喺 Oracle Cloud 上使用時需要注意嘅地方。

Overview

Hindsight 係一套「自我托管、私隱優先」嘅 AI 知識管理工具。佢唔係單純嘅聊天機械人，而係一個具備記憶同檢索能力嘅服務。用戶可以將自己嘅資料放入去，Hindsight 會先將內容切成可以處理嘅片段，再產生 embedding 向量，儲存喺資料庫；當用戶問問題時，系統會將問題轉成向量，搵出最相關嘅內容片段，然後交畀 LLM 生成答案。呢種做法正正係「Retrieval-Augmented Generation（RAG）」嘅典型實現。

Hindsight 喺設計上相當靈活。佢可以接駁市面上大部分 LLM provider，例如 OpenAI、DeepSeek、Anthropic，甚至本地模型。喺呢個部署案例入面，Hindsight 透過 LiteLLM 作為統一接口，令模型管理更加集中，亦避免咗被單一雲端供應商鎖死。

另外，Hindsight 支援「zero-LLM」模式。喺處理文件嘅時候，系統可以選擇唔經 LLM 做 fact extraction，而係直接將文本切成 chunks（片段）儲存。對於大型文件或者運算資源有限嘅環境，呢個模式可以大幅減少處理時間，避免 DeepSeek 等模型喺長時間生成時出現超時問題。

Architecture

Hindsight 嘅核心係一個容器化嘅 API 服務，官方鏡像係 ghcr.io/vectorize-io/hindsight:latest-slim。喺實際部署時，佢通常會同以下服務一齊運行：

• PostgreSQL：Hindsight 嘅主資料庫，喺 compose 範例入面用主機名 pg-main 表示。資料庫用戶名係 hindsight，密碼由 .env 入面嘅 HINDSIGHT_DB_PASSWORD 提供。
• LiteLLM：LLM 同 Embeddings 嘅代理服務，容器主機名係 litellm，預設聽端口 4000。Hindsight 會將所有模型請求經呢個服務轉發實際嘅模型後端。
• Embeddings 模型：通常會用本地或遠端嘅 embedding 模型，例如 e5-large。呢啲模型負責將文字轉成向量。

架構流程大致如下：

1. 用戶將文件或對話內容匯入 Hindsight。
2. Hindsight 將內容分割成文本片段（chunks）。
3. 每個片段經 LiteLLM 發送至 embeddings 模型，產生向量。
4. 向量連同原文儲存喺 PostgreSQL。
5. 用戶查詢時，查詢文字會轉成向量。
6. 系統用向量相似度搜尋最相關嘅片段。
7. 相關片段連同用戶問題送入 LLM，生成最終答案。

呢個設計令 Hindsight 可以透過更換 embedding 模型或 LLM 而改變表現，而唔使改動核心應用程式。

Deployment

Hindsight 可以部署喺任何支援 Docker 嘅環境。呢個案例以 Oracle Cloud 為例，假設用戶已經有一台 Ubuntu Linux VM，並且安裝好 Docker Engine 同 Docker Compose Plugin。

首先建立專案目錄，並喺入面建立 .env 檔案，設定以下變數：

HINDSIGHT_DB_PASSWORD=your_strong_password
HINDSIGHT_LLM_KEY=your_litellm_api_key
HINDSIGHT_API_LLM_MODEL=deepseek/deepseek-chat
HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL=e5-large
HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE=20

然後建立 docker-compose.yml。以下係構成 Hindsight 服務嘅 compose 片段：

services:
  hindsight:
    image: ghcr.io/vectorize-io/hindsight:latest-slim
    container_name: hindsight
    restart: unless-stopped
    environment:
      - TZ=Asia/Hong_Kong
      - HINDSIGHT_API_DATABASE_URL=postgresql://hindsight:${HINDSIGHT_DB_PASSWORD}@pg-main:5432/hindsight
      - HINDSIGHT_API_LLM_PROVIDER=litellm
      # 必須設 LLM_BASE_URL：litellm provider 預設空 -> 會打去 api.openai.com 被拒
      - HINDSIGHT_API_LLM_BASE_URL=http://litellm:4000
      - HINDSIGHT_API_LLM_API_KEY=${HINDSIGHT_LLM_KEY}
      - HINDSIGHT_API_LLM_MODEL=${HINDSIGHT_API_LLM_MODEL}
      - HINDSIGHT_API_LITELLM_API_BASE=http://litellm:4000
      - HINDSIGHT_API_LITELLM_API_KEY=${HINDSIGHT_LLM_KEY}
      - HINDSIGHT_API_EMBEDDINGS_PROVIDER=litellm
      # embeddings provider 係 raw HTTP call /embeddings（唔經 litellm SDK）-> 唔可以加 openai/ prefix
      - HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL=${HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL}
      # embed batch 100 對本地 e5-large 太慢（~80s+ 爆 timeout）-> 調細到 20
      - HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE=${HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE}
      # zero-LLM 模式：chunks mode 直接 chunk 文本，唔經 LLM fact extraction（deepseek 慢/超時問題）
      - HINDSIGHT_API_RETAIN_EXTRAC

注意，最後一行喺官方文件中應該係類似 HINDSIGHT_API_RETAIN_EXTRACT_MODE=chunks 嘅完整設定。實際使用時請參照官方最新嘅環境變數清單。

喺 Oracle Cloud 上，你需要確保 PostgreSQL 同 LiteLLM 都喺同一個 Docker network，並且可以互相用主機名訪問。可以使用 docker network create hindsight-net，再將所有 service 加入同一網絡。

部署指令係：

docker compose up -d

如果一切正常，Hindsight 就會開始初始化資料庫，並等候用戶加入內容。

Configuration

Hindsight 嘅配置主要透過環境變數進行。以下係幾個重要項目：

• TZ：時區。設為 Asia/Hong_Kong，令日誌同排程時間符合香港時間。
• HINDSIGHT_API_DATABASE_URL：PostgreSQL 連線字串。格式係 postgresql://用戶:密碼@主機:5432/資料庫名。
• HINDSIGHT_API_LLM_PROVIDER：指定 LLM 後端類型。呢度用 litellm。
• HINDSIGHT_API_LLM_BASE_URL：LiteLLM 服務地址。呢個變數必須設定，因為 LiteLLM provider 預設係空；如果唔設，系統會試吓連去 api.openai.com，導致 API key 被拒或連接失敗。
• HINDSIGHT_API_LLM_MODEL：指定 LLM 模型名稱。透過 LiteLLM，模型名可以帶 provider 前綴，例如 deepseek/deepseek-chat。
• HINDSIGHT_API_EMBEDDINGS_PROVIDER：Embeddings 供應商。呢度用 litellm。
• HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL：Embeddings 模型名。同 LLM 唔同，呢度係 raw HTTP call 去 /embeddings，所以唔可以加 openai/ 呢類前綴，否則 LiteLLM 會搵唔到 route。
• HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE：Embeddings 批次大小。原本 batch size 100 對本地 e5-large 太慢，需要大概 80 秒，容易超時；所以調細到 20 或者更低。

除咗環境變數，仲要注意 PostgreSQL 需要啟用 pgvector 擴充，先可以儲存向量數據。如果行緊 postgres:16 或以上版本，通常可以用 pgvector/pgvector 鏡像或手動安裝。

Operations

日常操作主要有以下幾類：

查看日誌

docker compose logs -f hindsight

日誌會顯示 API 請求、模型呼叫、資料庫查詢同錯誤訊息。如果發現 LiteLLM 連接失敗或 embedding timeout，可以優先睇呢度。

重啟服務

修改 .env 或 docker-compose.yml 之後，需要重新建立容器：

docker compose up -d --force-recreate

如果只需要重啟 Hindsight：

docker restart hindsight

更新鏡像

Hindsight 開發進度快，建議定期更新：

docker compose pull hindsight
docker compose up -d

備份資料庫

Hindsight 嘅知識庫全部儲存在 PostgreSQL。可以使用 pg_dump 定期備份：

docker exec pg-main pg_dump -U hindsight hindsight > hindsight_backup.sql

如果係用 Docker volume 儲存 PostgreSQL 資料，亦可以備份整個 volume。

資源監控

Oracle Cloud Always Free VM 通常資源有限。Embeddings 模型非常食 CPU 同記憶體，尤其係本地運行 e5-large 時。可以用 docker stats 監察 CPU、記憶體使用量，並按需要調整 HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE。

FAQ

Hindsight 係咪一定要用 Oracle Cloud？

唔係。Hindsight 係一套自托管服務，任何可以運行 Docker 嘅 Linux 伺服器都得。Oracle Cloud 只係其中一個常見選擇，特別係因為 Always Free 計劃可以提供免費 VM。

點解要經 LiteLLM，唔直接接 OpenAI？

LiteLLM 係統一接口，可以接駁多個 LLM provider。噉樣做有幾個好處：可以隨時切換模型、統一 API key 管理、避免 Hindsight 直接綁死某一家雲端供應商。喺香港或中國內地環境，亦可以透過 LiteLLM 接入更穩定嘅模型後端。

HINDSIGHT_API_LLM_BASE_URL 唔設會點？

根據 Hindsight 嘅設定，如果 LLM_PROVIDER=litellm 但 LLM_BASE_URL 留空，LiteLLM 會預設向 api.openai.com 發送請求。假如你用嘅 API key 唔係來自 OpenAI，請求就會被拒。所以一定要設定為 http://litellm:4000。

Embeddings 模型名點解唔可以加 openai/ 前綴？

因為 Hindsight 對 embeddings 嘅呼叫方式係 raw HTTP call，直接打去 /embeddings 端點，而唔係經 LiteLLM SDK 嘅模型映射。如果模型名帶有 openai/ 呢類前綴，LiteLLM 會將成個字串當成模型 ID，導致 route 唔匹配而失敗。

「zero-LLM 模式」係咩？

即係 HINDSIGHT_API_RETAIN_EXTRACT_MODE=chunks 呢一類設定。喺呢個模式之下，Hindsight 唔會叫 LLM 將內容抽取成結構化 fact，而係直接將文本切成 chunks 保存。好處係快、平、穩定；壞處係可能冇咁深入理解語意。對於以搜尋同問答為主嘅場景，chunks mode 通常已經夠用。

如果 embedding 太慢點算？

可以降低 HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE。例如由 100 降至 20，可以將處理時間由 80 秒縮短到合理範圍。亦可以考慮改用 GPU 或者更細嘅 embedding 模型。

Related Links

• docker
• litellm
• postgres
• Oracle Cloud
• RAG
• openai
• deepseek

Source

Coverage auto (container scan)