# V2 模型长任务异步体验与开发质量基线验收报告

日期：2026-08-26  
阶段状态：已完成开发与本地验收，允许继续开发和受控测试；不代表生产开放条件已经满足。

## 1. 阶段结论

本阶段已将法律问答等长时间模型调用从浏览器同步等待改造成持久化后台任务。前端提交后立即获得任务编号，通过轮询展示排队、检索、模型生成、输出校验和完成状态；失败后可重试，降级结果不会伪装成成功，无法自动恢复时可进入人工接管并记录处理结果。

已使用当前开发环境的真实 `gpt-5.6-sol` 完成一次约两分钟的端到端验收。任务在服务重启后仍可查询，证明任务状态和审计证据不是浏览器内存状态。

## 2. 目标与边界

本阶段解决以下问题：

- 避免 HTTP 请求和页面在模型生成期间持续阻塞约两分钟；
- 让用户看到任务当前阶段、进度、尝试次数和建议操作；
- 将重试、显式 fallback、人工接管和人工处理结果纳入同一状态机；
- 为排队耗时、执行耗时、失败率、降级率和人工接管率建立可查询基线；
- 让本地单进程开发和共享部署 Worker 使用同一份持久化任务数据。

本阶段没有放宽以下上线边界：

- 当前 GPT 会员桥接仍只用于开发和测试，不作为生产 Provider 合同；
- 真实用户注册仍受正式政策、同意证据和受控试点门禁约束；
- fallback 只表示降级结果，不等于模型成功；
- 本地审计记录不包装成第三方存证、司法效力或真实双云验收结论。

## 3. 交付范围

### 3.1 持久化任务状态机

新增 `model_inference_jobs` 数据模型和 Alembic 迁移，状态包括：

- `queued`：已接收，等待执行；
- `running`：Worker 已领取，正在检索、调用模型或校验输出；
- `succeeded`：真实模型调用和结果处理成功；
- `fallback`：使用了显式降级结果，可重试或转人工；
- `failed`：执行失败且当前没有可交付结果；
- `awaiting_human`：进入人工接管队列；
- `resolved`：人工处理完成并留下处理说明；
- `cancelled`：任务取消的保留状态。

任务记录包含租户、业务类型、进度、尝试次数、最大尝试次数、错误码、审计运行编号、Worker 租约、接管原因、处理人、排队/执行/总耗时和完整时间戳。

### 3.2 API 与租户隔离

新增的核心 API：

- `POST /api/v1/legal/qa/jobs`
- `POST /api/v1/legal/contract-review/jobs`
- `GET /api/v1/model-jobs`
- `GET /api/v1/model-jobs/metrics`
- `GET /api/v1/model-jobs/{job_id}`
- `POST /api/v1/model-jobs/{job_id}/retry`
- `POST /api/v1/model-jobs/{job_id}/handoff`
- `POST /api/v1/model-jobs/{job_id}/resolve`

Contract API 增加法律问答任务代理，使用服务端可信的租户与用户上下文，不接受浏览器自行伪造租户。Python SDK 和两份 OpenAPI 契约同步更新。

### 3.3 后台执行与故障恢复

- 本地单进程开发可使用应用后台任务，降低启动复杂度；
- Compose/共享部署使用独立 Worker 领取持久化任务；
- Worker 支持跨租户公平领取任务、批次上限和执行者名称；
- 运行任务具有租约，进程异常退出后可回收超时租约，避免永久卡死；
- 重试会创建清晰的新执行尝试并清理旧错误/旧结果，保留任务审计链；
- fallback、失败和人工接管是不同业务结果，指标口径不会混淆。

### 3.4 前端长任务体验

法律问答页面已改为：

1. 提交后立即返回任务编号；
2. 根据服务端建议间隔轮询，展示排队、检索、模型生成和校验阶段；
3. 展示当前尝试次数与最大尝试次数；
4. 页面轮询超过 10 分钟时只停止当前浏览器等待，不取消服务端任务；
5. 成功后显示答案、引用和 AI 审计链路；
6. fallback 明确标为降级结果，并提供“重试”和“转人工”；
7. 失败状态提供可重试与人工接管入口；
8. 人工接管后显示队列状态，不再让用户反复提交同一请求。

## 4. 真实模型端到端验收

验收环境：已登录的超级管理员 Chrome 会话，本地 Web `:3000`、Contract API `:8100`、AI Platform API `:8101`，Provider 为开发环境 `gpt-5.6-sol`。

测试问题：技术开发合同中的知识产权归属和验收条款应重点关注哪些风险？

验收证据：

| 项目 | 结果 |
| --- | --- |
| 任务编号 | `model-job-899d26992bb24cd7` |
| 最终状态 | `succeeded / completed` |
| 尝试次数 | 1 |
| 排队耗时 | 169 ms |
| 模型执行耗时 | 126,497 ms |
| 总耗时 | 126,667 ms |
| AI 审计运行编号 | `run-8439276a0a0a` |
| 浏览器控制台错误 | 未发现 |
| 服务重启后查询 | 仍可查询，状态和耗时未丢失 |

前端在模型生成期间持续显示后台生成状态，没有维持两分钟的同步 HTTP 请求；最终显示答案、3 条引用及审计链路入口。

