README.md

metadata

title: OilVerse
emoji: 🛢️
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860

🛢️ OilVerse — 油刃有余

花旗杯 · 油刃有余：油价因子量化分析预测平台 OilVerse: Oil Price Factor Quantitative Analysis and Forecasting Platform

---

📋 系统概述

基于 Temporal Fusion Transformer (TFT) + Conformal Quantile Regression + LightGBM 多模型集成的 WTI/Brent 油价月度风险预测系统。融合 329 个宏观经济、金融市场、地缘政治及 LLM 情绪因子，实现从数据采集到行业对冲决策的 端到端自动化管线。

🔬 核心技术创新

模块	技术	亮点
多模型集成	QR + CQR + LightGBM + TFT	4模型加权融合，分位数回归预测区间
Conformal Prediction	自适应 Conformal 校准	统计保证 80%+ 覆盖率，无分布假设
特征筛选漏斗	T-test → Granger → VIF → SHAP	329 → 17 精选因子，多阶段严格筛选
Regime 匹配	历史市场状态检测	自动匹配当前市场与历史情境（COVID/地缘冲突等）
因果网络	Granger 因果 + PC 算法	17 因子因果关系图，超越相关性分析
另类数据	SiliconFlow LLM 情绪评分	Qwen2.5-7B 新闻事件评分 + 消费者信心 + VIX 恐惧指数
因果叙事链	事件时间线 + 4 步因果推导	事件→因子异动→风险信号→对冲建议
AI Agent	混合架构 (本地秒回+LLM增强)	支持自然语言交互查询平台数据

---

🏗️ 系统架构

graph TB
  subgraph 数据层 [📡 数据层 — 7 数据源]
    A1[FRED API<br>95+ 宏观指标] --> B[面板构建器]
    A2[EIA API<br>35+ 能源数据] --> B
    A3[AKShare<br>消费者信心] --> B
    A4[SiliconFlow LLM<br>新闻情绪评分] --> B
    B --> C[月频面板<br>434月 × 329特征]
  end

  subgraph 特征层 [🔬 特征工程]
    C --> D[特征筛选漏斗<br>329→17]
    D --> E[精选17因子:<br>价格/供给/需求/地缘/技术/情绪]
  end

  subgraph 模型层 [🎯 多模型集成]
    E --> F1[Quantile Regression]
    E --> F2[Conformal QR]
    E --> F3[LightGBM]
    E --> F4[Temporal Fusion<br>Transformer]
    F1 & F2 & F3 & F4 --> G[Ensemble Engine<br>动态加权集成]
  end

  subgraph 决策层 [🛡️ 风险决策]
    G --> H[Conformal 校准<br>概率区间]
    H --> I[Regime 匹配<br>历史情境对标]
    I --> J[行业对冲<br>5大行业 × 3工具]
    I --> K[NLG 报告<br>自然语言研判]
  end

  subgraph 展示层 [📊 Dashboard]
    J & K --> L[React 前端<br>9 页面]
    L --> M[AI Agent<br>智能问答]
  end

---

📁 目录结构

.
├── run.py                      # 🚀 一键运行主入口
├── config.py                   # 全局配置 (路径/基准/行业)
├── api_server.py               # FastAPI 后端服务 (14 个 API)
├── requirements.txt            # Python 依赖
│
├── core/                       # 核心引擎
│   ├── engine.py               # Walk-Forward 引擎 + 多模型集成
│   ├── tft_model.py            # Temporal Fusion Transformer
│   ├── analysis.py             # SHAP/因子分析/NLG报告/消融实验
│   ├── hedging.py              # 对冲决策 + 回测
│   └── feature_selection.py    # 特征筛选漏斗 (329→17)
│
├── pipeline/                   # 数据管道
│   ├── data_pipeline.py        # 面板构建 (33 CSV → 1 面板)
│   ├── live_data.py            # 实时 API 数据更新
│   ├── news_sentiment.py       # LLM 新闻情绪因子
│   ├── news_intelligence.py    # 新闻事件解析
│   └── causal_analysis.py      # Granger 因果网络
│
├── agent/                      # AI Agent
│   ├── chat.py                 # 混合架构: 本地快速回复 + LLM 增强
│   └── __init__.py
│
├── frontend/                   # React 前端 (Vite)
│   ├── src/
│   │   ├── pages/              # 9 个页面组件
│   │   │   ├── P1Overview.jsx          # 决策概览 + 因果叙事链
│   │   │   ├── P2FactorAnalysis.jsx    # SHAP 因子分析
│   │   │   ├── P3RiskPrediction.jsx    # 风险预测时间线
│   │   │   ├── P4StressTest.jsx        # 压力测试情景
│   │   │   ├── P5IndustryImpact.jsx    # 行业冲击 + 对冲
│   │   │   ├── P6ModelValidation.jsx   # 消融实验 + 校准
│   │   │   ├── P7DataGovernance.jsx    # 数据治理
│   │   │   ├── P9AIAgent.jsx           # AI 智能问答
│   │   │   └── P9Pipeline.jsx          # 端到端管道 DAG
│   │   ├── components/         # 通用组件
│   │   │   ├── Sidebar.jsx     # 侧边栏导航
│   │   │   ├── EventTimeline.jsx # 因果叙事链时间线
│   │   │   └── CausalNetworkGraph.jsx  # 因果网络图
│   │   ├── context/            # React Context 状态管理
│   │   └── api.js              # API 请求封装
│   └── index.html
│
├── data/csv_raw/               # 原始 CSV 数据 (33 个文件)
├── output/                     # 管线输出
│   ├── v2_results_WTI.csv      # WTI 预测结果
│   ├── v2_results_Brent.csv    # Brent 预测结果
│   ├── v2_shap_records.json    # SHAP 解释性数据
│   ├── v2_nlg_reports.json     # NLG 自然语言报告
│   ├── v2_hedging.json         # 对冲决策
│   ├── v2_hedge_backtest.json  # 对冲回测
│   ├── v2_scenarios.json       # 压力测试情景
│   ├── v2_regime_data.json     # Regime 匹配数据
│   ├── v2_ablation.json        # 消融实验结果
│   ├── causal_analysis.json    # 因果网络分析
│   ├── event_timeline.json     # 事件时间线
│   └── feat_sel_funnel.json    # 特征筛选记录
└── scripts/                    # 数据获取脚本

