Hindsight 安装部署完全指南Docker、Helm、pip 与嵌入式部署全场景详解【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文是 HindsightAgent Memory That Learns的安装部署实战指南围绕官方安装文档hindsight-docs/versioned_docs/version-0.6/developer/installation.md展开覆盖支持平台与硬件要求、PostgreSQL 向量扩展选型、Docker 快速启动与镜像变体、Helm/Kubernetes 生产部署、Bare Metalpip安装、Windows 原生部署、以及在 Python 应用内嵌运行的两种模式。读完本文你将能够根据开发、生产、受限网络等不同场景选择最合适的部署路径并完成端到端配置。部署方式总览与选型原则Hindsight 提供了多种部署方式官方文档给出的选型建议如下部署方式适用场景核心特征Docker快速开始、开发、小型部署单容器同时承载 API 与 Control Plane内置嵌入式 PostgreSQLpg0Helm / Kubernetes生产、自动扩缩容、云环境支持内置或外部 PostgreSQL可独立扩展 WorkerBare Metalpip在宿主机上以独立服务运行hindsight-api/hindsight-api-slim两个发行包Windows 原生不使用 Docker 的 Windows 环境开箱支持 pg0也可对接外部 PostgreSQLPython 内嵌在 Python 应用内部程序化使用hindsight-all提供进程内与托管子进程两种模式所有方式背后都共享同一个核心架构API Server默认 8888 端口负责记忆的写入retain、召回recall与反思reflect等核心能力Control Plane默认 9999 端口是基于 Next.js 的 Web UI用于管理 memory banks、探索实体、测试查询。Docker 的 standalone 镜像将两者打包在一起而 Helm chart 与 pip 包则允许按需拆分。支持平台与硬件要求平台支持矩阵Hindsight 支持 Linux、macOS、Windows 三大平台均同时支持 Docker、Bare Metalpip与嵌入式数据库pg0三种形态平台DockerBare Metal (pip)Embedded DB (pg0)备注Linuxx86_64、ARM64✅✅✅完全支持生产环境推荐macOSApple Silicon、Intel✅✅✅完全支持Windowsx86_64✅✅✅完全支持可选用外部 PostgreSQL见 Windows 章节所有平台都支持嵌入式数据库 pg0 用于开发Windows 上还可以额外使用外部 PostgreSQL 安装。数据库前提PostgreSQL 14 与向量扩展Hindsight 需要PostgreSQL 14并启用向量扩展以支持相似度检索可选扩展包括pgvector默认pgvectorscalevchordscannAlloyDB通过环境变量HINDSIGHT_API_VECTOR_EXTENSION选择使用哪一种。从源码看这一配置在 hindsight-api-slim/hindsight_api/_vector_index.py 中得到了明确实现# Extensions a user can set via HINDSIGHT_API_VECTOR_EXTENSION. CONFIGURABLE_EXTENSIONS (pgvector, pgvectorscale, vchord, scann)并映射到实际的 PostgreSQL 扩展名vector/vectorscale/vchord/alloydb_scann。值得注意的是pgvectorscale后端在 Azure 上运行时还会被解析为运行时专用的pg_diskann使用不同的WITH子句这属于运行时解析结果而不是用户直接设置的值。扩展相关的 schema 管理逻辑如非可重定位扩展固定 schema在 hindsight-api-slim/hindsight_api/_pg_extensions.py 中有完整处理。默认情况下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 搭配任意首选向量扩展仓库的 docker/docker-compose 目录为上述多种数据库与扩展组合提供了现成的 Compose 示例包括alloydb、external-pg、pg_search、pg_textsearch、pgroonga、timescale、vchord等可作为参考。LLM Provider 前提需要配置 LLM API Key用于事实抽取fact extraction、实体解析entity resolution与答案生成answer generation。支持的 provider、模型推荐与配置方式详见文档中的 Models 章节从 pyproject 看hindsight-api-slim/pyproject.toml 直接集成了openai、anthropic、cohere、google-genai、litellm等多家 SDK也支持本地 llama.cpplocal-llm额外依赖见 pyproject.toml。硬件与内存要求Hindsight 设计目标是在普通商用硬件上运行内存占用主要取决于使用的是full镜像内置本地 embedding 与 reranker 模型还是slim镜像将模型推理委托给外部服务组件最低内存推荐内存说明API — Full 镜像1.5 GB2 GB加载本地 BGE embedder约 130 MB与 MiniLM cross-encoder约 90 MB另含 PyTorch/ONNX 运行时。空闲 RSS 约 0.8–1.0 GB负载下约 1.2–1.5 GBAPI — Slim 镜像512 MB1 GB无本地模型稳态 RSS 主要来自 Python 运行时与数据库连接需配置外部 embedding 与 reranker provider如 TEI、OpenAI、CohereControl PlaneUI128 MB256 MBNext.js 进程非常轻量Worker若分离部署与 API 镜像变体相同与 API 镜像变体相同Worker 加载与 API 服务器相同的模型PostgreSQL512 MB1 GB随记忆量与索引规模增长降低内存占用的建议full 镜像内存的大头来自内置的 embedding 与 reranker 模型及其 PyTorch/ONNX 运行时。若想把部署压到几百 MB 内存切换到slim镜像并配置外部 embedding 与 reranker provider即可。CPU 与 GPU 权衡CPU-only 下 2 vCPU 足以支撑开发与基础负载生产流量下本地 rerankercross-encoder是主要瓶颈通常需要 GPU 来保持召回延迟可接受另一种做法是把 reranking 卸载到专用 GPU 硬件上的外部 reranker provider如 TEI、Cohere。从 docker/standalone/Dockerfile 可以看到 full 镜像构建时默认预下载的正是这两个默认模型embedding 模型BAAI/bge-small-en-v1.5与 reranker 模型cross-encoder/ms-marco-MiniLM-L-6-v2并带有指数退避重试逻辑。方式一Docker 部署快速开始适用场景快速开始、开发、小型部署。使用一个容器运行全部组件含嵌入式 PostgreSQLexport OPENAI_API_KEYsk-xxx docker run --rm -it --pull always -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启动后API Serverhttp://localhost:8888Control PlaneWeb UIhttp://localhost:9999所有已发布镜像均使用 Cosign 签名校验为可选操作见下文验证镜像签名。生产环境务必设置稳定的HINDSIGHT_API_WORKER_IDWorker 默认以容器主机名作为自身标识而 Docker 默认把主机名设为容器 ID——每次重启都会变化。这意味着容器宕机时正在处理的任务会停留在旧 ID 下新容器无法将其识别为己有。设置稳定的HINDSIGHT_API_WORKER_ID例如-e HINDSIGHT_API_WORKER_IDhindsight-prod可让 Worker 跨重启保持同一身份。即使单容器部署也建议设置。诊断与恢复命令见 Admin CLI 文档的Recovering stuck or zombie operations章节。Docker 镜像变体变体大小AMD64大小ARM64使用时机Fulllatest约 9 GB约 3.7 GB默认。除 LLM 外无需任何外部服务即可开箱即用Slimslim约 500 MB约 500 MB当你已依赖外部 embedding/reranking 服务OpenAI、Cohere、TEI时使用。镜像显著更小、部署更快但需配置外部 providerslim 镜像对应hindsight-api-slimpip 包。二者的差异在构建层面同样可见standalone Dockerfile 通过INCLUDE_LOCAL_MODELS构建参数决定是否安装local-ml额外依赖torch、sentence-transformers 等详见 docker/standalone/Dockerfile。在自定义镜像中内置自定义模型生产部署使用非默认本地模型时如果你使用非默认的本地 embedder 或 reranker应在构建时把模型烘焙进自定义镜像而不是启用 Helm 的modelCachePVC。仓库提供了可运行的示例 docker/docker-compose/custom-models其做法是基于 slim 镜像构建仅安装实际需要的依赖与模型通过ARG EMBEDDER/ARG RERANKER指定要烘焙的模型默认示例选用多语言变体sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2与cross-encoder/mmarco-mMiniLMv2-L12-H384-v1在运行时设置HF_HUB_OFFLINE1与TRANSFORMERS_OFFLINE1使任何运行时下载模型的尝试都会立刻失败从而确认模型确实已内置。快速开始export HINDSIGHT_API_LLM_API_KEYsk-xxx docker compose -f docker/docker-compose/custom-models/docker-compose.yaml up --build自定义模型docker compose -f docker/docker-compose/custom-models/docker-compose.yaml build \ --build-arg EMBEDDERyour-org/your-embedder \ --build-arg RERANKERyour-org/your-reranker随后同步修改 docker-compose.yaml 中的HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL与HINDSIGHT_API_RERANKER_LOCAL_MODEL使运行时指向相同的模型 ID。为什么不直接用 model-cache PVC相比把模型烘焙进镜像PVC 增加了存储成本每个 worker 副本一个 PVC、ReadWriteOnce会把 Pod 钉死在节点上、卸载/升级时需要生命周期管理、首次启动仍依赖 HuggingFace 可达。而镜像分层每个节点只需拉取一次容器运行时免费缓存也没有孤儿存储的清理问题。完整对比见 custom-models/README.md。可用镜像 Tag# StandaloneAPI Control Plane ghcr.io/vectorize-io/hindsight:latest # Full最新版本 ghcr.io/vectorize-io/hindsight:latest-slim # Slim最新版本 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:latest注具体版本号以发布为准文档中的0.4.9为示例当前仓库各包版本见各pyproject.toml如 hindsight-api-slim/pyproject.toml 中 version 为 0.9.2。验证镜像签名镜像使用 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.8分布式 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 文档。从仓库的 helm/hindsight/values.yaml 可以看到 Worker 相关默认值worker.enabled: false、replicaCount: 2以及 API 的 liveness/readiness 探针配置——liveness 走/health/live不访问数据库慢数据库只会触发 readiness 摘除流量而不会重启 Podreadiness 走/health检查数据库可达性。该 chart 的所有选项都可以在 values.yaml 中查阅。方式三Bare Metalpip安装适用场景在宿主机上以独立服务运行 Hindsight。安装pip install hindsight-api # Full——开箱即用 pip install hindsight-api-slim # Slim——需外部 embedding、reranking 与数据库服务使用hindsight-api-slim时必须为所有模型操作配置外部 provider。从源码看包结构验证了两者的关系hindsight-api-slim是核心实现包其 console scripts 在 hindsight-api-slim/pyproject.toml 中定义hindsight-api hindsight_api.main:main hindsight-worker hindsight_api.worker.main:main hindsight-local-mcp hindsight_api.mcp_local:main hindsight-admin hindsight_api.admin.cli:main而hindsight-apifull 包在其 pyproject 中引入hindsight-api-slim[local-ml,local-onnx,embedded-db]等额外依赖因此 full 与 slim 的差异仅在于是否内置本地 ML 模型依赖。使用嵌入式数据库运行开发/测试export HINDSIGHT_API_LLM_PROVIDERgroq export HINDSIGHT_API_LLM_API_KEYgsk_xxxxxxxxxxxx hindsight-api这会在~/.hindsight/data/创建数据库并在 http://localhost:8888 启动 API。从 hindsight-api-slim/hindsight_api/main.py 可以看到进程退出时会通过_cleanup()显式停止 pg0并注册 SIGINT/SIGTERM 信号处理。使用外部 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;。CLI 选项hindsight-api --port 9000 # 自定义端口默认8888 hindsight-api --host 127.0.0.1 # 仅绑定 localhost hindsight-api --workers 4 # 多个 worker 进程 hindsight-api --log-level debug # 详细日志以上选项在 hindsight-api-slim/hindsight_api/main.py 的 argparse 定义中都有完整实现。除此之外CLI 还支持更多生产级选项包括--reload——代码变更自动重载仅开发环境--access-log/--no-access-log——访问日志开关--proxy-headers与--forwarded-allow-ips——反代场景下的X-Forwarded-*头信任--ssl-keyfile/--ssl-certfile——直接启用 TLS--daemon——以后台守护进程方式运行每个选项都对应环境变量如HINDSIGHT_API_HOST、HINDSIGHT_API_PORT、HINDSIGHT_API_LOG_LEVEL、HINDSIGHT_API_WORKERSCLI 参数优先于环境变量。运行时还会根据平台自动选用 uvloop非 Windows或 winloopWindows事件循环。Control PlaneWeb UI独立运行Control Plane 可以脱离 API 单独用 npx 运行npx vectorize-io/hindsight-control-plane --api-url http://localhost:8888它会连接到你正在运行的 API 服务器提供管理 memory banks、探索实体、测试查询的可视化界面。选项选项环境变量默认值说明-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 原生部署适用场景不使用 Docker在 Windows 上原生运行 Hindsight。Hindsight 在 Windows 上开箱即支持嵌入式数据库pg0pip install hindsight-api set HINDSIGHT_API_LLM_PROVIDERopenai set HINDSIGHT_API_LLM_API_KEYsk-xxx set HINDSIGHT_API_LLM_MODELgpt-4o-mini hindsight-api使用外部 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;然后指向自己的数据库运行 Hindsightpip 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 Serverhttp://localhost:8888如果配置了外部 embedding/reranking provider同样可以使用 slim 包pip install hindsight-api-slim。从 hindsight-api-slim/pyproject.toml 可以看到 Windows 平台的依赖差异Windows 使用winloopuvloop 的 Windows 移植作为事件循环非 Windows 平台才安装uvloop。Windows 中国网络环境注意事项如果在中国网络限制环境下使用 WindowsDeepSeek 可以很好地用作HINDSIGHT_API_LLM_PROVIDER但DeepSeek 不提供 embeddings 端点。推荐使用本地 embedding在受限网络下兼顾隐私与可靠性。启动 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 本身并不直接读取它。上面的flashrankreranker 属于纯 Python 实现的本地重排序方案无需 GPU 即可运行。方式五在 Python 应用内嵌运行适用场景不单独运行服务器进程而是在 Python 应用中程序化使用 Hindsight。pip install hindsight-all # Full——开箱即用 pip install hindsight-all-slim # Slim——需外部 embedding、reranking 与数据库服务从 hindsight-all/pyproject.toml 可以看到hindsight-all聚合了hindsight-api-slim[all]、hindsight-client与hindsight-embed三个包这就是它同时支持两种内嵌模式的原因。hindsight-all支持两种内嵌模式进程内模式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?)托管子进程模式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 的源码注释可以看到HindsightEmbedded的更多行为细节数据按 profile 隔离存储在~/.pg0/instances/hindsight-embed-{profile}/支持retain()/retain_batch()、recall()、reflect()、create_bank()、create_mental_model()等全部客户端方法以及对应的 async 变体aretain、arecall、areflect等只转发显式传入的设置未指定的项由守护进程按profile 的 .env 文件 → 父进程环境 → 守护进程自身默认值的顺序解析这让未携带凭据的客户端也能复用已有配置。完整的 Python SDK API 参考见 Python SDK。部署后的下一步完成安装后建议按以下顺序深入Configuration——环境变量与设置详解Models——ML 模型与 provider 说明Monitoring——指标与可观测性此外仓库还提供了大量可直接复用的部署参考docker/docker-compose下有针对 TEI、local-llm、CUDA、nginx、S3 文件存储等场景的 Compose 示例helm/hindsight/values.yaml 是 Helm chart 的完整参数文档docker/standalone/start-all.sh 展示了容器内 API 与 Control Plane 的启动编排逻辑。常见问题速查问题解决方案容器重启后任务卡住无法恢复设置稳定的HINDSIGHT_API_WORKER_ID生产用 Helm 的 StatefulSet WorkerFull 镜像内存占用过高切换 slim 镜像配置外部 embedding/rerankerTEI、OpenAI、Cohere生产环境想避免运行时下载模型基于 slim 镜像构建自定义镜像把非默认本地模型烘焙进镜像分层见 custom-models 示例中国网络环境下模型下载失败设置HF_ENDPOINThttps://hf-mirror.comembedding 用本地 providerreranker 可用flashrankWindows 下想用自带数据库默认 pg0 开箱即用也可winget install PostgreSQL.PostgreSQL.17后编译 pgvector开发机不想装 PostgreSQL使用嵌入式数据库 pg0数据位于~/.hindsight/data/【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考