OpenSearch 重建索引脚本

脚本路径

scripts/reindex_opensearch.php

脚本作用

根据 PostgreSQL 中已经完成向量化的 chunk，重新构建 OpenSearch 中的 proofdb_chunks 索引内容，并刷新每条 chunk 的派生搜索字段。

脚本会做这些事：

确保 OpenSearch 索引存在。
判断当前是“断点续跑”还是“全量重建”。
按 archive 选取待处理数据，并按 OpenSearch bulk batch 调用现有 indexing handler。
批量写入 chunk 文档。
输出基于 chunk 数的进度条、batch 明细和最终统计结果。

断点续跑语义

默认模式下，脚本会尽量保留已经完成的 indexed 进度：

如果 OpenSearch 索引还在，就只把 queued / indexing / failed_retryable 的 chunk 重新置回 pending，然后继续处理。
如果 OpenSearch 索引已经不存在，脚本会自动切换到全量重建模式，把所有已向量化 chunk 重新置回 pending。

这意味着如果中途断电、断网、进程被杀：

已经标记为 indexed 的 chunk 进度不会丢。
未完成的那部分在下次重跑脚本时会继续。

如果你明确想从头开始全部重建，可以手动加 --reset。

更具体地说：

如果 PostgreSQL 里该 chunk 已经是 indexed，默认 resume 不会重写它，即使 OpenSearch 里同 _id 文档已经存在。
--reset 会把目标范围内所有已向量化 chunk 的 search_index_status 统一重置为 pending，然后重新 upsert 到 OpenSearch。

运行前提

PostgreSQL 可连接。
OpenSearch 可连接。
目标 chunk 的 embedding_status 已经是 embedded。
项目依赖已安装完成。
从项目根目录执行命令。

如果本地 OpenSearch 使用 HTTPS 且证书是自签名：

OPENSEARCH_SSL_VERIFY=false php scripts/reindex_opensearch.php

运行命令

全量重建：

php scripts/reindex_opensearch.php

强制从头全量重建：

php scripts/reindex_opensearch.php --reset

只重建一个 archive：

php scripts/reindex_opensearch.php --archive_uid=01KQHVREB6XPYF604RVZAP9NNY

成功输出示例

Progress granularity: OpenSearch bulk batches (up to 500 chunks each)
Reindexing [================================] 100.0% (14/14)
Batch #1 archive=01KQHVREB6XPYF604RVZAP9NNY chunks=14 progress=14/14
OpenSearch reindex completed.
Index: proofdb_chunks
Archive filter: (all embedded archives)
Mode: resume
Eligible embedded chunks: 14
OpenSearch bulk size: 500
Reset chunks: 3
Indexed archives: 1
Processed batches: 1
Indexed chunk rows now marked indexed: 14
Archives: 01KQHVREB6XPYF604RVZAP9NNY

关于进度条为什么可能“0 到 100”

这个脚本的进度条是按 chunk 数 计算的，但刷新粒度是 一次 OpenSearch bulk batch 完成后。

所以如果：

当前只有一个 archive 需要处理
且该 archive 的待处理 chunk 数小于等于 opensearch.bulk.chunk_size

那么终端上就会像是从 0 直接跳到 100。这不是脚本没工作，而是因为这次实际只跑了 1 个 bulk batch。

适用场景

proofdb_chunks 被误删后恢复。
数据库里 search_index_status=3，但 OpenSearch 中没有对应文档。
索引 mapping 重建后，需要把已经 embedding 完成的数据重新灌回 OpenSearch。
archive 的 summary、title、tags 等搜索元数据有更新后，需要刷新到 OpenSearch。

重要限制

这个脚本只处理已经向量化完成的 chunk。

它不会：

重新生成 embedding。
修复 embedding 失败的数据。
修复 PostgreSQL 中缺失的 archive 或 chunk。

4.0 KiB Raw Blame History Unescape Escape