【Qlib 系列 第2讲】数据规范与特征管线：从原始行情到可训练样本

一、开篇说明

Qlib 第二讲的重点，不是再介绍框架有哪些模块，而是把第一讲里的“架构认知”往前推进一步：当一个团队准备用 Qlib 做真实研究时，原始行情、交易日历、停复权信息、标签定义、特征计算和训练样本之间，应该怎样形成一条稳定的数据链路。很多项目一开始看起来进展很快，数据能下载，特征能生成，模型也能训练，但真正进入持续迭代后，很快会遇到结果不可复现、验证表现偏高、线上表现回落、特征解释不清、样本口径来回变化等问题。它们表面上像模型问题，根本上通常是数据规范和特征管线没有先立住。

Qlib 的价值在于把研究流程工程化，但工程化并不等于把脚本放进框架里运行。真正的工程化，是每个输入都有来源，每个字段都有含义，每个时间点都有可见性边界，每个标签都能回放，每个特征都能解释，每次训练都能找到对应的数据版本和参数版本。只有做到这些，模型结果才有比较意义，后续回测、组合构建和生产衔接才不会建立在松散基础上。

这里还要先澄清一个常见误解：Qlib 不是用来替代数据治理的。它可以帮助团队组织数据、配置实验、管理训练流程，但不能自动判断某个字段是否提前泄漏，也不能自动知道某个标签是否符合交易执行逻辑。框架解决的是“流程如何组织”，数据规范解决的是“输入是否可信”。两者必须配合，不能互相替代。

本文聚焦 Qlib 数据管线的专业落地方法，不讨论收益承诺，也不把某个配置包装成固定答案。这里讨论的是一套更稳的工作方法：先把数据契约写清楚，再把标签和样本切分固化下来，然后建立特征字典、质量门禁和复盘记录。这样做的目标不是让流程显得复杂，而是减少后续反复返工，让研究结果真正可验证、可复现、可交接。

二、输入规范

Qlib 数据链路的第一步，是定义输入规范。输入规范不是简单列出“需要哪些文件”，而是明确每类数据进入系统之前必须满足什么条件。行情数据要说明价格字段口径、复权方式、成交量单位和交易日历来源；基础信息要说明证券代码是否存在历史变更、退市样本如何处理、行业分类采用哪个版本；如果接入财务或事件数据，还要说明公告时间、可见时间和生效时间之间的区别。很多泄漏并不是模型代码造成的，而是从输入层就把未来信息带进来了。

时间轴是输入规范里最重要的一部分。量化研究里，时间错位比缺失值更危险。缺失值通常能被统计出来，时间错位却可能让结果悄悄变好。比如一个字段在自然日上看属于当天，但在真实交易时点并不可见，如果直接参与当天训练或回测，就会造成隐性泄漏。Qlib 里无论是日频还是更细粒度的数据，都应该先明确“这条数据在什么时候可被模型使用”，再决定它进入哪个样本窗口。

输入规范还要包含缺失和异常处理原则。缺失值不能一概填补，停牌导致的缺失、数据接口失败导致的缺失、字段本身不适用导致的缺失，处理方式应当不同。异常值也一样，真实极端行情和数据错误必须分开。比较稳的做法是在标准化层保留异常标记，而不是只把数值修平。后续模型如果对某类被标记样本特别敏感，团队可以在复盘时看到证据，而不是只能猜测。

还要注意代码表和样本池的治理。很多研究结果不稳定，原因并不在特征，而在样本池口径变了。今天使用全市场，明天排除某些状态样本，后天又换成某个指数成分池，如果这些变化没有版本记录，模型表现变化就无法解释。Qlib 项目里应当把样本池作为正式输入，而不是在训练脚本里临时筛选。样本池的来源、纳入条件、排除条件和生效日期，都应进入配置和运行记录。

对于团队协作来说，输入规范最好形成一份可以执行的清单。每次新增数据源、修改字段口径或调整交易日历，都必须经过清单检查。清单不需要写得很繁琐，但要能回答三个问题：这类数据从哪里来，什么时候可见，进入训练前经过哪些转换。只要这三个问题稳定，后面的标签和特征才有可信基础。

三、方法框架

从原始数据到可训练样本，建议拆成四层：原始层、标准层、研究层和训练层。原始层尽量保留数据原貌，只做必要落盘和基础校验；标准层负责字段命名、单位统一、时间对齐和复权口径处理；研究层负责标签、特征、样本窗口和实验配置；训练层输出模型可以直接读取的数据集。分层的价值，是把不同职责隔开，避免所有逻辑混在一个脚本里。

原始层不能被随意覆盖。即使上游数据后来补全或更正，也应保留版本记录，否则历史实验就无法回放。标准层要承担统一口径的职责，不同研究员不应该各自写一套复权、对齐和缺失处理逻辑。研究层则允许更快迭代，但每次迭代都要留下配置和版本。训练层应尽量稳定，作为模型训练的最终输入，不再临时改字段或临时补样本。

