TL;DR:Hindsight 0.8.0-slim 净减磁盘 6.87GB + 召回速度 3x 提升,但容器内 GLIBC 与 0.7.1 bind mount 的 PG vector.so 不兼容(GLIBC_2.38 缺失),必须用全新 data 目录。本文给一套「容器全挂 NVMe」迁移方法 + 5 个兼容性细节,在 Jetson/edge 设备上可直接复用。
1. 为什么必须升级 0.8.0
Hindsight(开源 AI Agent 记忆系统,基于 pgvector 向量库)从 0.7.1 到 0.8.0 不是普通 patch,有 3 个硬收益:
| 指标 | 0.7.1 full | 0.8.0-slim | 变化 |
|---|---|---|---|
| 镜像大小 | 8.17GB | 1.3GB | -6.87GB |
| 召回速度 | 0.5s | 0.16s | 3x 提升 |
| API 路径 | /v1/banks/{bank_id} | /v1/default/banks/{bank_id} | 改名 |
| Retain API | 单条 | items[] 数组 | 支持批量 |
| 6.87GB 是净减(卸载 0.7.1 full 后) | | | |
2. 升级前的真实架构
我在 Jetson AGX Orin(64GB 显存 / 1.7TB NVMe)上的原部署:
Hindsight 0.7.1 full
└─ /app/hindsight/data (NVMe 1.7TB) bind-mount → /home/hindsight/.pg0
└─ bge-large-zh-v1.5 embedding (512 token 限制,触发 consolidation 卡死)
└─ 本地 sentence-transformers reranker (触发 Hindsight #1897 issue,60s+ 卡死)
/app 是 NVMe bind mount(根分区 57GB 装系统 + Docker 镜像层;/app 是 1.7TB 海量空间),这是 6/8 那次决策的产物。
3. 升级翻车的 5 个真实细节
3.1 容器内 GLIBC 版本冲突(最隐蔽)
症状:0.7.1 bind mount 出来的 PG data 目录,放到 0.8.0-slim 容器里启不起来。 真因:
0.7.1 容器内 glibc = 2.38
0.8.0-slim 容器内 glibc = 2.31
PG vector.so 是 0.7.1 容器编译的(用 glibc 2.38)
→ 0.8.0 容器用 2.31 加载时找不到 GLIBC_2.38 符号
→ 数据库迁移失败,容器起不来
解决:0.8.0 容器必须用全新 data 目录,不能挂旧 data。
3.2 容器挂载路径必须在 NVMe
根分区 57GB,装完系统 + Docker 镜像层后只剩 16GB 可用。0.7.1 full 镜像 8.17GB 已经把空间吃紧。0.8.0-slim 1.3GB 虽小,但 data 目录(初始空)有 PG 索引 145MB,retain 一段时间后会涨。
根分区 vs NVMe 设计原则:所有跟 hindsight 相关的东西,都放到 /app/hindsight/ 树下(NVMe 上)。
| 类型 | 路径(在 NVMe) |
|---|---|
| Hindsight PG data | /app/hindsight/data/ |
| bge-m3 模型 | /app/hindsight/hf-cache/bge-m3-models/ |
| 0.7.1 backup | /app/hindsight/data.backup-20260608-232800/ |
| HF 旧 backup | /app/hindsight/hf_cache/hub/ |
| 重启脚本 | /app/hindsight/start_all.sh |
3.3 bge-large-zh-v1.5 512 token 限制(必换 bge-m3)
bge-large-zh-v1.5 是早期中文 embedding,只有 512 token 限制。Hindsight 的 consolidation(自动去重)会拼 batch 描述,一旦超过 512 token 就永久 retry 卡死。 换 bge-m3 后: - token 限制 512 → 8192 - 维度 768 → 1024(注意:维度变了,0.7.1 的旧 embedding 不能复用,要 re-embed) - 多语言(中文 + 英文 + 跨语言检索)
3.4 RRF reranker 替代本地 cross-encoder(规避 #1897)
Hindsight 0.7.1/0.8.0 都有 issue #1897:CrossEncoderReranker.ensure_initialized() 裸 await + asyncio.gather 无 timeout。切本地 bge-reranker-v2-m3 会触发 60s+ HTTP 卡死。
workaround:用 RRF(Reciprocal Rank Fusion)算法,0 模型、纯算法,0.5s 内召回。精度比 cross-encoder 低 5-15%,但生产够用。
3.5 容器内嵌 PG 启动 bug(0.7.1 时代)
Hindsight 自带 embedded pg0(不是外部 PG 容器),0.7.1 容器重启后 start-all.sh 启 PG 有 bug:容器起来后还要手动 docker exec hindsight pg0.start() + 等 30s。
0.8.0 修复了这点——0.8.0-slim 启动脚本里自动启 PG,不需要手动干预。
4. 完整迁移步骤
Step 1:停旧容器,备份当前 data(NVMe 上)
docker stop hindsight vllm
# 不删 data,先备份到 NVMe 其他位置(给回退留余地)
cp -a /app/hindsight/data /app/hindsight/data.backup-pre-0.8.0-$(date +%H%M)
Step 2:拉 0.8.0-slim 镜像(656MB,3-5 分钟)
# Jetson 上无 clash 代理,需要配置 ghcr.1ms.run 镜像源
docker pull ghcr.1ms.run/vectorize-io/hindsight-api:0.8.0-slim
Step 3:0.7.1 容器启全新空 data 目录(根分区临时放,稍后挪 NVMe)
mkdir -p /tmp/hindsight-fresh
chmod 0700 /tmp/hindsight-fresh
Step 4:启 0.8.0-slim 容器(用全新 data)
docker rm -f hindsight 2>/dev/null
docker run -d --name hindsight --network host --restart=always \
-v /tmp/hindsight-fresh:/home/hindsight/.pg0 \
-e HINDSIGHT_API_LLM_PROVIDER=deepseek \
-e HINDSIGHT_API_LLM_MODEL=deepseek-v4-flash \
-e HINDSIGHT_API_LLM_BASE_URL=https://api.deepseek.com/v1 \
-e HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai \
-e HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=BAAI/bge-m3 \
-e HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=http://localhost:8000/v1 \
-e HINDSIGHT_API_RERANKER_PROVIDER=rrf \
-e HINDSIGHT_API_RETAIN_EVERY_N_TURNS=20 \
ghcr.1ms.run/vectorize-io/hindsight-api:0.8.0-slim
# 等 30s 后 health 200
sleep 30 && curl -sf http://localhost:8888/health
Step 5:把全新 data 目录挪到 NVMe
# 1. 停容器
docker stop hindsight
# 2. 删掉 0.7.1 时代旧的空 data 目录(节省 760MB)
rm -rf /app/hindsight/data
# 3. 把新 145MB 全新 data 挪到 NVMe
mv /tmp/hindsight-fresh /app/hindsight/data
# 4. 用新挂载路径重启容器
# (在 /app/hindsight/start_all.sh 中改 -v /app/hindsight/data:/home/hindsight/.pg0)
bash /app/hindsight/start_all.sh
Step 6:bge-m3 模型从根分区挪 NVMe
# 1. 停 vLLM
docker stop vllm
# 2. 准备 NVMe 目录
mkdir -p /app/hindsight/hf-cache
# 3. 同盘 mv(秒挪,不用 cp)
mv /home/cronuser/hf-cache/bge-m3-models /app/hindsight/hf-cache/bge-m3-models
# 4. 改 start_vllm.sh 的源路径
sed -i 's|/home/cronuser/hf-cache/bge-m3-models|/app/hindsight/hf-cache/bge-m3-models|g' /app/start_vllm.sh
# 5. 重启 vLLM
bash /app/start_vllm.sh
5. 升级前后对比
| 项 | 0.7.1 full | 0.8.0-slim |
|---|---|---|
| 镜像 | 8.17GB (full) | 1.3GB (slim) |
| 净磁盘 | 38G/57G(71%) | 34G/57G(60%) |
| Recall | 0.5s | 0.16s (3x) |
| Retain | 5-10s | 28s (LLM 4K token) |
| GLIBC 兼容 | 2.38 容器编译 vector.so | 2.31 容器重新装 PG |
| bge-m3 | ✗(512 token 卡死) | ✓ (8192 token) |
| Embedded PG 启停 | 需手动 docker exec | 自动 |
| 挂载根分区数据 | 是(根分区吃紧) | 否(全 NVMe) |
6. 可直接复用的 5 条要点
- 容器镜像别偷懒挂旧 data——0.7.1 → 0.8.0 必用全新 data 目录,GLIBC 版本冲突无法绕过
- 容器挂载全归 NVMe——根分区 57GB 装系统已经够紧,bind mount 一旦写满系统直接挂
- bge-large-zh-v1.5 必换 bge-m3——512 token 限制会让 Hindsight consolidation 永久卡死
- 本地 reranker 暂缓切——Hindsight #1897 issue 在 0.7.1/0.8.0 都未修,先用 RRF 算法
- 统一重启脚本:
/app/hindsight/start_all.sh一行启 vLLM + Hindsight 两个容器,根分区腾出 4.3GB
7. 待解决(下一步)
- Hindsight #1897 官方修复后,可以切回 bge-reranker-v2-m3(精度 +5-15%)
- 0.7.1 时代 8,579 条干净数据(在 0.7.1 backup 里)可以走
/v1/default/banks/{bank_id}/import端点迁移 - 容器内启 bge-reranker-v2-m3 试 TEI 独立服务 — TEI 无 arm64 镜像,需要换方案
版本说明:基于 Jetson AGX Orin + Docker 27.x + Hindsight 0.8.0-slim(2026-06-09)+ bge-m3 1024 维 + DeepSeek flash 实测。 参考: - Hindsight 官方文档:https://github.com/vectorize-io/hindsight - Hindsight 0.8.0 升级 changelog - 上一篇文章:Hindsight 60s 不返回根因诊断(系列文 1)
本文由 admin 原创，转载请注明出处。
评论
0