Json-Python-Server/README.md

Lazy Stat（FastAPI 时间序列分析后端）

基于 FastAPI 的时间序列数据分析服务：上传 CSV → 运行多种统计/时序/多变量分析 → 返回结构化结果（包含 steps[] 明细，便于前端渲染与调试）。

功能概览

• 15+ 分析步骤：统计概览、时间序列分析、ACF/PACF、平稳性、正态性、季节分解、频谱、相关性、PCA、聚类、因子分析、协整检验、VAR 等
• 统一输出结构：每一步包含 summary + data/columns（或 dict 结果），且保证 JSON 可序列化
• 可选绘图：通过 generate_plots 控制是否生成图片，并通过文件接口访问

快速开始（本地）

一键启动（使用 uv 管理虚拟环境/依赖）：

bash run.sh

启动后访问：

• Swagger: http://localhost:60201/docs
• ReDoc: http://localhost:60201/redoc
• Health: http://localhost:60201/health

服务入口为 app.main:app（见 app/main.py）。

Docker / Compose

使用 Compose：

docker compose up --build

Compose 配置见 docker-compose.yml。

环境变量

示例文件见 .env.example。常用变量：

• HOST / PORT：监听地址与端口（默认 0.0.0.0:60201）
• ENV / DEBUG：运行环境
• MAX_MEMORY_MB：内存阈值（超过会触发 gc）
• ANALYSIS_TIMEOUT：分析超时（如有）
• MY_API_KEY：外部大模型 API Key

开发/冒烟测试如果不希望调用外部大模型，可设置：

export MY_API_KEY=simulation-mode

如果希望仅开放 v2（OSS URL）分析接口、禁用 v1 上传/文件/图片接口，可设置：

export API_MODE=v2

API 使用

所有 API 都挂在 /api 前缀下。

1) 上传 CSV

POST /api/upload（当前实现仅支持 CSV）：

curl -F "file=@test/comprehensive_test_data.csv" \
		 -F "task_description=demo" \
		 http://localhost:60201/api/upload

返回会给出 filename（服务端保存后的文件名），后续分析时使用它。

2) 运行分析

POST /api/analyze：

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 同能力）。

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 会对测试数据跑完整流程，并把每一步的 summary + details 输出到 test/results/*.txt，适合检查 p 值、数组、DataFrame 等完整信息：

python3 run_analysis_on_test_data.py

部署

生产部署说明见 DEPLOYMENT.md。