標籤

從零開始：Hindsight 記憶系統安裝教學

從零開始：Hindsight 記憶系統安裝教學

前置準備

在開始安裝 Hindsight 之前，讓我們先確認你的環境滿足以下需求。

系統需求

Hindsight 支援 macOS、Linux 和 Windows（透過 WSL）。以下是建議的硬體規格：

  • 記憶體：至少 4GB RAM，推薦 8GB 以上
  • 硬碟空間：至少 5GB 可用空間（用於存放向量資料庫）
  • 處理器：任何現代 CPU 都可以運行

必要軟體

在安裝 Hindsight 之前，你需要先準備好以下軟體：

1. Python 3.11 或更高版本

Hindsight 是用 Python 開發的，所以需要 Python 環境。你可以到 Python 官網 下載安裝，或是使用以下指令檢查是否已安裝：

python3 --version

如果顯示的版本號低於 3.11，你需要更新 Python。

2. PostgreSQL 資料庫

Hindsight 使用 PostgreSQL 搭配 pgvector 擴展來儲存和檢索向量資料。你可以選擇：

  • 選項 A：使用 Docker（推薦）

如果你已經安裝了 Docker，可以快速啟動一個支援 pgvector 的 PostgreSQL：

  docker run \
    --name hindsight-postgres \
    -e POSTGRES_DB=hindsight \
    -e POSTGRES_USER=hindsight \
    -e POSTGRES_PASSWORD=your_secure_password \
    -p 5432:5432 \
    -vectorize/pgvector-pg16:latest
  • 選項 B：本地安裝

如果你想在本地安裝 PostgreSQL，可以參考 PostgreSQL 官網 的安裝說明。建議安裝版本 16 或更新版本。

3. 網路環境

Hindsight 預設在本機的 8888 端口運行，確保這個端口沒有被其他程式佔用。如果你計畫讓外部工具連接，你需要配置適當的網路設定。

安裝步驟

第一步：建立安裝目錄

建議你在家目錄下建立一個專門放置 Hindsight 的資料夾：

mkdir -p ~/.openclaw/hindsight
cd ~/.openclaw/hindsight

這個資料夾將會存放 Hindsight 的所有相關檔案、日誌和資料庫備份。

第二步：建立 Python 虛擬環境

為了避免與其他 Python 專案產生衝突，建議使用虛擬環境：

python3 -m venv .venv

建立完成後，啟用虛擬環境：

source .venv/bin/activate

你的命令列前面應該會出現 (.venv) 的標示，表示現在在虛擬環境中操作。

第三步：安裝 Hindsight

透過 pip 安裝 Hindsight 及其所有依賴：

pip install hindsight-api

這個指令會自動安裝 Hindsight API 伺服器以及所有必要的元件。視你的網路速度，安裝過程可能需要幾分鐘。

第四步：準備資料庫

啟動 Hindsight 之前，你需要確認 PostgreSQL 正在運行，並且已經建立好一個空白資料庫。

建立資料庫（使用 Docker 的情況）：

docker exec -it hindsight-postgres psql -U hindsight -c "CREATE DATABASE hindsight;"

建立資料庫（本地安裝的情況）：

createdb -U postgres hindsight

如果你在本地的 PostgreSQL 設定了不同的使用者名稱或密碼，請相應調整指令。

第五步：設定環境變數

Hindsight 需要一些環境變數來正確運行。建議建立一個 .env 檔案來管理這些設定：

cd ~/.openclaw/hindsight
touch .env

然後編輯這個檔案，填入你的設定：

# 資料庫設定
DATABASE_URL=postgresql://hindsight:your_secure_password@localhost:5432/hindsight

# LLM 設定（使用 MiniMax 為例）
HINDSIGHT_API_LLM_PROVIDER=minimax
HINDSIGHT_API_LLM_API_KEY=your_minimax_api_key
HINDSIGHT_API_LLM_MODEL=MiniMax-M2.7
HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.com/v1

如果你不知道要填什麼 API Key，或是想先測試看看，可以先跳過 LLM 設定，Hindsight 的基本功能依然可以運作。LLM 設定主要是用來啟用「自動萃取記憶」的功能。

第六步：啟動 Hindsight

一切準備就緒後，輸入以下指令啟動 Hindsight：

