README.md

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

# 🛢️ OilVerse — 油刃有余

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

[![Python](https://img.shields.io/badge/Python-3.10+-blue?logo=python)](https://python.org)
[![React](https://img.shields.io/badge/React-18+-61DAFB?logo=react)](https://react.dev)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green?logo=fastapi)](https://fastapi.tiangolo.com)
[![TFT](https://img.shields.io/badge/Model-TFT+CQR+LightGBM-orange)](https://arxiv.org/abs/1912.09363)
[![License](https://img.shields.io/badge/License-Academic-lightgrey)]()

---

## 📋 系统概述

基于 **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增强) | 支持自然语言交互查询平台数据 |

---

## 🏗️ 系统架构

```mermaid
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
```

---

## 📁 目录结构

```text
.
├── 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. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 运行完整管线

```bash
# 完整流程 (含 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. 启动服务

```bash
# 启动后端 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 双基准 |

---

## 👥 团队

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