Files

T

Simon 880f4c50fe docs: Qlib 安装可用性验证报告 + 基线验证脚本

- pyqlib（0.9.8.dev32 源码安装）验证：import / 数据落盘 / storage 底层读回 / Alpha158 / LGBModel 均通过（scripts/qlib_verify.py 可重复）
- 记录格式要点：小写 instrument、instruments 3 列、provider_uri 需 {'day': path} 字典
- 如实记录未打通项：D.features→训练→回测高层链路仍待 QlibEngine 实现（建议按官方 dump 规则落盘）
- 项目回归保持 81 passed / ruff clean

2026-09-06 18:02:22 +08:00

4.6 KiB

Raw Permalink Blame History

Qlib 安装与可用性验证报告

验证时间：2026-09 · 环境：Linux aarch64 / CPython 3.12.13（uv 虚拟环境）安装方式：pyqlib 源码 git 安装并固定 commit（pyqlib @ git+https://github.com/microsoft/qlib.git@79633dd，见 backend/pyproject.toml）复现：cd backend && uv run python ../scripts/qlib_verify.py

结论摘要

项目	结果
qlib 导入与版本	✅ `qlib.__version__ == 0.9.8.dev32`
依赖组件	✅ lightgbm 4.7.0 / scipy / sklearn / joblib 可用；❌ numba 缺失（可选，未影响本验证路径）；CatBoost/XGBoost/PyTorch 模型为可选未装（import 时提示跳过属正常）
数据目录落盘与底层读回	✅ calendars / instruments / features 二进制均可写入并被 qlib storage 读回
项目回归	✅ pytest 81 passed、ruff clean（含 Qlib 改动后仍全绿）
Alpha158 / LGBModel 导入	✅ 可导入
D.features → Dataset → 训练/回测高层链路	⚠️ 未打通（原因见下，属 QlibEngine 实现任务，非安装问题）

结论：pyqlib 在本机（aarch64 + py3.12）已成功安装且核心数据存储可读写；当前可用的是「安装 + 数据落盘 + 底层读回」基线，而非完整的 Qlib 研究工作流。

1. 已验证通过的项目（有脚本断言）

import qlib、qlib.__version__（0.9.8.dev32，源码安装路径在 backend/.venv）。
合成 6 只股票、60 个交易日后可正确写入：
- calendars/day.txt（每行一个 %Y-%m-%d）
- instruments/all.txt
- features/<instrument>/<field>.day.bin（float32，按日历逐日对齐）
qlib.init(provider_uri={"day": <dir>}, region=REG_CN) 后：
- 日历读回长度一致
- instruments 解析出符号与起止时间
- 每只股票 close.day.bin 读回非空数值
lightgbm、qlib.contrib.data.handler.Alpha158、qlib.contrib.model.gbdt.LGBModel 导入成功。

2. 过程中踩到的格式要点（写 QlibEngine 时直接可用）

该源码版（0.9.8.dev32）与旧版 Qlib 在数据目录约定上有差异，已实测确认：

instrument / feature 命名统一小写：feature 目录与 instruments 文件第一列必须小写（如 600519.sh），storage 内部会 instrument.lower() 后拼接路径。
instruments 文件仅 3 列：instrument<TAB>start<TAB>end（没有第 4 列 TYPE）。
provider_uri 用字典形式：qlib.init(provider_uri={"day": <path>})。若直接传字符串，会被挂到 __DEFAULT_FREQ，导致 D.features(freq="day") 查不到数据而返回空（实测复现）。
.day.bin 每个值 float32、按该股在全局日历中的交易日逐日对齐（缺失可用 NaN），文件名 <field>.day.bin（字段名小写、无 $ 前缀）。

3. 未通过 / 未验证项（需要说明，不回避）

D.features 高层读取仍报错：手动生成的 bin 在该 dev 版上进入 dataset 读取时出现形状不一致（shapes (200,) vs (0,)），推测与 bin 对齐 / 每 instrument 起止切片细节有关。手工 float32 文件虽能被 storage 读回，但未必满足 dataset 层对文件长度的精确预期（storage 直读 60 个值返回 59 个，见下）。
因此 QLibDataset → Alpha158 → LightGBM 训练 → 回测尚未在项目内跑通。

为什么 storage 直读 60 返回 59

FileFeatureStorage.data 对文件做了一些尾部/NaN 处理（实测 60 值读回 59）。这提示 bin 文件的预期长度与全局日历并非简单相等 —— 为避免手工格式猜错，QlibEngine 实现时应使用官方 dump 工具（qlib.dump_bin / qlib.tests 中生成样例的代码）产出数据，或阅读其 dump 实现确认行对齐规则后再自建落盘，而不要依赖上述手工 bin 约定。

4. 下一步（若继续 Qlib 集成）

用官方 dump 路径（或对照 qlib 自带样例数据生成代码）建立 qlib_adapter/provider.py：把本地 SQLite 行情按正确 bin 布局导出到 data/qlib。
qlib_adapter/dataset.py：QLibDataset 配置（Alpha158 / 自定义字段），供 QlibEngine.run_factor_test 与 run_backtest 使用。
工作流仍经 QuantEngine Protocol 注入，LocalEngine 保持默认，切换不伤业务层（见 app/quant/engine.py、app/quant/qlib_adapter/engine.py）。

附：Qlib 安装贡献说明

commit 8f8b6d2（由项目维护者提交）完成源码 git 安装与依赖固化；本报告基于该安装后的实际运行验证。若后续调整 qlib commit，建议重跑 uv run python ../scripts/qlib_verify.py 确认基线仍通过。

4.6 KiB Raw Permalink Blame History Unescape Escape