feat: add Tushare Qlib data bridge
This commit is contained in:
@@ -0,0 +1,225 @@
|
||||
# Tushare 本地数据盘点、Qlib 接入与回测手册
|
||||
|
||||
截至 2026-07-26，Quant OS 已能只读盘点另一个任务生成的 Tushare
|
||||
Parquet 镜像，校验已完成分区，并转换为不可变的 Qlib 0.9.7 provider。
|
||||
这条路径已经完成两次 byte-identical 的本地动量回测。
|
||||
|
||||
当前证据的边界是：
|
||||
|
||||
```text
|
||||
completed_partitions_only_not_full_mirror
|
||||
production_ready = false
|
||||
investment_value_claim = false
|
||||
gate_credit = []
|
||||
```
|
||||
|
||||
它证明“本地 Tushare 数据可以进入 Qlib 并可重放”，不证明镜像已经下载完整，
|
||||
也不证明策略收益有效或 Quant OS 已达到 `BASELINE_60`。
|
||||
|
||||
## 1. 2026-07-26 点时盘点
|
||||
|
||||
镜像中共有 93 个状态为 `completed` 的 Parquet，均通过 SQLite 记录的文件大小、
|
||||
SHA-256 和 Parquet row count 校验；另有 1 个遗留 `running` job。
|
||||
|
||||
| 表 | 文件数 | 行数 | 当前范围/说明 |
|
||||
| --- | ---: | ---: | --- |
|
||||
| `daily` | 35 | 28,731 | 1990-12-19—1993-10-29，138 个代码、731 个交易日 |
|
||||
| `trade_cal` | 37 | 13,004 | SSE 1990—2026 日历，8,689 个开市日 |
|
||||
| `stock_basic` | 4 | 5,869 | 当前上市/退市/暂停上市等基础快照 |
|
||||
| `stock_company` | 3 | 6,294 | SSE/SZSE/BSE 公司资料 |
|
||||
| `index_basic` | 7 | 9,643 | CSI/SW/SSE/SZSE 等指数基础资料 |
|
||||
| `index_classify` | 6 | 870 | 申万 2014/2021 分类 |
|
||||
| `bse_mapping` | 1 | 248 | 北交所新旧代码映射 |
|
||||
| **合计** | **93** | **64,659** | **5,734,035 bytes Parquet** |
|
||||
|
||||
`daily` 原计划覆盖 1990-12—2026-07，共 428 个月；当前完成 35 个月，约
|
||||
8.2%。下载进程已停止，SQLite 仍遗留
|
||||
`daily/month=1993-11` 的 `running` 状态。日志显示首先发生 DNS 解析失败，
|
||||
错误处理阶段又发生 `sqlite3.OperationalError: unable to open database
|
||||
file`。因此不能把这个状态解释为仍在后台下载，也不要在 Quant OS
|
||||
转换过程中修改或自动恢复原下载器。
|
||||
|
||||
尚未落盘的生产关键表包括：
|
||||
|
||||
- `adj_factor`、`index_daily`；
|
||||
- `index_member_all`、`index_weight`；
|
||||
- `stk_limit`、`suspend_d`、`stock_st`；
|
||||
- `daily_basic`。
|
||||
|
||||
其中历史 `stock_st` 权限探测被拒绝。即使其他下载完成，历史 ST 仍需要新的
|
||||
授权数据源或明确的降级门禁。
|
||||
|
||||
## 2. 已确认的数据质量
|
||||
|
||||
- 已完成 Parquet 自然键无重复，核心日线字段无空值；
|
||||
- 无负成交量或负成交额，日线日期与同期 SSE 开市日完全对应；
|
||||
- 17 条早期 OHLC 包络异常；默认拒绝，只有显式
|
||||
`--ohlc-policy expand-range` 才按原始 `open/high/low/close` 四价的
|
||||
min/max 修复，并记录数量与异常键 hash；
|
||||
- 2 条 `pct_chg` 与保存精度下重算结果的偏差超过 0.02 个百分点；
|
||||
- 日线代码 `000022.SZ` 不在当前 `stock_basic` 快照；
|
||||
- `stock_basic` 存在遗留非标准代码 `T600018.SH`，转换器不会把它当成
|
||||
A 股代码；
|
||||
- `index_basic.base_point` 存在分区类型漂移，后续 canonical 合并时必须
|
||||
显式 cast。
|
||||
|
||||
Tushare 的 `daily` 是未复权行情，停牌期间不返回记录；`vol` 单位为手，
|
||||
`amount` 单位为千元。转换器固定执行：
|
||||
|
||||
```text
|
||||
600000.SH -> SH600000
|
||||
000001.SZ -> SZ000001
|
||||
430047.BJ -> BJ430047
|
||||
volume = vol * 100
|
||||
money = amount * 1000
|
||||
factor = 1
|
||||
```
|
||||
|
||||
未上市、退市后和停牌缺口在 Qlib feature 中保留为 `NaN`。字段语义来源见
|
||||
[Tushare 日线接口](https://tushare.pro/document/2?doc_id=27)与
|
||||
[复权因子接口](https://tushare.pro/document/2?doc_id=28)。
|
||||
|
||||
## 3. Quant OS 如何使用这些数据
|
||||
|
||||
当前已经实现的链路是研究/引擎验证路径：
|
||||
|
||||
```text
|
||||
Tushare mirror
|
||||
-> 只读取 SQLite completed jobs
|
||||
-> 文件大小 + SHA-256 + Parquet row count/footer 校验
|
||||
-> 新目录原子发布 Qlib binary provider
|
||||
-> provider tree hash + data_version + manifest verifier
|
||||
-> Qlib momentum / Alpha158 research runner
|
||||
```
|
||||
|
||||
正式 Quant OS 还需要第二条生产数据路径：
|
||||
|
||||
```text
|
||||
完整 Tushare/JQData PIT 数据
|
||||
-> canonical immutable snapshot
|
||||
-> Quant OS 本地事件回测 / decision
|
||||
-> 聚宽、QMT、Qlib 的同输入分层比较
|
||||
```
|
||||
|
||||
Qlib 适合因子、模型和组合研究，不拥有原始数据，也不替代 Quant OS 的
|
||||
Signal/Target/Order/Broker 合同。当前 Tushare adapter 只实现第一条链路；
|
||||
在复权、真实 benchmark、历史成分、停牌、涨跌停和 ST 数据补齐前，不会把它
|
||||
接入生产 decision。
|
||||
|
||||
## 4. 可运行命令
|
||||
|
||||
从 Quant OS 根目录执行。镜像路径只放在当前 shell 环境变量中，不写入 Git：
|
||||
|
||||
```bash
|
||||
export QUANT_OS_ROOT=/path/to/quants-strategies/quant-os
|
||||
export TUSHARE_MIRROR_ROOT=/path/to/tushare-mirror
|
||||
cd "$QUANT_OS_ROOT"
|
||||
|
||||
python3.12 -m venv .venv-qlib312
|
||||
source .venv-qlib312/bin/activate
|
||||
python -m pip install -r requirements/research-py312.txt
|
||||
export PYTHONPATH=src:.
|
||||
```
|
||||
|
||||
盘点并验证全部 completed 文件：
|
||||
|
||||
```bash
|
||||
python tools/tushare_qlib.py inventory \
|
||||
--mirror-root "$TUSHARE_MIRROR_ROOT" \
|
||||
--output-json artifacts/tushare-inventory.json
|
||||
```
|
||||
|
||||
当前未复权数据只能显式构建技术验证 provider；每次必须使用新目录，工具拒绝
|
||||
覆盖已有 provider：
|
||||
|
||||
```bash
|
||||
python tools/tushare_qlib.py build \
|
||||
--mirror-root "$TUSHARE_MIRROR_ROOT" \
|
||||
--output-dir data/qlib/tushare-early-v1 \
|
||||
--start 1990-12-19 \
|
||||
--end 1993-10-29 \
|
||||
--minimum-observations 60 \
|
||||
--allow-unadjusted \
|
||||
--ohlc-policy expand-range \
|
||||
--output-json artifacts/tushare-qlib-build.json
|
||||
|
||||
python tools/tushare_qlib.py verify \
|
||||
data/qlib/tushare-early-v1 \
|
||||
--output-json artifacts/tushare-qlib-verify.json
|
||||
```
|
||||
|
||||
运行 Qlib 0.9.7 本地回测：
|
||||
|
||||
```bash
|
||||
PYTHONHASHSEED=0 python -m platforms.qlib_runner \
|
||||
--provider-uri data/qlib/tushare-early-v1 \
|
||||
--market tushare_a \
|
||||
--benchmark SH999999 \
|
||||
--start 1992-01-02 \
|
||||
--end 1993-10-28 \
|
||||
--feature-start 1991-01-02 \
|
||||
--lookback 20 \
|
||||
--topk 10 \
|
||||
--n-drop 2 \
|
||||
--rebalance weekly \
|
||||
--output-json artifacts/tushare-qlib-momentum.json
|
||||
```
|
||||
|
||||
Qlib simulator 会消费结束日后的下一 provider session，所以 backtest `end`
|
||||
必须早于 provider 最后一个交易日。Quant OS 对受管 provider 会在 Qlib
|
||||
初始化前检查 market、benchmark、起始边界和这个终点条件。
|
||||
|
||||
`artifacts/` 与 `data/qlib/` 均被 Git 忽略。原始 Parquet、token、绝对镜像
|
||||
路径和回测临时产物不得提交到仓库。
|
||||
|
||||
## 5. 本次真实本地运行证据
|
||||
|
||||
最终 v4 provider：
|
||||
|
||||
| 证据 | 值 |
|
||||
| --- | --- |
|
||||
| adapter source SHA-256 | `2228c23af176a0f2fcf311e88dca9bdc5d63fd36fa5a3c2d3e42808a405e7243` |
|
||||
| data version | `3378aa75a5601bde476ad07bea90418966a66a037ca59195dec93d77b41cc3f8` |
|
||||
| provider tree SHA-256 | `dc85b8daf692a66641afef64398700264c6054f1dac84b1211cb258a06b62948` |
|
||||
| manifest SHA-256 | `862e7435bb0be7c8a3c66180e49761c110056c1a3cc02c1618e70d9eb566d945` |
|
||||
| provider 文件/大小 | 975 / 1,085,886 bytes |
|
||||
| calendar | 1990-12-19—1993-10-29，731 sessions |
|
||||
| market | 107 个至少有 60 条记录的 A 股代码 |
|
||||
| selected rows | 27,998 |
|
||||
|
||||
回测参数为 1992-01-02—1993-10-28、20 日动量、周频、Top 10、每期 drop 2，
|
||||
初始资金 1,000 万，Qlib 0.9.7、Python 3.12.13、`PYTHONHASHSEED=0`。
|
||||
相同命令连续执行两次，结果 JSON 逐 byte 相同：
|
||||
|
||||
| 证据/指标 | 值 |
|
||||
| --- | ---: |
|
||||
| result JSON SHA-256 | `92ff9b8cea746e9c89ddf62fcfe3feb21248ca9112d9e10d24e0639058a86020` |
|
||||
| runner source SHA-256 | `fa8118819252c55e99e67de356cc961d8a4a22f82256b4d62579a45426d96167` |
|
||||
| signal | 4,700 行；hash `cfad4087d68b7f71e33f0f46fc5bb97db985e02ac2515f01857e2ab6813a5909` |
|
||||
| portfolio report | 466 行；hash `5f8606fb64963d3e2618f66503e6ae94048c24b62c5d8e1806ff44ec57558b04` |
|
||||
| strategy cumulative return | -52.5251% |
|
||||
| max drawdown | -87.7604% |
|
||||
| synthetic benchmark cumulative return | 196,302.0822% |
|
||||
| total cost / turnover | 0.016013 / 29.567521 |
|
||||
|
||||
这些收益数字没有投资解释。原因包括未复权早期行情、没有真实指数 benchmark、
|
||||
没有历史成分/ST/停牌/涨跌停、按全区间至少 60 条观测筛选带来的非 PIT
|
||||
偏差，以及 1992—1993 特殊市场阶段。极端 synthetic benchmark 恰好说明
|
||||
为什么“程序跑完”不能等价为“回测有效”。
|
||||
|
||||
## 6. 何时可以升级为正式研究数据
|
||||
|
||||
至少完成以下步骤后，才能新建 production-eligible provider：
|
||||
|
||||
1. 修复下载器错误状态并完成目标日期的 `daily`；
|
||||
2. 补齐 `adj_factor`，冻结复权基准日和公式；
|
||||
3. 使用 `index_daily` 替换合成 benchmark；
|
||||
4. 指数策略补齐 `index_member_all/index_weight`；
|
||||
5. 补齐 `suspend_d/stk_limit`，为历史 `stock_st` 找到授权来源或保持硬阻断；
|
||||
6. 冻结下载 job、请求 hash、Parquet hash、转换器 hash 和新 `data_version`；
|
||||
7. 运行真实长样本 walk-forward/OOS，而不是复用本次早期 smoke；
|
||||
8. 同一冻结输入进入 Quant OS 本地回测、聚宽和可用 QMT，生成 L1—L4
|
||||
差异报告。
|
||||
|
||||
Qlib provider 的目录格式和缺失值/复权约定参见
|
||||
[Qlib Data Layer 文档](https://qlib.readthedocs.io/en/latest/component/data.html)。
|
||||
Reference in New Issue
Block a user