Honcho 嵌入向量维度修改：从 1536 到 1024

Nite 收录于教程

2026-06-26 约 200 字预计阅读 1 分钟

问题

Honcho 用 pgvector 存嵌入向量。首次启动时 Alembic 迁移会把 embedding 列固定为 vector(1536)——这是 Honcho 的默认值。

我在 .env 里设的是：

EMBEDDING_VECTOR_DIMENSIONS=1024
EMBEDDING_MODEL_CONFIG__MODEL=bge-m3
EMBEDDING_MODEL_CONFIG__TRANSPORT=openai
EMBEDDING_MODEL_CONFIG__DIMENSIONS_MODE=always

bge-m3 输出 1024 维向量，但数据库列已经是 vector(1536) 了。启动验证器检测到 schema 和配置不一致，直接拒绝启动，API 容器日志里报维度不匹配。

为什么不能改 .env 就完事

EMBEDDING_VECTOR_DIMENSIONS 在 Honcho 里被当作不可变配置。维度由 Alembic 迁移在首次运行时 pin 住，之后改 .env 不会触发 ALTER COLUMN。官方文档的 Bootstrapping non-default dimensions 章节专门讲了这个问题。

要改维度，得用容器内的 scripts/configure_embeddings.py 脚本，而且表得是空的。如果有数据，官方说只能重建新部署再迁移数据，没有原地 re-embedding 的途径。

部署结构

我的 Honcho 用 Podman + Quadlet 部署在 ~/pod/honcho，结构大致是：

文件	作用
`honcho.pod`	Pod 定义，publish 8001:8000
`honcho-database.container`	pgvector/pgvector:pg15
`honcho-redis.container`	Redis 缓存
`honcho-api.container`	Honcho API 服务
`honcho-deriver.container`	Deriver 服务
`.env`	环境变量配置

数据库容器用的是 pgvector/pgvector:pg15 镜像，自带 pgvector 扩展。init.sql 里只有一行 CREATE EXTENSION IF NOT EXISTS vector;。

修复步骤

1. 启动临时容器

API 容器因为验证失败起不来，但数据库和 Redis 是好的。需要一个能访问数据库网络的容器来跑脚本，同时覆盖 entrypoint 让它别启动 Honcho：

systemctl --user start honcho-database.service honcho-redis.service

podman run --rm -d --name honcho-bootstrap \
  --pod systemd-honcho \
  -v /home/nite/pod/honcho/.env:/app/.env:ro \
  -e DB_CONNECTION_URI=postgresql+psycopg://postgres:[email protected]:5432/postgres \
  --entrypoint sh \
  ghcr.io/plastic-labs/honcho:latest \
  -c "sleep 300"

--pod systemd-honcho 是 Quadlet 生成的 pod 名（加了 systemd- 前缀）。用 --entrypoint sh -c "sleep 300" 让容器只是活着，不跑 Honcho 的启动流程。

2. 预览修改

podman exec honcho-bootstrap /app/.venv/bin/python scripts/configure_embeddings.py --dry-run

dry-run 会输出打算做什么：DROP HNSW 索引 → ALTER 列为 vector(1024) → 重建 HNSW 索引。确认无误再执行。

3. 执行修改

podman exec honcho-bootstrap /app/.venv/bin/python scripts/configure_embeddings.py --yes

脚本在单事务内完成，我的表是空的所以直接 ALTER 没问题。

4. 清理并启动

podman rm -f honcho-bootstrap
systemctl --user start honcho-api.service honcho-deriver.service

验证一下：

curl -s http://127.0.0.1:8001/health
# {"status":"ok"}