必须重建索引，因为Dify不自动刷新向量索引，旧索引仍指向已删改文本，导致检索错位、引用失效或返回空内容；重建方式有后台手动、API批量和CLI命令行三种，平滑切换需启用双索引、验证新索引、原子切换并清理旧索引。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
为什么必须重建索引
知识库文档更新后，Dify不会自动刷新向量索引，旧索引仍指向已删除或修改的文本块，导致检索结果错位、答案引用失效、甚至返回空内容。不重建索引就上线新文档，等于让AI在过期地图上导航。
触发重建的三种方式
方法一：后台手动触发（适合单次小范围更新）
进入 Dify 管理后台 → 点击左侧「知识库」→ 找到目标知识库 → 点击右上角「…」→ 选择「重新索引」→ 等待状态栏变为「已完成」。
方法二：API批量重建（适合多知识库或CI/CD集成）
调用 /v1/knowledge-bases/{kb_id}/indexing-status 获取当前状态，确认为 idle 后，POST 请求 /v1/knowledge-bases/{kb_id}/re-index，Body 为空 JSON {}。响应返回 task_id，需轮询 /v1/tasks/{task_id} 直至 status 变为 succeeded。
方法三：CLI命令行重建（适合运维脚本化操作）
在部署 Dify 的服务器上执行：dify-cli knowledge-base reindex --kb-id "kb-abc123"。该命令会阻塞等待完成，失败时直接抛出非零退出码，可嵌入 Shell 脚本做条件判断。
平滑切换的关键操作
第一步：启用双索引模式
在 Dify 后端配置中将 REINDEXING_STRATEGY 设为 swap（默认为 inplace）。这会让系统在重建期间保留旧索引服务，同时构建全新索引副本，避免查询中断。
第二步：确认新索引就绪
重建完成后，不要立即切流。先用测试 query 调用 /v1/knowledge-bases/{kb_id}/search?query=测试关键词&top_k=3，比对返回的 document_id 和 content 是否与最新文档一致。若出现旧段落或缺失字段，说明切分逻辑或 embedding 模型版本不匹配，需检查 chunk_size 和 embedding_model 配置是否与首次建库时完全相同。
第三步：原子化切换
执行 PUT /v1/knowledge-bases/{kb_id}/switch-index，Body 中传入 {"target_index_version": "v2"}。该操作是原子的，毫秒级完成，旧索引立即下线，新索引瞬间接管全部流量。【target_index_version 必须与重建任务返回的 version 字段严格一致，大小写敏感】
第四步：清理旧索引
切换成功 5 分钟后，确认无报错日志且监控指标平稳，再执行 DELETE /v1/knowledge-bases/{kb_id}/index?v=old_version 彻底释放磁盘空间。未清理的旧索引会持续占用向量库资源，影响后续重建速度。