### 4.1 验收中发现并修复的质量问题

第一次真实运行暴露出模板兼容问题：数据库中的 `legal_chat_default` 使用 `{{question}}`，旧渲染器只按 Python 单花括号格式处理，导致实际提示词残留 `{question}`，模型错误判断为“没有提供问题”。

已修复为同时兼容：

- V1/导入模板的双花括号占位符；
- Python 风格的单花括号占位符；
- 不含占位符的旧纯文本模板。

修复后通过真实数据库模板渲染检查，问题和检索上下文均已注入，提示词中不再残留 `{question}` 或 `{review_context}`。该次首跑只能证明异步链路成功，不能作为答案质量样本；答案质量基线应使用修复后的后续样本重新累计。

## 5. 指标基线

新增租户级模型任务指标接口，可按时间窗口返回：

- 各状态任务数量；
- fallback、失败、人工接管、重试比例；
- 排队、执行和总耗时的 P50/P95。

当前本地开发数据库只有 1 条真实样本：总任务 1、失败率 0、fallback 率 0、总耗时 P50 为 126,667 ms。样本量过小，不能据此承诺正式 SLO；它只用于证明口径与采集链路可工作。

建议受控试点的初始观察门槛：

- 至少累计 30 个真实长任务后再确定 P50/P95 基线；
- 分开统计排队等待和 Provider 执行时间；
- fallback、重试后成功、人工处理成功不得合并为“一次成功”；
- 按租户、业务类型和 Provider 下钻，避免总体数据掩盖单租户故障。

## 6. 自动化验证结果

| 验证项 | 结果 |
| --- | --- |
| AI Platform 全量测试 | 通过 |
| 模型任务状态机测试 | 3/3 通过 |
| Provider/提示词相关测试 | 通过 |
| Worker 测试 | 7/7 通过 |
| Contract API 法律问答代理 | 2/2 通过 |
| Python SDK 测试 | 5/5 通过 |
| 基础设施发布工具测试 | 92/92 通过 |
| Next Web 全量脚本测试 | 通过 |
| Next Web TypeScript 检查 | 通过 |
| 两份 OpenAPI YAML 解析 | 通过 |
| Alembic 头检查与本地 PostgreSQL 升级 | 单一 head，升级成功 |
| 本地三服务健康检查 | Web/API/AI 均返回 200 |

已知非本阶段失败：Contract API 全量测试中，账号冲突测试仍期望未配置正式政策时注册返回 200，而当前正确的 fail-closed 上线门禁返回 503。该测试与异步模型任务无关，本阶段没有为了让旧测试通过而削弱合规门禁。

本机没有可用的 Docker CLI，因此未在本机执行 `docker compose config --quiet`；Compose 配置已由基础设施自动化测试覆盖，仍应在具备 Docker 的 CI/预发布主机再次验证。

## 7. 主要代码与配置位置

- AI 任务领域服务：`yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/model_jobs.py`
- AI 任务 API：`yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/api/model_jobs.py`
- 数据迁移：`yuqei-ai-platform/services/ai-platform-api/migrations/versions/20260826_0026_add_model_inference_jobs.py`
- Worker：`yuqei-ai-platform/services/worker/src/yuqei_worker/main.py`
- 提示词兼容修复：`yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/prompts.py`
- SDK：`yuqei-ai-sdk-python/src/yuqei_sdk/ai_platform.py`
- Contract API 代理：`yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/api/contracts_core.py`
- Web 页面：`yuqei-contract-platform/apps/contract-web/src/app/legal-qa/legal-qa-client.tsx`
- Compose：`yuqei-infra/compose/docker-compose.yml`

## 8. 尚未解决的产品与工程风险

1. 页面刷新或离开后，后端任务仍存在，但页面还没有“我的模型任务”历史入口；用户需要任务列表页才能自然回到未完成任务。
2. 尚未实现提交幂等键，网络重发可能创建两个业务相同的任务。
3. 尚未提供用户主动取消与 Worker 协作取消；当前 `cancelled` 是预留状态。
4. 当前只有轮询，没有站内通知、邮件或企业微信完成通知。
5. 指标接口已经存在，但尚未接入试点运营后台的模型任务专属告警与 SLA 看板。
6. 真实输出质量还需要自动规则：占位符泄漏、答非所问、引用为空、引用与正文不一致都应进入质量告警或人工复核。
7. 真实 Provider 的生产 API 密钥、限流、成本预算、数据处理协议和故障演练仍未完成。

## 9. 下一阶段建议

建议进入“模型任务运营闭环与质量门禁”，按以下顺序推进：

1. 增加“我的模型任务”历史与详情页，支持刷新、跨页面返回和继续查看；
2. 为创建任务增加幂等键，并实现可协作取消；
3. 将模型任务指标接入 P1-07 运营后台，增加排队过长、P95 超标、fallback 激增和人工队列积压告警；
4. 增加输出质量校验器，对占位符泄漏、缺少引用、明显拒答或答非所问自动失败/转人工；
5. 在修复后的提示词上完成至少 30 个受控样本，建立真实耗时、成功率和答案质量基线；
6. 取得生产 Provider 和法务材料后，再进行受控预发布验收，不以当前 GPT 会员桥接直接开放真实用户。