市场数据源¶

📎 引用文件

本文引用的文件 - agent/backtest/loaders/registry.py - agent/backtest/loaders/base.py - agent/src/market_data.py - agent/backtest/loaders/yahoo_loader.py - agent/backtest/loaders/yahoo_client.py - agent/backtest/loaders/tushare.py - agent/backtest/loaders/eastmoney_loader.py - agent/backtest/loaders/eastmoney_client.py - agent/backtest/loaders/ccxt_loader.py - agent/backtest/loaders/binance_loader.py - agent/backtest/loaders/cn_adjust.py - agent/src/config/env_schema.py

简介¶

本文件为 Vibe-Trading 的市场数据源集成提供综合文档，覆盖 Yahoo Finance、Tushare、Binance、CCXT、东方财富等主流数据源的接入方式、API 特性与配置项；说明各数据源的数据格式差异、时区处理与复权因子计算；描述数据获取策略、频率限制与错误恢复机制；并给出多市场同步的最佳实践（一致性保证与增量更新）、常见问题诊断方法与性能调优技巧。

项目结构¶

Vibe-Trading 将“数据源加载器”抽象为统一接口，并通过注册表与回退链实现跨市场的自动选择与容错。关键路径： - 统一入口与路由：market_data.fetch_market_data - 加载器注册与回退：loaders.registry - 通用能力：重试/预算/缓存/校验：loaders.base - 具体数据源：yahoo_loader、tushare、eastmoney_loader、ccxt_loader、binance_loader - 客户端层：yahoo_client、eastmoney_client - 复权因子：cn_adjust - 配置中心：env_schema（环境变量与默认值）

graph TB A["调用方 fetch_market_data"] --> B["路由与分组 detect_source/_detect_market"] B --> C["回退链选择 FALLBACK_CHAINS"] C --> D["加载器实例化 get_loader_cls_with_fallback"] D --> E["Yahoo 加载器 yahoo_loader"] D --> F["Tushare 加载器 tushare"] D --> G["东方财富加载器 eastmoney_loader"] D --> H["CCXT 加载器 ccxt_loader"] D --> I["Binance 专用加载器 binance_loader"] E --> J["Yahoo 客户端 yahoo_client"] G --> K["东方财富客户端 eastmoney_client"] F --> L["A股复权因子 cn_adjust"]

图表来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/registry.py:136-193 - agent/backtest/loaders/yahoo_loader.py:173-271 - agent/backtest/loaders/tushare.py:116-202 - agent/backtest/loaders/eastmoney_loader.py:51-143 - agent/backtest/loaders/ccxt_loader.py:184-308 - agent/backtest/loaders/binance_loader.py:23-44

章节来源 - agent/src/market_data.py:16-63 - agent/backtest/loaders/registry.py:23-155

核心组件¶

DataLoaderProtocol：定义统一的 fetch 接口与元信息（name/markets/requires_auth），所有数据源必须实现 is_available 与 fetch。
注册表与回退链：按市场类型维护有序的回退顺序，优先使用对 IP 封禁更友好的公开端点，再降级到密钥型 REST。
通用工具：日期校验、OHLC 不变量校验、带预算的重试、本地 Parquet 缓存、JSON 安全序列化。
市场路由：根据符号后缀与模式匹配推断首选数据源，并在不可用时沿回退链尝试。

章节来源 - agent/backtest/loaders/base.py:27-119 - agent/backtest/loaders/base.py:163-236 - agent/backtest/loaders/base.py:243-439 - agent/backtest/loaders/registry.py:136-193 - agent/src/market_data.py:16-63

架构总览¶

下图展示从请求到数据返回的端到端流程，包括自动路由、回退链、加载器执行与客户端访问。

sequenceDiagram participant U as "调用方" participant M as "market_data.fetch_market_data" participant R as "registry.resolve_loader" participant L as "具体Loader" participant C as "客户端(如yahoo_client/eastmoney_client)" participant S as "外部服务(Yahoo/Tushare/Eastmoney/CCXT)" U->>M : 传入 codes/start/end/source/interval M->>M : detect_source + _detect_market M->>R : get_loader_cls_with_fallback(source) R-->>M : Loader类或抛出NoAvailableSourceError M->>L : loader.fetch(codes, start, end, interval) L->>C : 调用客户端拉取K线/行情 C->>S : HTTP/REST 请求(受节流/代理/超时保护) S-->>C : 原始数据(JSON/CSV) C-->>L : 标准化行/列 L-->>M : {symbol : DataFrame} M-->>U : JSON安全结果(含_provenance可选)

