127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
|
# Lazy Stat（FastAPI 时间序列分析后端）
|
|||
|
|
|
|||
|
|
基于 FastAPI 的时间序列数据分析服务：上传 CSV → 运行多种统计/时序/多变量分析 → 返回结构化结果（包含 `steps[]` 明细，便于前端渲染与调试）。
|
|||
|
|
|
|||
|
|
## 功能概览
|
|||
|
|
|
|||
|
|
- 15+ 分析步骤：统计概览、时间序列分析、ACF/PACF、平稳性、正态性、季节分解、频谱、相关性、PCA、聚类、因子分析、协整检验、VAR 等
|
|||
|
|
- 统一输出结构：每一步包含 `summary` + `data/columns`（或 dict 结果），且保证 JSON 可序列化
|
|||
|
|
- 可选绘图：通过 `generate_plots` 控制是否生成图片，并通过文件接口访问
|
|||
|
|
|
|||
|
|
## 快速开始（本地）
|
|||
|
|
|
|||
|
|
一键启动（使用 `uv` 管理虚拟环境/依赖）：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
bash run.sh
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
启动后访问：
|
|||
|
|
|
|||
|
|
- Swagger: `http://localhost:60201/docs`
|
|||
|
|
- ReDoc: `http://localhost:60201/redoc`
|
|||
|
|
- Health: `http://localhost:60201/health`
|
|||
|
|
|
|||
|
|
服务入口为 `app.main:app`（见 [app/main.py](app/main.py)）。
|
|||
|
|
|
|||
|
|
## Docker / Compose
|
|||
|
|
|
|||
|
|
使用 Compose：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
docker compose up --build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Compose 配置见 [docker-compose.yml](docker-compose.yml)。
|
|||
|
|
|
|||
|
|
## 环境变量
|
|||
|
|
|
|||
|
|
示例文件见 [.env.example](.env.example)。常用变量：
|
|||
|
|
|
|||
|
|
- `HOST` / `PORT`：监听地址与端口（默认 `0.0.0.0:60201`）
|
|||
|
|
- `ENV` / `DEBUG`：运行环境
|
|||
|
|
- `MAX_MEMORY_MB`：内存阈值（超过会触发 gc）
|
|||
|
|
- `ANALYSIS_TIMEOUT`：分析超时（如有）
|
|||
|
|
- `MY_API_KEY`：外部大模型 API Key
|
|||
|
|
|
|||
|
|
开发/冒烟测试如果不希望调用外部大模型，可设置：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
export MY_API_KEY=simulation-mode
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
如果希望仅开放 v2（OSS URL）分析接口、禁用 v1 上传/文件/图片接口，可设置：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
export API_MODE=v2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API 使用
|
|||
|
|
|
|||
|
|
所有 API 都挂在 `/api` 前缀下。
|
|||
|
|
|
|||
|
|
### 1) 上传 CSV
|
|||
|
|
|
|||
|
|
`POST /api/upload`（当前实现仅支持 CSV）：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -F "file=@test/comprehensive_test_data.csv" \
|
|||
|
|
-F "task_description=demo" \
|
|||
|
|
http://localhost:60201/api/upload
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
返回会给出 `filename`（服务端保存后的文件名），后续分析时使用它。
|
|||
|
|
|
|||
|
|
### 2) 运行分析
|
|||
|
|
|
|||
|
|
`POST /api/analyze`：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -H "Content-Type: application/json" \
|
|||
|
|
-d '{
|
|||
|
|
"filename": "<upload 返回的 filename>",
|
|||
|
|
"task_description": "demo",
|
|||
|
|
"language": "zh",
|
|||
|
|
"generate_plots": false
|
|||
|
|
}' \
|
|||
|
|
http://localhost:60201/api/analyze
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应结构要点：
|
|||
|
|
|
|||
|
|
- `meta`: 文件名、语言、是否绘图、创建时间等
|
|||
|
|
- `analysis.<lang>.steps[]`: 每个分析步骤的结构化结果（`key/title/summary/data/columns/api_analysis` 等）
|
|||
|
|
- `images`: 当 `generate_plots=true` 时包含图片文件名；可用 `GET /api/image/{filename}` 获取
|
|||
|
|
|
|||
|
|
### 2.1) v2：从 OSS URL 分析（推荐）
|
|||
|
|
|
|||
|
|
`POST /api/v2/analyze`：传入 `oss_url`，后端会下载到临时文件分析并返回结构化 `steps[]`；默认不产图（你也可以传 `generate_plots=true` 以保持与 v1 同能力）。
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -H "Content-Type: application/json" \
|
|||
|
|
-d '{
|
|||
|
|
"oss_url": "https://<your-oss-presigned-url>",
|
|||
|
|
"task_description": "demo",
|
|||
|
|
"language": "zh",
|
|||
|
|
"generate_plots": false
|
|||
|
|
}' \
|
|||
|
|
http://localhost:60201/api/v2/analyze
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3) 其他接口
|
|||
|
|
|
|||
|
|
- `GET /api/available_methods`：列出可用分析方法
|
|||
|
|
- `GET /api/list_uploads`：列出 uploads 文件
|
|||
|
|
- `GET /api/download/{filename}`：下载文件
|
|||
|
|
|
|||
|
|
## 生成“完整文本输出”（用于调试/验收）
|
|||
|
|
|
|||
|
|
脚本 [run_analysis_on_test_data.py](run_analysis_on_test_data.py) 会对测试数据跑完整流程，并把每一步的 `summary + details` 输出到 `test/results/*.txt`，适合检查 p 值、数组、DataFrame 等完整信息：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python3 run_analysis_on_test_data.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 部署
|
|||
|
|
|
|||
|
|
生产部署说明见 [DEPLOYMENT.md](DEPLOYMENT.md)。
|