数据模型与验证¶

📎 引用文件

本文引用的文件 - agent/backtest/models.py - agent/backtest/loaders/_fundamental_schema.py - agent/backtest/loaders/base.py - agent/src/market_data.py - agent/backtest/validation.py - agent/src/entities/models.py - agent/src/config/schema.py

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考量
故障排查指南
结论
附录：使用示例

简介¶

本文件聚焦 Vibe-Trading 的数据模型与验证系统，围绕以下目标展开： - 核心数据模型设计：MarketData、FundamentalData、TimeSeries 的结构定义与职责边界。 - Pydantic 模型验证规则：数据类型检查、业务规则校验与异常处理策略。 - 财务数据模式：资产负债表、利润表、现金流量表的字段规范与派生指标。 - 数据质量检查：缺失值检测、异常值识别、数据一致性验证。 - 数据转换管道：格式标准化、单位换算、时间序列对齐。 - 实际使用示例：如何定义新数据模型并执行数据验证。

项目结构¶

本项目将“市场数据”“基本面数据”“回测/验证”“实体与配置”分层组织： - 市场数据层：统一通过加载器（Loader）获取 OHLCV，支持多源自动回退与行级裁剪。 - 基本面数据层：以统一字段 Schema 映射 SEC XBRL 概念，提供原始与派生字段。 - 回测与验证：对交易结果进行统计检验（蒙特卡洛、Bootstrap、滚动窗口）。 - 实体与配置：非价格型资产（基金、债券等）的强类型实体；MCP/Agent 配置的 Pydantic 校验。

graph TB subgraph "数据接入" MD["市场数据入口 fetch_market_data"] LBase["加载器基类 validate_ohlc / 缓存"] FSchema["基本面字段Schema RAW_FIELDS / DERIVED_FIELDS"] end subgraph "数据模型" BM["回测数据模型 Position/Fill/Trade/EquitySnapshot"] EM["实体模型 Instrument/Fund/Bond"] CM["配置模型 Pydantic: MCPServerConfig/AgentConfig"] end subgraph "验证与质量" VAL["统计验证 Monte Carlo / Bootstrap / Walk-Forward"] QG["数据质量 OHLC不变量/缺失/异常"] end MD --> LBase LBase --> BM FSchema --> BM BM --> VAL EM --> CM QG --> VAL

图表来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/base.py:31-119 - agent/backtest/loaders/_fundamental_schema.py:28-189 - agent/backtest/models.py:13-118 - agent/src/entities/models.py:141-397 - agent/src/config/schema.py:301-513 - agent/backtest/validation.py:29-341

章节来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/base.py:31-119 - agent/backtest/loaders/_fundamental_schema.py:28-189 - agent/backtest/models.py:13-118 - agent/src/entities/models.py:141-397 - agent/src/config/schema.py:301-513 - agent/backtest/validation.py:29-341

核心组件¶

MarketData（市场数据）：通过统一入口 fetch_market_data 聚合多源加载器，按市场自动选择首选源并支持回退链；返回标准化 OHLCV 记录，支持最大行数裁剪与来源溯源。
FundamentalData（基本面数据）：以 RAW_FIELDS 与 DERIVED_FIELDS 定义统一字段族，SEC_CONCEPT_MAP 将稀疏 SEC 事实映射到标准字段；派生字段通过依赖计算得到。
TimeSeries（时间序列）：由加载器产出的 DataFrame（日期索引 + OHLCV 列）构成；在加载器边界通过 validate_ohlc 保证结构一致性与数值合理性。
回测数据模型：Position、FillRecord、TradeRecord、EquitySnapshot 描述头寸、成交、完整交易与权益快照，作为回测与验证的输入。
实体与配置：Instrument/Fund/Bond 等实体用于非价格现金流资产；MCPServerConfig/AgentConfig 等 Pydantic 模型负责配置安全与约束。

