# VibeQuant

**Repository Path**: lele2015/vibe-quant

## Basic Information

- **Project Name**: VibeQuant
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vibe-Quant 量化策略平台

基于 Tushare + LightGBM + Optuna 的 A 股量化选股策略平台，支持从股票池获取、因子计算、模型训练优化到信号生成和回测验证的全自动化流程。

## 📦 目录结构

```
vibe-quant/
├── pipeline_data_prepare.py           # 数据准备阶段（0-A, 0-B, 0-C）
├── pipeline_stage1.py                 # 阶段一：因子计算 + 评估 + 基础模型
├── pipeline_stage2.py                 # 阶段二：Optuna 超参数优化
├── pipeline_stage3.py                 # 阶段三：可视化分析
├── pipeline_stage4.py                 # 阶段四：选股信号生成
├── pipeline_stage5.py                 # 阶段五：Backtrader 回测验证
├── config.py                          # 配置管理（环境变量 > YAML > 自动检测）
├── config.yaml.template               # 配置文件模板（供 init_config.py 使用）
├── requirements.txt                   # Python 依赖
├── README.md                          # 本文件
│
├── scripts/
│   ├── init_config.py                 # 配置初始化（从模板生成 + 交互式修改）
│   ├── industry_browser.py            # 行业/概念板块交互式浏览（空格多选 + 搜索）
│   ├── model_utils.py                 # 模型备份元数据构建工具
│   ├── restore_model.py               # 模型恢复工具（交互式版本选择）
│   ├── data_utils.py                  # 公共数据工具（日期、拆分、验证）
│   ├── factor_utils.py                # 公共因子计算模块（TA-Lib 24+ 因子）
│   ├── get_i_industry_stocks.py       # 获取行业/概念股票池
│   ├── download_it_stocks_history.py  # 批量下载历史行情（增量 + 重试）
│   ├── split_data.py                  # 训练/回测数据拆分（固定日期阈值）
│   ├── batch_factors.py               # 批量因子计算（--mode training|backtest）
│   ├── evaluate_all_factors.py        # 因子评估 (IC/IR)
│   ├── train_lgb_model_all_stocks.py  # LightGBM 基础模型训练
│   ├── optuna_lgb_optimization.py     # Optuna 超参数优化
│   ├── visualize_optuna_results.py    # 优化结果可视化
│   ├── generate_latest_signals.py     # 最新选股信号生成
│   ├── backtest_backtrader_multi.py   # 多股票组合回测
│   ├── backtest_backtrader_utils.py   # 回测工具函数
│   ├── script_config.py               # 脚本通用配置
│   │
│   └── stock_pool/                    # 股票池公共模块
    │   ├── fetcher.py                 # API 重试、缓存、元数据（含双文件完整性校验）
    │   ├── validation.py              # 4 级单文件验证 + 双文件联合验证
    │   ├── classification_cache.py    # 行业/概念分类统一获取与缓存
│       ├── reporter.py                # Markdown/JSON 双格式输出
│       └── cli.py                     # 命令行接口
│
├── docs/                               # 流程分析文档
│   ├── DATA_PREPARE_FLOW_ANALYSIS.md
│   ├── PIPELINE_STAGE1_ANALYSIS.md
│   ├── PIPELINE_STAGE2_ANALYSIS.md
│   ├── PIPELINE_STAGE3_ANALYSIS.md
│   ├── PIPELINE_STAGE4_ANALYSIS.md
│   └── PIPELINE_STAGE5_ANALYSIS.md
│
└── logs/                              # 运行日志目录
```

## 🚀 快速开始

### 前提条件

1. **Python 环境**：Python 3.12+
2. **依赖安装**：
   ```bash
   pip install -r requirements.txt
   ```
