docs: 精简 README 文档结构
This commit is contained in:
483
README.md
483
README.md
@@ -1,352 +1,211 @@
|
|||||||
# ProStock
|
# ProStock
|
||||||
|
|
||||||
A股量化投资框架 - 从数据获取到模型训练的完整解决方案
|
A股量化投资框架，用于量化股票投资分析。
|
||||||
|
|
||||||
## 功能特性
|
## 特性
|
||||||
|
|
||||||
### 1. 数据层 (src/data/)
|
- **数据管理**：Tushare API 行情数据获取，DuckDB 本地数据存储
|
||||||
- **多源数据接入**: Tushare API 集成，支持日线、股票基础信息、交易日历
|
- **因子引擎**：DSL 表达式驱动的高性能因子计算框架（基于 Polars）
|
||||||
- **DuckDB 存储**: 高性能嵌入式数据库，支持 SQL 查询下推
|
- **机器学习**：支持 LightGBM 回归和 LambdaRank 排序学习
|
||||||
- **智能同步**: 增量/全量同步策略，自动检测数据更新需求
|
- **组件化设计**：灵活的数据处理器、股票池管理、过滤器组合
|
||||||
- **速率控制**: 令牌桶算法实现 API 限流
|
|
||||||
- **并发优化**: ThreadPoolExecutor 多线程数据获取
|
|
||||||
|
|
||||||
### 2. 因子层 (src/factors/)
|
## 环境要求
|
||||||
- **类型安全**: 严格的截面因子 vs 时序因子区分
|
|
||||||
- **防泄露机制**: 框架层面防止未来数据和跨股票数据泄露
|
|
||||||
- **因子组合**: 支持因子加减乘除和标量运算
|
|
||||||
- **高性能计算**: Polars 向量化操作，零拷贝数据导出
|
|
||||||
- **灵活扩展**: 基类抽象便于自定义因子
|
|
||||||
|
|
||||||
### 3. 模型层 (src/models/)
|
- Python 3.10+
|
||||||
- **插件架构**: 装饰器注册机制，新模型即插即用
|
- uv 包管理器
|
||||||
- **阶段感知**: 训练/测试阶段区分，防止数据泄露
|
|
||||||
- **多模型支持**: LightGBM、CatBoost 等模型统一接口
|
## 安装
|
||||||
- **数据处理**: 缺失值处理、缩尾、标准化、中性化等
|
|
||||||
- **时序划分**: WalkForward、ExpandingWindow 等时间序列划分策略
|
```bash
|
||||||
|
# 克隆项目
|
||||||
|
cd ProStock
|
||||||
|
|
||||||
|
# 使用 uv 安装依赖
|
||||||
|
uv pip install -e .
|
||||||
|
```
|
||||||
|
|
||||||
|
## 配置
|
||||||
|
|
||||||
|
创建 `config/.env.local` 文件：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Tushare Token（必需）
|
||||||
|
TUSHARE_TOKEN=your_token_here
|
||||||
|
|
||||||
|
# 数据存储路径（可选，默认 data/）
|
||||||
|
DATA_PATH=data
|
||||||
|
|
||||||
|
# API 速率限制（可选，默认 100）
|
||||||
|
RATE_LIMIT=100
|
||||||
|
|
||||||
|
# 并发线程数（可选，默认 10）
|
||||||
|
THREADS=10
|
||||||
|
```
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 1. 同步股票数据
|
||||||
|
|
||||||
|
```python
|
||||||
|
from src.data.sync import sync_all
|
||||||
|
|
||||||
|
# 增量同步（默认）
|
||||||
|
sync_all()
|
||||||
|
|
||||||
|
# 强制全量同步
|
||||||
|
sync_all(force_full=True)
|
||||||
|
|
||||||
|
# 自定义线程数
|
||||||
|
sync_all(max_workers=20)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 计算因子
|
||||||
|
|
||||||
|
```python
|
||||||
|
from src.factors import FactorEngine
|
||||||
|
|
||||||
|
# 初始化引擎
|
||||||
|
engine = FactorEngine()
|
||||||
|
|
||||||
|
# 添加因子（推荐使用字符串表达式）
|
||||||
|
engine.add_factor("ma20", "ts_mean(close, 20)")
|
||||||
|
engine.add_factor("alpha", "cs_rank(ts_mean(close, 5) - ts_mean(close, 20))")
|
||||||
|
|
||||||
|
# 计算因子值
|
||||||
|
result = engine.compute(["ma20", "alpha"], "20240101", "20240131")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 训练模型
|
||||||
|
|
||||||
|
```python
|
||||||
|
from src.training import Trainer, DateSplitter, StockPoolManager
|
||||||
|
from src.training.components.models import LightGBMModel
|
||||||
|
|
||||||
|
# 创建模型
|
||||||
|
model = LightGBMModel(params={
|
||||||
|
"objective": "regression",
|
||||||
|
"num_leaves": 20,
|
||||||
|
"learning_rate": 0.01,
|
||||||
|
"n_estimators": 1000,
|
||||||
|
})
|
||||||
|
|
||||||
|
# 创建数据划分器
|
||||||
|
splitter = DateSplitter(
|
||||||
|
train_start="20200101",
|
||||||
|
train_end="20231231",
|
||||||
|
val_start="20240101",
|
||||||
|
val_end="20241231",
|
||||||
|
test_start="20250101",
|
||||||
|
test_end="20251231",
|
||||||
|
)
|
||||||
|
|
||||||
|
# 创建训练器并训练
|
||||||
|
trainer = Trainer(
|
||||||
|
model=model,
|
||||||
|
splitter=splitter,
|
||||||
|
target_col="future_return_5",
|
||||||
|
feature_cols=["ma_5", "ma_20", "volume_ratio"],
|
||||||
|
)
|
||||||
|
|
||||||
|
trainer.train(data)
|
||||||
|
results = trainer.get_results()
|
||||||
|
```
|
||||||
|
|
||||||
## 项目结构
|
## 项目结构
|
||||||
|
|
||||||
```
|
```
|
||||||
ProStock/
|
ProStock/
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── config/ # 配置管理
|
│ ├── config/ # 配置管理
|
||||||
│ │ ├── settings.py # pydantic-settings 配置
|
│ ├── data/ # 数据获取与存储
|
||||||
│ │ └── __init__.py
|
│ │ ├── api_wrappers/ # Tushare API 封装
|
||||||
│ │
|
│ │ ├── storage.py # DuckDB 存储
|
||||||
│ ├── data/ # 数据获取与存储
|
│ │ └── sync.py # 数据同步调度
|
||||||
│ │ ├── api_wrappers/ # Tushare API 封装
|
│ ├── factors/ # 因子计算框架
|
||||||
│ │ │ ├── api_pro_bar.py # Pro Bar行情数据接口(主用)
|
│ │ ├── engine/ # 执行引擎
|
||||||
│ │ │ ├── api_stock_basic.py # 股票基础信息接口
|
│ │ ├── metadata/ # 因子元数据管理
|
||||||
│ │ │ ├── api_trade_cal.py # 交易日历接口
|
│ │ ├── dsl.py # DSL 表达式层
|
||||||
│ │ │ ├── api_bak_basic.py # 历史股票列表接口
|
│ │ └── translator.py # Polars 翻译器
|
||||||
│ │ │ ├── api_namechange.py # 股票名称变更接口
|
│ └── training/ # 训练模块
|
||||||
│ │ │ ├── api_stock_st.py # ST股票信息接口
|
│ ├── core/ # 训练核心
|
||||||
│ │ │ ├── api_daily_basic.py # 每日指标接口
|
│ └── components/ # 组件（模型、处理器、过滤器）
|
||||||
│ │ │ ├── api_stk_limit.py # 涨跌停价格接口
|
├── tests/ # 测试文件
|
||||||
│ │ │ ├── financial_data/ # 财务数据接口
|
├── data/ # 数据存储
|
||||||
│ │ │ │ ├── api_income.py # 利润表接口
|
└── docs/ # 文档
|
||||||
│ │ │ │ ├── api_balance.py # 资产负债表接口
|
|
||||||
│ │ │ │ ├── api_cashflow.py # 现金流量表接口
|
|
||||||
│ │ │ │ ├── api_fina_indicator.py # 财务指标接口
|
|
||||||
│ │ │ │ └── api_financial_sync.py # 财务数据同步调度中心
|
|
||||||
│ │ │ └── __init__.py
|
|
||||||
│ │ ├── client.py # Tushare 客户端（含限流）
|
|
||||||
│ │ ├── config.py # 数据模块配置
|
|
||||||
│ │ ├── db_manager.py # DuckDB 表管理和同步
|
|
||||||
│ │ ├── db_inspector.py # 数据库信息查看工具
|
|
||||||
│ │ ├── rate_limiter.py # 令牌桶限流器
|
|
||||||
│ │ ├── storage.py # DuckDB 存储核心
|
|
||||||
│ │ ├── sync.py # 数据同步主逻辑
|
|
||||||
│ │ └── __init__.py
|
|
||||||
│ │
|
|
||||||
│ ├── factors/ # 因子计算框架
|
|
||||||
│ │ ├── base.py # 因子基类（截面/时序）
|
|
||||||
│ │ ├── composite.py # 组合因子和标量运算
|
|
||||||
│ │ ├── data_loader.py # DuckDB 数据加载器
|
|
||||||
│ │ ├── data_spec.py # 数据规格定义
|
|
||||||
│ │ ├── engine.py # 因子执行引擎
|
|
||||||
│ │ └── __init__.py
|
|
||||||
│ │
|
|
||||||
│ ├── models/ # 模型训练框架
|
|
||||||
│ │ ├── core/ # 核心抽象
|
|
||||||
│ │ │ ├── base.py # 处理器/模型/划分基类
|
|
||||||
│ │ │ └── splitter.py # 时间序列划分策略
|
|
||||||
│ │ ├── models/ # 模型实现
|
|
||||||
│ │ │ └── models.py # LightGBM、CatBoost
|
|
||||||
│ │ ├── processors/ # 数据处理器
|
|
||||||
│ │ │ └── processors.py # 标准化、缩尾、中性化等
|
|
||||||
│ │ ├── pipeline.py # 处理流水线
|
|
||||||
│ │ ├── registry.py # 插件注册中心
|
|
||||||
│ │ └── __init__.py
|
|
||||||
│ │
|
|
||||||
│ └── __init__.py
|
|
||||||
│
|
|
||||||
├── docs/ # 文档
|
|
||||||
│ ├── factor_framework_design.md # 因子框架设计
|
|
||||||
│ ├── ml_framework_design.md # 模型框架设计
|
|
||||||
│ ├── db_sync_guide.md # 数据同步指南
|
|
||||||
│ └── ...
|
|
||||||
│
|
|
||||||
├── data/ # 数据存储（DuckDB）
|
|
||||||
│ ├── prostock.db # 主数据库文件
|
|
||||||
│ └── stock_basic.csv # 股票基础信息缓存
|
|
||||||
│
|
|
||||||
├── config/ # 配置文件
|
|
||||||
│ └── .env.local # 环境变量（API Token等）
|
|
||||||
│
|
|
||||||
└── tests/ # 测试文件
|
|
||||||
├── test_sync.py
|
|
||||||
└── factors/
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 快速开始
|
## 因子框架
|
||||||
|
|
||||||
### 1. 安装依赖
|
### 支持的函数
|
||||||
|
|
||||||
**⚠️ 本项目强制使用 uv 作为 Python 包管理器**
|
**时间序列函数 (ts_*)**：
|
||||||
|
- `ts_mean`, `ts_std`, `ts_max`, `ts_min`, `ts_sum`
|
||||||
|
- `ts_delay`, `ts_delta`
|
||||||
|
- `ts_corr`, `ts_cov`, `ts_rank`
|
||||||
|
|
||||||
```bash
|
**截面函数 (cs_*)**：
|
||||||
# 安装 uv (如果尚未安装)
|
- `cs_rank` - 截面排名
|
||||||
pip install uv
|
- `cs_zscore` - Z-Score 标准化
|
||||||
|
- `cs_neutralize` - 行业/市值中性化
|
||||||
|
- `cs_winsorize` - 缩尾处理
|
||||||
|
|
||||||
# 安装项目依赖
|
**数学函数**：
|
||||||
uv pip install -e .
|
- `log`, `exp`, `sqrt`, `sign`, `abs`
|
||||||
```
|
- `max_`, `min_`, `clip`
|
||||||
|
- `if_`, `where`
|
||||||
|
|
||||||
### 2. 配置环境变量
|
### 因子元数据管理
|
||||||
|
|
||||||
创建 `config/.env.local` 文件：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
TUSHARE_TOKEN=your_tushare_token_here
|
|
||||||
DATA_PATH=data
|
|
||||||
RATE_LIMIT=100
|
|
||||||
THREADS=10
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 数据同步
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 首次同步 - 全量同步（从20180101开始）
|
|
||||||
uv run python -c "from src.data.sync import sync_all; sync_all(force_full=True)"
|
|
||||||
|
|
||||||
# 日常同步 - 增量同步（自动从最新日期开始）
|
|
||||||
uv run python -c "from src.data.sync import sync_all; sync_all()"
|
|
||||||
|
|
||||||
# 预览同步（检查需要同步的数据量）
|
|
||||||
uv run python -c "from src.data.sync import preview_sync; preview_sync()"
|
|
||||||
|
|
||||||
# 自定义线程数
|
|
||||||
uv run python -c "from src.data.sync import sync_all; sync_all(max_workers=20)"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. 查看数据库状态
|
|
||||||
|
|
||||||
```bash
|
|
||||||
uv run python -c "from src.data.db_inspector import get_db_info; get_db_info()"
|
|
||||||
```
|
|
||||||
|
|
||||||
## 使用示例
|
|
||||||
|
|
||||||
### 因子计算
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from src.factors import FactorEngine
|
from src.factors.metadata import FactorManager
|
||||||
from src.factors.api import close, ts_mean, cs_rank
|
|
||||||
import polars as pl
|
|
||||||
|
|
||||||
# 初始化引擎
|
# 初始化管理器
|
||||||
engine = FactorEngine()
|
manager = FactorManager()
|
||||||
|
|
||||||
# 方式1：使用 DSL 表达式注册
|
# 添加因子
|
||||||
engine.register("ma20", ts_mean(close, 20))
|
manager.add_factor({
|
||||||
engine.register("price_rank", cs_rank(close))
|
"factor_id": "F_001",
|
||||||
|
"name": "mom_5d",
|
||||||
# 方式2：使用字符串表达式（推荐）
|
"desc": "5日价格动量",
|
||||||
engine.add_factor("ma20", "ts_mean(close, 20)")
|
"dsl": "cs_rank(close / ts_delay(close, 5) - 1)",
|
||||||
engine.add_factor("alpha", "cs_rank(ts_mean(close, 5) - ts_mean(close, 20))")
|
"category": "momentum",
|
||||||
|
|
||||||
# 方式3：从 metadata 查询（需先在 metadata 中定义）
|
|
||||||
engine.add_factor("mom_5d")
|
|
||||||
|
|
||||||
# 计算因子
|
|
||||||
result = engine.compute(
|
|
||||||
factor_names=["ma20", "price_rank"],
|
|
||||||
start_date="20240101",
|
|
||||||
end_date="20240131"
|
|
||||||
)
|
|
||||||
|
|
||||||
# 查看执行计划
|
|
||||||
plan = engine.preview_plan("ma20")
|
|
||||||
```
|
|
||||||
|
|
||||||
### 模型训练
|
|
||||||
|
|
||||||
```python
|
|
||||||
from src.training import (
|
|
||||||
Trainer,
|
|
||||||
LightGBMModel,
|
|
||||||
DateSplitter,
|
|
||||||
StockPoolManager,
|
|
||||||
NullFiller,
|
|
||||||
Winsorizer,
|
|
||||||
StandardScaler,
|
|
||||||
STFilter,
|
|
||||||
check_data_quality,
|
|
||||||
)
|
|
||||||
from src.factors import FactorEngine
|
|
||||||
import polars as pl
|
|
||||||
|
|
||||||
# 1. 创建模型
|
|
||||||
model = LightGBMModel(params={
|
|
||||||
"objective": "regression",
|
|
||||||
"metric": "mae",
|
|
||||||
"num_leaves": 20,
|
|
||||||
"learning_rate": 0.01,
|
|
||||||
"n_estimators": 1000,
|
|
||||||
})
|
})
|
||||||
|
|
||||||
# 2. 准备因子数据
|
# 查询因子
|
||||||
engine = FactorEngine()
|
df = manager.get_factors_by_name("mom_5d")
|
||||||
engine.add_factor("ma5", "ts_mean(close, 5)")
|
|
||||||
engine.add_factor("ma20", "ts_mean(close, 20)")
|
|
||||||
|
|
||||||
# 计算全市场因子
|
|
||||||
data = engine.compute(
|
|
||||||
factor_names=["ma5", "ma20", "future_return_5"],
|
|
||||||
start_date="20200101",
|
|
||||||
end_date="20231231"
|
|
||||||
)
|
|
||||||
|
|
||||||
# 3. 创建数据处理器
|
|
||||||
processors = [
|
|
||||||
NullFiller(feature_cols=["ma5", "ma20"], strategy="mean"),
|
|
||||||
Winsorizer(feature_cols=["ma5", "ma20"], lower=0.01, upper=0.99),
|
|
||||||
StandardScaler(feature_cols=["ma5", "ma20"]),
|
|
||||||
]
|
|
||||||
|
|
||||||
# 4. 创建股票池筛选函数
|
|
||||||
def stock_pool_filter(df: pl.DataFrame) -> pl.Series:
|
|
||||||
"""筛选小市值股票"""
|
|
||||||
code_filter = (
|
|
||||||
~df["ts_code"].str.starts_with("300") & # 排除创业板
|
|
||||||
~df["ts_code"].str.starts_with("688") # 排除科创板
|
|
||||||
)
|
|
||||||
return code_filter
|
|
||||||
|
|
||||||
pool_manager = StockPoolManager(
|
|
||||||
filter_func=stock_pool_filter,
|
|
||||||
required_columns=["total_mv"],
|
|
||||||
)
|
|
||||||
|
|
||||||
# 5. 创建过滤器
|
|
||||||
st_filter = STFilter(data_router=engine.router)
|
|
||||||
|
|
||||||
# 6. 创建数据划分器
|
|
||||||
splitter = DateSplitter(
|
|
||||||
train_start="20200101",
|
|
||||||
train_end="20221231",
|
|
||||||
val_start="20230101",
|
|
||||||
val_end="20230630",
|
|
||||||
test_start="20230701",
|
|
||||||
test_end="20231231",
|
|
||||||
)
|
|
||||||
|
|
||||||
# 7. 创建训练器
|
|
||||||
trainer = Trainer(
|
|
||||||
model=model,
|
|
||||||
pool_manager=pool_manager,
|
|
||||||
processors=processors,
|
|
||||||
filters=[st_filter],
|
|
||||||
splitter=splitter,
|
|
||||||
target_col="future_return_5",
|
|
||||||
feature_cols=["ma5", "ma20"],
|
|
||||||
)
|
|
||||||
|
|
||||||
# 8. 执行训练
|
|
||||||
results = trainer.train(data)
|
|
||||||
|
|
||||||
# 9. 获取预测结果
|
|
||||||
predictions = trainer.get_results()
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 核心设计
|
## 常见任务
|
||||||
|
|
||||||
### 1. 数据防泄露机制
|
```bash
|
||||||
|
# 运行所有测试
|
||||||
|
uv run pytest
|
||||||
|
|
||||||
**截面因子 (CrossSectionalFactor)**:
|
# 同步财务数据
|
||||||
- 防止日期泄露：每天只传入 `[T-lookback+1, T]` 数据
|
uv run python -c "from src.data.api_wrappers.financial_data import sync_financial; sync_financial()"
|
||||||
- 允许股票间比较：传入当天所有股票数据
|
|
||||||
- 典型应用：PE排名、市值分位数、当日收益率排名
|
|
||||||
|
|
||||||
**时序因子 (TimeSeriesFactor)**:
|
# 批量注册因子
|
||||||
- 防止股票泄露：每只股票单独计算
|
uv run python src/scripts/register_factors.py
|
||||||
- 允许历史数据访问：传入完整时间序列
|
|
||||||
- 典型应用：移动平均线、RSI、历史波动率
|
|
||||||
|
|
||||||
### 2. 插件注册机制
|
|
||||||
|
|
||||||
```python
|
|
||||||
from src.models.registry import PluginRegistry
|
|
||||||
|
|
||||||
# 注册自定义处理器
|
|
||||||
@PluginRegistry.register_processor("my_processor")
|
|
||||||
class MyProcessor(BaseProcessor):
|
|
||||||
stage = PipelineStage.TRAIN
|
|
||||||
|
|
||||||
def fit(self, data):
|
|
||||||
# 学习参数
|
|
||||||
return self
|
|
||||||
|
|
||||||
def transform(self, data):
|
|
||||||
# 转换数据
|
|
||||||
return data
|
|
||||||
|
|
||||||
# 使用
|
|
||||||
processor_class = PluginRegistry.get_processor("my_processor")
|
|
||||||
processor = processor_class()
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. 数据同步策略
|
## 依赖项
|
||||||
|
|
||||||
**智能增量同步**:
|
- pandas >= 2.0.0
|
||||||
```python
|
- polars >= 0.20.0
|
||||||
from src.data.db_manager import SyncManager
|
- numpy >= 1.24.0
|
||||||
|
- tushare >= 2.0.0
|
||||||
manager = SyncManager()
|
- pydantic >= 2.0.0
|
||||||
result = manager.sync(
|
- lightgbm >= 4.0.0
|
||||||
table_name="daily",
|
- pytest
|
||||||
fetch_func=get_daily,
|
|
||||||
start_date="20240101",
|
|
||||||
end_date="20240131"
|
|
||||||
)
|
|
||||||
# 自动检测：表不存在→全量，表存在→增量
|
|
||||||
```
|
|
||||||
|
|
||||||
## 文档
|
## 文档
|
||||||
|
|
||||||
- [因子框架设计](docs/factor_framework_design.md) - 因子计算架构详解
|
更多详细信息请参阅 `docs/` 目录：
|
||||||
- [模型框架设计](docs/ml_framework_design.md) - 模型训练架构详解
|
|
||||||
- [数据同步指南](docs/db_sync_guide.md) - DuckDB 数据同步 API 说明
|
|
||||||
- [代码审查报告](docs/code_review_factors_20260222.md) - 因子框架代码审查
|
|
||||||
|
|
||||||
## 开发规范
|
- [因子表达式文档](docs/factor_expressions_document.md)
|
||||||
|
- [API 接口规范](docs/api/API_INTERFACE_SPEC.md)
|
||||||
- **Python 版本**: 3.10+
|
- [财务数据接口](docs/api/FINANCIAL_API_SPEC.md)
|
||||||
- **代码风格**: Google 风格文档字符串
|
|
||||||
- **类型提示**: 强制类型注解
|
|
||||||
- **测试**: pytest 框架
|
|
||||||
- **包管理**: uv (禁止直接使用 pip/python)
|
|
||||||
|
|
||||||
## 技术栈
|
|
||||||
|
|
||||||
- **数据处理**: Polars, Pandas, NumPy
|
|
||||||
- **数据存储**: DuckDB (嵌入式 OLAP 数据库)
|
|
||||||
- **API 接口**: Tushare Pro
|
|
||||||
- **机器学习**: LightGBM, CatBoost, scikit-learn
|
|
||||||
- **配置管理**: pydantic-settings
|
|
||||||
|
|
||||||
## 许可证
|
## 许可证
|
||||||
|
|
||||||
MIT License
|
MIT
|
||||||
|
|||||||
Reference in New Issue
Block a user