章节来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/_fundamental_schema.py:28-189 - agent/backtest/loaders/base.py:50-119 - agent/backtest/models.py:13-118 - agent/src/entities/models.py:141-397 - agent/src/config/schema.py:301-513

架构总览¶

下图展示从数据接入到验证输出的端到端流程，包括数据清洗、模型化与统计检验。

sequenceDiagram participant U as "调用方" participant M as "市场数据入口 fetch_market_data" participant R as "加载器注册表/回退链" participant B as "加载器基类 validate_ohlc" participant S as "基本面Schema resolve_field" participant V as "统计验证 run_validation" U->>M : 请求代码/区间/频率 M->>R : 按市场匹配首选源与回退链 R-->>M : 可用加载器 M->>B : 拉取OHLCV并清洗 B-->>M : 通过validate_ohlc的DataFrame U->>S : 解析基本面字段(可选) S-->>U : 原始/派生字段 U->>V : 传入权益曲线/交易记录 V-->>U : 蒙特卡洛/Bootstrap/滚动窗口结果

图表来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/base.py:50-119 - agent/backtest/loaders/_fundamental_schema.py:196-217 - agent/backtest/validation.py:286-341

详细组件分析¶

市场数据（MarketData）¶

功能要点
自动源选择：根据符号模式推断首选源（如 US/HK/A股/加密货币/外汇），并按市场回退链尝试。
数据裁剪：每标的限制返回行数，避免工具负载过大。
来源溯源：可输出使用的源、是否发生回退、货币换算标记等。
关键路径
detect_source -> get_loader_cls_with_fallback -> loader.fetch -> cap_rows -> _json_safe
错误与健壮性
加载器不可用或失败时记录日志并切换到下一源；超过最大重试次数后标记为未解析。

flowchart TD Start(["开始"]) --> Detect["推断首选源"] Detect --> Chain{"构建回退链"} Chain --> TryFetch["尝试加载器.fetch()"] TryFetch --> |成功| Clean["JSON安全化/裁剪行数"] TryFetch --> |失败| Next{"还有备用源?"} Next --> |是| TryFetch Next --> |否| Unresolved["标记_unresolved"] Clean --> Done(["结束"]) Unresolved --> Done

图表来源 - agent/src/market_data.py:51-84 - agent/src/market_data.py:97-223

章节来源 - agent/src/market_data.py:51-84 - agent/src/market_data.py:97-223

基本面数据（FundamentalData）¶

字段体系
原始字段（RAW_FIELDS）：收入、成本、毛利、营业利润、净利润、总资产、总权益、总债务、现金、稀释股本、经营现金流、资本支出等。
派生字段（DERIVED_FIELDS）：ROE、ROA、毛利率/资产比、资产增长率、应计项、杠杆等，基于依赖字段计算。
SEC 概念映射（SEC_CONCEPT_MAP）：将不同公司披露的概念名归一到统一字段，优先顺序保障 PIT 安全。
解析与计算
resolve_field 将字段名解析为原始或派生规格；派生字段通过 compute 函数在依赖就绪后计算。
数据质量
安全除法：分母为零时返回 NaN，避免除零污染下游指标。

classDiagram class 原始字段 { +revenue +cogs +gross_profit +operating_income +net_income +total_assets +total_equity +total_debt +cash +shares_diluted +cfo +capex } class 派生字段 { +roe +roa +gross_profitability +asset_growth +accruals +leverage } class SEC概念映射 { +映射表 } 原始字段 <.. 派生字段 : "依赖" SEC概念映射 --> 原始字段 : "归一化"

图表来源 - agent/backtest/loaders/_fundamental_schema.py:28-189 - agent/backtest/loaders/_fundamental_schema.py:196-217

章节来源 - agent/backtest/loaders/_fundamental_schema.py:28-189 - agent/backtest/loaders/_fundamental_schema.py:196-217

时间序列（TimeSeries）与数据质量¶