图表来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/registry.py:158-193 - agent/backtest/loaders/yahoo_client.py:156-205 - agent/backtest/loaders/eastmoney_client.py:269-324 - agent/backtest/loaders/ccxt_loader.py:426-501

详细组件分析¶

Yahoo Finance（yahoo_loader + yahoo_client）¶

适用市场：美股、港股、印度、加拿大、期货/外汇后缀约定
认证：无需认证，通过共享节流会话降低 IP 限流风险
时间粒度映射：1D/1H/4H→1h/1W/1M 等；分钟/小时保持真实时间戳，日及以上归一至午夜
时区处理：交易时间为 UTC 秒级时间戳，转为无时区 DatetimeIndex；非日内区间归一化对齐
数据格式：open/high/low/close/volume，缺失字段补齐或丢弃无效条
客户端特性：v8 chart 端点；quoteSummary/options 需要 cookie+crumb 握手，401 自动刷新并重试一次
缓存：支持 opt-in 本地 parquet 缓存，键包含 source/symbol/timeframe/date range/fields

flowchart TD Start(["进入 Yahoo 加载器"]) --> CheckSupported{"是否支持的代码?"} CheckSupported -- 否 --> ReturnNone["返回空/跳过"] CheckSupported -- 是 --> MapInterval["映射 interval"] MapInterval --> FetchChart["调用 yahoo_client.get_chart"] FetchChart --> ParseRows["解析为 OHLCV 行"] ParseRows --> Normalize["转 DatetimeIndex 并归一化(非日内)"] Normalize --> Clip["裁剪到[start,end]闭区间"] Clip --> CachePut{"可缓存?"} CachePut -- 是 --> Put["写入本地 parquet"] CachePut -- 否 --> Done["返回 DataFrame"] Put --> Done

图表来源 - agent/backtest/loaders/yahoo_loader.py:44-73 - agent/backtest/loaders/yahoo_loader.py:125-170 - agent/backtest/loaders/yahoo_client.py:156-205 - agent/backtest/loaders/base.py:301-439

章节来源 - agent/backtest/loaders/yahoo_loader.py:173-271 - agent/backtest/loaders/yahoo_client.py:71-93 - agent/backtest/loaders/yahoo_client.py:95-153

Tushare（A股/港股/基金/指数）¶

适用市场：A股、港股、期货、基金；分钟级需积分门槛
认证：需要 TUSHARE_TOKEN
数据格式：daily/fund_daily/index_daily/hk_daily；分钟级 stk_mins
复权因子：A股/基金使用前复权（qfq），指数与港股不调整
频率限制：识别配额拒绝关键词，采用固定间隔重试（约65秒内完成三次）
基本面字段：可按 fields 合并 daily_basic 指标（仅股票）

flowchart TD S(["开始"]) --> Type{"代码类型"} Type -- 指数/ETF/港股/美股权/加密 --> SkipAdj["跳过复权或跳过"] Type -- A股/基金 --> FetchDaily["拉取日线"] FetchDaily --> AdjFactor["拉取 adj_factor"] AdjFactor --> QFQ["apply_qfq 前复权"] QFQ --> MergeBasic{"是否请求基本面?"} MergeBasic -- 是 --> Merge["合并 daily_basic 字段"] MergeBasic -- 否 --> Done["返回DataFrame"] Merge --> Done SkipAdj --> Done

图表来源 - agent/backtest/loaders/tushare.py:204-265 - agent/backtest/loaders/cn_adjust.py:27-78 - agent/backtest/loaders/tushare.py:51-79

章节来源 - agent/backtest/loaders/tushare.py:116-202 - agent/backtest/loaders/tushare.py:322-382 - agent/backtest/loaders/cn_adjust.py:1-78

东方财富（Eastmoney）¶

适用市场：A股、港股、美股（通过搜索发现市场前缀并缓存）
认证：无需认证，但严格 IP 限流，统一走节流客户端
数据格式：push2his kline；secid 地址方案（A股/港股/美股）
时间粒度：1D/1W/1M/1m/5m/15m/30m/1H/60m
复权：fqt=1 表示前复权（客户端参数）