这个分层框架还有一个好处：问题定位更快。如果模型结果异常，先看训练层样本是否变化；样本没变，再看研究层标签和特征版本；研究层没变，再回到标准层检查字段和时间轴；最后才看原始层是否有数据源变化。固定排查顺序能减少大量无效讨论，也能避免一遇到问题就直接改模型参数。

在 Qlib 项目里，配置化是这套框架的核心支撑。数据路径、交易日历、样本区间、标签窗口、特征列表、训练参数，都应该进入配置，而不是散落在脚本常量里。配置化的实际价值，是让实验具备可复制的描述方式。只要配置能完整描述一次运行，后续就能比较不同实验之间到底改了什么。

配置化还可以减少团队协作中的口径漂移。研究员调整标签窗口，工程同事调整数据路径，平台同事调整调度频率，如果这些动作分别散落在不同脚本里，最后很容易出现“大家都没改错，但组合起来不一致”的情况。把关键选择收敛到配置文件里，再配合版本记录，才能让一次实验成为可审计对象。

放到 Qlib 语境下，配置至少要覆盖五类对象：第一是数据区域，包括 provider_uri、交易日历、instruments 和样本池；第二是特征区域，包括 DataHandler 使用的 feature 表达式、processor 顺序和缺失处理方式；第三是标签区域，包括 label 表达式、预测窗口和无法交易样本处理；第四是 Dataset 区域，包括 train、valid、test 的时间切分；第五是模型与回测区域，包括模型参数、信号解释方式、组合构建器和成本设定。只要这五类对象散落在脚本里，Qlib 的可复现实验能力就会被削弱。

一个可维护的 Qlib 实验配置，不一定要复杂，但要让专业用户一眼看清楚数据如何进入模型。例如配置里应能看到使用哪个 instruments，样本区间从哪里到哪里，label 是未来几期收益还是排序目标，特征是否经过 CSRankNorm、ZScoreNorm 或缺失填补，训练集和验证集是否按时间隔离。这样后续查看 recorder 里的结果时，才知道指标来自哪一套输入，而不是只看到一个模型分数。

四、操作步骤

落地时可以按六步推进。第一步是冻结输入契约，先把行情、日历、代码表、复权方式和字段口径固定下来。不要在输入还不稳定时急着扩展特征，因为后续任何表现变化都可能来自输入变化。第二步是建立标准层，把字段命名、时间索引、缺失标记和异常标记统一处理，并保留处理日志。标准层的目标不是产生模型样本，而是产生可信的中间数据。

第三步是定义标签。标签要先于大规模特征扩展，因为标签决定模型学习目标。标签定义至少要说明预测对象、观察窗口、持有期、是否扣除成本、如何处理停牌和无法交易样本。标签一旦变化，应视为一次重要实验变更，而不是普通参数调整。第四步是构建样本切分。训练集、验证集和测试集应按时间顺序隔离，不建议在时序任务中随机打散。切分脚本应该固化，不能每次实验手写。

第五步是建立特征字典。每个特征都应记录名称、业务含义、输入字段、计算窗口、标准化方式、可见性边界、异常处理和版本状态。特征字典不是一次性文档，而是随着特征新增、修改、废弃同步更新。第六步是训练前门禁。只有当字段完整、时间对齐、标签覆盖、特征缺失率、样本数量和分布漂移都通过检查后，样本才进入训练。

这一步尤其要避免“先跑起来再说”的习惯。临时跑通一次当然容易，但如果过程没有记录，后面就无法复现。比如一个特征临时做了截尾处理，一个标签临时排除了无法成交样本，一个训练配置临时换了样本区间，只要没有进入版本记录，后续任何结论都会变得含糊。Qlib 的实验流程应当鼓励快速试验，但快速试验也需要最小记录，而不是无记录地试。

这六步看起来比直接写脚本慢，但它能避免最常见的返工。很多团队浪费时间，不是因为缺少模型，而是因为每次结果变化都不知道原因。把步骤固定下来，团队至少能判断变化来自数据、标签、特征、样本还是训练参数。定位能力本身就是效率。

五、验证与回测

验证数据管线时，不要只看模型指标。首先要验证结构是否正确：同一个样本的特征、标签和时间索引是否对齐；标签是否真的发生在特征可见时间之后；训练集和验证集之间是否存在重叠；退市、停牌、缺失等特殊样本是否按规则处理。结构验证不过关，任何模型表现都不值得讨论。

其次要做稳定性验证。同一份配置在同一份数据版本上重复运行，应该得到一致样本和一致标签。如果重复运行结果不同，要先查随机过程、缓存、排序、并行处理和依赖版本，而不是直接进入模型解释。Qlib 的实验管理能力可以帮助记录配置和结果，但前提是团队愿意把关键上下文都交给配置管理。

