启动 Hindsight：pip 或 Docker，端口与 LLM 环境变量

你将得到什么

• 本机可访问的 Hindsight API：http://localhost:8888
• （Docker 路径）Control Plane Web UI：http://localhost:9999
• 已配置可用的 LLM 环境变量（至少 HINDSIGHT_API_LLM_API_KEY）
• 用一次 curl / 版本接口确认服务已起来

Hindsight 是面向 AI Agent 的记忆系统：Agent 通过 retain() 写入、recall() 检索、reflect() 基于记忆生成带 disposition 的回答。本课只负责把服务跑起来；下一课用官方 Python 客户端打通三步。

开始前准备

1. 准备一个 支持结构化输出（structured output） 的 LLM API Key。官方 Quick Start 示例直接用 OpenAI Key；Models 页推荐 Groq + openai/gpt-oss-20b 等更快更省的组合。本课两种都写，你选一种即可。
2. 二选一运行环境：
   • 路径 A：Python + pip install hindsight-api（默认只起 API，端口 8888）
   • 路径 B：Docker，镜像 ghcr.io/vectorize-io/hindsight:latest（同时起 API 8888 + Control Plane 9999）
3. 若走 Docker：本机已安装 Docker，且能拉 ghcr.io 镜像。

把密钥放进环境变量，不要写进代码仓库：

export OPENAI_API_KEY="sk-..."   # 或你选用的 Provider 对应密钥

步骤 1（路径 A）：pip 安装并启动 API

官方 Quick Start 的 Python 路径：

pip install hindsight-api
export OPENAI_API_KEY="sk-..."
export HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY
hindsight-api

对照结果：

• 终端不再立刻退出；进程保持前台运行。
• API 地址为 http://localhost:8888（与官方文档一致）。
• 数据默认落在本机 ~/.hindsight/data/（见官方部署说明）。

另开一个终端探测版本（端口通即可；字段名以你本机响应为准）：

curl -sS http://localhost:8888/health || curl -sS http://localhost:8888/

对照结果：HTTP 非连接拒绝即可；若返回 JSON/文本健康信息则更理想。连不上时检查：进程是否还在跑、是否被防火墙挡、是否改了 --port。

自定义端口（官方说明默认 8888）：

hindsight-api --port 9000

则后续客户端 base_url 要改成 http://localhost:9000。

步骤 2（路径 B）：Docker 一键起 API + Control Plane

官方 Quick Start 的 Docker 命令（注意 --shm-size=1g 与双端口映射）：

export OPENAI_API_KEY="sk-..."
docker run -it --pull always --name hindsight --restart unless-stopped --shm-size=1g \
  -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

对照结果（与官方一致）：

浏览器打开 http://localhost:9999 应能看到 Control Plane；8888 供下一课的 Hindsight(base_url=...) 使用。

数据卷挂载到 $HOME/.hindsight-docker，容器删掉后记忆库仍可保留。若容器名冲突：

docker rm -f hindsight

再重新执行上面的 docker run。

步骤 3：生产注意点 — 稳定的 WORKER_ID

官方 Quick Start 明确提醒：生产环境请设置稳定的 HINDSIGHT_API_WORKER_ID。

原因：worker 默认用容器 hostname 作身份；Docker 每次重启 hostname（容器 ID）会变，正在处理的异步任务会留在旧 ID 下，新容器认不出，任务会卡住。

示例（在 docker run 上追加）：

-e HINDSIGHT_API_WORKER_ID=hindsight-prod

本地试用可先不设；一旦打算长期跑或会重启容器，建议立刻加上。诊断与恢复命令见官方 Admin CLI「Recovering stuck operations」（Quick Start 同页链接）。

步骤 4：LLM Provider 怎么配（对照官方 Models 页）

Quick Start 最简写法只要求：

export HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY

更完整时（摘自 Models · Configuration）：

# OpenAI（Chat Completions，默认 provider 常为 openai）
export HINDSIGHT_API_LLM_PROVIDER=openai
export HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=gpt-4o-mini

# 或 Groq（官方推荐之一：快、成本友好）
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-20b

要点：

1. Hindsight 需要支持 structured output 的 LLM；不要用不支持该能力的模型硬扛。
2. 只设 PROVIDER 不设 MODEL 时，会用该 Provider 的官方默认模型（见 Models 页「Provider Default Models」表）。
3. 官方注明：Groq free tier（约 8k TPM）不够一次 retain；需付费档或其他 Provider。
4. Embedding / Cross-Encoder 默认会从 HuggingFace 自动下载本地模型（BAAI/bge-small-en-v1.5 等）；首次启动可能多等一会儿，属正常。

Docker 下把同样的 -e 传进去即可，例如：

-e HINDSIGHT_API_LLM_PROVIDER=openai \
-e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-e HINDSIGHT_API_LLM_MODEL=gpt-4o-mini

步骤 5：自检清单

若 API 起来但 retain 报 LLM 错：先核对 Key、Provider、Model 是否匹配；再看 Models 页「Tested Models」表换一个已验证型号。

下一课：安装 hindsight-client，对同一个 bank_id 跑通 retain → recall → reflect，并处理异步 retain。