yuqei/ai-contract-platform
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
af057ff16592e62dedcd5e46de67e84854ea6292
ai-contract-platform/project-docs/archive/implementation-history/V2-ai-trace-admin-console-2026-06-23.md
T
yuqei af057ff165 chore: archive project history and preserve delivery controls 
Keep current plans and release controls discoverable without losing historical evidence, and include the reviewed Windows start/stop workflow.
2026-10-08 19:05:30 +08:00

8.2 KiB
Raw Blame History

V2 AI Trace 管理后台闭环记录

日期：2026-06-23

本轮目标

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

已落地内容

  1. AI run 审计字段增强。

    • AiRunAudit.prompt_preview
    • ai_run_audits.prompt_preview
    • 新增迁移 20260623_0006_add_ai_run_prompt_preview.py

  2. 法律问答调用写入 Prompt 摘要。

    • 每次 /api/v1/legal/qa 会把渲染后的 Prompt 截取前 4000 字符写入审计。
    • 保留 provider、model、provider_status、provider_error、token、费用、耗时、检索来源等既有 trace 字段。

  3. 契约和 SDK 同步。

    • OpenAPI AiRun 新增 prompt_preview。
    • Python SDK AiRunAudit 新增 prompt_preview。

  4. 前端管理区新增 AI Trace 可视化。

    • 新增 /admin/ai-traces。
    • 管理侧边栏新增 AI Trace。
    • 管理首页新增 AI 调用 Trace 入口。
    • 页面支持：
      • 最近调用数、总 token、平均耗时、异常调用数。
      • 按状态筛选。
      • 按问题、模型、错误、法条来源搜索。
      • 展开查看 Prompt、回答、知识命中、token、费用、错误、Trace ID。

  5. 前端同源代理。

    • 新增 /api/ai-platform/audit/ai-runs。
    • 服务端读取：
      • AI_PLATFORM_API_BASE_URL
      • NEXT_PUBLIC_AI_PLATFORM_API_BASE_URL
      • 默认 http://localhost:8101

  6. 本轮补齐单条 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] 同源代理。

  7. AI Trace 页面升级为双栏工作台。

    • 左侧保留调用列表、搜索、状态筛选和质量筛选。
    • 右侧展示选中调用的完整追查详情。
    • 顶部显示 Trace ID、Provider 状态、检索策略、来源数、耗时、费用。
    • 详情区集中展示 Prompt、回答、知识命中分数、质量标签、复核状态、token 成本和 provider 错误。
    • 质量标签仍可在详情内直接处理为待处理、已复核、误报、已处理。

  8. 本轮补齐 Trace 到质量改进项的处理闭环。

    • Trace 详情自动加载已有质量改进项，并识别是否已经关联当前 run 和质量标签。
    • 对缺少依据、来源不足、fallback、模型失败、token 异常、耗时异常等标签显示“生成改进项”入口。
    • 创建改进项时自动带入 source_run_ids、source_label_codes、Prompt 模板、知识库来源和根因建议。
    • 创建成功后当前标签显示“已关联改进项”，管理员可以进入质量看板继续处理。

  9. 本轮补齐 Trace 与质量看板的双向回看。

    • 质量看板的改进项卡片可从 source_run_ids 一键打开原始 Trace。
    • /admin/ai-traces?runId=... 会自动选中并加载对应 Trace 详情。
    • Trace 详情会展示关联改进项的状态、类型、负责人、优先级和处理结果摘要。

  10. 本轮补齐质量改进项筛选和效果回看。

    • 质量看板的改进项支持按来源 Trace ID、标签 code、处理人、状态、优先级、动作类型和维度组合筛选。
    • Trace 详情的关联改进项展示改前、当前、完成后的异常率和质量分。
    • Trace 详情同步展示异常率变化和质量分变化，帮助判断处理动作是否有效。

  11. 本轮补齐质量改进项详情页和审计链。

    • AI Platform 新增 GET /api/v1/audit/quality-improvement-actions/{action_id}。
    • OpenAPI 和 Python SDK 同步新增单条质量改进项查询。
    • 合同 Web 新增 /admin/ai-quality-dashboard/[actionId] 详情页。
    • 详情页集中展示来源 Trace、关联 Prompt、知识库、导入批次、处理记录和效果曲线。
    • 质量看板改进项卡片新增“查看详情”入口。

  12. 本轮补齐配置变更反向追溯。

    • Prompt 中心展示每个 Prompt 版本由哪些质量改进项触发，并可回到改进项详情。
    • 新增 /admin/ai-knowledge，展示知识库导入批次和触发它们的质量改进项。
    • 新增 /admin/ai-models，展示模型配置记录和触发调参的质量改进项。
    • 新增合同 Web 同源代理 /api/ai-platform/model-configs。
    • 改进项详情页可直达 Prompt 中心、知识导入和模型配置记录。

  13. 本轮补齐配置变更执行增强。

    • 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 是否改善”。
  • 给知识库导入增加真实文件上传/解析队列和失败重试记录。
Reference in New Issue View Git Blame Copy Permalink