Qlib 的 Online/Offline 双模式与 Qlib-Server面向集中式数据管理的远程数据架构【免费下载链接】qlibQlib is an AI-oriented Quant investment platform that aims to use AI tech to empower Quant Research, from exploring ideas to implementing productions. Qlib supports diverse ML modeling paradigms, including supervised learning, market dynamics modeling, and RL, and is now equipped with https://github.com/microsoft/RD-Agent to automate RD process.项目地址: https://gitcode.com/GitHub_Trending/qli/qlib本篇基于 Qlib 官方文档docs/advanced/server.rst讲清楚 Qlib 的 Online在线与 Offline离线两种数据使用模式的设计动机、Qlib-Server 的定位并结合当前仓库源码深入剖析 Qlib 客户端如何切换到 Online 模式、数据请求在客户端与服务端之间如何流转、disk_cache等关键参数的真实含义帮助读者理解并落地一套“数据集中管理、远程访问”的量化研究数据架构。两种模式Offline 与 OnlineQlib 支持两种数据使用模式Online模式与Offline模式。官方文档中默认介绍的是Offline模式即数据放在本地由 Qlib 在本地完成表达式计算与缓存而Online模式则是为了解决以下三类实际问题引自 server.rst集中式数据管理用户不必自行管理不同版本的数据数据由中心统一维护减少缓存生成量避免每个研究节点各自生成重复的磁盘缓存支持远程访问让数据可以被远程访问而不是必须与计算任务放在同一台机器上。换言之Offline 模式适合单机研究场景当团队内多人共享一套市场数据、或计算集群与数据仓库分离时Online 模式能显著降低数据维护与缓存成本。Qlib-Server 的定位Qlib-Server 是为 Qlib 配套设计的服务器系统它利用 Qlib 本身完成基础计算并在此基础上提供了完整的服务器体系与缓存机制。通过 Qlib-Server提供给 Qlib 的数据可以以集中化的方式被管理接入 Qlib-Server 后用户即可让 Qlib 运行在 Online 模式下引自 server.rst。官方文档将 Qlib-Server 的完整实现与部署细节指向独立的 Qlib-Server 开源项目及其文档站点。当前仓库qlib 主库中保留的则是客户端一侧的接入能力Provider 抽象、Client 连接、NFS 缓存挂载与远程请求逻辑下文结合源码展开。客户端如何切换到 Online 模式qlib.init的default_conf参数切换模式的入口是qlib.init。从源码 qlib/init.py#L25 可以看到init函数的默认配置参数为default_confclient其文档说明the default value is client. Accepted values: client/server.也就是说当前仓库中qlib.init默认就以client模式启动。初始化流程中与 Online 模式相关的核心逻辑集中在provider_uri的处理上qlib/init.py#L61-L110遍历C.provider_uri中每个频率freq对应的 URI通过C.dpm.get_uri_type(provider_uri)判断其类型如果 URI 指向一个本地路径且不存在时直接报错 “Invalid provider uri ... This path does not exist”按本地模式处理如果 URI 形如 NFS 地址例如172.23.233.89//data/csdesign从源码结构看会判定为远程场景使用 client provider并调用_mount_nfs_uri自动挂载远程缓存目录。_mount_nfs_uriqlib/init.py#L87-L185实现了自动挂载逻辑对provider_uri做格式合法性校验不匹配^[a-zA-Z0-9.:/\-_]$会抛出ValueError然后执行sudo mount.nfs将远程数据目录挂载到本地路径对于带的 URI 会退化为mount -o anon若已挂载则仅告警跳过。这说明Online 模式的典型部署形态是Qlib-Server 侧将缓存目录以 NFS 方式暴露客户端在qlib.init时自动挂载后再读取缓存文件。初始化完成后data_path会为每个 freq 生成本地可用的数据 URIqlib/init.py#L83后续所有数据访问都建立在DProvider之上。Provider 体系Local 与 Client 的抽象Qlib 将数据访问统一抽象为 Provider。qlib/data/data.py 定义了如下层次节选BaseProviderqlib/data/data.py#L1140-L1190对外的统一接口暴露calendar、instruments、list_instruments、features等方法features中的disk_cache参数语义为0 表示跳过缓存、1 表示使用缓存、2 表示替换缓存见 docstringqlib/data/data.py#L1175-L1176LocalProviderqlib/data/data.py#L1193-L1221Offline 模式下的本地实现直接查询本地日历/标的/数据集缓存并能通过features_uri返回本地缓存 URIClientProviderqlib/data/data.py#L1224-L1259Online 模式下的客户端实现把请求转发给 Qlib-Server。模块末尾通过Wrapper注册全局单例Cal / Inst / FeatureD / PITD / ExpressionD / DatasetD / Dqlib/data/data.py#L1283-L1332。register_all_wrappers按配置中的calendar_provider、instrument_provider、dataset_provider、provider等字段实例化具体 Provider 并注册到对应的 Wrapper 上——Online/Offline 的差异最终就是这一组配置项指向了不同的实现类。ClientProvider 的请求模型ClientProvider的 docstring 明确了它与服务端交互的四类请求qlib/data/data.py#L1224-L1237请求类型服务端响应Calendar直接返回日历列表Instruments无过滤直接返回标的列表/字典Instruments带过滤返回标的列表/字典Features返回一个缓存 URI其工作流为客户端连接服务器并发送请求后进入等待服务端会即时回应“缓存是否可用”客户端只在收到feature_available为 true 的响应后才结束等待。docstring 中还标注了一个已知限制BUG 注释当前每次请求都需要重新建立连接、等待并断开无法在同一条连接内连续发送多个请求底层通信可参考 python-socketIO 客户端文档原文如此从源码注释推断其通信框架为 socketIO 风格。ClientProvider.__init__的构造过程印证了这一点qlib/data/data.py#L1239-L1259它创建Client(C.flask_server, C.flask_port)即连接到 Qlib-Server 侧的 Flask 服务地址再依次对Cal、Inst、DatasetD调用set_conn(self.client)把 socket 连接注入到对应的 Client 侧 Provider 中。三类 Client 侧 Provider 的实现细节ClientInstrumentProvider标的信息远程查询ClientInstrumentProviderqlib/data/data.py#L985-L1024的list_instruments方法通过self.conn.send_request(request_typeinstrument, ...)把 instruments、起止时间、频率、as_list等参数发给服务端并通过msg_proc_func把响应中的时间区间统一转换为pd.Timestamp对最后从队列中取结果超时时间为配置项C[timeout]若结果本身是异常对象则直接抛出。ClientDatasetProvider特征数据的两条取数路径ClientDatasetProvider.datasetqlib/data/data.py#L1040-L1137是 Online 模式取特征数据的核心按disk_cache参数分为两条路径disk_cache 0跳过数据集缓存向服务端发送request_typefeature请求disk_cache: 0服务端生成表达式缓存并返回 URI客户端直接从表达式缓存读取数据源码注释注明此路径默认使用多核multi-kernel方式计算disk_cache ! 0使用数据集缓存同样发送request_typefeature请求disk_cache: 1服务端生成数据集缓存并返回 URI随后客户端通过C.dpm.get_data_uri(freq)拼接出本地挂载路径mnt_feature_uri注释标注该 NFS 挂载用于 demo再用DiskDatasetCache.read_data_from_cache(mnt_feature_uri, start_time, end_time, fields)直接从挂载的文件系统读取并切片数据。从源码结构看这正是文档所述“减少缓存生成、远程访问”的落地方式计算由服务端集中完成并落盘客户端只负责挂载 按 URI 读取本地不再重复生成数据集缓存。另外两点值得注意若传入 dict 形式的 instruments股票池配置会告警“从 dict of instruments 获取特征不推荐因为特征不会被缓存股票池每天会被清理”qlib/data/data.py#L1051-L1056若读取失败AttributeError例如dpm未配置会包装为IOError(Unable to fetch instruments from remote server!)抛出qlib/data/data.py#L1136-L1137。features_uri让服务端拿到缓存位置服务端需要知道请求对应的缓存 URI 由谁决定、如何拼接。LocalProvider.features_uriqlib/data/data.py#L1209-L1221返回DatasetD._dataset_uri(...)而DatasetD._dataset_uri的静态实现DiskDatasetCache._uri(...)的 docstring 明确写道Get task uri, used when generating rabbitmq task in qlib_server qlib/data/data.py#L489结合参数说明instruments、fields、起止时间、freq、disk_cache、inst_processors从源码结构可以推断 Qlib-Server 侧通过 RabbitMQ 分发数据计算任务而 URI 是任务之间定位缓存产物的“地址”。已知限制inst_processors 暂不受支持使用 Online 模式时有一个明确的限制ClientDatasetProvider在使用数据集缓存disk_cache ! 0路径时不支持inst_processorsqlib/data/data.py#L1104-L1110。源码中同时存在两处TODO: qlib-server support inst_processors/need to change the code of qlib-server at the same timeqlib/data/data.py#L507、qlib/data/data.py#L1104说明该能力需要 Qlib-Server 侧同步改造。若实际传入了inst_processors客户端会直接抛出ValueError并给出替代方案提示改用D.features(disk_cache0)或qlib.init(dataset_cacheNone)。小结与实践建议单机研究使用默认 Offline 模式即可数据与缓存都在本地团队共享数据 / 计算与存储分离部署 Qlib-Server客户端通过qlib.init的provider_uri指向远程数据源。若为 NFS 地址客户端会自动执行mount.nfs挂载缓存目录qlib/init.py#L87-L185理解取数链路请求经由ClientProvider→ClientInstrumentProvider/ClientDatasetProvider发往服务端qlib/data/data.py#L1224-L1259disk_cache0走表达式缓存disk_cache1/2走服务端生成的数据集缓存 URI 再本地读取注意限制Online 模式暂不支持inst_processors且当前每次请求需独立建连批量请求场景需自行规划。Qlib-Server 的部署、运维与更多服务端能力请参考 Qlib-Server 官方开源项目及其文档站点当前 qlib 主仓库文档 server.rst 的 Reference 一节即指向该外部项目。【免费下载链接】qlibQlib is an AI-oriented Quant investment platform that aims to use AI tech to empower Quant Research, from exploring ideas to implementing productions. Qlib supports diverse ML modeling paradigms, including supervised learning, market dynamics modeling, and RL, and is now equipped with https://github.com/microsoft/RD-Agent to automate RD process.项目地址: https://gitcode.com/GitHub_Trending/qli/qlib创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考