# model-prediction

**Repository Path**: blue-cave/model-prediction

## Basic Information

- **Project Name**: model-prediction
- **Description**: 一个专注于模型预测的开源项目，提供高效、准确的预测算法和工具，支持多种应用场景，助力开发者快速实现数据驱动的决策。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# model-prediction

的历史数据预测服务：提供**模型训练**与**预测**两个接口，模型与元数据仅保存至 `models/` 目录，不使用数据库。所有依赖与运行均在**项目虚拟环境（venv）**内进行，不安装到全局。

## 安装（仅虚拟环境）

在项目根目录执行，使用项目自带的 venv，不污染全局 Python：

```bash
# 1. 创建虚拟环境（仅创建，不安装包到全局）
python -m venv venv

# 2. 激活虚拟环境
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# Windows CMD:
venv\Scripts\activate.bat
# Linux / macOS:
source venv/bin/activate

# 3. 在虚拟环境中安装依赖（仅安装到 venv）
pip install -r requirements.txt
```

## 启动服务

**必须先激活 venv**，再启动 API：

```bash
# 激活 venv 后
python run.py
```

或：

```bash
uvicorn src.api.main:app --host 0.0.0.0 --port 8000
```

默认访问：http://localhost:8000 ，交互文档：http://localhost:8000/docs

## 接口说明

### POST /train（训练）

- **请求**：`multipart/form-data`，必填 `file`（CSV 文件），可选 `forecast_period`（预测步数，默认 1；也可用环境变量 `FORECAST_PERIOD` 配置）。
- **成功**：200，返回 `status`、`message`、`best_model_name`、`leaderboard`。
- **样本不足**：400，需至少 300 条可训练样本。
- 训练完成后，Pipeline 与元数据写入 `models/pipeline.joblib`、`models/meta.json`。

### POST /predict（预测）

- **请求**：`multipart/form-data`，必填 `file`（CSV，与训练同结构），可选 `forecast_period`（默认取 `models/meta.json` 中训练时的 `forecast_period`，再兜底环境变量 `FORECAST_PERIOD`）。
  - 兼容保留 `horizon_days`，但要求与 `forecast_period` 一致，否则会返回 400（避免触发重新训练）。
- **成功**：200，返回 `forecast`（时间点 + 预测值）、`metadata`（algorithm、inference_latency_ms 等）。
- **未训练**：503，需先调用 `/train`。
- **数据长度不足**：400，需满足 `min_history_length`（见 meta）。

## 数据格式

- **文件**：CSV，UTF-8 编码。
- **必需列**：`date`（时间）、`pollution_today`（目标变量）；可含其他特征列。
- **行数**：训练建议 ≥300 条；预测时至少需满足训练时保存的 `min_history_length`。

示例：

```csv
date,pollution_today,dew,temp,press,wnd_spd,snow,rain,pollution_yesterday
2025/1/1,75.21,-1.2,4.8,1012.3,2.1,0,0,75.21
2025/1/2,76.85,-0.8,5.1,1008.5,1.5,0,0,75.21
```

## 示例调用

```bash
# 训练（上传 CSV）
curl -X POST "http://localhost:8000/train" -F "file=@data.csv" -F "forecast_period=3"

# 预测（上传与训练同结构的 CSV）
curl -X POST "http://localhost:8000/predict" -F "file=@data.csv" -F "forecast_period=3"
```

## 项目结构

```
model-prediction/
├── config/          # 默认列名（date, pollution_today）
├── src/
│   ├── etl/         # ETL 与训练深度分档
│   ├── engine/      # ForecastingEngine、AutoTSWrapper（Auto_TS）
│   └── api/         # FastAPI：/train、/predict
├── models/          # 训练产出（pipeline.joblib、meta.json）
├── docs/            # 开发流程文档等
├── venv/            # 虚拟环境（不提交）
├── requirements.txt
├── run.py           # 启动入口
└── README.md
```

## 说明

- **依赖与运行均在虚拟环境中进行**，请勿在全局执行 `pip install` 或直接使用系统 `python` 运行服务。
- 详细开发流程与方案见 [docs/开发流程文档.md](docs/开发流程文档.md)。