暂存
This commit is contained in:
+2
-2
@@ -5,8 +5,8 @@
|
||||
- [setup_database.md](/www/proofdb/scriptdoc/setup_database.md): PostgreSQL 结构初始化与升级
|
||||
- [setup_admin_users.md](/www/proofdb/scriptdoc/setup_admin_users.md): 管理员用户表与首个管理员账号初始化
|
||||
- [setup_opensearch.md](/www/proofdb/scriptdoc/setup_opensearch.md): OpenSearch 索引初始化
|
||||
- [reembed_chunks.md](/www/proofdb/scriptdoc/reembed_chunks.md): chunk 向量重新生成与断点续跑
|
||||
- [reindex_opensearch.md](/www/proofdb/scriptdoc/reindex_opensearch.md): OpenSearch 重建索引与回灌
|
||||
- [backfill_archive_content.md](/www/proofdb/scriptdoc/backfill_archive_content.md): 历史 archive `content` 正文字段回填
|
||||
|
||||
## 当前运维脚本
|
||||
|
||||
@@ -14,8 +14,8 @@
|
||||
scripts/setup_database.php
|
||||
scripts/setup_admin_users.php
|
||||
scripts/setup_opensearch.php
|
||||
scripts/reembed_chunks.php
|
||||
scripts/reindex_opensearch.php
|
||||
scripts/backfill_archive_content.php
|
||||
```
|
||||
|
||||
## 推荐顺序
|
||||
|
||||
@@ -1,76 +1,13 @@
|
||||
# Archive Content 回填脚本
|
||||
# Archive Content 回填脚本（已废弃）
|
||||
|
||||
## 脚本路径
|
||||
`archives.content` 与 `archives.raw` 已经从 PostgreSQL 设计中移除。
|
||||
|
||||
```text
|
||||
scripts/backfill_archive_content.php
|
||||
```
|
||||
因此：
|
||||
|
||||
## 脚本作用
|
||||
- `scripts/backfill_archive_content.php` 不再执行任何回填逻辑
|
||||
- 该脚本现在只会输出废弃提示并退出
|
||||
|
||||
回填历史 `archives.content` 字段。
|
||||
当前约定是：
|
||||
|
||||
这个脚本主要用于修复旧数据中 `content` 为空的问题。它会按下面顺序尝试生成 `content`：
|
||||
|
||||
1. 如果 archive 有 `raw`，就按当前导入规则把原始 Markdown 规范化成正文文本。
|
||||
2. 如果 `raw` 为空，就按 `chunk_index` 顺序拼接现有 chunk 的 `text` 作为回退正文。
|
||||
|
||||
脚本不会伪造 `raw`。如果历史数据里 `raw` 丢了，脚本只会尽力补 `content`。
|
||||
|
||||
## 运行前提
|
||||
|
||||
- 当前环境中的 PostgreSQL 配置可用。
|
||||
- 项目依赖已安装完成。
|
||||
- 从项目根目录执行命令。
|
||||
|
||||
## 运行命令
|
||||
|
||||
默认只处理 `content` 为空的 archive：
|
||||
|
||||
```bash
|
||||
php scripts/backfill_archive_content.php
|
||||
```
|
||||
|
||||
只处理一个 archive：
|
||||
|
||||
```bash
|
||||
php scripts/backfill_archive_content.php --archive_uid=01KQHVREB6XPYF604RVZAP9NNY
|
||||
```
|
||||
|
||||
强制重算，即使 `content` 已经有值：
|
||||
|
||||
```bash
|
||||
php scripts/backfill_archive_content.php --force
|
||||
```
|
||||
|
||||
只预览，不写数据库：
|
||||
|
||||
```bash
|
||||
php scripts/backfill_archive_content.php --dry-run
|
||||
```
|
||||
|
||||
## 成功输出示例
|
||||
|
||||
```text
|
||||
[updated] 01KQHVREB6XPYF604RVZAP9NNY source=chunks content_length=6375
|
||||
Archive content backfill completed.
|
||||
Archive filter: auto
|
||||
Force mode: no
|
||||
Dry run: no
|
||||
Scanned: 1
|
||||
Updated: 1
|
||||
From raw: 0
|
||||
From chunks: 1
|
||||
Skipped: 0
|
||||
```
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 修复旧版本导入留下的 `archives.content` 为空问题。
|
||||
- 导入逻辑更新后，希望重算归一化正文。
|
||||
- 为后续 AI / RAG / archive 级读取补齐正文字段。
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 如果历史数据既没有 `raw`，也没有 chunks，脚本会跳过该 archive。
|
||||
- 用 chunks 回填时，得到的是拼接后的正文文本，不会恢复原始 Markdown 结构。
|
||||
- archive 正文从 `chunks` 重建
|
||||
- 原始 Markdown 由 PostgreSQL 外部的原始来源负责保存
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# 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
|
||||
```
|
||||
@@ -13,10 +13,29 @@ scripts/reindex_opensearch.php
|
||||
脚本会做这些事：
|
||||
|
||||
1. 确保 OpenSearch 索引存在。
|
||||
2. 把已向量化 chunk 的 `search_index_status` 重置为待索引。
|
||||
3. 按 archive 批量重新投递索引任务。
|
||||
4. 调用现有 OpenSearch indexing handler 批量写入 chunk 文档。
|
||||
5. 输出重建统计结果。
|
||||
2. 判断当前是“断点续跑”还是“全量重建”。
|
||||
3. 按 archive 选取待处理数据，并按 OpenSearch bulk batch 调用现有 indexing handler。
|
||||
4. 批量写入 chunk 文档。
|
||||
5. 输出基于 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。
|
||||
|
||||
## 运行前提
|
||||
|
||||
@@ -40,6 +59,12 @@ OPENSEARCH_SSL_VERIFY=false php scripts/reindex_opensearch.php
|
||||
php scripts/reindex_opensearch.php
|
||||
```
|
||||
|
||||
强制从头全量重建：
|
||||
|
||||
```bash
|
||||
php scripts/reindex_opensearch.php --reset
|
||||
```
|
||||
|
||||
只重建一个 archive：
|
||||
|
||||
```bash
|
||||
@@ -49,15 +74,33 @@ php scripts/reindex_opensearch.php --archive_uid=01KQHVREB6XPYF604RVZAP9NNY
|
||||
## 成功输出示例
|
||||
|
||||
```text
|
||||
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)
|
||||
Reset chunks: 14
|
||||
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` 被误删后恢复。
|
||||
|
||||
@@ -14,6 +14,7 @@ scripts/setup_database.php
|
||||
|
||||
- `archives` 表存在。
|
||||
- `chunks` 表存在。
|
||||
- `archives.content` 与 `archives.raw` 冗余列会被移除。
|
||||
- 档案与 chunk 的常用索引存在。
|
||||
- embedding / search index 相关状态字段存在。
|
||||
- `updated_time` 自动更新时间触发器存在。
|
||||
|
||||
Reference in New Issue
Block a user