微服务技术栈即完成度细则

[lyy001017]

描述

目标

搭建一个可复用的基于 Chronos-2 时间序列预测系统，后端基于 FastAPI + AutoGluon + MCP，前端基于 React + Vite + Ant Design，提供 Zero-shot / Finetune 预测、指标评估（WQL/WAPE/IC/IR）、可视化和 MCP 工具接入，用于快速集成到业务预测场景。

已完成内容

1. 后端（server）

• 技术栈

  • FastAPI / Pydantic（API 服务）
  • AutoGluon TimeSeries（Chronos-2 接入）/ PyTorch
  • Pandas（数据处理）
  • MCP（FastMCP + mcp Python SDK）

• 数据输入字段示例

  • Data（item_id,timestamp,target,covarties)
  • 根据item_id作为不同时间序列标识
  • timestamp支持分钟频、时频、日频、年频等时间间隔
  • target 待预测目标值
  • covarties 分为历史协变量和未来已知协变量，特别的未来已知协变量需提供未来预测步长日期的相应协变量数据并传入对应协变量列名，其余协变量将被识别作为过去协变量（开启with_cov）。

• 核心能力

  • Zero-shot 预测
  • Finetune 预测
  • 多分位预测输出（P5-p95预测输出）
  • 误差指标指标输出：WQL / WAPE / IC / IR
  • MCP 工具接入

• 业务服务

  • DataProcess（app/services/process.py）：
    • 解析 Markdown 的 ```json块数据输入
    • 校验字段：timestamp / item_id / target
    • with_cov 开关：传入covarties。开启并在json中提供未来已知协变量列名的字段被识别为未来已知协变量，其余被自动识别为历史协变量；关闭时进行单变量预处理（忽略协变量）。
  • ZeroShot (app/services/zero_shot_forecast.py）：
    • 基于Chronos2 Zero-shot 预测服务
    • 预测输出覆盖p5-p95区间多分位数
  • FineTune (app/services/finetune_forecast.py）：
    • 基于Chronos2 Finetune 预测服务
    • 提供微调参数（步长、学习率等）及协变量进行微调预测。
  • Metrics （app/services/custom_metrics.py）：
    • 提供WQL、WAPE、IC、IR等指标预测（根据提供数据内部切分出数据进行预测验证）

• API 路由

  • GET /health：健康检查
  • POST /zeroshot：Zeroshot预测
  • POST /finetune：Finetune预测

• 错误码/异常

  • 响应格式统一为：
    {
    "success": false,
    "error_code": "1001",
    "message": "错误信息",
    "details": {}
    }
  • 主要错误示例：
    • DATA_FORMAT_ERROR：输入格式错误（Markdown 无法解析、timestamp 无法解析等）
    • DATA_MISSING_COLUMNS：必要字段缺失（timestamp/item_id/target 或协变量列缺失）
    • DATA_EMPTY：history_data 为空
    • FUTURE_COV_MISMATCH：future_cov 长度不等于 prediction_length
    • VALIDATION_ERROR：参数合法性错误（prediction_length 超限、quantiles 超范围等）
    • MODEL_NOT_READY：AutoGluon 未安装或不可用
    • MODEL_LOAD_FAILED：模型加载失败（权重路径缺失/模型文件不完整）
    • MODEL_PREDICT_FAILED：模型预测失败（推理过程中异常）
    • (内部) evaluate_failed：指标计算异常（记录在 metrics.warnings 中）

• MCP 能力

  • Tools：
    • chronos_zeroshot_forecast
      • 入参：markdown, prediction_length, quantiles, metrics, with_cov, freq
      • 返回：predictions + metrics + prediction_length + quantiles
    • chronos_finetune_forecast
      • 入参：markdown, prediction_length, quantiles, metrics, with_cov, freq, finetune_num_steps, finetune_learning_rate, finetune_batch_size, context_length
      • 返回：predictions + metrics
  • Resources：
    • chronos://overview（服务介绍）
    • chronos://sample_markdown（Markdown 输入样例）
    • chronos://error_codes（错误码说明）
  • Prompts：
    • chronos_zeroshot_guide（Zero-shot 操作指南）
    • chronos_finetune_guide（Finetune 操作指南）
    • 提示词文件化（md文档）存放在server/app/mcp/handlers/prompt_templates/

测试（当前待完善）

• 已有基础测试：server/tests/test_forecast_output.py
• 缺少：
  • 预测接口 e2e 测试
  • metrics 逻辑单测（IC/IR）

2. 前端（frontend）

• 技术栈

  • React 18 / TypeScript / Vite
  • Ant Design
  • ECharts

• 主要能力

  • Markdown 文件上传
  • 参数配置（prediction_length / quantiles / metrics / with_cov / finetune 参数）
  • 指标卡（WQL/WAPE/IC/IR + warning）
  • 可视化图表（P50 主线 + P10~P90 区间）
  • 结果表格与导出
  • 使用教程 Drawer

• API 封装

  • src/api/client.ts
    • zeroshot / finetune 封装
    • 支持 metrics/quantiles/context_length/with_cov

• 异常展示

  • 统一显示请求错误
  • 指标 warning 显示在 MetricsCard

3. 工程与文档

• Docker 与编排

  • docker-compose.yml 一键启动
    -服务：

    • server：后端（容器名timeseries_forecast，端口：5001）

    • frontend：前端（容器名timeseries_forecast_frontend，对外暴露端口：5173:80）
      -用法：
      docker compose up -d

    • 配置：

  • 后端 config.env:
    • DEBUG,LOG_LEVEL,APP_NAME,APP_VERSION
    • CHRONOS_MODEL_PATH,AG_CHRONOS_MODEL_NAME,DEFAULT_CONTEXT_LENGTH,MAX_CONTEXT_LENGTH,MAX_UPLOAD_MB
    • MCP_ENABLED,MCP_PATH,MCP_VERSION
  • 前端.env（可选）：
    • VITE_API_BASE_URL=/api

• 根README

  • 根 README 链接到子目录 README
  • 统一说明
    • 项目结构与技术栈
    • 后端/前端本地开发启动方式
    • Docker 启动方式
    • MCP 能力说明
    • 测试运行方式与覆盖范围
    • 如何在将本项目扩展并接入其他项目

验收标准

1. 前端

• 前端 npm run dev 能正常启动
• Markdown 上传正常解析并可提取展示摘要
• 参数配置后调用 API 成功
• 预测结果在图表与表格展示一致（n+1..n+m）
• 指标卡展示 WQL/WAPE/IC/IR输出正常
• With Cov 开关关闭时，协变量被忽略

2. 服务端

• /health 正常返回
• /zeroshot 预测返回 predictions + metrics
• /finetune 预测返回 predictions + metrics + model_id
• 预测输出时间范围严格是未来 n+1..n+m
• IC/IR 使用历史最后 m 天作为验证区间
• with_cov=false 时 future_cov 被忽略

3. MCP

• MCP SSE 地址可连接（/mcp/sse）
• list_tools 返回两类工具
• list_resources 返回 sample_markdown 等资源
• get_prompt 返回对应指南
• ollama_client.py 能调用工具并输出结果

4. 部署

• docker compose up --build 可一键启动前后端
• 后端容器可访问 /docs
• 前端容器可访问页面并调用后端