feat: add ai platform migrations and provider flow

2026-06-22 20:58:47 +08:00
parent 3f46b59f76
commit ccf35ca586
17 changed files with 673 additions and 12 deletions
@@ -0,0 +1,77 @@
+# 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。