ai-contract-platform/project-docs/V2-ai-knowledge-ingestion-worker-timeline-2026-06-23.md

V2 AI 知识库上传任务与配置执行时间线闭环

日期：2026-06-23

本轮目标

按照《AI 合同平台 V2 重构版开发方案》，继续把知识库上传、文档解析、OCR、失败重试这类长流程能力收敛到 yuqei-ai-platform，合同 Web 只做管理展示和触发动作。

已完成

1. AI Platform 新增 KnowledgeIngestionJob

   • 记录知识库上传任务状态：queued / running / succeeded / failed
   • 记录解析状态：pending / parsed / failed / ocr_required / ocr_skipped
   • 记录 OCR 状态：not_required / pending / skipped / succeeded / failed
   • 记录失败原因、重试次数、关联导入批次、关联文档、worker 名称。

2. 上传接口升级为可追踪任务

   • POST /api/v1/knowledge-bases/{knowledge_base_id}/documents
   • 成功上传会返回 ingestion_job
   • 解析失败或扫描件无可读文本时，也会落一条失败任务，并在错误响应中返回任务信息。

3. 失败重试入口

   • GET /api/v1/knowledge-ingestion-jobs
   • POST /api/v1/knowledge-ingestion-jobs/{job_id}/retry
   • 当前 MVP 对已有关联导入批次的任务执行重建索引。
   • 对解析前失败且原始文件未暂存的任务，明确返回需要重新上传，避免伪造“已重试成功”。

4. 数据库迁移

   • 新增迁移：20260623_0011_add_knowledge_ingestion_jobs.py
   • 新增表：knowledge_ingestion_jobs
   • 增加状态、批次、文档、时间字段索引。

5. OpenAPI 与 Python SDK

   • OpenAPI 增加 KnowledgeIngestionJob schema 和任务查询/重试接口。
   • KnowledgeDocumentUploadResult 增加 ingestion_job。
   • AiQualityImprovementExecutionBundle 增加 knowledge_ingestion_jobs。
   • SDK 增加 list_knowledge_ingestion_jobs、retry_knowledge_ingestion_job。

6. 管理区前端

   • /admin/ai-knowledge 增加 Ingestion jobs 任务状态区。
   • 支持查看上传任务状态、解析状态、OCR 状态、失败原因、重试次数。
   • 失败任务支持从页面触发 retry。
   • 质量改进项详情页新增统一配置执行时间线：
     • 模型参数发布/回滚
     • Prompt 发布/回滚
     • 知识库上传任务
     • 知识库重建索引

与 V2 方案的一致性

• 新能力位于 yuqei-ai-platform，没有写入合同业务后端。
• 合同 Web 只通过 AI Platform API 代理展示和触发动作。
• SDK 与 OpenAPI 同步更新，保持 AI 中台调用边界清晰。
• OCR 目前是任务状态和扩展点，不假装已有完整 OCR 引擎。
• 真正 worker 队列后续可以直接消费 knowledge_ingestion_jobs，不需要推翻管理页和 SDK。

验证

• python -m pytest yuqei-ai-platform\services\ai-platform-api\tests\test_platform_data.py -q
• python -m pytest yuqei-ai-sdk-python\tests\test_ai_platform.py -q
• npm --prefix yuqei-contract-platform/apps/contract-web run build
• OpenAPI YAML 解析通过
• git diff --check 通过

后续建议

下一步可继续进入真实 worker 执行循环：把当前 API 同步解析逻辑拆成任务创建 + worker 消费，并接入对象存储暂存原始上传文件、真实 OCR provider、任务日志和幂等键。