hindsight-api

你應該會看到類似以下的輸出：

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8888 (Press CTRL+C to quit)

恭喜！Hindsight 已經成功啟動了！

驗證安裝

檢查健康狀態

開啟另一個終端機視窗，輸入以下指令檢查 Hindsight 是否正常運行：

curl http://localhost:8888/health

如果一切正常，你應該會看到這樣的回應：

{"status":"healthy","database":"connected"}

測試基本功能

讓我們用 curl 測試一下基本的 API 功能是否正常。

測試建立記憶：

curl -X POST "http://localhost:8888/v1/default/banks/test/memories/retain" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"content": "這是一個測試記憶"}
    ]
  }'

測試召回記憶：

curl -X POST "http://localhost:8888/v1/default/banks/test/memories/recall" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "測試"
  }'

如果這兩個測試都成功執行，恭喜！你的 Hindsight 安裝完全正常。

基本設定

開機自動啟動（macOS / Linux）

如果你希望 Hindsight 在系統啟動時自動運行，可以使用 launchd（macOS）或 systemd（Linux）來設定開機服務。

對於 macOS 使用者，Hindsight 官方建議使用 launchd。設定方式請參考系統檔案 ~/Library/LaunchAgents/ 或詢問 AI 助理幫你建立一個 LaunchAgent plist 檔案。

對於 Linux 使用者，你可以使用 systemd 建立一個服務單元。這需要管理員權限，但設定完成後 Hindsight 就會在開機時自動啟動。

日誌管理

Hindsight 的日誌預設輸出到終端機。如果你想將日誌寫入檔案以便日後查看，可以使用以下指令：

hindsight-api > ~/.openclaw/hindsight/hindsight.log 2>&1 &

這樣日誌就會自動寫入 ~/.openclaw/hindsight/hindsight.log 檔案。

備份資料庫

建議定期備份你的 PostgreSQL 資料庫。你可以使用以下指令：

pg_dump -U hindsight hindsight > backup_$(date +%Y%m%d).sql

疑難排解

常見問題 1：端口已被佔用

如果啟動時出現「Port already in use」錯誤，表示 8888 端口已被其他程式佔用。你可以：

  1. 找出哪個程式在使用這個端口：lsof -i :8888
  2. 停止該程式，或是在 .env 中設定 HINDSIGHT_PORT=8889 來使用其他端口

常見問題 2：資料庫連線失敗

如果看到「connection refused」錯誤，請確認：

  1. PostgreSQL 正在運行
  2. 資料庫和用戶已正確建立
  3. DATABASE_URL 格式正確
  4. 防火牆沒有阻擋本地連線

常見問題 3：API Key 無效

如果你在設定 LLM 時遇到 401 或 403 錯誤，請確認：

  1. API Key 正確且尚未過期
  2. HINDSIGHTAPILLMBASEURL 包含 /v1 後綴（以 MiniMax 為例，應該是 https://api.minimaxi.com/v1 而非 https://api.minimaxi.com）
  3. 你的 API Key 有足夠的配額

下一步

恭喜你成功安裝了 Hindsight！現在你的 AI 系統已經具備長期記憶的能力。

接下來你可以：

  1. 將 Hindsight 與 OpenClaw 整合，啟用自動記憶萃取功能
  2. 閱讀本系列的第三篇文章，瞭解我在串接 MiniMax API 時遇到的問題與解決方法
  3. 探索 Hindsight 的更多進階功能

總結

這篇文章帶你從零開始安裝 Hindsight 記憶系統。我們討論了：

  • 安裝前的環境準備（Python、PostgreSQL、網路）
  • 完整的六步安裝流程
  • 如何驗證系統正常運作
  • 基本設定與日常維護
  • 常見問題的解決方法

Hindsight 的安裝雖然需要一些前置作業，但一旦架設完成，你就擁有了一個專屬的 AI 記憶中心。這個投資絕對值得。

如果有任何問題，歡迎在下方留言討論！

相關文章：

  • 《讓 AI 記得你：Hindsight 記憶系統完整解析》
  • 《從 404 到正常運行：Hindsight MiniMax 串接疑難排解》
電子郵件發布
標籤：

留言

張貼留言

歡迎留下您的心靈足跡👍