ai-contract-platform/project-docs/archive/implementation-history/V2-ai-knowledge-worker-object-storage-ocr-2026-06-23.md

AI Platform V2 知识库 Worker / 对象存储 / OCR 闭环记录

时间：2026-06-23 19:58

本轮目标

按照《AI 合同平台 V2 重构版开发方案》，把知识库导入从“同步上传即解析”升级为：

1. 上传接口只负责接收原始文件、写入对象存储、创建 ingestion job。
2. worker 真实消费 queued/failed 任务，读取暂存原始文件，解析并落库为导入批次、文档、切片。
3. OCR 走可配置 provider，扫描件在未配置 OCR 时明确进入待 OCR 状态。
4. 管理后台展示真实任务状态，避免误导管理员以为上传已完成解析。

已完成

1. 对象存储暂存

• 新增 ObjectStorage 协议。
• 新增 local fallback：LocalObjectStorage。
• 新增 S3/MinIO 兼容实现：S3CompatibleObjectStorage。
• 上传接口返回 202 Accepted 和 KnowledgeIngestionJob。
• job 记录新增：
  • title
  • reference
  • mime_type
  • file_size_bytes
  • storage_backend
  • storage_bucket
  • storage_object_key

2. Worker 消费循环

• worker 支持：
  • --health
  • --run-once
  • 默认持续轮询
• run_once 会：
  • 从数据库获取 queued/failed ingestion job
  • 标记为 running
  • 读取对象存储原始文件
  • 解析文本/PDF/DOCX/可 OCR 图片
  • 成功后创建 import batch、document、chunk
  • 失败后记录 parse/ocr 状态和错误原因

3. OCR Provider

• 新增 DisabledOcrProvider。
• 新增 HttpOcrProvider，通过配置接入真实 OCR 服务。
• 支持 bearer token。
• OCR 返回 JSON 中的 text、content 或 result 字段。
• 扫描图片/PDF 无可读文本且 OCR 未配置时，job 会标记为：
  • status=failed
  • parse_status=ocr_required
  • ocr_status=pending

4. 重试语义

• 有对象存储引用的失败任务，重试后重新进入 queued。
• 没有保留原始文件的旧任务，才提示重新上传。

5. SDK / OpenAPI / 前端

• Python SDK upload_knowledge_document 返回 KnowledgeIngestionJob。
• OpenAPI 上传接口改为 202 + KnowledgeIngestionJob。
• 管理后台知识库上传成功后展示“已入队，等待 worker 解析”。
• 前端代理透传 AI Platform 的 202 状态码。
• 知识库筛选项同时来源于已完成批次和待处理任务。

配置项

AI Platform API：

AI_PLATFORM_OBJECT_STORAGE_BACKEND=local|s3
AI_PLATFORM_OBJECT_STORAGE_LOCAL_DIR=.runtime/ai-platform-objects
AI_PLATFORM_OBJECT_STORAGE_BUCKET=ai-platform-uploads
AI_PLATFORM_OBJECT_STORAGE_ENDPOINT_URL=http://localhost:9000
AI_PLATFORM_OBJECT_STORAGE_ACCESS_KEY_ID=...
AI_PLATFORM_OBJECT_STORAGE_SECRET_ACCESS_KEY=...
AI_PLATFORM_OBJECT_STORAGE_REGION_NAME=us-east-1

Worker：

YUQEI_WORKER_DATABASE_URL=postgresql+psycopg://...
YUQEI_WORKER_OBJECT_STORAGE_BACKEND=local|s3
YUQEI_WORKER_OBJECT_STORAGE_LOCAL_DIR=.runtime/ai-platform-objects
YUQEI_WORKER_OBJECT_STORAGE_BUCKET=ai-platform-uploads
YUQEI_WORKER_OBJECT_STORAGE_ENDPOINT_URL=http://localhost:9000
YUQEI_WORKER_OBJECT_STORAGE_ACCESS_KEY_ID=...
YUQEI_WORKER_OBJECT_STORAGE_SECRET_ACCESS_KEY=...
YUQEI_WORKER_OBJECT_STORAGE_REGION_NAME=us-east-1
YUQEI_WORKER_OCR_PROVIDER=disabled|http
YUQEI_WORKER_OCR_ENDPOINT_URL=https://ocr.example.com/extract
YUQEI_WORKER_OCR_API_KEY=...
YUQEI_WORKER_OCR_TIMEOUT_SECONDS=30

验证结果

已通过：

python -m pytest yuqei-ai-platform\services\ai-platform-api\tests\test_platform_data.py -q
python -m pytest yuqei-ai-platform\services\worker\tests -q
python -m pytest yuqei-ai-sdk-python\tests\test_ai_platform.py -q
python -c "import yaml, pathlib; yaml.safe_load(pathlib.Path('yuqei-ai-platform/packages/ai-openapi/openapi.yaml').read_text(encoding='utf-8')); print('openapi ok')"
npm --prefix yuqei-contract-platform/apps/contract-web run build

下一步建议

1. 增加 worker 进程部署脚本和 systemd/docker compose 运行方式。
2. 给知识库导入任务增加后台“立即执行一次 worker”的管理按钮。
3. 增加 OCR provider 管理界面，把 endpoint、key、超时、启用状态纳入 AI Platform 配置中心。
4. 增加对象存储连通性健康检查，提前发现 MinIO/S3 凭据错误。