Hindsight 安装部署实战Docker、Helm、裸机 pip 与 Python 进程内嵌入的四条路径【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个「会学习的 Agent 记忆系统」Agent Memory That Learns支持多种部署形态Docker 单容器、Helm/Kubernetes 生产集群、宿主机 pip 裸机运行以及直接嵌入 Python 应用进程。本文基于仓库中 developer/installation.md 的完整内容结合 hindsight-api-slim 的 pyproject.toml、CLI 入口 与 Dockerfile 等源码完整覆盖平台支持矩阵、硬件要求、各部署方式的命令与参数、镜像变体、签名校验与 Windows 特殊配置帮助读者按自身基础设施选型并落地一套可运行的 Hindsight 服务。一、支持平台与前置条件1.1 平台支持矩阵Hindsight 支持Linux、macOS和Windows三种运行方式Docker、Bare Metal pip、嵌入式数据库 pg0的覆盖情况如下平台DockerBare Metal (pip)Embedded DB (pg0)说明Linuxx86_64, ARM64✅✅✅完整支持推荐用于生产macOSApple Silicon / arm64✅✅✅完整支持macOSIntel / x86_64✅⚠️ 仅限 slim✅请使用hindsight-all-slim/hindsight-api-slim。完整包依赖的本地 ML 模型栈PyTorch、MLX没有 Intel-Mac 预编译轮子pip install hindsight-all会静默回退到数月前的旧版本。建议 slim 包搭配托管 embedding/reranker 服务商或使用进程内 ONNX 后端hindsight-api-slim[local-onnx]Windowsx86_64✅✅✅完整支持外部 PostgreSQL 方案见下文 Windows 小节所有平台都支持嵌入式数据库pg0用于开发。从源码看这一点对应在 hindsight-api-slim/pyproject.toml 中的embedded-dbextrapg0-embedded0.15.0hindsight-all的all依赖正是hindsight-api-slim[local-ml,local-onnx,embedded-db]而「Intel Mac 仅限 slim」的结论也与该文件中local-mlextra 的依赖构成一致——torch、sentence-transformers、mlx 等均无 Intel-Mac 轮子这解释了文档中「完整包静默回退旧版本」的现象。此外文件中标注requires-python 3.11pip 安装方式要求 Python 3.11。1.2 前置条件PostgreSQLHindsight 需要PostgreSQL 14以及一个向量扩展用于相似度检索支持的扩展有pgvector默认pgvectorscalevchordscannAlloyDB通过HINDSIGHT_API_VECTOR_EXTENSION环境变量选择使用哪一种详见 Configuration。默认情况下Hindsight 使用pg0—— 一个在本机内嵌运行的 PostgreSQL。这对开发很方便但不推荐用于生产。生产环境应使用外部 PostgreSQL 加任一受支持的向量扩展常见选项Supabase— 内置 pgvector 的托管 PostgreSQLNeon— 带 pgvector 的 Serverless PostgreSQLAzure Database for PostgreSQL— 支持 pgvector 与 pgvectorscaleGoogle AlloyDB / AlloyDB Omni— 支持 pgvector 与 ScaNNAWS RDS / Cloud SQL— 启用 pgvector 扩展自建— PostgreSQL 14 加你偏好的向量扩展1.3 前置条件LLM Provider你需要一个 LLM API Key用于事实抽取fact extraction、实体消解entity resolution和答案生成。支持的提供商、模型推荐与配置方式见 Models。1.4 硬件要求完整镜像 vs 精简镜像Hindsight 设计为可在普通硬件上运行。资源占用主要取决于使用完整镜像内置本地 embedding 与 reranker 模型还是精简镜像将这些能力委托给外部提供商组件最低内存推荐内存说明API — 完整镜像1.5 GB2 GB会将本地 BGE embedder约 130 MB与 MiniLM cross-encoder约 90 MB加载进内存另有 PyTorch/ONNX 运行时 arena。空闲 RSS 约 0.8–1.0 GB负载下约 1.2–1.5 GBAPI — 精简镜像512 MB1 GB无本地模型稳态 RSS 由 Python 运行时与数据库连接主导。需要外部 embedding 与 reranker 提供商如 TEI、OpenAI、CohereControl PlaneUI128 MB256 MBNext.js 进程很轻量Worker如独立部署与 API 镜像变体相同与 API 镜像变体相同Worker 加载与 API 服务相同的模型PostgreSQL512 MB1 GB随记忆与索引数量增长缩小占用完整镜像的内存大头是内置 embedding/reranker 模型及其 PyTorch/ONNX 运行时。若想把部署压缩到几百 MB 内存切换为slim镜像并配置外部 embedding 与 reranker 提供商即可。CPU 与 GPU纯 CPU 下 2 vCPU 足以应对开发和基础负载。生产流量下本地 rerankercross-encoder是主要瓶颈通常需要 GPU 才能保持召回延迟合理也可以把 rerank 卸载到外部 reranker 提供商如 TEI、Cohere在专用 GPU 硬件上运行。二、Docker 部署适用场景快速开始、开发、小规模部署。2.1 单容器快速启动内嵌 PostgreSQL用一个容器跑起全部组件内嵌 pg0 数据库export OPENAI_API_KEYsk-xxx docker run -it --pull always --name hindsight --restart unless-stopped --shm-size1g -p 8888:8888 -p 9999:9999 \ -e HINDSIGHT_API_LLM_API_KEY$OPENAI_API_KEY \ -v hindsight-data:/home/hindsight/.pg0 \ ghcr.io/vectorize-io/hindsight:latestAPI Server: http://localhost:8888Control PlaneWeb UI: http://localhost:9999从 docker/standalone/Dockerfile 可以看出官方镜像是多阶段构建API 构建阶段基于python:3.11-slim并用uv sync --locked锁定工作区依赖完整镜像安装local-mlembedded-dbextraslim 镜像只装embedded-dbSDK 与控制面阶段分别基于node:24-slim。构建参数INCLUDE_API/INCLUDE_CP/INCLUDE_LOCAL_MODELS/PRELOAD_ML_MODELS决定了最终镜像是 API-only、Control Plane-only 还是带/不带本地 ML 模型——这正是latest与slim两个变体差异的构建层来源。2.2 数据持久化命名卷 vs 宿主目录挂载容器以非 root 用户UID 1000运行。上面命令使用的hindsight-data命名卷是推荐做法——Docker 会创建由容器用户所有的卷无需任何额外设置。如果你改用宿主目录绑定挂载-v $HOME/.hindsight-docker:/home/hindsight/.pg0该目录必须归 UID 1000 所有否则内嵌数据库会因Permission denied启动失败sudo chown -R 1000:1000 $HOME/.hindsight-docker不要用--user换成其他 UID 来绕过该问题镜像只定义了hindsight用户UID 1000其他 UID 在/etc/passwd中没有条目启动会在一个按 UID 查询运行用户的库里直接崩溃KeyError: getpwuid(): uid not found: 1042以 UID 1000默认值运行并将目录 chown 对齐是使用宿主绑定挂载的支持方式。如果无法 chown 该目录例如挂载了固定uid的 NAS 共享请改用命名卷。2.3 生产建议设置稳定的HINDSIGHT_API_WORKER_IDWorker 默认使用容器主机名作为身份标识而 Docker 默认将主机名设为容器 ID每次重启都会变化。这意味着容器宕机时正在处理的任务会停留在旧 ID 下新容器无法识别它是自己的任务。请把HINDSIGHT_API_WORKER_ID设为稳定值例如-e HINDSIGHT_API_WORKER_IDhindsight-prod使 Worker 在重启间保持同一身份。即使单容器部署也建议这样做。诊断与恢复命令见 Admin CLI - Recovering stuck operations。2.4 镜像变体与可用 Tag变体大小AMD64大小ARM64适用时机Fulllatest~9 GB~3.7 GB默认。embedding 与 rerank 在镜像内完成LLM 始终走外部包括本地推理场景Slimslim~500 MB~500 MB已经依赖外部服务做 embedding/rerankOpenAI、Cohere、TEI时使用。镜像显著更小、部署更快。需要外部提供商slim 镜像对应 pip 包hindsight-api-slim。两个镜像都不打包 llama.cpp因此内置llamacppprovider 在 Docker 中不可用。如需本地推理请在 Hindsight 旁边启动 llama.cpp或 Ollama、LM Studio、vLLM并把HINDSIGHT_API_LLM_BASE_URL指向它——仓库提供了可用的 compose 文件 docker/docker-compose/local-llm/。自定义镜像中打包自定义模型生产中使用非默认本地模型时如果使用了非默认的本地 embedder 或 reranker请在构建期把模型烘焙进自定义镜像而不是启用 Helm 的modelCachePVC。可运行的示例见 docker/docker-compose/custom-models/。可用镜像 Tag# StandaloneAPI Control Plane ghcr.io/vectorize-io/hindsight:latest # Full最新 release ghcr.io/vectorize-io/hindsight:latest-slim # Slim最新 release ghcr.io/vectorize-io/hindsight:0.4.9 # Full指定版本 ghcr.io/vectorize-io/hindsight:0.4.9-slim # Slim指定版本 # 仅 API ghcr.io/vectorize-io/hindsight-api:latest ghcr.io/vectorize-io/hindsight-api:latest-slim # 仅 Control Plane ghcr.io/vectorize-io/hindsight-control-plane:latest2.5 镜像签名校验Cosign所有发布镜像都用 Cosign 的 keyless OIDC 方式签名校验是可选的。校验任意 tagcosign verify ghcr.io/vectorize-io/hindsight:tag \ --certificate-identity-regexp ^https://github\.com/vectorize-io/hindsight/\.github/workflows/(sign-images|release)\.yml.* \ --certificate-oidc-issuer https://token.actions.githubusercontent.com三、Helm / Kubernetes 部署适用场景生产部署、自动扩缩、云环境。# 使用内置 PostgreSQL 安装 helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \ --set api.llm.providergroq \ --set api.llm.apiKeygsk_xxxxxxxxxxxx \ --set postgresql.enabledtrue # 或使用外部 PostgreSQL helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \ --set api.llm.providergroq \ --set api.llm.apiKeygsk_xxxxxxxxxxxx \ --set postgresql.enabledfalse \ --set api.database.urlpostgresql://user:passpostgres.example.com:5432/hindsight # 安装指定版本 helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight --version 0.1.3 # 升级到最新 helm upgrade hindsight oci://ghcr.io/vectorize-io/charts/hindsight要求Kubernetes 集群GKE、EKS、AKS 或自建Helm 3.83.1 分布式 Worker高吞吐部署可启用独立的 worker pod让任务处理独立扩缩helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \ --set worker.enabledtrue \ --set worker.replicaCount3Chart 将 worker 部署为 StatefulSet每个 pod 有稳定名称如hindsight-worker-0Worker 将其作为HINDSIGHT_API_WORKER_ID使用pod 重启后仍能认领之前自己领取的任务。如果将 chart 换成普通 Deployment必须为每个副本显式设置HINDSIGHT_API_WORKER_ID——否则主机名随机化先前领取的任务会变成孤儿。诊断方法见 Admin CLI - Recovering stuck operations。Worker 服务的配置细节与架构见 Services - Worker ServiceChart 的全部选项见 helm/hindsight/values.yaml。四、Bare Metalpip部署适用场景把 Hindsight 作为独立服务运行在宿主机上。4.1 安装pip install hindsight-api # Full —— 开箱即用 pip install hindsight-api-slim # Slim —— embedding、rerank 与数据库都需要外部服务使用hindsight-api-slim时必须为所有模型操作配置外部提供商详见 Configuration。从 hindsight-api-slim/pyproject.toml 的[project.optional-dependencies]可以确认各能力对应的安装 extralocal-mlsentence-transformers、torch、flashrank、mlx 等本地 embedding/rerank 模型栈、local-llmllama.cpp 离线推理、local-onnx进程内 ONNX embedding、embedded-dbpg0 内嵌 PostgreSQL、oracleOracle 数据库支持。pip 安装完成后会注册四个命令行入口hindsight-api、hindsight-worker、hindsight-local-mcp、hindsight-admin分别对应 main.py、worker、本地 MCP 服务与 Admin CLI。4.2 使用内嵌数据库运行开发/测试export HINDSIGHT_API_LLM_PROVIDERgroq export HINDSIGHT_API_LLM_API_KEYgsk_xxxxxxxxxxxx hindsight-api这会在~/.hindsight/data/下创建数据库并在 http://localhost:8888 启动 API。4.3 使用外部 PostgreSQL 运行生产export HINDSIGHT_API_DATABASE_URLpostgresql://user:passlocalhost:5432/hindsight export HINDSIGHT_API_LLM_PROVIDERgroq export HINDSIGHT_API_LLM_API_KEYgsk_xxxxxxxxxxxx hindsight-api注意数据库必须已存在且已启用 pgvectorCREATE EXTENSION vector;。4.4 CLI 选项hindsight-api --port 9000 # 自定义端口默认8888 hindsight-api --host 127.0.0.1 # 仅绑定本机 hindsight-api --workers 4 # 多 worker 进程 hindsight-api --log-level debug # 详细日志结合 hindsight_api/main.py 的参数解析与 hindsight_api/config.py 中的常量可以确认默认值与文档一致默认 host 为0.0.0.0DEFAULT_HOST、默认端口8888DEFAULT_PORT、默认 worker 进程数1DEFAULT_WORKERS--log-level的可选值为critical/error/warning/info/debug/trace。每个参数都有对应环境变量HINDSIGHT_API_HOST、HINDSIGHT_API_PORT、HINDSIGHT_API_LOG_LEVEL、HINDSIGHT_API_WORKERS。从源码结构看main.py还额外提供--reload开发热重载、--access-log/--no-access-log、--proxy-headers、--ssl-keyfile/--ssl-certfile以及--daemon守护模式等选项--idle-timeout已被标记为废弃并忽略守护进程不再因空闲自动退出仅为兼容旧启动器保留。4.5 独立运行 Control PlaneWeb UIControl Plane 可以用 npx 独立运行npx vectorize-io/hindsight-control-plane --api-url http://localhost:8888它会连接到正在运行的 API server提供管理记忆库、浏览实体、测试查询的可视化界面。选项选项环境变量默认值说明-p, --portPORT9999监听端口-H, --hostnameHOSTNAME0.0.0.0绑定主机名-a, --api-urlHINDSIGHT_CP_DATAPLANE_API_URLhttp://localhost:8888Hindsight API 地址HINDSIGHT_CP_ACCESS_KEY(无)保护 Control Plane UI 的访问密钥。设置后用户必须输入该密钥登录示例# 自定义端口运行 npx vectorize-io/hindsight-control-plane --port 9999 --api-url http://localhost:8888 # 使用环境变量 export HINDSIGHT_CP_DATAPLANE_API_URLhttp://api.example.com npx vectorize-io/hindsight-control-plane # 生产部署 PORT80 HINDSIGHT_CP_DATAPLANE_API_URLhttps://api.hindsight.io npx vectorize-io/hindsight-control-plane五、Windows 部署适用场景在 Windows 上原生运行 Hindsight不使用 Docker。Hindsight 在 Windows 上使用内嵌数据库pg0开箱即用——安装后即可运行pip install hindsight-api set HINDSIGHT_API_LLM_PROVIDERopenai set HINDSIGHT_API_LLM_API_KEYsk-xxx set HINDSIGHT_API_LLM_MODELgpt-4o-mini hindsight-api5.1 使用外部 PostgreSQL可选如果偏好使用自己的 PostgreSQL 实例而非内嵌数据库# 安装 PostgreSQL winget install PostgreSQL.PostgreSQL.17 # 编译 pgvector需要 Visual Studio Build Tools git clone https://github.com/pgvector/pgvector.git cd pgvector # 打开 x64 Native Tools Command Prompt for VS 并运行 set PGROOTC:\Program Files\PostgreSQL\17 nmake /F Makefile.win nmake /F Makefile.win install # 创建数据库并启用 vector 扩展 psql -U postgres -c CREATE DATABASE hindsight; psql -U postgres -d hindsight -c CREATE EXTENSION vector;然后让 Hindsight 指向你的数据库pip install hindsight-api set HINDSIGHT_API_DATABASE_URLpostgresql://postgreslocalhost:5432/hindsight set HINDSIGHT_API_LLM_PROVIDERopenai set HINDSIGHT_API_LLM_API_KEYsk-xxx set HINDSIGHT_API_LLM_MODELgpt-4o-mini hindsight-apiAPI Server: http://localhost:8888如果为 embedding 与 rerank 配置了外部提供商也可以改用 slim 包pip install hindsight-api-slim详见 Configuration。5.2 Windows 中国网络环境注意事项在 Windows 且处于中国网络限制环境下DeepSeek 适合用作HINDSIGHT_API_LLM_PROVIDER但 DeepSeek 不提供 embeddings 端点。建议使用本地 embeddings在受限网络下隐私与可靠性更好。启动 Hindsight 前设置HF_ENDPOINThttps://hf-mirror.com让 Hugging Face 模型下载走中国可访问的镜像。set HF_ENDPOINThttps://hf-mirror.com set HINDSIGHT_API_LLM_PROVIDERdeepseek set HINDSIGHT_API_LLM_API_KEYsk-your-deepseek-key set HINDSIGHT_API_LLM_MODELdeepseek-v4-flash set HINDSIGHT_API_LLM_BASE_URLhttps://api.deepseek.com set HINDSIGHT_API_EMBEDDINGS_PROVIDERlocal set HINDSIGHT_API_EMBEDDINGS_LOCAL_MODELBAAI/bge-small-en-v1.5 set HINDSIGHT_API_RERANKER_PROVIDERflashrank hindsight-apiHF_ENDPOINT变量由 Hugging Face 工具链huggingface_hub使用而不是 Hindsight 本身——这也是为什么本地 reranker 选flashrank纯 Python/CPU 实现而非依赖重模型的方案。六、嵌入 Python 应用适用场景不运行独立服务进程直接从 Python 以编程方式使用 Hindsight。pip install hindsight-all # Full —— 开箱即用Linux、Windows、Apple Silicon Mac pip install hindsight-all-slim # Slim —— embedding、rerank 与数据库需外部服务Intelx86_64Mac 上请安装hindsight-all-slim——参见上文支持平台。从 hindsight-all/pyproject.toml 可见hindsight-all是聚合包它依赖hindsight-api-slim[all]API 本体、hindsight-clientHTTP 客户端与hindsight-embed守护进程管理。hindsight-all支持两种嵌入模式6.1 进程内模式HindsightServer服务器以后台线程形式运行在你的应用进程内。适合希望最紧密集成、且已自行管理进程生命周期的场景from hindsight import HindsightServer, HindsightClient with HindsightServer(llm_provideropenai, llm_api_keysk-xxx) as server: client HindsightClient(base_urlserver.url) client.retain(bank_idalice, contentAlice prefers concise answers.) results client.recall(bank_idalice, queryHow should I respond to Alice?)实现见 hindsight-all/hindsight/server.pyServer构造时若未指定端口会自动探测一个空闲端口_find_free_portstart()在新线程中创建独立事件循环、实例化MemoryEngine并用create_app构建 FastAPI 应用交给 uvicornserver.url属性返回http://{host}:{port}供HindsightClient使用。默认db_urlpg0即内嵌 PostgreSQL。6.2 托管子进程模式HindsightEmbedded服务器以后台守护进程形式运行可被多个 Python 进程或会话共享守护进程在首次使用时启动。from hindsight import HindsightEmbedded client HindsightEmbedded(llm_provideropenai, llm_api_keysk-xxx) client.retain(bank_idalice, contentAlice prefers concise answers.) results client.recall(bank_idalice, queryHow should I respond to Alice?)从 hindsight-all/hindsight/embedded.py 的实现可以看到几个值得注意的细节Profile 机制HindsightEmbedded(profilemyapp, ...)用 profile 名做数据隔离profile 数据存储在~/.pg0/instances/hindsight-embed-{profile}/与 hindsight-embed CLI 共享同一套守护进程管理接口配置继承只转发显式传入的配置项——未显式设置的项由守护进程按「profile 的 .env 文件 → 父进程环境变量 → 守护进程默认值」的顺序解析避免客户端用占位符覆盖已有凭据传则表示显式清空密钥用于本地免认证 LLM 服务自愈_ensure_started是线程安全的若发现守护进程已失联会自动重启因此文档示例中无需手动管理守护进程生命周期支持uiTrue参数在守护进程旁附带启动 Control Plane Web UIui_port默认为daemon_port 10000idle_timeout参数已废弃并被忽略——守护进程不再因空闲自动退出仅为兼容旧调用方保留。完整的 Python API 参考可查阅仓库中的 Python 客户端 hindsight-clients/python/。七、选型小结与下一步场景推荐路径关键点快速体验 / 开发Docker 单容器Full内嵌 pg0一条docker run起 API(8888) UI(9999)命名卷持久化低资源 / 已有向量服务Docker slim 镜像 或 piphindsight-api-slim配置外部 embedding/rerank内存可压到数百 MB生产集群Helm chart 分布式 workerStatefulSet显式HINDSIGHT_API_WORKER_ID外部 PostgreSQL宿主机常驻服务piphindsight-api 外部 PostgreSQL记住CREATE EXTENSION vector;应用内集成piphindsight-allHindsightServer/HindsightEmbedded进程内线程模式 vs 共享守护进程模式后续可继续阅读Configuration —— 环境变量与完整配置项Models —— ML 模型与提供商Monitoring —— 指标与可观测性Admin CLI —— 管理命令与卡死操作恢复【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考