回测阶段还要关注研究数据和回测数据是否同源同口径。训练样本里使用的价格、回测撮合里使用的价格、成本模型里使用的价格，如果来自不同处理链路，就可能出现解释不一致。比较稳的做法，是把训练样本、预测输出、回测输入和组合构建之间的字段映射写清楚。这样当回测结果和训练指标不一致时，才能判断是模型问题、信号映射问题，还是回测口径问题。

还需要单独验证极端样本。极端样本不一定要删除，但一定要知道它们如何进入训练、如何影响标签、如何影响特征分布。真实市场里存在停牌、涨跌停、成交稀疏、复权跳变、行业分类变更等复杂情形，如果训练前完全不看这些样本，模型在回测阶段可能表现正常，但一旦进入更真实的交易约束，就会暴露问题。验证极端样本的意义不是追求完美数据，而是知道系统边界在哪里。

验证报告建议固定模板。报告不需要堆很多图，但必须包含输入版本、标签版本、特征版本、样本区间、切分方式、门禁结果、异常样本说明和本轮结论。结论要区分“流程是否可信”和“模型是否值得继续”。流程不可信时，不应该因为某个指标好看就进入下一阶段。

六、常见误区

第一个误区，是把数据能读出来等同于数据可训练。能读出来只说明格式没有问题，不说明口径、时间、缺失和标签都正确。第二个误区，是先堆特征再定义标签。这样做容易让特征工程变成无边界试错，最后很难解释模型到底学到了什么。第三个误区，是把缺失值全部统一填补。统一填补会掩盖缺失来源，使模型可能依赖本不该依赖的样本结构。

第四个误区，是样本切分随手写。一次实验一种切分方式，结果之间就失去可比性。第五个误区，是只记录模型参数，不记录数据版本和特征版本。模型参数本身不能解释结果，只有和输入、标签、特征一起记录，才构成完整证据。第六个误区，是把验证集表现当成上线依据。验证集只能说明离线环境下的拟合与泛化情况，不能替代交易成本、信号映射、组合约束和执行稳定性检查。

这些误区并不复杂，但很常见。避免它们的关键不是写更多代码，而是建立固定流程。流程一旦固定，很多错误会在进入训练前就被拦住。

七、工具落地

在工具层面，建议把 Qlib 项目拆成几个稳定目录或模块：数据准备、标准化处理、标签生成、特征生成、样本构建、实验配置、训练输出和复盘报告。每个模块都有明确输入和输出，不跨层写临时逻辑。这样做可以让团队成员更容易接手，也便于自动化调度。

日志同样重要。一次训练至少要保存运行配置、数据版本、样本摘要、门禁结果和输出路径。失败运行也要保存日志，因为失败样本往往更能暴露流程问题。很多团队只保存成功结果，导致问题出现时缺少反例材料。真正成熟的流程，应该让失败也能被复盘。

如果未来要接入生产，工具落地还要提前考虑回滚。数据版本能不能回退，特征版本能不能回退，标签脚本能不能回退，训练配置能不能回退，这些都决定了系统能否稳定运行。没有回滚能力的研究链路，一旦进入生产，就会把小问题放大成协作风险。

同时，工具落地要避免过度依赖个人命名习惯。目录命名、配置命名、特征命名、实验命名都应保持一致。命名看似细节，实际上决定检索效率。一个团队如果不能快速找到某次实验对应的数据和配置，就很难持续积累经验。Qlib 项目的长期价值，来自实验资产的沉淀，而不是某一次训练输出。

八、复盘与结语

Qlib 数据规范与特征管线的最终目标，是让研究结果成为团队资产，而不是个人脚本。团队资产有三个特点：能复现，能解释，能迁移。能复现意味着同一配置可以跑出同一结果；能解释意味着结果变化可以追到具体层级；能迁移意味着新人或其他项目可以沿用同一套方法，而不是重新摸索。

复盘时不要只写“效果提升”或“效果下降”，而要写清楚变化来自哪里。是标签口径变了，还是特征窗口变了；是样本覆盖变了，还是缺失处理变了；是模型参数变了，还是回测口径变了。只要能把这些问题说清楚，哪怕本轮结果不好，也能沉淀经验。

这一讲真正要强调的是：Qlib 的数据管线不是辅助环节，而是整个研究体系的地基。地基不稳，模型越复杂，问题越难解释；地基稳了，后续 Alpha 建模、回测模块、实验管理、多模型集成和生产衔接才会有清晰路径。把数据契约、标签、特征、门禁和复盘连接起来，Qlib 才能从一个研究框架变成可持续运行的投研基础设施。

九、风险揭示与免责声明