全量重索引迁移指南
本章节介绍如何将向量库从旧结构迁移到新版高并发 Ingest 流程，归纳常见动因、操作步骤、性能观测与标准作业流程（SOP），为例行或突发重建提供参考。迁移过程涉及多种场景和技术细节，需结合实际需求进行评估。
迁移动因
迁移通常由以下几类原因驱动，具体分类及说明如下：
| 分类 | 说明 |
|---|---|
| 模型升级 | 嵌入模型切换（Gemini → Qwen）导致向量语义空间不兼容 |
| 维度变更 | EMBED_DIM 调整（768 → 1024）需要重新写入一致维度 |
| 分块策略优化 | chunkText 改版（标题先切 + 标点再切）影响上下文粒度 |
| 元数据模式变更 | 新增 language、url 归一化策略，需要一致性回填 |
| 数据清理 | 积累无用 / 旧路径 / draft 遗留向量需清除 |
迁移前需充分了解上述动因，以便制定合适的迁移方案。
环境准备
在正式迁移前，需完成环境和权限的准备工作。以下是主要的检查项：
- 确认 Cloudflare Vectorize 索引名称及维度与
wrangler.toml中 EMBED_DIM 一致 - 验证
ADMIN_TOKEN权限（/admin/clear-all、/admin/upsert） - 测试嵌入 API，确保返回合法维度
- 配置本地网络代理（如需），减少失败重试
确保所有准备项均已通过，有助于后续流程顺利进行。
操作流程
迁移操作分为若干步骤，以下表格总结了每一步的动作、命令及产出：
| 步骤 | 动作 | 命令 / 行为 | 产出 |
|---|---|---|---|
| 1 | 统计现状 | （可选）采样查询 topK | 基线样本 |
| 2 | 清空向量库 | DELETE /admin/clear-all | 计数日志 totalDeleted |
| 3 | 启动 ingest | npm run ingest (fast-ingest) | 并发批量写入 |
| 4 | 监控日志 | 观察 chunks/sec & 错误率 | 性能与失败样本 |
| 5 | 验证抽查 | /admin/test-query & /debug | 匹配质量确认 |
| 6 | 记录指标 | 耗时、总向量、失败重试数 | 迁移过程记录 |
| 7 | 上线 | 切换前端指向更新后 Worker | 生效 |
每一步都需关注产出结果，及时调整策略以保证迁移质量。
清空阶段说明
在清空阶段，需通过 Worker 的 DELETE /admin/clear-all 接口批量删除旧数据。该操作会循环模拟查询批次（dummy vector topK=100）并调用 deleteByIds，直到批量返回不足为止。输出的 totalDeleted 可用于确认旧数据体量。
注意：Vectorize 暂无“一键 truncate”，批量删除需控制超时，必要时分多次执行，避免因超时导致删除不完整。
Ingest 高并发阶段
高并发 ingest 阶段涉及多个关键参数，合理配置可提升写入效率。以下是主要参数及其作用：
MAX_CONCURRENT_FILES // 文件读取 + 解析并发
MAX_CONCURRENT_EMBEDDINGS // API 调用并发
EMBEDDING_BATCH_SIZE // 单请求文本数量（Qwen=10, Gemini=1）
UPLOAD_BATCH_SIZE // 聚合后单次 upsert 数量（示例 300）
调度逻辑为：文件按批启动 → 分块 → 分批嵌入 → 聚合到阈值即触发 upsert。失败的 upload 批会回退到队列头部等待重试，确保数据最终一致。
小结
本章总结了向量库重索引迁移的动因、准备、操作流程及关键参数。通过规范化清空、批量高并发 ingest、性能监控与指标记录，可有效提升迁移效率并降低风险。建议迁移前充分验证环境与权限，迁移过程中关注性能与错误率，迁移后及时抽查匹配质量，确保新结构稳定上线。