flowchart TD A["输入代码"] --> Resolve["resolve_secid(按后缀/A股/港股/美股搜索)"] Resolve --> KLT{"是否支持的时间粒度?"} KLT -- 否 --> None["返回空"] KLT -- 是 --> Fetch["fetch_kline(secid,klt,fqt,beg,end)"] Fetch --> Frame["_frame_from_rows 构建OHLCV"] Frame --> Out["返回DataFrame"]

图表来源 - agent/backtest/loaders/eastmoney_client.py:208-236 - agent/backtest/loaders/eastmoney_client.py:269-324 - agent/backtest/loaders/eastmoney_loader.py:112-143

章节来源 - agent/backtest/loaders/eastmoney_loader.py:51-143 - agent/backtest/loaders/eastmoney_client.py:1-325

CCXT（加密货币通用）¶

适用市场：加密货币现货与合约（USD-M 永续）
认证：公共数据无需 API Key；合约保证金档位需外部 artifact
数据格式：OHLCV；永续额外包含 mark price、资金费率、结算时间
分页与预算：每页 limit=1000，设置 CCXT_TIMEOUT_MS 与 CCXT_FETCH_BUDGET_S 控制超时与总预算
代理：支持 ALL_PROXY/HTTP_PROXY/HTTPS_PROXY
符号解析：BASE-USDT-PERP → swap；否则 spot

sequenceDiagram participant L as "CCXT DataLoader" participant X as "Exchange(由CCXT创建)" participant P as "分页拉取" L->>X : fetch_ohlcv(symbol,timeframe,since,limit) loop 直到结束或达到预算 P->>X : 下一页(since=last_ts+1) X-->>P : OHLCV 列表 end P-->>L : 合并后的DataFrame Note over L,P : 若为永续则追加mark价格与资金费率

图表来源 - agent/backtest/loaders/ccxt_loader.py:226-308 - agent/backtest/loaders/ccxt_loader.py:426-501 - agent/backtest/loaders/ccxt_loader.py:310-372

章节来源 - agent/backtest/loaders/ccxt_loader.py:184-308 - agent/backtest/loaders/ccxt_loader.py:374-424

Binance（专用 CCXT 封装）¶

作用：在加密回退链中作为独立源与 OKX 并列，避免被单一源耗尽
行为：强制使用 binance/binanceusdm，继承 CCXT 的速率限制与代理配置

章节来源 - agent/backtest/loaders/binance_loader.py:1-45

数据格式与时区处理要点¶

统一输出：trade_date 索引 + open/high/low/close/volume 数值列
Yahoo：UTC 秒级时间戳转无时区；非日内归一至午夜对齐
Eastmoney：字符串日期转 datetime；支持 fqt 前复权
Tushare：A股/基金使用前复权；指数/港股不调整；分钟级无复权
CCXT：毫秒时间戳转 datetime；永续附加 mark/funding 列

章节来源 - agent/backtest/loaders/yahoo_loader.py:125-170 - agent/backtest/loaders/eastmoney_loader.py:145-177 - agent/backtest/loaders/tushare.py:204-265 - agent/backtest/loaders/ccxt_loader.py:426-501

依赖关系分析¶

路由依赖：market_data.detect_source 决定首选源；_detect_market 决定回退链
回退链：按市场类型排序，优先低封禁风险源（如腾讯/Yahoo/Eastmoney），再落到密钥型（Tushare/Finnhub/AlphaVantage/Tiingo/FMP）
加载器耦合：Binance 复用 CCXT；Yahoo/Eastmoney 各自客户端；Tushare 依赖 cn_adjust
配置依赖：DataConfig 集中管理各类 Token/超时/预算/代理开关

graph LR MD["market_data"] --> REG["registry.FALLBACK_CHAINS"] MD --> SRC["detect_source"] REG --> YAH["yahoo_loader"] REG --> TS["tushare"] REG --> EM["eastmoney_loader"] REG --> CC["ccxt_loader"] CC --> BIN["binance_loader"] YAH --> YC["yahoo_client"] EM --> EC["eastmoney_client"] TS --> ADJ["cn_adjust"]

图表来源 - agent/src/market_data.py:16-63 - agent/backtest/loaders/registry.py:136-155 - agent/backtest/loaders/binance_loader.py:23-44

章节来源 - agent/backtest/loaders/registry.py:136-193 - agent/src/config/env_schema.py:153-198

性能考虑¶