---

🚀 快速启动

1. 安装依赖

pip install -r requirements.txt

2. 运行完整管线

# 完整流程 (含 API 数据更新)
python run.py

# 跳过数据更新 (使用现有数据)
python run.py --skip-update

管线执行流程 (~4.5 分钟):

Step	内容	耗时
Step 0	全特征 API 数据更新 (FRED/EIA/AKShare)	~45s
Step 1	特征筛选漏斗 (329→17)	~8s
Step 2	Walk-Forward 预测 (WTI + Brent, TFT×多fold)	~180s
Step 3	对冲决策 ×5 行业	~5s
Step 4	NLG 报告生成	~3s
Step 5	模型评估	~5s
Step 6	消融实验 (窗口 + 因子组)	~20s
Step 7	因果网络分析 (Granger + 滚动)	~15s

3. 启动服务

# 启动后端 API
python api_server.py
# → http://localhost:8765

# 启动前端 (新终端)
cd frontend && npm install && npm run dev
# → http://localhost:5173

---

📊 Dashboard 功能 (9 页面)

页面	功能	技术亮点
📊 P1 · 决策概览	风险等级/方向/波动率 + NLG 研判 + 因果叙事链	Regime 匹配 + 事件时间线
🔍 P2 · 因子分析	SHAP 因子重要度 + 6 因子组分解 + 因果网络图	GNN-style 因果 DAG 可视化
📈 P3 · 风险预测	1M/3M 概率区间 + 历史回测时间线	Conformal Prediction 校准
⚡ P4 · 压力测试	4 情景 (基准/VIX翻倍/供给中断/需求崩塌)	多维度冲击模拟
🏭 P5 · 行业与对冲	5 行业风险矩阵 + 工具比较 + 60M 回测	期货/期权/领口策略
🔬 P6 · 模型验证	消融实验 + Conformal 覆盖率 + 方法论对比	Walk-Forward 防信息泄露
🗄️ P7 · 数据治理	特征目录 + 数据质量 + 中文标注	329 特征全量元数据
🤖 P8 · AI Agent	自然语言智能问答 + 预设问题	混合架构: 本地+LLM
⚙️ P9 · 自动化管道	Pipeline DAG 可视化 + 执行日志	端到端自动化展示

---

📈 模型性能

Walk-Forward 回测 (2018-01 → 2026-03)

指标	值	说明
覆盖率 (1M)	80.5%	Conformal 80% 区间
CQR 覆盖率	83.3%	超额覆盖 ✅
WIS	0.3900	加权区间评分
高波动覆盖	66.4%	极端行情时的覆盖

消融实验

实验	覆盖率	WIS	结论
全模型 (QR+CQR+LGB+TFT)	80.5%	0.3900	✅ 最佳
-Price因子	80.6%	0.3891	价格因子贡献显著
-Supply因子	79.9%	0.3895	供给因子有贡献
仅LightGBM	73.3%	0.4307	多模型优于单模型

---

🔗 因果叙事链

完整故事线: 新闻事件 → 因子异动 → 风险信号触发 → 对冲建议

平台内置 12 个精选油市事件 (2020-2026)，覆盖 5 类：

• 🔴 地缘冲突 (俄乌战争/中东紧张)
• 🟢 供给变动 (OPEC+减产/美国页岩油)
• 🟡 需求冲击 (COVID/中国复苏)
• 🔵 宏观政策 (美联储加息/通胀)
• 🟣 能源政策 (特朗普/IRA法案)

---

🗂️ 数据说明

维度	详情
时间跨度	1990-01 至 2026-03 (约 434 个月)
原始特征数	329 个 (33 个 CSV 文件)
精选特征数	17 个 (经 4 阶段筛选漏斗)
数据源	FRED · EIA · Baker Hughes · AKShare · SiliconFlow LLM
因子分组	价格(Price) · 供给(Supply) · 需求(Demand) · 地缘风险(Risk_Geo) · 技术(Technical) · 另类(Alternative)
预测基准	WTI + Brent 双基准

---

👥 团队

花旗杯竞赛参赛队伍 · 团队项目