3. **Tushare Token**：注册 [Tushare Pro](https://tushare.pro) 获取 API Token
4. **TA-Lib**：系统级安装 `libta-lib`（`apt install libta-lib-dev` 或 `brew install ta-lib`）

### 配置

配置优先级：**环境变量 > YAML 文件 > 自动检测 > 默认值**

**方式 1：环境变量（推荐）**
```bash
export TUSHARE_TOKEN="your_token_here"
export VQ_START_DATE="2023-01-01"
export VQ_END_DATE="current"
```

**方式 2：配置初始化脚本（推荐）**
```bash
# 交互式初始化（引导填写 Token、行业、日期、概念等）
python3 scripts/init_config.py --work-dir ~/vq_work

# 行业一键初始化（概念自动跟随行业名）
python3 scripts/init_config.py --token your_token --industry 半导体 \
  --keywords "半导体,芯片" --start-date 2023-01-01

# 行业 + 概念独立配置
python3 scripts/init_config.py --token your_token --industry 锂电池 \
  --concept-name 电池概念 --concept-keywords "锂电池,电池" --pool-mode combined

# 仅概念板块模式
python3 scripts/init_config.py --token your_token --concept-name AI芯片 --pool-mode concept_only
```

**方式 3：行业/概念浏览选择（推荐用于精确配置）**
```bash
# 浏览并选择行业分类（自动写入精确 Tushare 代码 industry_codes）
python3 scripts/industry_browser.py

# 浏览并选择概念板块
python3 scripts/industry_browser.py --browse concept
```

选择后 config.yaml 中会同时保存行业名称和精确代码：
```yaml
industry_name: 采掘
industry_code: 801020.SI          # Tushare 精确代码
industry_keywords: [采掘]          # 人可读的名称
industry_codes: [801020.SI]       # 机可用的代码（快速路径）
stock_pool_file: 801020.SI股票池.md
```

使用精确代码可跳过全量分类获取和关键词匹配，直接获取成分股。

**方式 4：手动配置**
```bash
cp config.yaml.template config.yaml
# 编辑 config.yaml，填入相应配置
```

### 运行

**分阶段运行（推荐）**：
```bash
python3 pipeline_data_prepare.py      # 数据准备（0-A 股票池 + 0-B 行情 + 0-C 拆分）
python3 pipeline_stage1.py            # 因子计算 + IC/IR 评估 + 基础模型
python3 pipeline_stage2.py            # Optuna 超参数优化
python3 pipeline_stage3.py            # 可视化分析
python3 pipeline_stage4.py            # 最新选股信号生成
python3 pipeline_stage5.py            # 回测因子计算 + Backtrader 回测验证
```

## 📋 执行步骤

| 阶段 | 步骤 | 说明 | 实际耗时 |
|------|------|------|----------|
| 数据准备 | 0-A | 获取行业/概念股票池（支持 `combined` 模式，双文件联合验证） | ~60s |
| 数据准备 | 0-B | 增量下载历史行情 | ~3-5min 首次 / ~1s 增量 |
| 数据准备 | 0-C | 固定日期阈值拆分训练/回测 | ~12s |
| 阶段一 | 1 | 批量因子计算（60 因子 + 22 rank 特征） | ~15s |
| 阶段一 | 2 | 因子评估 (IC/IR，60 因子) | ~35s |
| 阶段一 | 3 | LightGBM 基础模型训练 + 自动备份（含元数据） | ~13s |
| 阶段二 | 4 | Optuna 超参数优化（50 trials）+ 自动备份（模型+参数+元数据） | ~10min |
| 阶段三 | 5 | 优化结果可视化（7 面板） | ~5s |
| 阶段四 | 6 | 最新选股信号生成（5 分位，it_stocks 实时计算，模型缺失自动恢复） | ~2s |
| 阶段五 | 7-A | 回测因子计算（60+ 因子，backtesting_data → backtesting_factors） | ~30s |
| 阶段五 | 7-B | Backtrader 回测验证（170 只股票，4 个月，模型缺失自动恢复） | ~10s |

## 🛠️ 核心修复与改进

### P0 修复（影响结果正确性）

| 修复 | 阶段 | 旧行为 | 新行为 |
|------|------|--------|--------|
| **Future_Return 方向** | Stage 1 | `pct_change(N).shift(N)` 计算过去收益率 | `shift(-N) / close - 1` 计算未来收益率 |
| **训练/回测因子列名统一** | Stage 5 | `batch_backtest_factors.py` 输出 `Boll_Upper`、`ATR`（与训练期不同） | 使用 `factor_utils`，输出 `Boll_Upper_20`、`ATR_14`（与训练期一致） |
| **因子计算合并** | Stage 1/5 | `batch_alpha158_factors.py` + `batch_backtest_factors.py` 两份重复代码 | 合并为 `batch_factors.py --mode training|backtest` |
| **验证列名不匹配** | Stage 0 | `required_cols` 含 `date`/`volume`（不存在列） | 修正为 `trade_date`/`vol`，验证正式生效 |
| **验证函数日期列名** | Stage 0 | `check_step0_download_history()` 用 `df['date']`（不存在列） | 修正为 `df['trade_date']`（v1.2 只修了 `required_cols`，漏了日期处理） |
| **数据拆分日期不一致** | Stage 0 | 比例拆分（不同股票拆分日期不同） | 固定日期阈值（所有股票同一切分日） |
| **配置日期不生效** | Stage 0 | `HISTORY_START_DATE` 硬编码 | 读取 `config.get('start_date')` |
| **Stage 4 数据过时** | Stage 4 | 读取 `training_factors/`（训练期数据） | 读取 `it_stocks/` 实时计算因子 |
| **Stage 4 特征不匹配** | Stage 4 | 硬编码 24 个特征 | `model.feature_name_` 动态提取 |

### P1 修复（质量与可维护性）

| 修复 | 说明 |
|------|------|
| **配置统一管理** | 所有脚本改用 `get_config()`，消除硬编码 `yaml.safe_load(open(...))` |
| **异常可追溯** | `except: pass` → `print(f"  ⚠️ ... - {e}")` |
| **Rank 特征全线打通** | Stage 1 计算 → Stage 2 优化 → Stage 5 回测，全链路使用 |
| **Optuna 最终模型重训** | 从 `best_iteration_` 获取最优迭代数，在 70% 数据上重训（原仅 56%） |
| **Optuna 搜索空间可配置** | `config.yaml` 中 `optuna.search_space` 完整生效 |
| **横截面排名因子扩展** | 从 10 个扩展到 18 个（含 Returns_60d, Volatility, ATR 等） |
| **Step 0-A 自动 fallback** | 股票池文件不存在/过小时自动调用 `--force` 生成，无需手动干预 |
| **_auto_detect 占位符修复** | `config.py` 自动检测不再跳过 `<auto-detected>` 占位符 |

### v1.8 新增修复

| 修复 | 说明 |
|------|------|
| **缓存验证增强** | `check_cache_valid()` 新增 `.md` + `.json` 双文件完整性校验，避免元数据有效但数据文件损坏时跳过获取 |
| **联合验证函数** | 新增 `validation.check_stock_pool_files()`，双文件联合检查，任一有效即通过 |
| **init_config 概念支持** | 新增 `--concept-name` / `--concept-keywords` / `--pool-mode` CLI 参数，交互模式新增概念提示 |
| **概念接口适配** | `concept_pool_fetcher.py` 适配 akshare 1.18.60，使用 `stock_board_concept_cons_em()` |
| **config.py 默认概念配置** | `DEFAULT_CONFIG` 新增 `concept` 段，安全默认值 |
| **evaluate_all_factors 日期列修复** | IC 计算和训练数据中增加 `trade_date` 列，避免 KeyError |

### 新增公共模块

| 模块 | 用途 | 使用方 |
|------|------|--------|
| `scripts/data_utils.py` | 日期计算、期间验证、固定日期拆分函数 | Stage 0 |
| `scripts/factor_utils.py` | 24 个 TA-Lib 技术指标 + 5 个量价衍生因子 | Stage 1 / Stage 4 / Stage 5 |
| `scripts/init_config.py` | 配置初始化（从模板生成 + 交互式修改） | 安装时 |
| `scripts/industry_browser.py` | 行业/概念板块交互式浏览（空格多选 + 搜索，写入 config.yaml） | Step 0-A 前置 |
| `scripts/model_utils.py` | 模型备份元数据构建（config 快照、因子信息、IC 排名、特征重要性） | Stage 1 / Stage 2 |
| `scripts/restore_model.py` | 模型恢复工具（交互式版本选择，按元数据展示详情） | 手动恢复 |

## 📈 策略性能对比

| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 股票池 | 31 只 | **170 只** | 5.5x |
| 因子数 | 50 | **60** | +20% |
| 特征选择 | IC 绝对值 | **LightGBM importance** | 更精准 |
| 基线 Fold 5 R² | 0.002 | **0.093** | 46x |
| Optuna 验证集 R² | 0.062 | **0.175** | 2.8x |
| Optuna 测试集 R² | 0.006 | **0.212** | 37x |
| 回测总收益（4 个月） | **+2.81%** | **+13.88%** | 4.9x |

### 关键优化

| 优化 | 说明 |
|------|------|
| **放开股票池主板限制** | 从仅 `主板` 扩展为全部市场（含科创板和创业板），173 只股票 |
| **增加量价衍生因子** | `Amplitude`、`Intraday_Return_5d`、`Gap_5d`、`VWAP_Dist`、`Vol_Price_Prod_5d` |
| **特征选择改进** | 增加 LightGBM importance 方法（`config.model.feature_selection: ic | importance`） |
| **配置分段** | `config.yaml` 按 pipeline 阶段分节，带注释 |

## 📊 数据目录 (`config.yaml` 中 `data_dir` 指定)

| 文件/目录 | 说明 |
|----------|------|
| `it_stocks/*.csv` | 原始历史行情数据（每只股票一个 CSV，含 `ts_code` 列） |
| `training_data/*.csv` | 训练期行情数据（拆分后，固定日期前） |
| `backtesting_data/*.csv` | 回测期行情数据（拆分后，固定日期后） |
| `training_factors/*_factors.csv` | 训练期因子（24 基础 + 18 rank） |
| `backtesting_factors/*_factors.csv` | 回测期因子（24 基础 + 18 rank + 3 扩展） |
| `training_factors_combined.csv` | 合并训练数据（42 因子 + 3 目标） |
| `training_lgb_model.pkl` | LightGBM 基线模型（15 IC 选择特征） |
| `lgb_model_optuna.pkl` | Optuna 优化模型（42 特征） |
| `optuna_best_params.json` | 最优超参数 |
| `optuna_trials.csv` | Optuna 试验历史 |
| `optuna_optimization_visualization.png` | 优化可视化图表 |
| `models/` | 模型备份目录（含时间戳版本 + `_latest` 指针 + JSON 元数据说明） |
| `{industry}_latest_signals/` | 最新选股信号报告 |

## 📊 信号输出

| 信号等级 | 含义 | 操作建议 |
|---------|------|---------|
| Signal 5 | 最看多 | 优先配置 |
| Signal 4 | 看多 | 推荐关注 |
| Signal 3 | 中性 | 持有观望 |
| Signal 2 | 看空 | 谨慎减持 |
| Signal 1 | 最看空 | 高风险回避 |

## ⚙️ 关键配置

### 环境变量

| 环境变量 | 说明 | 示例 |
|---------|------|------|
| `TUSHARE_TOKEN` | Tushare API Token（必须） | `your_token` |
| `VQ_START_DATE` | 历史数据起始日期 | `2023-01-01` |
| `VQ_END_DATE` | 历史数据结束日期 | `current` |
| `VQ_INDUSTRY_NAME` | 行业名称 | `半导体` |
| `VQ_INDUSTRY_KEYWORDS` | 行业关键词 | `半导体,芯片` |
| `VQ_DATA_DIR` | 数据存储目录 | `~/my_data` |
| `VQ_MODEL_TYPE` | 模型类型 | `baseline` / `optuna` |

### 模型选择

- `baseline`：快速验证（~1 分钟全流程，R² ~0.09）
- `optuna`：预测准确性高（~12 分钟全流程，R² ~0.21，比 baseline 提升 133%）

## 💡 最佳实践

1. **先初始化配置** — 使用 `python3 scripts/init_config.py` 引导式生成配置文件
2. **浏览行业/概念** — 使用 `python3 scripts/industry_browser.py` 交互式选择行业或概念板块，写入精确 Tushare 代码到 `industry_codes`，后续股票池获取自动走快速路径
   - 行业模式：`python3 scripts/industry_browser.py`
   - 概念模式：`python3 scripts/industry_browser.py --browse concept`
3. **分阶段执行** — 使用 `pipeline_stage*.py` 分步运行，便于定位问题
4. **模型备份** — Stage 1/2 训练完成后自动备份到 `{data_dir}/models/`，无需手动操作
5. **模型恢复** — 模型文件缺失时自动从备份恢复，也可手动：`python3 scripts/restore_model.py`
6. **日常更新** — 股票池缓存有效时，增量下载 + 信号更新仅需 ~5 分钟
7. **模型选择**：baseline 用于快速验证，optuna 用于生产信号
8. **查看详细文档** — `docs/` 目录下每个阶段的详细分析含版本变更日志

## 📝 日志文件

每个阶段运行时会生成带时间戳的日志文件：

```
logs/
├── pipeline_data_prepare_20260510_100000.log
├── pipeline_stage1_20260510_101030.log
└── ...
```

## 📞 技术支持

- 初始化配置：`python3 scripts/init_config.py`
- 浏览行业/概念：`python3 scripts/industry_browser.py`
- 恢复模型：`python3 scripts/restore_model.py`
- 查看日志：`ls -lt logs/ | head -5`
- 检查配置：`python3 config.py`
- 验证环境：`python3 -c "import tushare, lightgbm, akshare; print('✅ 环境OK')"`