时间序列形态
由加载器产出带日期索引的 DataFrame，包含 open/high/low/close/volume 等列。
数据质量检查
validate_ohlc：强制结构不变量（high>=open/close, low<=open/close），拒绝非正价格（可配置允许负价场景），支持 drop/warn/raise 策略。
缺失值：加载器内部先 dropna，再由 validate_ohlc 清理结构性脏条。
异常值：通过不变量与阈值策略过滤，确保下游 JSON 序列化严格（无 NaN/Inf）。

flowchart TD In(["输入DataFrame"]) --> CheckCols{"包含OHLC列?"} CheckCols --> |否| OutKeep["原样返回"] CheckCols --> |是| Structural{"结构不变量检查"} Structural --> Positivity{"价格正性检查(可配)"} Positivity --> Strategy{"策略: drop/warn/raise"} Strategy --> |drop| Clean["剔除无效行"] Strategy --> |warn| Keep["保留并记录警告"] Strategy --> |raise| Err["抛出异常"] Clean --> Out(["输出"]) Keep --> Out Err --> Out

图表来源 - agent/backtest/loaders/base.py:50-119

章节来源 - agent/backtest/loaders/base.py:50-119

回测数据模型（Position/Fill/Trade/EquitySnapshot）¶

角色与职责
Position：单一标的持仓状态（方向、入场价、时间、规模、杠杆、佣金等）。
FillRecord：单笔成交证据（数量、名义价值、费用、保证金、原因等）。
TradeRecord：完整往返交易（进出场价/时间、盈亏、持有期、手续费等）。
EquitySnapshot：某时刻组合状态（资金、浮盈、权益、持仓数）。
用途
作为回测引擎与统计验证的输入，保证不可变性与可追溯性。

classDiagram class Position { +symbol +direction +entry_price +entry_time +size +leverage +entry_bar_idx +entry_commission } class FillRecord { +symbol +timestamp +bar_idx +action +signed_quantity +notional +execution_price +fee +margin +reason +holding_bars } class TradeRecord { +symbol +direction +entry_price +exit_price +entry_time +exit_time +size +leverage +pnl +pnl_pct +exit_reason +holding_bars +commission +entry_margin +exit_margin } class EquitySnapshot { +timestamp +capital +unrealized +equity +positions } FillRecord --> TradeRecord : "组成" Position --> TradeRecord : "闭合" TradeRecord --> EquitySnapshot : "驱动权益曲线"

图表来源 - agent/backtest/models.py:13-118

章节来源 - agent/backtest/models.py:13-118

实体与配置（非价格资产与Pydantic校验）¶

实体模型
Instrument/Fund/Bond：描述非价格现金流资产，强制币种、日期规范化与范围校验（如面值>0、费率[0,1]、到期日不早于成立日等）。
Pydantic 配置
MCPServerConfig/AgentConfig：对传输方式、OAuth、工具白名单等进行严格校验，防止危险配置（如在线券商通配符白名单）。

classDiagram class Entity { +entity_id +name +entity_type +domicile +parent_id } class Instrument { +instrument_id +currency +name +issuer +inception_date } class Security { +symbol +exchange +security_type } class Fund { +vintage_year +structure +strategy +commitment +management_fee_rate } class Bond { +face_value +coupon_rate +coupon_frequency +maturity_date +day_count } Instrument <|-- Security Instrument <|-- Fund Instrument <|-- Bond Entity <.. Instrument : "关联发行主体"

图表来源 - agent/src/entities/models.py:141-397 - agent/src/config/schema.py:301-513

章节来源 - agent/src/entities/models.py:141-397 - agent/src/config/schema.py:301-513

依赖关系分析¶

市场数据入口依赖加载器注册表与回退链，最终产出标准化 DataFrame。
基本面数据依赖 SEC 概念映射与派生计算逻辑，产出统一字段面板。
回测数据模型被统计验证模块消费，生成蒙特卡洛、Bootstrap、滚动窗口结果。
实体与配置模块独立于行情路径，但为上层工具与通道提供安全约束。

