【Qlib 系列 第1讲】架构入门：数据层、模型层与策略层协同机制

一、为什么第 1 讲先讲 Qlib 的分层，而不是先跑一个回测

很多人第一次接触 Qlib，最自然的念头是赶快把一个模型跑起来，再接个回测，看是不是能出结果。但如果一上来就这么做，后面往往很快会遇到一个共同问题：代码能跑，流程却说不清。你可能在训练脚本里顺手写了数据清洗，在 notebook 里手工拼了标签，又在回测部分临时加了几个过滤条件。单看某次实验也许没有问题，可一旦你想复现、迭代，或者交给别人接手，整条链路会立刻变得混乱。

Qlib 真正的价值，并不只是“可以做量化研究”，而是它试图把研究、训练、回测、组合构建和实验记录这几件原本容易散在不同脚本里的事情，压成一条相对清楚、可追溯的流程。因此第 1 讲最该做的，不是急着追求一个漂亮结果，而是先搞清楚它到底把量化研究拆成了哪些层，每一层负责什么，你自己的代码又该接在哪一层。

如果这张地图没立起来，后面最容易出现三类问题。第一，把数据逻辑写进模型脚本，导致训练和生产口径不一致。第二，把信号生成和组合构建混在同一个 notebook 里，后续根本没法复现。第三，误以为 Qlib 只是“带数据接口的模型框架”，忽略了它在实验组织和研究纪律上的价值。也正因为如此，本讲的目标只有一个：先把分层看懂，再谈后面的模型和策略。

二、Qlib 最核心的三层主干：数据层、模型层、策略层

如果把 Qlib 看成一个研究操作系统，那么它最核心的抽象其实并不复杂，主要就是三层。

第一层是数据层。它负责回答四个问题：数据从哪里来，字段如何定义，标签如何构造，训练集和测试集怎样按时间切分。Qlib 在这一层的重点，不是给你一张现成 DataFrame，而是提供一套可以把原始市场数据整理成研究样本的规范入口。也就是说，你不应该先手工导出一份 CSV，再在某个脚本里临时写 label = future_return。更稳的做法，是把这些逻辑放在统一的数据处理抽象里，让它们成为研究配置的一部分。

第二层是模型层。它的职责很单纯，就是读取已经整理好的样本，完成拟合，并输出一个可以排序、可以评价、也可以继续交给策略层使用的预测分数。模型层最大的纪律，就是不要再顺手去改数据口径。如果你在训练模型时还在补缺失、修标签、重新筛资产池，那说明分层已经塌了。

第三层是策略层。它不负责判断模型是不是好模型，而是负责把模型输出的分数变成真正可以回测和分析的持仓决策。这里至少包括排序、选股或选行业、仓位分配、调仓规则、成本映射等环节。Qlib 的价值在于，它允许你把“预测”和“如何交易这个预测”明确拆开。这样你就能单独比较：到底是模型有效，还是组合映射方式更重要。

三、数据层为什么最容易被低估，但其实最决定研究口径

很多初学者第一次看 Qlib，会更关注模型支持哪些算法，反而忽略数据层。可在真正的量化研究里，数据层往往比模型层更决定结果是否可信。原因很简单：标签定义错一点、时间切分松一点、复权口径混一点，模型训练再规范，最后也只是在错误世界里认真学习。

Qlib 在数据层最值得重视的地方，不是“配置项很多”，而是它在逼你把研究口径显式写出来。比如你到底用哪些字段作为特征，未来几天收益作为标签，训练与验证时间边界怎么定，缺失值和标准化怎么处理，这些都不该散在十几个 notebook 里，而应被收进统一的数据处理定义里。只要这一层做得清楚，后面不管换模型、换市场还是换回测区间，至少输入口径是一致的。

这也是为什么在 Qlib 里，像 DatasetH、DataHandlerLP 这样的对象比看起来更重要。它们并不只是“封装一下数据”，而是在帮你把原本容易临时发挥的研究动作固定下来。你之后回头看一轮实验，不只是知道它用了哪个模型，还知道它到底是拿什么样的样本、什么样的时间切分和什么样的标签口径做出来的。

四、模型层的边界必须守住：模型负责拟合，不负责顺手修世界

模型层在 Qlib 中看起来很直观，但也最容易被用歪。很多人训练模型时，会习惯性在脚本里补上几句临时数据处理，比如删掉某些样本、再对某些字段做标准化、或者顺手改一下标签计算方式。从短期看，这样写很快；从长期看，这会让模型层开始承担本不属于它的职责。

