yuqei/ai-contract-platform

Fork 0

Files

T

yuqei a3bb78e06b

Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s

Details

release: freeze V2 release candidate

2026-07-12 15:32:24 +08:00

8.2 KiB

Raw Blame History

V2 AI Trace 管理后台闭环记录

日期：2026-06-23

本轮目标

让管理员能在 V2 管理区直接查看 AI 调用 Trace，定位每次法律问答或后续 AI 能力调用的模型、Prompt、知识命中、token、费用、错误和耗时。

已落地内容

AI run 审计字段增强。
- AiRunAudit.prompt_preview
- ai_run_audits.prompt_preview
- 新增迁移 20260623_0006_add_ai_run_prompt_preview.py
法律问答调用写入 Prompt 摘要。
- 每次 /api/v1/legal/qa 会把渲染后的 Prompt 截取前 4000 字符写入审计。
- 保留 provider、model、provider_status、provider_error、token、费用、耗时、检索来源等既有 trace 字段。
契约和 SDK 同步。
- OpenAPI AiRun 新增 prompt_preview。
- Python SDK AiRunAudit 新增 prompt_preview。
前端管理区新增 AI Trace 可视化。
- 新增 /admin/ai-traces。
- 管理侧边栏新增 AI Trace。
- 管理首页新增 AI 调用 Trace 入口。
- 页面支持：
  - 最近调用数、总 token、平均耗时、异常调用数。
  - 按状态筛选。
  - 按问题、模型、错误、法条来源搜索。
  - 展开查看 Prompt、回答、知识命中、token、费用、错误、Trace ID。
前端同源代理。
- 新增 /api/ai-platform/audit/ai-runs。
- 服务端读取：
  - AI_PLATFORM_API_BASE_URL
  - NEXT_PUBLIC_AI_PLATFORM_API_BASE_URL
  - 默认 http://localhost:8101
本轮补齐单条 Trace 详情钻取。
- AI Platform 新增 GET /api/v1/audit/ai-runs/{run_id}。
- OpenAPI 新增 getAiRun 契约。
- Python SDK 新增 get_ai_run_audit(run_id)。
- 合同 Web 新增 /api/ai-platform/audit/ai-runs/[runId] 同源代理。
AI Trace 页面升级为双栏工作台。
- 左侧保留调用列表、搜索、状态筛选和质量筛选。
- 右侧展示选中调用的完整追查详情。
- 顶部显示 Trace ID、Provider 状态、检索策略、来源数、耗时、费用。
- 详情区集中展示 Prompt、回答、知识命中分数、质量标签、复核状态、token 成本和 provider 错误。
- 质量标签仍可在详情内直接处理为待处理、已复核、误报、已处理。
本轮补齐 Trace 到质量改进项的处理闭环。
- Trace 详情自动加载已有质量改进项，并识别是否已经关联当前 run 和质量标签。
- 对缺少依据、来源不足、fallback、模型失败、token 异常、耗时异常等标签显示“生成改进项”入口。
- 创建改进项时自动带入 source_run_ids、source_label_codes、Prompt 模板、知识库来源和根因建议。
- 创建成功后当前标签显示“已关联改进项”，管理员可以进入质量看板继续处理。
本轮补齐 Trace 与质量看板的双向回看。
- 质量看板的改进项卡片可从 source_run_ids 一键打开原始 Trace。
- /admin/ai-traces?runId=... 会自动选中并加载对应 Trace 详情。
- Trace 详情会展示关联改进项的状态、类型、负责人、优先级和处理结果摘要。
本轮补齐质量改进项筛选和效果回看。
- 质量看板的改进项支持按来源 Trace ID、标签 code、处理人、状态、优先级、动作类型和维度组合筛选。
- Trace 详情的关联改进项展示改前、当前、完成后的异常率和质量分。
- Trace 详情同步展示异常率变化和质量分变化，帮助判断处理动作是否有效。
本轮补齐质量改进项详情页和审计链。
- AI Platform 新增 GET /api/v1/audit/quality-improvement-actions/{action_id}。
- OpenAPI 和 Python SDK 同步新增单条质量改进项查询。
- 合同 Web 新增 /admin/ai-quality-dashboard/[actionId] 详情页。
- 详情页集中展示来源 Trace、关联 Prompt、知识库、导入批次、处理记录和效果曲线。
- 质量看板改进项卡片新增“查看详情”入口。
本轮补齐配置变更反向追溯。
- Prompt 中心展示每个 Prompt 版本由哪些质量改进项触发，并可回到改进项详情。
- 新增 /admin/ai-knowledge，展示知识库导入批次和触发它们的质量改进项。
- 新增 /admin/ai-models，展示模型配置记录和触发调参的质量改进项。
- 新增合同 Web 同源代理 /api/ai-platform/model-configs。
- 改进项详情页可直达 Prompt 中心、知识导入和模型配置记录。
本轮补齐配置变更执行增强。
- AI Platform 新增模型配置发布记录：
  - 新增 ai_provider_config_changes 表和迁移 20260623_0009_add_provider_config_changes.py。
  - POST /api/v1/model-configs 支持 changed_by、change_note 审计字段。
  - 新增 GET /api/v1/model-configs/changes 查看模型参数变更前后快照。
