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


## 问题

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](https://honcho.dev/docs/v3/contributing/configuration#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：

```bash
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:postgres@127.0.0.1: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. 预览修改

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

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

### 3. 执行修改

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

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

### 4. 清理并启动

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

验证一下：

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

---

> 作者: Nite  
> URL: https://www.nite07.com/zh-cn/posts/honcho-embedding-dimensions/