一个健康的分层边界应该是：数据层先定义好 feature 和 label，模型层只接收已经切好的训练集、验证集和测试集，然后输出预测结果。模型层当然可以有自己的训练参数、早停逻辑和损失函数，但它不应该再去动样本定义。如果这一层混乱，后面最典型的后果就是：同一个模型，在 notebook 里效果很好，搬到调度环境里立刻失真，因为研究时那几句“顺手处理”根本没有被正式纳入流程。

把模型层守干净的另一个好处，是你更容易比较模型本身的差异。若数据层不变，策略层也不变，那么不同模型输出差异才真正说明模型能力不同。否则你看起来是在比较模型，实际上是在比较谁顺手做了更多隐藏预处理，这样的结论几乎没有研究价值。

五、策略层真正解决的问题，是“同一个信号怎样变成不同的组合表达”

很多人一说到策略层，就默认这是回测之后的事情。其实不是。策略层并不是“模型结束后的附属品”，而是决定模型输出如何转成交易表达的关键环节。一个分数序列本身不会自动变成收益，它还要经过排序、筛选、仓位分配、调仓节奏和成本约束，最后才会形成一条真正可分析的收益曲线。

这也是 Qlib 里像 TopK、Dropout、回测配置这些组件有意义的原因。它们把“预测能力”和“组合映射能力”拆开了。比如同一个模型输出的分数，你可以用最简单的 TopK 持有，也可以加掉队剔除、换手约束、行业暴露限制。若不把这些动作单独放在策略层，研究者就很容易把模型效果和组合工程效果混成一件事。

在实务里，这种拆分非常重要。因为很多时候，模型本身未必差，问题只是策略层把它映射得太激进；反过来也一样，有时模型信号并不稳定，却被组合层的风险控制暂时盖住了问题。只要策略层被清楚独立出来，这些差异就更容易被识别，而不是全压在“回测结果好不好”一个表面指标上。

六、实验记录为什么不是加分项，而是研究纪律的一部分

Qlib 另一个容易被低估的部分，是实验记录。很多初学者会把 Recorder 之类的东西理解成“好看一点的日志”。其实不是。实验记录的真正作用，是把输入、配置、结果和产物绑定在一起。换句话说，它是在帮你给每一轮研究留下可以复盘、可以追责、也可以继续迭代的上下文。

这一点对量化研究尤其关键。因为量化研究最容易出现的，不是代码报错，而是“当时好像做了什么，后来却说不清”。你可能记得某次回测效果很好，却不确定当时用的是哪个标签口径；你可能知道模型参数改过一次，却忘了那次改动是为了修正哪一层逻辑；你也可能只剩一张收益图，却不知道它对应的资产池和交易成本假设是什么。Recorder 解决的正是这种研究失忆。

只要把记录这层做好，后面每一次改动就不再只是“再跑一遍看看”，而会变成“在一个有上下文的实验序列里继续推进”。这对个人研究和团队协作都很重要，因为它让你知道自己究竟是在做新实验，还是在重复昨天那次本来就没锁清楚条件的尝试。

七、第一次上手 Qlib 时，真正该先确认什么

第 1 次接触 Qlib，最容易焦虑的是环境和数据。很多人会想把下载数据、训练模型、回测和分析一次性全打通，结果一层没稳住，另外几层的问题也一起冒出来。更稳的顺序其实应该更克制。

第一，先确认安装环境没有问题，至少能正常导入 qlib 并完成初始化。第二，确认 provider_uri 指向的数据目录真实存在，且当前环境能读。第三，确认区域配置与你研究市场一致，比如做 A 股就用 REG_CN，不要在还没搞清交易日历和字段语义时就混入口径。第四，先跑通最小初始化代码，而不是一上来就接复杂模型。

这个顺序看起来慢，但它会大幅降低排错成本。因为你越早把问题拆开，就越不容易在一个失败现象里同时猜环境、数据、模型和策略哪一层出了问题。Qlib 作为框架，本来就是为了解决流程复杂度的，你自己上手时也应该按同样思路把问题拆开。

八、初学者最容易混淆的几个边界

关于 Qlib，最常见的误解有几个。第一，把它当成一个单纯的模型库，觉得它只是“又一个能训 LightGBM 的地方”。实际上它更像一个研究流程框架。第二，把它当成开箱即用的实盘系统，期待它直接替你解决订单执行、账户管理和风控总线问题。它当然能帮助你接近生产化，但它本身不是券商级 OMS。