节流与限速
Yahoo/Eastmoney：进程级最小间隔与共享会话，避免 IP 封禁
CCXT：enableRateLimit=True，超时与预算控制
Tushare：配额拒绝识别与退避重试
预算与重试
retry_with_budget：基于单调时钟的硬截止与指数退避，仅对声明的瞬时异常重试
check_budget：分页间快速失败，防止长尾挂起
本地缓存
基于内容寻址的 parquet 缓存，仅对已收盘区间生效；读写失败不影响主流程
批量与采样
cap_rows：对返回记录进行步长采样，控制工具负载
代理与网络
CCXT 支持系统代理变量；Yahoo/Eastmoney 通过共享客户端统一处理

章节来源 - agent/backtest/loaders/base.py:163-236 - agent/backtest/loaders/base.py:243-439 - agent/backtest/loaders/ccxt_loader.py:50-57 - agent/backtest/loaders/yahoo_client.py:44-68 - agent/backtest/loaders/eastmoney_client.py:32-40 - agent/src/market_data.py:66-84

故障排查指南¶

无可用数据源
现象：NoAvailableSourceError
排查：检查市场回退链、凭据（如 TUSHARE_TOKEN）、网络与代理
配额/限频
Tushare：出现“每分钟/每天/抽取/频率”等关键字即触发退避重试
Yahoo/Eastmoney：观察日志中的节流提示，适当增大最小间隔
401 未授权（Yahoo）
现象：quoteSummary/options 返回 401
处理：客户端自动刷新 crumb/cookies 并重试一次
历史不完整（CCXT）
现象：请求范围大于实际返回且命中页上限
处理：扩大预算或缩小时间窗；检查交易所可用性
复权因子缺失（Tushare）
现象：adj_factor 为空或不可用
处理：该标的将被丢弃，避免在污染价格上回测
本地缓存问题
现象：读取失败或损坏
处理：忽略并回退到在线拉取；检查缓存根目录权限与磁盘空间

章节来源 - agent/backtest/loaders/tushare.py:18-48 - agent/backtest/loaders/yahoo_client.py:95-153 - agent/backtest/loaders/ccxt_loader.py:493-501 - agent/backtest/loaders/base.py:475-533

结论¶

Vibe-Trading 通过统一的数据加载协议、注册表与回退链，实现了跨市场、跨数据源的稳健集成。Yahoo、东方财富、Tushare、CCXT/Binance 各有侧重：前者适合公开免费数据与高并发场景，后者提供丰富的加密资产与合约数据。结合节流、预算、重试与本地缓存，系统在稳定性与性能之间取得平衡。建议在生产环境开启缓存、合理设置预算与间隔，并根据市场特征选择合适的回退顺序。

附录¶

配置项速查（数据相关）¶

TUSHARE_TOKEN：Tushare 令牌
CCXT_EXCHANGE：CCXT 交易所标识（默认 binance）
CCXT_TIMEOUT_MS / CCXT_FETCH_BUDGET_S：CCXT 超时与总预算
VIBE_TRADING_DATA_CACHE / VIBE_TRADING_DATA_CACHE_ROOT：是否启用与缓存根路径
VIBE_TRADING_YAHOO_MIN_INTERVAL / VIBE_TRADING_EASTMONEY_MIN_INTERVAL：Yahoo/东方财富最小请求间隔
FINNHUB_API_KEY / ALPHAVANTAGE_API_KEY / TIINGO_API_KEY / FMP_API_KEY：其他密钥型数据源

章节来源 - agent/src/config/env_schema.py:153-198

多市场同步最佳实践¶

一致性保证
统一输出 schema（trade_date + OHLCV），必要时做 OHLC 不变量校验
对跨源合并场景，使用同一时间基准（如午夜对齐）与去重策略
增量更新
以 end_date 为边界，仅拉取新增区间；利用本地缓存避免重复下载
对活跃标的（当日）不缓存，避免钉住未完成 K 线
回退策略
明确首选源与同市场回退链；对 local/qveris 等本地源禁止静默降级到网络源
监控与可观测性
开启 _provenance 记录实际使用的源与是否发生回退
统计 _unresolved 集合，定位无法解析的符号

章节来源 - agent/src/market_data.py:198-223 - agent/backtest/loaders/base.py:328-439 - agent/backtest/loaders/registry.py:117-124

← 外汇期货数据源数据源架构设计 →