Hindsight 部署内存足迹规划指南：Full/Slim 镜像选型、组件基线与容量排障

Hindsight 部署内存足迹规划指南Full/Slim 镜像选型、组件基线与容量排障【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight为 Hindsight 部署做内存RAM容量规划时最容易踩的坑是把一台机器跑全套当成唯一形态。本文基于 Hindsight 官方向导《Size Hindsight Memory Footprint for Real Deployments》2026-04-28-guide-size-hindsight-memory-footprint-for-deployments.md展开并结合 安装指南、配置指南、服务架构文档 与 性能文档 中的实现证据给出分组件的内存基线、full/slim 镜像的选型逻辑、三种典型部署配方以及内存告急时的系统化排障路径。读完你可以为不同规模的 Hindsight 部署给出可辩护的内存预算并知道超支时该查哪里。核心结论速览先给快速答案这也是原始向导给出的基线Full API 镜像最低约 1.5 GB推荐 2 GB——因为它在进程内加载本地 embedding 模型与 rerankercross-encoder模型Slim API 镜像最低约 512 MB推荐 1 GB——前提是 embedding 和 reranking 都外置到独立服务控制面Control Plane很轻量Worker与 API 同镜像同足迹必须按同一规格单独预算PostgreSQL需要独立的容量余量。组件最低 RAM推荐 RAM说明来自安装指南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 提供方如 TEI、OpenAI、Cohere控制面UI128 MB256 MBNext.js 进程轻量Worker独立部署时同 API 镜像变体同 API 镜像变体Worker 与 API 加载同一套模型PostgreSQL512 MB1 GB随记忆条数与索引规模增长这些数字来自 安装指南的硬件一节。需要强调的是它们不是理论下限而是把本地模型开销、运行时开销以及 PostgreSQL 与 worker 的呼吸空间都算进去之后的规划值。先选 full 还是 slim再选机器原始向导指出选机器之前的最大分叉是是否把本地 embedding 和 reranking 打包进 API 进程。选full想要一站式部署、可以接受多占 RAM选slim想要更小的宿主机并愿意按 配置指南 接外部提供方。这一项决策通常比纠结 VM 规格档位更重要。full 买的是便利slim 买的是更小的足迹。 下面用仓库中的真实镜像与包规格来量化这个选择。Docker 镜像变体安装指南给出了两个变体的磁盘体积与适用场景变体体积AMD64体积ARM64何时使用Fulllatest~9 GB~3.7 GB默认。embedding 与 reranking 在镜像内运行LLM 始终外置Slimslim~500 MB~500 MB已经依赖外部服务做 embedding 与 rerankingOpenAI、Cohere、TEI时使用镜像更小、部署更快且要求配置外部提供方对应的可用标签包括ghcr.io/vectorize-io/hindsight:latestFull、...:latest-slimSlim、...:0.4.9-slim指定版本的 Slim以及 API-only 与控制面单独镜像。pip 侧的对应关系是hindsight-apiFull开箱即用与hindsight-api-slimSlim需要外部 embedding、reranking 与数据库提供方嵌入 Python 应用场景则对应hindsight-all/hindsight-all-slim见 hindsight-all 包。一个值得注意的折中方案slim 镜像 进程内 ONNX embedding。hindsight-api-slim[local-onnx]可以用 ONNX Runtime 在进程内跑 embedding 模型默认intfloat/multilingual-e5-small384 维在保持镜像较小的同时避免为 embedding 单独起服务。相关环境变量与启动示例见 配置指南的 Embeddings 一节。外部 embedding / reranker 提供方怎么选Slim 路径的成立依赖外部模型服务配置指南中与之直接相关的选项包括HINDSIGHT_API_EMBEDDINGS_PROVIDER取值local、onnx、tei、openai、cohere、google、zeroentropy、litellm、litellm-sdk等默认localHINDSIGHT_API_EMBEDDINGS_TEI_URL指向自建的 TEIText Embeddings Inference服务HINDSIGHT_API_EMBEDDINGS_MAX_CONCURRENT_REQUESTS默认 8远端 embedding 的并发请求数直接决定导入大文档时的吞吐各云厂商OpenAI、Cohere、ZeroEntropy、Gemini/Vertex、LiteLLM 代理等的 API key、模型与批量大小参数。Reranker 侧同样外置化HINDSIGHT_API_RERANKER_PROVIDER支持local、tei、cohere、openrouter、flashrank、litellm、rrf等提供方默认local并支持按序号配置的 failover 链——主 reranker 不可达时按序切换避免reranker 挂掉直接把 recall 拉垮。详见 配置指南的 Reranker 一节。仓库中也有可直接套用的 compose 示例如 TEI 组合同时外置 embedding 与 reranking与 本地 LLM 组合。三种典型部署配方原始向导给出了三个起点这里补充对应的仓库侧操作细节1. 笔记本 / 个人开发机full 镜像 嵌入式数据库pg02 vCPU、2–4 GB RAM。官方单容器 Docker 命令即为此形态安装指南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 在 8888 端口控制面 UI 在 9999 端口。嵌入式 pg0 只建议用于开发生产应使用外部 PostgreSQL 14pgvector/pgvectorscale/vchord/scann 之一。2. 小型云 VMslim 镜像 外部 embedding 与 reranker1–2 GB RAM 外加独立数据库。对应hindsight:latest-slim镜像或pip install hindsight-api-slim然后按上文配置 TEI/OpenAI/Cohere 等外部提供方。3. 较重的生产环境API 与 worker 分离、PostgreSQL 独立扩容、在意 recall 延迟时把 reranker 移出 API 主机。Helm 下的做法安装指南helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \ --set worker.enabledtrue \ --set worker.replicaCount3chart 将 worker 部署为 StatefulSet每个 Pod 以稳定 Pod 名作为HINDSIGHT_API_WORKER_ID。裸机上的等价操作是服务文档# 关闭 API 内建 worker HINDSIGHT_API_WORKER_ENABLEDfalse hindsight-api # 启动独立 worker可多实例 hindsight-worker --worker-id worker-1 hindsight-worker --worker-id worker-2注意服务文档的选型表开发和小规模生产用 API 内建 worker 即可独立 worker 是高吞吐与长任务隔离场景才值得引入的——而每个独立 worker 都意味着一整份 API 镜像的模型内存开销。生产环境还应固定HINDSIGHT_API_WORKER_ID单容器部署也建议否则容器重启后 hostname 变化重启前正在处理的任务会挂在旧 ID 下无法被新容器认领。内存压力从哪里来本地模型与 reranker原始向导的判断是对生产流量reranker 通常是最先让主机感觉贵的东西纯 CPU 机器上它会成为主要的延迟与内存压力点。这与仓库内两处证据吻合性能文档的延迟表中Recall 的典型延迟为 100–600 ms而其主要瓶颈一栏写明Re-ranker (on CPU)优化策略是用 GPU 做 rerank 或降低预算安装指南的 CPU/GPU 说明2 vCPU 纯 CPU 足以应付开发与基础负载但生产流量下本地 rerankercross-encoder是主要瓶颈通常受益于 GPU或者把 reranking 外置到独立的 TEI/Cohere 等 GPU 服务。从源码配置结构看还有几个直接决定进程 RSS 曲线的 reranker/embedding 参数值得在容量规划时留意均来自 配置指南变量默认对内存的影响HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT4本地 reranking 的并发上限防止负载下 CPU 抖动并发越高同时在内存中驻留的推理张量越多HINDSIGHT_API_RERANKER_FLASHRANK_CPU_MEM_ARENAfalse置true时 ONNX 预分配的内存 arena 永不收缩RSS 单调增长false以略慢的分配换有界的 RSSHINDSIGHT_API_RERANKER_FLASHRANK_BATCH_SIZE32每次前向的注意力张量按batch × heads × seq²分配且 batch 内按最长候选 padding候选很长时调大它会急剧抬高峰值内存HINDSIGHT_API_EMBEDDINGS_ONNX_CPU_MEM_ARENAfalse同上arena 缓存释放块且永不归还RSS 保持在进程生命周期内的高水位HINDSIGHT_API_EMBEDDINGS_ONNX_BATCH_SIZE32ONNX 提供方在进程内运行该值决定一次encode()的激活张量从而峰值内存上限直接影响大批量导入HINDSIGHT_API_RERANKER_LOCAL_ALLOW_MPS/HINDSIGHT_API_EMBEDDINGS_LOCAL_ALLOW_MPSfalseApple Silicon MPS 按输入形状缓存独立的 kernel/分配池且从不释放变长负载下内存可无限增长文档实测空闲实例达到约 20 GB因此默认禁用这些参数的共同指向是同一句话如果某次部署比预期更大元凶多半是模型本地性哪些模型驻留在进程内以及推理运行时的内存池行为而不是控制面或 API 框架本身。GPU 加速路径可参考 CUDA compose 配方其代价是自定义镜像磁盘约 11 GB基础 CPU 镜像约 9 GB 之上叠加 CUDA 运行时因此只在确实有 GPU 可使用时才值得构建。内存告急时的排障顺序原始向导给出的五步排查法按依赖顺序逐层工作确认镜像变体full 还是 slimfull 镜像的基线就是 1.5 GB 起在 1 GB 机器上看起来热是符合预期的slim 镜像热则说明配置没真正外置检查HINDSIGHT_API_EMBEDDINGS_PROVIDER/HINDSIGHT_API_RERANKER_PROVIDER是否仍为local。检查 worker 是否与 API 共享主机每个独立 worker 都加载与 API 同款的模型栈同主机双份进程就是双份模型内存。用ss -s/ps aux核对进程数并确认HINDSIGHT_API_WORKER_ENABLED的实际取值。确认 PostgreSQL 是否在同机被饿死PG 最低 512 MB、推荐 1 GB且随记忆与索引增长同主机跑 API PG 时两者要在预算上互相留足空间。复查外部提供方配置embedding/reranker 是否真正走外部服务、批量与并发参数如HINDSIGHT_API_EMBEDDINGS_MAX_CONCURRENT_REQUESTS、reranker 的 batch size是否偏大。对照服务形态文档API 与 worker 分离部署时按 服务文档核对每个角色的预算——API 无状态、可横向扩展所有状态在 PostgreSQL控制面只是连到 API 的轻量 Web UI。另外两个可操作细节worker 缩容或移除前先用hindsight-admin decommission-worker worker-id释放其任务每个角色都暴露/health、/health/ready与/metrics端点可用于监控内存与任务积压见 监控文档。FAQ问1 GB 内存能跑 Hindsight 吗能但基本只有一条路slim 镜像 外部 embedding/reranker 提供方此时稳态 RSS 由 Python 运行时与 DB 连接主导最低约 512 MB。full 镜像最低 1.5 GB不适合这个内存包络。问Worker 需要单独做内存预算吗需要。Worker 与 API 使用相同的包与 Docker 镜像、加载同一套模型栈服务文档same package and Docker image as the API service应按又一个 API 进程来预算。3 个 worker 副本就是 3 份 full 镜像的模型内存。问控制面是内存大头吗不是。控制面是相对轻量的 Next.js 进程128 MB 最低 / 256 MB 推荐。真正主导足迹的是本地 embedding 与本地 reranking。延伸阅读安装指南 — 硬件基线表、镜像变体与标签、Docker/Helm/裸机部署方式配置指南 — embedding 与 reranker 提供方、批量/并发/内存相关的全部环境变量服务文档 — API/Worker/控制面三服务的拆分与 worker 配置性能文档 — Recall/Reflect/Retain 延迟特征与 reranker 瓶颈分析Helm chart values — 生产部署的全部 chart 选项【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考