- AI Platform 新增知识导入批次执行接口：
  - GET /api/v1/knowledge-import-batches/{batch_id} 返回批次、文档、chunk 明细。
  - GET /api/v1/knowledge-import-batches/{batch_id}/documents 返回批次文档。
  - GET /api/v1/knowledge-import-batches/{batch_id}/chunks 返回批次切片。
  - POST /api/v1/knowledge-import-batches/{batch_id}/reindex 按批次重建索引。
- OpenAPI 和 Python SDK 同步新增上述契约和客户端方法。
- 合同 Web 新增同源代理：
  - /api/ai-platform/model-configs/changes
  - /api/ai-platform/knowledge-import-batches/[batchId]
  - /api/ai-platform/knowledge-import-batches/[batchId]/documents
  - /api/ai-platform/knowledge-import-batches/[batchId]/chunks
  - /api/ai-platform/knowledge-import-batches/[batchId]/reindex
- /admin/ai-models 从只读页升级为可编辑执行页：
  - 支持新增/编辑模型配置。
  - 支持启用、默认模型、temperature、max tokens、base URL 参数保存。
  - 保存即生成模型参数发布记录。
  - 页面展示最近参数发布记录和触发调参的质量改进项。
- /admin/ai-knowledge 从只读页升级为知识批次执行页：
  - 支持展开批次详情。
  - 展示文档列表、索引状态、chunk locator、embedding provider/model/dimension。
  - 支持按批次重建索引，并展示重建结果。

验收重点

AI Platform 执行一次法律问答后，GET /api/v1/audit/ai-runs 返回 prompt_preview。
GET /api/v1/audit/ai-runs/{run_id} 能按 ID 返回完整 Trace 详情，缺失 ID 返回 404。
合同 Web 打开 /admin/ai-traces 能看到列表、筛选、指标和详情。
AI Platform 不可用时，页面显示清晰错误状态，不影响管理区其他页面。
管理员在 Trace 工作台选中一条记录后，可直接查看 Prompt、回答、命中来源、质量标签、耗时和费用。
管理员可在 Trace 详情的异常质量标签旁一键生成质量改进项，生成后能看到已关联状态。
管理员可从质量看板的改进项回到原始 Trace，也能在 Trace 详情看到关联改进项处理进展。
管理员可按来源 Trace、标签 code、处理人和状态组合筛选改进项，并在 Trace 详情查看处理后的效果变化。
管理员可打开单个质量改进项详情页，集中查看来源、关联变更、处理记录和效果曲线。
管理员可从 Prompt、知识导入、模型配置页面反向查看触发它们的质量改进项。
管理员可在模型配置页保存参数，保存后可看到模型参数发布记录。
管理员可在知识导入页展开批次，查看文档和 chunk 状态，并按批次重建索引。

本轮验证

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

建议下一步

进入配置执行结果质量闭环：

将模型参数发布记录、Prompt 发布记录、知识库重建索引记录统一挂回质量改进项详情页。
在改进项详情页展示“执行动作是否完成、是否产生新版本/新索引、后续 Trace 是否改善”。
给知识库导入增加真实文件上传/解析队列和失败重试记录。

8.2 KiB Raw Blame History