第三，误以为 Qlib 的难点在 API 多。实际上真正难的不是会不会调用接口，而是你有没有把数据口径、标签定义、时间切分和实验记录这些基础研究纪律真正守住。第四，觉得 Recorder 之类的东西是后面再加的“增强功能”。恰恰相反，在一个长期研究流程里，实验留痕本来就是主干的一部分，而不是最后可有可无的装饰。

只要这些边界先看清，Qlib 的学习路线会清楚很多。你不会再纠结“为什么它要搞这么多层”，而会明白这些层本来就是量化研究需要被拆开的东西，只是以前很多人把它们混写在了一起。

九、建议的第 1 周推进顺序

如果你准备把 Qlib 纳入自己的日常研究栈，更稳的推进方式通常不是一口气全学，而是按层拆开。第 1 天只做环境初始化和数据目录确认。第 2 天只看数据层，重点理解 Handler、Dataset 和时间切分。第 3 天接一个最简单的模型，把 fit -> predict 跑通。第 4 天再接策略层，确认分数到持仓的映射。第 5 天开始看 Recorder，把实验留痕这件事固定下来。

这样推进的好处很明确。每一层都能单独验收，只要某一层出错，问题不会扩散成整条链路一起发散。你会更容易看出到底是环境问题、数据问题、模型问题，还是策略映射问题。对初学者来说，这比一开始就追求“完整跑通一次”要稳得多。

十、为什么第一次跑通 Qlib 时，最该确认的不是收益曲线，而是层和层之间有没有串线

很多人第一次把 Qlib 一整条链路跑通后，最自然地会去看最终回测图。这当然无可厚非，但如果只看收益结果，反而容易错过更关键的事情。对 Qlib 来说，第一次成功真正最值得确认的，其实是数据层、模型层、策略层之间有没有被你不小心串线。比如标签是否还在模型脚本里临时修改，组合规则是否写死在 notebook 中没有正式进入策略配置，实验记录是否真的绑定到了这轮训练和回测结果上。

这个检查之所以重要，是因为 Qlib 的价值本来就不只是“能跑通”，而是“能有纪律地跑通”。若第一次成功只是让你得到一张收益图，但底层边界仍然混乱，那么后面每多做一次实验，混乱都会被放大。相反，只要第一次就开始检查层间边界是否清楚，后面你做迭代时就会轻松很多，因为每一层该改什么、该保留什么都比较明确。

所以，第 1 讲真正的验收，不该只是出现结果，而是出现结果的同时，结构仍然清楚。这一点比单次指标好看更重要。

十一、为什么 Qlib 适合用来建立研究纪律，而不只是节省代码量

很多人第一次喜欢上 Qlib，是因为它能把很多原本要手写的流程封装起来，看起来像是“少写了很多代码”。这当然是它的一个优点，但若只把它理解到这里，就低估了它最有价值的部分。Qlib 更重要的地方，其实是它在逼你形成研究纪律。它要求你把数据口径、训练配置、策略表达和实验留痕分开，这会迫使很多原本依赖个人习惯和临场发挥的动作被正式化。

这种正式化对量化研究特别重要。因为量化最怕的不是代码多，而是研究不可复现。一个框架如果只是帮你少写代码，却不能帮你把流程更清楚地组织起来，那么它带来的价值是有限的。Qlib 恰恰不止做到前者，还明显偏向后者。它适合的用户，往往不是只想快速试一次策略的人，而是希望建立长期研究生产线的人。

因此，第 1 讲理解 Qlib 时，最该看到的不是它替你省了多少代码，而是它在帮你把本来容易散落的研究动作重新编排成一条可管理链路。这个认识一旦到位，后面很多设计就会显得顺理成章，而不是“为什么框架这么重”。

十二、总结

Qlib 的学习门槛，从来不只是会不会调 API，而在于你是否愿意把量化研究真正拆成可管理的层次。数据层决定口径，模型层决定预测，策略层决定如何把预测变成组合，实验记录则把这一切绑定成可复现的研究过程。只要这张分层地图先立住，后面无论接什么模型、什么市场、什么回测规则，都能在同一套框架下清楚落位。

十三、系列衔接

本讲是《Qlib研究到交易完整学习计划》的第 1/11 讲，当前主题是《Qlib架构入门：数据层、模型层与策略层协同机制》。这是本系列的开篇，重点不是追求复杂结果，而是把后续每一讲都会反复用到的框架边界先立清楚。下一讲将进入《Qlib数据规范与特征管线：从原始行情到可训练样本》，把最容易影响研究口径的数据层进一步展开。

十四、风险揭示与免责声明