LumiBot / 数据源与路由
LumiBot 的行情从哪里来：25 个数据源模块、6 个路由键与三套复权口径
LumiBot 回测出来的曲线，取决于它读了谁的数据。官方仓库 lumibot/data_sources/ 下有 27 个文件（去掉 __init__.py 与 exceptions.py 后是 25 个数据源模块），lumibot/backtesting/ 下有 16 个回测类模块；两者不是一一对应，也不等于「你能拿到的数据商品数量」。
与「换一个数据源只改一个 import」的直觉不同，LumiBot 提供的是按资产类别路由：环境变量 BACKTESTING_DATA_SOURCE 既可以填一个值（yahoo / thetadata / polygon / ibkr / polymarket），也可以填一段 JSON，把股票、期权、加密、加密期货、期货、连续期货分别指向不同的 provider。这是它比较独有的写法。
还有三处口径差会直接改变回测结论：① Yahoo 有分红调整，Alpaca / Polygon / Tradier 没有；② 宏观数据只能走 ALFRED 的 point-in-time，官方明确不用公开 CSV 回退；③ ThetaData 是可选依赖，但包里塞着一个 39 MB 的 jar。
- 仓库：Lumiwealth/lumibot，默认分支
dev（HEAD28afefe8，2026-09-18） - PyPI：
lumibot 4.5.91，wheel 37,810,900 字节（本机解包实测 231 个条目） - 打包方式：
setup.py，extra_requires只有thetadata一项 - 采集日期 2026-09-22；本站未连接任何数据源账号，未实盘下单
读取路径
数据来源 → 路由键 → 回测引擎（示意）
BACKTESTING_DATA_SOURCE 说明，2026-09-22 采集）。示意图仅重述出处事实；可用性以你的账号与官方文档为准。三类来源：免费的、券商自带的、要花钱的，还有你自己的文件
先把「数据从哪来」分成四类，再谈怎么配。这四类的前置条件完全不同——免费源不需要账号，券商源要求你已经连上券商，付费源要订阅，自有文件要自己保证格式正确。
| 来源类别 | 代表实现 | 覆盖资产 | 要不要账号或订阅 | 适用场景 | 注意点 |
|---|---|---|---|---|---|
| 免费公共源 | yahoo（YahooDataBacktesting）、alpha_vantage | 美股与部分指数、外汇、加密的日线与部分分钟线 | 不需要账号 | 第一次跑通回测、做日线级别的策略验证 | 字段能力有限；日线粒度为主，做分钟级或期权回测会不够用 |
| 券商自带历史 | alpaca、tradier、schwab、interactive_brokers_rest、projectx、tradovate | 与你在该券商的授权标的范围一致 | 要有券商账户与 API 凭据 | 让回测数据与实盘数据来自同一家券商，减少口径差 | 「能连券商」与「能拉历史」是两件事；部分券商的历史深度受权限与合约限制 |
| 付费专业源 | thetadata、polygon、databento | 股票、期权链与期权历史、期货、加密等 | 要订阅；部分需要单独申请 | 期权、期货、细粒度或长历史的严谨回测 | 官方把 ThetaData 列为可选 extras；未订阅时相关模块存在但拉不到数据 |
| 预测合约历史 | polymarket（PolymarketBacktesting） | Polymarket 预测合约价格历史 | 回测历史价格不需要私钥；真实下单另有一套凭据 | 研究预测市场类策略 | 这类数据不是传统 OHLCV，官方对照表里该行的除权/分红列均为 N/A |
| 加密交易所 | ccxt（CcxtBacktesting） | 官方回测示例覆盖 Kraken、Binance、KuCoin、BitMEX、Bybit、OKX | 多数公开历史不需要密钥；私有接口需要 | 加密现货与部分衍生品的回测 | 官方明确不承诺覆盖全部 CCXT 交易所；这 6 家是「有回测示例」，不等于「全部支持」 |
| 自有文件 | pandas（CSV，Yahoo dataframe 格式）、polars | 由你的文件决定 | 不需要账号 | 离线复现、公司内部数据、把外部数据接进来 | 列名与索引必须符合官方约定；格式不对时不会报「列名错」而是给出更含糊的失败 |
| 宏观与基本面 | FRED（内置 agent 工具）、SEC（内置 agent 工具） | 宏观序列、公司基本面与文件 | FRED 要 FRED_API_KEY；SEC 走官方接口带 User-Agent | 给 agent 做宏观与基本面研究 | 不属回测行情通道；FRED 用 ALFRED 的 point-in-time 口径，见下文第 5 节 |
export BACKTESTING_DATA_SOURCE=thetadata # or yahoo, ibkr, polygon, polymarket 只是示例。真正决定成败的不是这句注释，而是你有没有那个 provider 的访问权限。本站未连接任何数据源账号，因此本页只陈述「代码里实现了什么」，不声称任何数据源在你机器上可用。代码里到底实现了几条通道
下面两份清单来自本机对仓库 /contents/ 接口的逐项清点（2026-09-22）。模块存在 ≠ 你有权限：付费源没订阅、券商源没授权，模块照样在，只是拿不到数据。
数据源目录：27 个文件 / 25 个模块
包含 data_source.py 基类、exceptions.py，以及同一数据商的多条实现（如 databento_data 与 databento_data_pandas、databento_data_polars）。把 pandas / polars 两条实现数成两个数据商，是最常见的口径误读。
回测目录：17 项 / 16 个回测类
除各 provider 对应的回测类外，还有 routed_backtesting（按路由键分派）、backtesting_broker（回测券商模拟）、data_provenance（数据出处信息）、thetadata_backtesting_pandas 这类变体。真正跨源分派的入口是 routed。
| 类别 | 模块清单（逐项） | 适用场景 | 注意点 |
|---|---|---|---|
| 免费公共源 | yahoo_data、yahoo_data_polars、alpha_vantage_data | 日线策略快速验证 | Yahoo 有分红口径，别的源可能没有，见第 4 节 |
| 券商行情 | alpaca_data、interactive_brokers_data、interactive_brokers_rest_data、ibkr_gateway、tradier_data、schwab_data、tradovate_data、projectx_data、bitunix_data | 回测数据与实盘同源 | IBKR 有两条独立路径（常规与 REST 网关），别当成同一家两种写法 |
| 付费专业源 | databento_data、databento_data_pandas、databento_data_polars、polygon_data_polars | 期权、期货、细粒度历史 | pandas 与 polars 是同一数据商的两条实现 |
| 预测与加密 | polymarket_data、ccxt_data、ccxt_backtesting_data | 预测合约、加密现货与衍生品 | CCXT 的交易所范围要按官方那几组名单核对 |
| 自有文件 | pandas_data、polars_data、polars_mixin | 离线复现与内部数据 | polars_mixin 是共用混入类，不是一个数据源 |
| 基础设施 | data_source（基类）、data_source_backtesting、exceptions、example_broker_data | 开发者扩展自己的数据源 | example_broker_data 是给开发者抄的模板，不是真实数据商 |
| 回测模块 | 说明 | 适用场景 | 注意点 |
|---|---|---|---|
routed_backtesting | 按 BACKTESTING_DATA_SOURCE 的 JSON 把请求分派到不同 provider | 混合资产组合（股票 + 期权 + 期货） | 不用路由就不要开它；单值配置更简单也更好排查 |
data_provenance | 记录数据的出处信息 | 需要写清「这条曲线来自谁」的研究 | 它管的是记录，不是取数 |
backtesting_broker | 回测环境下的券商替身：撮合、持仓、现金 | 所有回测都会经过它 | 它模拟的是券商行为，不是真实券商；真实行为差异见券商矩阵页 |
| 股票与期权回测类 | yahoo_backtesting、polygon_backtesting、thetadata_backtesting、thetadata_backtesting_pandas、alpaca_backtesting、alpha_vantage_backtesting、ibkr_rest_backtesting、pandas_backtesting | 标的为股票、ETF 或期权 | 带 _pandas 的是同一 provider 的实现变体，不是新数据商 |
| 期货与加密回测类 | databento_backtesting（含 pandas / polars）、ccxt_backtesting | 期货、连续期货、加密现货与衍生品 | 期货还有到期与换月问题，与现货回测不是同一套假设 |
| 预测合约回测类 | polymarket_backtesting | Polymarket 预测合约 | 数据形态不是传统 OHLCV，除权与分红列在官方对照表里为 N/A |
| 怎么选 | 先看你要回测的资产类别，再反查哪几个回测类覆盖它 | 避免「先选 provider 再发现缺资产」 | 拿不准时先用免费源跑通一套最小回测，确认流程再换源 |
BACKTESTING_DATA_SOURCE 怎么写：单值与多 provider
这是 LumiBot 在数据层比较独有的地方。单值时所有资产都走同一个 provider；填 JSON 时可以按资产类别分开指定，键一共 6 个。下面两段是官方 README 的原样写法。
# 写法一：单值，所有资产走同一个数据源 export BACKTESTING_DATA_SOURCE=yahoo export BACKTESTING_DATA_SOURCE=thetadata # 官方注释里给的其他取值：yahoo, ibkr, polygon, polymarket # 写法二：JSON 多 provider 路由（官方 README 例子） export BACKTESTING_DATA_SOURCE='{"default":"thetadata","option":"thetadata","crypto":"ibkr","crypto_future":"ibkr","future":"ibkr","cont_future":"ibkr"}'
| 路由键 | 管什么 | 什么时候必须单独设 | 注意点 |
|---|---|---|---|
default | 没被其它键命中的资产类型都走它 | 几乎总是要设，它是兜底 | 只填这一个等于回到「单值」模式；少了它，未覆盖的资产类型可能没有数据源可走 |
option | 期权链与期权历史 | 期权回测几乎必然需要 | 不是所有 provider 都有期权历史；官方推荐付费源覆盖这块 |
crypto | 加密现货 | 股票源不支持加密时 | 常见组合是股票走付费源、加密走券商或 CCXT |
crypto_future | 加密永续/期货 | 做加密衍生品时 | 可路由到现货历史，但报价符号必须被保留，见本页第 5 节 |
future | 期货合约 | 做期货回测时 | 期货还有到期与换月问题，需另看官方的换月策略文档 |
cont_future | 连续期货序列 | 需要跨合约连续价格时 | 连续合约是构造出来的序列，与单合约价格不同，别混用 |
拼一段 BACKTESTING_DATA_SOURCE
选择每个路由键要用的数据源，下方实时生成可直接粘贴的 shell 变量。取值全部来自官方 README 与仓库模块名。
{}
这个工具只做字符串拼接。它不检测你的账号、不验证数据源可用性、不检查你的 Python 环境，也不代表官方配置建议。生成的字符串请自行核对键名与取值，并以官方 README 与文档为准。若某个键留空，它不会出现在输出里，表示该资产类型跟随 default。
为什么同一只票，两条曲线的收益不一样
官方 README 里有一张「Data source comparison」表，把 OHLCV、除权调整、分红、分红调整收益四列分别标了出来。这张表是本站认为最容易被跳过、却最影响结论的一页内容。
| 数据源 | OHLCV | 除权调整 | 分红 | 分红调整收益 | 对策略的影响 | 注意点 |
|---|---|---|---|---|---|---|
| Yahoo | 有 | 有 | 有 | 有 | 长期持有类策略的收益计算更接近含息口径 | 免费源里字段最全的一档，但数据质量与覆盖范围有限 |
| Alpaca | 有 | 有 | 无 | 无 | 高股息标的的持有收益会被低估 | 适合把回测数据与 Alpaca 实盘对齐的场景 |
| Polygon | 有 | 有 | 无 | 无 | 同上；跨年回测的累计收益会系统性偏低 | 付费源，覆盖范围比 Yahoo 广 |
| Tradier | 有 | 有 | 无 | 无 | 同上 | 券商源，与你的账户权限相关 |
| Polymarket | 有 | N/A | N/A | N/A | 预测合约没有除权与分红概念 | 数据形态与股票不同，别拿同一套假设套用 |
| Pandas / CSV | 有 | 有 | 有 | 有 | 取决于你的文件本身；官方要求 Yahoo dataframe 格式 | 「有分红列」不等于「你已经填对了分红列」 |
| 同一标的、换数据源 | — | — | — | — | 分红口径不同会导致同一策略的收益与回撤同时变化 | 换数据源后要重跑基准对照，别把差异归因于策略改动 |
被忽略的三个细节：报价符号、宏观修订值、39 MB 的 jar
这三条都不在「快速开始」里，但都会影响结论是否能复现。
| 口径 | 规则 | 为什么重要 | 注意点 |
|---|---|---|---|
| 加密期货报价符号 | 不得把请求的 USDT / USDC / EUR 报价静默替换成 USD；缺失时应「fail honestly」，或在策略代码里显式改成别的报价 | 稳定币之间不是 1:1，静默替换会让回测与实盘的成交价口径不一致 | 官方原文强调这是不变量（invariant），即框架层面承诺不做这件事 |
| 宏观数据口径 | 内置 FRED 工具要求 FRED_API_KEY，并请求 ALFRED 的 realtime_start / realtime_end | 宏观序列会被修订：今天的 GDP 快照与当年公布的初值不是同一个数，用修订后数据回测宏观策略等于偷看未来 | 官方明确不使用公开 CSV 回退，理由就是公开端点可能含修订值 |
| ThetaData 依赖形态 | extras_require 只有 thetadata 一项；仓库内 lumibot/resources/ThetaTerminal.jar 为 39,187,662 字节（≈39 MB） | 本机实测：这个 jar 确实在 PyPI 的 wheel 里（37,810,900 字节，231 个条目） | 是否需要本机 Java 运行时，本站未实测，不做结论；setup.py 只在 jar 存在时打包，并打印 "ThetaData is optional" |
| 批量取价上限 | agent 工具 market_last_prices 单次 symbols 上限 150；market_load_history_table 每次只加载一个 symbol | 扫描一个较大的股票池时，超限或漏 symbol 会得到不完整的结果却不一定报错 | 官方要求：对缺失的 symbol 不要编造价格，要用返回的可用/缺失清单判断 |
| 时框元数据 | 存储的时框元数据必须与请求一致；缺分钟序列时不能拿日线存储冒充分钟输出 | 否则你会以为在跑分钟策略，实际用的是日线 | 取不到就应当保持不可用，而不是换一个粒度顶上 |
| 窗口与 warmup | 独立 start/end 窗口是闭区间、必须带显式时区偏移、且拒绝越过策略时间的 end；计算不借用其它月/年的预热数据 | 借用预热数据会引入未来信息，这与指标时间安全是同一类问题 | 详见未来函数与时间安全 |
取不到数据时，按这个顺序查
下面这些是回测取数环节最常出现的现象。顺序建议是：先确认 provider 与权限，再确认资产类型路由，最后才是格式与粒度。
| 现象 | 可能原因 | 怎么确认 | 注意点 |
|---|---|---|---|
| 回测一开就取不到任何数据 | provider 没设、设了但没订阅、或凭据缺失 | 先看 BACKTESTING_DATA_SOURCE 的当前值，再确认对应 provider 的账号状态 | 模块存在不代表能取数；付费源的模块在未订阅时同样存在 |
| 股票能取、期权取不到 | 该 provider 没有期权历史，或路由里 option 键没设 | 核对 option 键是否指向支持期权的 provider | 官方推荐付费源覆盖期权历史；免费源一般不具备 |
| 加密期货价格看起来不对 | 报价被替换，或路由把 crypto_future 指到了不带该交易对的源 | 确认交易对是否存在；框架不应静默把 USDT 换成 USD | 缺失时应显式失败或在策略里显式改报价，不要靠猜 |
| 自有 CSV 加载失败或列错位 | 列名、索引或格式不符合官方约定的 Yahoo dataframe 格式 | 对照官方示例文件的列结构，逐列核对 | 格式问题常常表现为含糊的失败，不是「列名错」这种明确报错 |
| 批量扫描时结果不全 | 超过了单次 symbols 上限（150），或部分 symbol 不在数据源覆盖内 | 看返回的可用/缺失清单，而不是只看长度 | 不要为缺失的 symbol 编造价格；缩小池子或换源 |
| 日线策略跑出了分钟级频率的表现 | 时框元数据与请求不一致，或拿日线存储冒充分钟输出 | 核对请求的 timestep 与实际数据的时框 | 取不到就该保持不可用，不要用别的粒度顶替 |
| 跨日/跨周收益出现莫名跳变 | 时区偏移没写、或窗口 end 越过了策略时间 | 检查窗口是否带显式时区偏移，end 是否被框架拒绝 | 等价时区应被视为同一窗口，且不应改动策略时钟 |
关于 LumiBot 数据源的高频问题
以下回答基于 2026-09-22 对官方仓库目录、README 与仓库内工程文档的核对；具体行为以官方实现与你的账号权限为准。本站未连接任何数据源账号，不做收益声明。
LumiBot 自带数据吗？还是要我自己买？
它不提供自有行情商品，而是适配层：免费源（Yahoo、Alpha Vantage）可以开箱用日线；券商源要用你自己的券商凭据；付费源（ThetaData、Polygon、DataBento）要自己订阅；也可以直接喂自己的 CSV / Parquet。所以「LumiBot 能免费回测吗」的答案是：能，但只在你接受免费源的数据范围与字段能力时成立。具体覆盖以各数据源官方说明为准。
BACKTESTING_DATA_SOURCE 到底填一个值还是填 JSON？
两种都合法。只回测一类资产时填一个值最简单；混合资产（例如股票 + 期权，或股票 + 加密）时才需要用 JSON 把 default / option / crypto / crypto_future / future / cont_future 分别指向不同 provider。排查成本会随路由复杂度上升，建议先跑通单值再拆开。上文第 3 节有一个只做字符串拼接的生成器，可用于对照键名。
为什么同一个策略换数据源后收益差很多？
最常见的原因是分红与除权口径不同。官方对照表显示：Yahoo 同时提供除权调整、分红与分红调整收益；Alpaca / Polygon / Tradier 只有除权调整、没有分红；Polymarket 这几列都是 N/A。高股息标的的长期持有策略，在这三类数据源上的累计收益本来就会不同。换源后请重跑基准对照，不要把这部分差异当成策略改动带来的。
我能用公开 CSV 拿宏观数据吗？
官方在 agent 工具文档里给了明确态度：内置 FRED 工具要求 FRED_API_KEY，并请求 ALFRED 的 realtime_start / realtime_end，不使用公开 CSV 回退——因为公开端点可能包含修订后的值，而修订值不是当时能看到的信息。对宏观策略回测而言，这属于未来信息泄漏的一种。你当然可以自己用任何数据，但如果结论要用来说明「当时能做出什么判断」，就要用 point-in-time 版本。
ThetaData 是必需的吗？包里那个 39 MB 的文件是什么？
ThetaData 是可选依赖：setup.py 的 extra_requires 只有 thetadata 一项，并在打包时打印 "ThetaData is optional"。仓库内另有一个 lumibot/resources/ThetaTerminal.jar，大小 39,187,662 字节。本机实测：PyPI 4.5.91 的 wheel（37,810,900 字节）里确实带着这个 jar。是否需要本机 Java 运行时，本站未实测，因此不做结论。
它支持 A 股行情吗？
按本站核到的证据，仓库里没有 A 股数据源实现，数据源与券商模块都围绕美股、期权、期货、外汇、加密与预测合约组织。如果你的目标市场是 A 股，需要换工具组合；本站对比页说明了另一条路线的能力与边界，但不代表两者可以互相替代。详情以官方文档为准。
数据源模块这么多，我该怎么选？
按三件事决定：①你要回测的资产类别（期权、期货往往只能走付费源）；②回测数据是否要和实盘同源（同源能减少口径差，但受券商历史深度限制）；③你是否需要分红与除权口径完整。建议顺序：先用免费源验证策略逻辑，确认值得投入后再换付费源复算一遍，并对比两次结果差异。具体字段能力以官方对照表与各数据源文档为准。