226 lines
8.9 KiB
Markdown
226 lines
8.9 KiB
Markdown
# 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)。
|