114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
# Chunk 重新 Embedding 脚本
|
||
|
||
## 脚本路径
|
||
|
||
```text
|
||
scripts/reembed_chunks.php
|
||
```
|
||
|
||
## 脚本作用
|
||
|
||
根据 PostgreSQL 中已有的 `chunks.text`，重新生成 embedding，并把结果写回 `chunks.embedding_*` 字段。
|
||
|
||
脚本会做这些事：
|
||
|
||
1. 判断当前是“断点续跑”还是“全量重建”。
|
||
2. 把需要恢复的 chunk 状态置回 `pending`。
|
||
3. 逐个 archive 拉取待处理 chunk，并按 embedding request batch 调用现有 handler。
|
||
4. 输出基于 chunk 数的进度条、batch 明细和最终统计结果。
|
||
|
||
## 断点续跑语义
|
||
|
||
默认模式下，脚本会尽量**保留已经完成的 `embedded` 进度**：
|
||
|
||
- 只把 `queued / processing / failed_retryable` 的 chunk 重新置回 `pending`
|
||
- 已经是 `embedded` 的 chunk 不会重复生成
|
||
- `failed_terminal` 也不会自动重试
|
||
|
||
这意味着如果中途断电、断网、进程被杀：
|
||
|
||
- 已经成功写回 embedding 的 chunk 进度不会丢
|
||
- 未完成的那部分在下次重跑脚本时会继续
|
||
|
||
如果你明确想从头开始全部重新 embedding，可以手动加 `--reset`。
|
||
|
||
## 运行前提
|
||
|
||
- PostgreSQL 可连接。
|
||
- BigModel / Zhipu embedding API 配置可用。
|
||
- 项目依赖已安装完成。
|
||
- 从项目根目录执行命令。
|
||
|
||
## 运行命令
|
||
|
||
默认断点续跑：
|
||
|
||
```bash
|
||
php scripts/reembed_chunks.php
|
||
```
|
||
|
||
强制从头全量重新 embedding：
|
||
|
||
```bash
|
||
php scripts/reembed_chunks.php --reset
|
||
```
|
||
|
||
只处理一个 archive：
|
||
|
||
```bash
|
||
php scripts/reembed_chunks.php --archive_uid=01KQHVREB6XPYF604RVZAP9NNY
|
||
```
|
||
|
||
## 成功输出示例
|
||
|
||
```text
|
||
Progress granularity: embedding request batches (up to 32 chunks each)
|
||
Re-embedding [================================] 100.0% (14/14)
|
||
Batch #1 archive=01KQHVREB6XPYF604RVZAP9NNY chunks=14 progress=14/14
|
||
Chunk re-embedding completed.
|
||
Archive filter: (all chunks)
|
||
Mode: resume
|
||
Eligible chunks: 14
|
||
Embedding batch size: 32
|
||
Reset chunks: 2
|
||
Processed archives: 1
|
||
Processed batches: 1
|
||
Embedded chunk rows now marked embedded: 14
|
||
Terminal failures: 0
|
||
Archives: 01KQHVREB6XPYF604RVZAP9NNY
|
||
Next step: refresh OpenSearch vectors with `php scripts/reindex_opensearch.php`
|
||
```
|
||
|
||
## 关于进度条为什么可能“0 到 100”
|
||
|
||
这个脚本的进度条是按 **chunk 数** 计算的，但刷新粒度是 **一次 embedding request batch 完成后**。
|
||
|
||
所以如果：
|
||
|
||
- 当前只有一个 archive 需要处理
|
||
- 且该 archive 的待处理 chunk 数小于等于 `LLM_EMBEDDING_BATCH_SIZE`
|
||
|
||
那么整个 archive 会在 1 次请求里完成，终端看起来就会像是从 `0` 直接跳到 `100`。这不是进度丢失，而是因为这次实际只跑了 `1` 个 batch。
|
||
|
||
## reset 行为
|
||
|
||
加 `--reset` 后，会把目标范围内的 chunk：
|
||
|
||
- `embedding_status` 重置为 `pending`
|
||
- 清空 `embedding_ref`
|
||
- 清空 `embedding_model`
|
||
- 清空 `embedding_error`
|
||
- 同时把 `search_index_status` 置回 `pending`
|
||
|
||
所以 `--reset` 的语义是：**把 embedding 和后续索引链路都当成需要重建**。
|
||
|
||
## 重要限制
|
||
|
||
这个脚本不会直接重建 OpenSearch。
|
||
|
||
重新 embedding 完成后，如果你希望 OpenSearch 中也使用新的向量，请继续执行：
|
||
|
||
```bash
|
||
php scripts/reindex_opensearch.php
|
||
```
|