ai-contract-platform/project-docs/archive/implementation-history/V2-ai-platform-migration-provider-flow-2026-06-22.md

V2 AI Platform Migration and Provider Flow Closure

日期：2026-06-22

本轮目标

继续推进 yuqei-ai-platform 的真实运行能力，把上一轮“配置、Prompt、知识、审计可落库”推进到：

• 有 Alembic migration。
• 有 OpenAI-compatible Provider Adapter。
• 法律问答按“知识检索 -> Prompt 渲染 -> Provider 调用 -> 回退 -> 审计”运行。
• 默认仍可在无 API Key 的情况下稳定工作。

已完成

1. Alembic 迁移底座

   • 新增 alembic.ini。
   • 新增 migrations/env.py。
   • 新增首个迁移 20260622_0001_create_ai_platform_tables.py。
   • 覆盖表：
     • ai_provider_configs
     • prompt_templates
     • knowledge_documents
     • ai_run_audits

2. Provider Adapter

   • 新增 providers.py。
   • 支持 DisabledProviderAdapter。
   • 支持 OpenAICompatibleProviderAdapter，接口按 /chat/completions 兼容格式调用。
   • 支持 AI_PLATFORM_PROVIDER_CALL_MODE。
   • 支持 AI_PLATFORM_PROVIDER_API_KEY、AI_PLATFORM_PROVIDER_BASE_URL、AI_PLATFORM_PROVIDER_REQUEST_TIMEOUT_SECONDS。
   • Provider 调用失败时可按 AI_PLATFORM_PROVIDER_FALLBACK_ENABLED 回退。

3. Prompt 渲染

   • 新增 prompts.py。
   • 法律问答模板支持：
     • {question}
     • {matter_context}
     • {citations}
   • 后台模板未写占位符时，会自动附加标准问题/背景/依据块。
   • 模板占位符写错时，会回退到内置默认模板，避免问答接口 500。

4. 法律问答主链路

   • 先检索知识文档。
   • 将检索结果转换为引用依据。
   • 渲染 Prompt。
   • 如果 provider 成功，使用 provider 回答。
   • 如果 provider 被禁用或失败，默认回退到规则型可审计回答。
   • 审计状态支持：
     • succeeded
     • fallback
     • failed

5. 部署配置

   • AI Platform Docker 镜像增加 alembic 和 httpx。
   • compose 本地环境显式设置：
     • AI_PLATFORM_REPOSITORY_BACKEND=sqlalchemy
     • AI_PLATFORM_DATABASE_AUTO_CREATE=true
     • AI_PLATFORM_PROVIDER_CALL_MODE=disabled
     • AI_PLATFORM_PROVIDER_FALLBACK_ENABLED=true

设计边界

• 合同系统仍不直接调用模型 provider。
• 合同系统仍只通过 SDK/OpenAPI 使用 AI 中台。
• 真实 provider 默认关闭，避免无密钥环境下影响开发、测试和演示。
• 当前 provider adapter 先支持 OpenAI-compatible 格式，DeepSeek、通义、私有模型可通过该格式优先接入。

下一轮建议

下一轮进入知识库检索增强：

1. 增加知识文档切分表。
2. 增加导入批次和索引状态。
3. 增加检索命中分数和来源定位。
4. 法律问答返回更结构化的“主要依据”列表。
5. 审计记录扩展 provider 错误、token、费用和命中文档 ID。