330 lines
16 KiB
Markdown
330 lines
16 KiB
Markdown
# Tushare 本地数据盘点、冻结边界与 Qlib 接入
|
||
|
||
点时证据：2026-07-31 00:40 CST。原先“93 个 completed 文件、日线只到
|
||
1993-10”的结论已经失效，不得再用于判断当前镜像。当前镜像约 7.7 GB，
|
||
SQLite job ledger 在该点时已有 378,707 条 `completed` 版本记录、约
|
||
1.80 亿行；同时仍有与本次中证 500 研究无关的指数任务处于 `running`。
|
||
|
||
```text
|
||
tushare_daily_completed_partitions = 428
|
||
tushare_daily_planned_partitions = 428
|
||
tushare_daily_completed_rows = 18,041,386
|
||
tushare_daily_market_data_from = 1990-12-19
|
||
tushare_daily_market_data_through = 2026-07-28
|
||
production_ready = false
|
||
investment_value_claim = false
|
||
gate_credit = []
|
||
```
|
||
|
||
这意味着数据已经足够做一条真实的 2018—2025 本地 Qlib 研究链，但不能把
|
||
“live raw mirror 很大”直接等同于“已经有可复现、可用于发布结论的数据集”。
|
||
正确边界是三层：
|
||
|
||
| 层 | 本机位置/产物 | 用途 | 是否可变 |
|
||
| --- | --- | --- | --- |
|
||
| live raw mirror | `$TUSHARE_MIRROR_ROOT` | 下载器持续落盘的 Parquet、权限探测和 job ledger | 是；不能直接作为可重放 run 的唯一引用 |
|
||
| scoped frozen release | `tools/tushare_snapshot.py` 生成的范围化 manifest | 固定日期、API、指数代码、所选 job/file hash 和选择规则 | manifest 不变；引用的 raw bytes 仍需留存 |
|
||
| Qlib provider | `data/qlib/...` + provider manifest | Qlib 0.9.7 可直接读取的 calendar/instruments/features | 否；是 frozen release 的派生物，不是原始数据备份 |
|
||
|
||
`tools/tushare_qlib.py` 和冻结工具都只读镜像，不调用 Tushare，也不读取或保存
|
||
token。snapshot 工具不复制 Parquet；manifest 能在源文件被覆盖时检测不一致，
|
||
但若要长期从 raw bytes 重建，还需要后续接入 content-addressed archive。
|
||
原始 Parquet、绝对路径、账号信息和本地运行 artifacts 不进入 Git。
|
||
|
||
## 1. 当前真实覆盖
|
||
|
||
下面同时区分“自然分区文件”和 SQLite 的“completed 版本记录”。下载器在
|
||
2026-07 月内多次刷新同一个分区，所以 `daily` 和 `adj_factor` 都是 428 个
|
||
自然月文件，却各有 430 条 completed 版本记录。job 行数求和会重复计算旧版
|
||
2026-07，不能当作当前文件行数。
|
||
|
||
| 数据 | 当前自然文件 | 当前行数 | 实际可见范围 | 可直接支持什么 |
|
||
| --- | ---: | ---: | --- | --- |
|
||
| `daily` | 428 | 18,041,386 | 1990-12-19—2026-07-28 | OHLC、前收、成交量额、收益与本地撮合输入 |
|
||
| `adj_factor` | 428 | 18,868,457 | 1990-12—2026-07；最大 `trade_date=20260729` | 区间内累计复权 |
|
||
| `trade_cal` | 39 completed 版本 | 13,423 | SSE 1990—2026 | 交易日历与完整性检查 |
|
||
| `stock_basic` | 4 | 5,869 | 当前上市、退市、暂停上市等快照 | 代码、上市/退市日期；不是 PIT 成分表 |
|
||
| `daily_basic` | 331 | 17,335,584 | 1999-01-04—2026-07-28 | 市值、换手、估值与横截面特征 |
|
||
| `stk_limit` | 235 | 17,878,521 | 2007-01-04—2026-07-29 | 逐股逐日真实涨跌停价格 |
|
||
| `suspend_d` | 37 | 641,379 | 非空记录 1999-05-04—2026-07-29 | 停复牌与可交易性 |
|
||
| `index_daily`，`000905.SH` | 37 年 job | 5,239 | 2004-12-31—2026-07-29 | 真实中证 500 benchmark |
|
||
| `index_weight`，`000905.SH` | 37 年 job | 129,000 | 2005-01-31—2026-06-30 | 中证 500 的历史定期成分/权重快照 |
|
||
| `index_member_all` | 1 | 3,000 | 申万行业层级及进出日期 | 行业分类；不能冒充中证 500 历史成分 |
|
||
|
||
`daily` 原计划覆盖 1990-12—2026-07，共 428 个月；当前完成
|
||
428 个月，约 100.0%。这里的
|
||
“完成”只指自然月文件覆盖，不代表 live mirror 已冻结，也不代表
|
||
production-ready。
|
||
|
||
另外已有 `income`、`balancesheet`、`cashflow`、`fina_indicator`、
|
||
`disclosure_date`、`moneyflow` 等数据。它们可以用于下一阶段的基本面、质量、
|
||
资金流特征，但财务报表必须按公告/披露可得日做 as-of join，不能直接按报告期
|
||
回填到历史日期。
|
||
|
||
### 仍然存在的硬缺口
|
||
|
||
- 2026-07-26 的权限探测明确显示 `stock_st` 为 `denied`。在获得授权历史
|
||
ST 源之前，不能声称完整复现 ST 股票的逐日交易限制；
|
||
- live ledger 在本次点时仍有 24 个 `running`：19 个
|
||
`931632CNY04.CSI` 的 `index_daily` 年任务和 5 个 `931632.CSI` 的
|
||
`index_weight` 年任务。它们与 `000905.SH` 的 2018—2025 release 无关，
|
||
但说明全镜像仍是移动目标；
|
||
- `daily` 的最新 completed 请求元数据包含 `20260729`，但当前 Parquet
|
||
的最大实际日期是 `20260728`；任何冻结工具都必须验证 Parquet 内容，而不能
|
||
只相信请求参数或 job 状态；
|
||
- 多个 completed 版本可指向同一个最终路径。冻结时必须按明确规则选择当前
|
||
canonical 版本并复核 size/SHA-256/Parquet row count，不能把所有
|
||
`completed` 盲目拼接；
|
||
- `stock_basic` 是当前快照，不得用它反向构造历史指数 universe。
|
||
|
||
## 2. 数据如何进入 Quant OS
|
||
|
||
第一条可用研究路径是中证 500 横截面研究：
|
||
|
||
```text
|
||
daily + adj_factor + trade_cal
|
||
+ index_daily(000905.SH)
|
||
+ index_weight(000905.SH)
|
||
-> scoped frozen release (2018-01-01—2025-12-31)
|
||
-> managed Qlib provider
|
||
-> momentum / Alpha158 / LightGBM
|
||
-> evidence JSON + provider verifier
|
||
```
|
||
|
||
第二条是本地事件回测输入：
|
||
|
||
```text
|
||
raw daily/pre_close + stk_limit + suspend_d
|
||
+ PIT universe + signal/target
|
||
-> Quant OS reference execution
|
||
-> ledger / replay / platform parity
|
||
```
|
||
|
||
两条路径不能混为一谈。Qlib 负责因子、模型和组合研究；Quant OS 的
|
||
Signal/Target/Order/Broker 合同、涨跌停、停牌、T+1、成交和对账仍由本地
|
||
事件链负责。历史 ST 未补齐时，本地执行链必须保留显式缺口或 fail-closed，
|
||
不能静默按普通股票处理后再把结果标为完整市场仿真。
|
||
|
||
### 复权口径
|
||
|
||
新 provider 对每个 symbol 使用 release 区间内第一个有效 `adj_factor` 作为
|
||
锚点：
|
||
|
||
```text
|
||
factor_t = adj_factor_t / first_valid_adj_factor
|
||
adjusted_OHLC_t = raw_OHLC_t * factor_t
|
||
adjusted_volume_t = raw_volume_in_shares_t / factor_t
|
||
money_t = raw_amount_in_CNY_t
|
||
```
|
||
|
||
这是“首个有效因子锚定的区间累计复权”，文档和证据中不要把它简写成
|
||
`qfq`。不用区间末因子做归一化，是为了避免研究区间末端信息参与早期价格的
|
||
缩放。停牌缺口保留为 `NaN`，不会伪造 K 线。
|
||
|
||
固定单位仍为：
|
||
|
||
```text
|
||
600000.SH -> SH600000
|
||
000001.SZ -> SZ000001
|
||
430047.BJ -> BJ430047
|
||
raw_volume_in_shares = Tushare vol * 100
|
||
raw_amount_in_CNY = Tushare amount * 1000
|
||
```
|
||
|
||
### universe 与 benchmark 口径
|
||
|
||
- benchmark 使用 `index_daily(000905.SH)`，Qlib symbol 为 `SH000905`；
|
||
- universe 使用 `index_weight(000905.SH)` 的历史快照，并按“只向未来
|
||
carry-forward、绝不从未来 backfill、月末权重下一交易日生效”生成时变
|
||
成分区间。这是 event-time / 保守次日生效 PIT 近似；源数据没有单独验证的
|
||
`published_at`，不能声称严格 knowledge-time PIT；
|
||
- `index_member_all` 是申万行业数据，不参与中证 500 universe；
|
||
- 研究报告必须分别披露 benchmark、universe、价格复权和可交易性过滤来源。
|
||
|
||
## 3. 现有代码基线与 v2 接口
|
||
|
||
### 现有基线
|
||
|
||
仓库当前基线的 `build` 只消费 `daily/trade_cal/stock_basic`，必须显式传
|
||
`--allow-unadjusted`，会生成 synthetic equal-weight benchmark，并按整个
|
||
研究区间的最少观测数筛选股票。它只能用于转换器/运行时技术验证：
|
||
|
||
```bash
|
||
PYTHONPATH=src:. python tools/tushare_qlib.py build \
|
||
--mirror-root "$TUSHARE_MIRROR_ROOT" \
|
||
--output-dir data/qlib/tushare-legacy-2018-2025 \
|
||
--start 2018-01-01 \
|
||
--end 2025-12-31 \
|
||
--minimum-observations 60 \
|
||
--allow-unadjusted \
|
||
--ohlc-policy fail \
|
||
--output-json artifacts/tushare/legacy-build.json
|
||
```
|
||
|
||
不要用这个结果回答“中证 500 策略是否有效”，也不要给它任何发布门禁分数。
|
||
|
||
### 已验证的 v2 接口
|
||
|
||
v2 已消费 `adj_factor`、真实指数行情和历史指数权重，并完成 provider
|
||
构建、验证和两次本地 run。实际构建命令为：
|
||
|
||
```bash
|
||
PYTHONPATH=src:. python tools/tushare_qlib.py build \
|
||
--mirror-root "$TUSHARE_MIRROR_ROOT" \
|
||
--output-dir data/qlib/tushare-csi500-2018-2025-v2 \
|
||
--start 2018-01-01 \
|
||
--end 2025-12-31 \
|
||
--market-name tushare_csi500 \
|
||
--benchmark-index-code 000905.SH \
|
||
--universe-index-code 000905.SH \
|
||
--minimum-observations 60 \
|
||
--ohlc-policy fail \
|
||
--output-json artifacts/tushare/csi500-2018-2025-build.json
|
||
```
|
||
|
||
这条命令不再传 `--allow-unadjusted`。provider manifest 必须记录复权口径、
|
||
真实 benchmark、时变 universe、所有 source job/file hash、转换器 hash、
|
||
质量统计和可重算 `data_version`。
|
||
|
||
`tools/tushare_snapshot.py` 是独立的 raw scoped freeze 入口。Qlib 核心输入
|
||
可以这样冻结：
|
||
|
||
```bash
|
||
python tools/tushare_snapshot.py \
|
||
--mirror-root "$TUSHARE_MIRROR_ROOT" \
|
||
--start 2018-01-01 \
|
||
--end 2025-12-31 \
|
||
--apis daily adj_factor trade_cal stock_basic index_daily index_weight \
|
||
--index-codes 000905.SH \
|
||
--output artifacts/local-tushare-20260731/scoped-source-manifest.json
|
||
```
|
||
|
||
默认会验证 size、SHA-256 和 Parquet row count。需要研究
|
||
`daily_basic/stk_limit/suspend_d` 时应再冻结一个明确包含它们的扩展
|
||
release；不要把未列入 manifest 的表暗中加入既有 run。当前 `build` 仍从
|
||
mirror 重新选择 source jobs，并不接受这份 manifest 作为参数，因此 run
|
||
验收还必须比较 provider manifest 与 scoped manifest 的 source
|
||
job/file hashes。
|
||
|
||
snapshot 工具在请求 `index_weight` 时会自动包含 `start.year-1` 的 pre-start
|
||
PIT anchor。本次 scoped manifest 与 provider 均为 221 个 source jobs，
|
||
全字段比对零差异，已经覆盖有效 roster 日期 `2017-12-29`：
|
||
|
||
```text
|
||
scoped_manifest_sha256 = 744a69828f527594e9f2787280095368c50deffa2f269c359ae65e2e0ac2d5f2
|
||
scoped_selection_sha256 = 66e91fffecba5fa042922c49e339f24212c3febf5b874279866fdca660f54fb5
|
||
scoped_source_jobs = 221
|
||
provider_source_jobs = 221
|
||
source_job_full_field_diff = 0
|
||
provider_source_jobs_before_read = 221
|
||
provider_source_jobs_after_read = 221
|
||
provider_selected_jobs_still_latest = true
|
||
provider_post_read_file_verification = true
|
||
```
|
||
|
||
冻结期间 SQLite 主文件/WAL 仍被无关下载任务更新：
|
||
`changed_through_file_verification=true`。这不是 selected scope 未冻结：
|
||
SQLite 事务读取期间 `changed_while_reading=false`，221 个 selected jobs
|
||
均完成两次 size/SHA-256/Parquet row-count 校验，验证后仍是各自 partition
|
||
的 latest，并与 provider 的 221 个 source jobs 全字段零差异。这里的证据边界
|
||
是“scoped jobs 稳定”，不是“整个 live DB/WAL 静止”。
|
||
|
||
scoped manifest 与 provider 的正式 lineage 由独立工具核对：
|
||
|
||
```bash
|
||
python tools/tushare_lineage.py \
|
||
--source-manifest artifacts/local-tushare-20260731/scoped-source-manifest.json \
|
||
--provider-dir data/qlib/tushare-csi500-2018-2025-v2 \
|
||
--output-json artifacts/tushare/csi500-2018-2025-lineage.json
|
||
```
|
||
|
||
结果为 221 个 jobs、6 个逐 job 字段
|
||
`id/path/row_count/byte_count/sha256/request_sha256` 全部一致，
|
||
`mismatch_count=0`、`converter_source_matches_current=true`。lineage artifact
|
||
同样明确 `investment_value_claim=false`、`gate_credit=[]`。
|
||
|
||
## 4. 2018—2025 provider 与双次回测实证
|
||
|
||
managed provider 已构建在新目录，并由独立 verifier 通过：
|
||
|
||
| 证据 | 实测值 |
|
||
| --- | --- |
|
||
| data version | `5bf19d2da064357ad1802bca4bfa0c0505ed63fe2b24785ec6c56ecff1724963` |
|
||
| provider tree SHA-256 | `f173b8095fd9a62a63807324fa48bad83f0c282eea3abba871d0b0efd30b199f` |
|
||
| provider manifest SHA-256 | `27fb6fedb6a4b114eae2aba44505fb6c4d32c7a9ae81e58c724dfadb8dd10ed0` |
|
||
| provider files / bytes | 10,011 / 71,707,194 |
|
||
| source stability | 221/221 jobs 在消费前后稳定；读取后重新校验文件且仍为 latest |
|
||
| calendar | 2018-01-02—2025-12-31，1,942 sessions |
|
||
| event-time PIT 近似 market | 1,111 个曾进入 `000905.SH` roster 的 instruments |
|
||
| snapshot coverage | 97 observed / 96 effective；最大日历间隔 36 天 |
|
||
| roster quality | 每个 observed snapshot 严格 500 constituents；weight sum 容差 ±0.5 |
|
||
| availability | 月末权重从下一 provider 交易日生效；`same_session_membership_use=false` |
|
||
| selected daily rows | 1,975,455 |
|
||
| price adjustment | 完整；0 个缺失 daily/adj keys；首个有效因子锚定 |
|
||
| OHLC quality | `--ohlc-policy fail`；0 个 envelope anomalies |
|
||
| benchmark | 真实 `index_daily(000905.SH)` / `SH000905` |
|
||
| release flags | `production_ready=false`、`investment_value_claim=false`、`gate_credit=[]` |
|
||
|
||
周频 20 日动量参数为 2019-01-02—2025-12-30、Top 50、每期 drop 5、
|
||
初始资金 1,000 万、开仓费 0.03%、平仓费 0.08%、最低费用 5 元、
|
||
`PYTHONHASHSEED=0`。相同命令连续执行两次，两个 JSON 逐 byte 相同：
|
||
|
||
| 证据/指标 | 实测值 |
|
||
| --- | ---: |
|
||
| run JSON SHA-256 | `803035a95ee9cf6f90af20cdf7e7024149b97e0113b585209a80f80048be87d3` |
|
||
| signal rows | 176,615 |
|
||
| portfolio report rows | 1,698 |
|
||
| strategy cumulative return | 0.253151986388197（25.3152%） |
|
||
| benchmark cumulative return | 0.789559383530678（78.9559%） |
|
||
| max drawdown | -0.6041641365538415（-60.4164%） |
|
||
| total cost / turnover | 0.03579348112198462 / 65.51393782463258 |
|
||
|
||
这组数字证明真实 Tushare → event-time/保守次日生效 PIT 近似 universe →
|
||
复权 Qlib provider →
|
||
momentum runner 的链路可重放，不证明策略可投资。策略显著跑输 benchmark，
|
||
且最大回撤超过 60%，不能把正累计收益单独拿出来宣传。
|
||
|
||
最终身份变化来自 verifier/转换器源码绑定；provider tree 与回测数值未变。
|
||
verifier 已确认 recorded/current converter SHA-256 一致。由于 run evidence
|
||
绑定 provider identity，两个 run JSON 的 SHA-256 随之更新。
|
||
|
||
## 5. 验证顺序
|
||
|
||
1. 对 live mirror 做快速元数据盘点，确认目标 API 和 `000905.SH` 范围；
|
||
2. 生成 2018—2025 scoped frozen release，并验证所选文件的 size、
|
||
SHA-256、Parquet footer/row count、自然键和日期边界；
|
||
3. 在冻结后从同一 source state 构建新 provider，绝不覆盖已有目录，并核对
|
||
provider/scoped manifest 的 source hashes；
|
||
4. 运行 `tools/tushare_qlib.py verify`，核对 manifest、tree hash、
|
||
calendar、instrument 和 feature 文件；
|
||
5. 运行同一条 Qlib momentum 命令两次，比较 evidence JSON 的关键输入、
|
||
signal/report hash 和重算指标；
|
||
6. 再进入 walk-forward、Alpha158/LightGBM、成本/风险扰动和本地事件回测。
|
||
|
||
完整可复制命令见
|
||
[`runbooks/TUSHARE_QLIB_LOCAL_RUN.md`](runbooks/TUSHARE_QLIB_LOCAL_RUN.md)。
|
||
|
||
## 6. 结果边界
|
||
|
||
2018—2025 的真实行情、复权、指数行情和历史权重会让回测比旧的
|
||
1990—1993 technical smoke 有意义得多，但仍只是一条研究证据：
|
||
|
||
- momentum smoke 的收益不能证明投资价值；
|
||
- Qlib 的成交模型不能替代 A 股逐股涨跌停、停牌、T+1 和真实容量仿真；
|
||
- 本次 Qlib run 使用统一 `limit_threshold=0.095`，只是 9.5% 市场级近似；
|
||
它没有消费已有 `stk_limit` 的逐股逐日价格，也不能表达不同板块、日期和
|
||
ST 股票的真实限制；
|
||
- `stock_st` 缺口没有因为已有 `namechange` 或 `stk_limit` 就自动消失；
|
||
- `index_weight` 没有单独验证的 `published_at`，因此这里不是严格
|
||
knowledge-time PIT；
|
||
- 复权以每个 symbol 在 provider 区间内的首个有效因子为锚。不同 `start`
|
||
构建的 provider 归一化基准不同，不能直接拼接其价格 level；需要统一起点
|
||
重建或显式重新归一化；
|
||
- 必须做时间切分、walk-forward/OOS、参数稳定性、成本压力和跨引擎差异；
|
||
- 本文不据此声称 Quant OS 已达到 60 分或 80 分标准。
|
||
|
||
相关字段语义参见
|
||
[Tushare 日线接口](https://tushare.pro/document/2?doc_id=27)、
|
||
[复权因子接口](https://tushare.pro/document/2?doc_id=28)和
|
||
[Qlib Data Layer](https://qlib.readthedocs.io/en/latest/component/data.html)。
|