graph LR MD["market_data.py"] --> LB["loaders/base.py"] FS["_fundamental_schema.py"] --> BM["backtest/models.py"] BM --> VAL["validation.py"] EM["entities/models.py"] --> CFG["config/schema.py"]

图表来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/base.py:50-119 - agent/backtest/loaders/_fundamental_schema.py:28-189 - agent/backtest/models.py:13-118 - agent/backtest/validation.py:286-341 - agent/src/entities/models.py:141-397 - agent/src/config/schema.py:301-513

章节来源 - agent/src/market_data.py:97-223 - agent/backtest/loaders/base.py:50-119 - agent/backtest/loaders/_fundamental_schema.py:28-189 - agent/backtest/models.py:13-118 - agent/backtest/validation.py:286-341 - agent/src/entities/models.py:141-397 - agent/src/config/schema.py:301-513

性能考量¶

加载器缓存：按 source/symbol/timeframe/date range/fields 生成内容寻址键，命中则直接读取 parquet，减少网络开销。
回退链与超时预算：通过预算与指数退避控制外部 API 调用，避免长时间阻塞。
结果裁剪：对返回记录按步长采样并固定最后一根K线，控制工具响应体积。
统计验证：蒙特卡洛与 Bootstrap 支持样本上限与内存保护，避免超大运行导致溢出。

章节来源 - agent/backtest/loaders/base.py:243-439 - agent/src/market_data.py:66-84 - agent/backtest/validation.py:60-113 - agent/backtest/validation.py:131-192

故障排查指南¶

OHLC 不一致
现象：high<low 或 high/low 不包围 open/close，或非正价格。
处理：validate_ohlc 默认丢弃无效行；可切换 warn/raise 策略定位问题。
数据源不可用
现象：首选源失败，触发回退链；若全部失败，结果中会出现 _unresolved 列表。
处理：检查网络、认证、代理；必要时调整 max_fallback_attempts。
基本面字段缺失
现象：SEC 概念未命中，字段为 NaN。
处理：确认 SEC_CONCEPT_MAP 覆盖；必要时在上游做补充映射。
配置校验失败
现象：在线券商不允许通配符白名单；HTTP 必须 HTTPS；OAuth 与静态 headers 互斥。
处理：按 MCPServerConfig/AgentConfig 的 model_validator 提示修正。

章节来源 - agent/backtest/loaders/base.py:50-119 - agent/src/market_data.py:158-223 - agent/backtest/loaders/_fundamental_schema.py:196-217 - agent/src/config/schema.py:373-492

结论¶

数据模型清晰分层：市场数据、基本面数据、回测模型与实体/配置各司其职。
验证贯穿全链路：从 OHLC 结构不变量到统计显著性检验，确保结果稳健。
可扩展性强：新增字段/模型可通过 Schema 与 Pydantic 快速集成，保持向后兼容与安全。
建议：在接入新数据源时，务必实现 validate_ohlc 与缓存适配；在扩展基本面字段时，遵循依赖声明与派生计算约定。

附录：使用示例¶

定义新数据模型（Pydantic）
参考配置模型的写法，使用 BaseModel 与 Field 约束类型与范围，并通过 model_validator 实现业务规则校验。
参考路径：agent/src/config/schema.py:301-513
执行数据验证
使用 run_validation 对权益曲线与交易记录进行蒙特卡洛、Bootstrap、滚动窗口分析。
参考路径：agent/backtest/validation.py:286-341
拉取市场数据
调用 fetch_market_data，指定 codes、start_date、end_date、source/auto、interval、max_rows。
参考路径：agent/src/market_data.py:97-223
解析基本面字段
使用 resolve_field 获取字段规格，按依赖计算派生指标。
参考路径：agent/backtest/loaders/_fundamental_schema.py:196-217
清洗时间序列
在加载器边界调用 validate_ohlc，确保 OHLC 不变量与价格正性。
参考路径：agent/backtest/loaders/base.py:50-119

← 数据处理管道数据源集成架构 →