Vibe-Trading 实战指南：Tushare `fina_indicator` 财务指标数据接口的完整用法与 PIT 安全回测集成

Vibe-Trading 实战指南Tusharefina_indicator财务指标数据接口的完整用法与 PIT 安全回测集成【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading上市公司财务指标是基本面量化研究的核心数据源而 Tushare 的fina_indicator接口财务指标数据将利润表、资产负债表、现金流量表中的原始科目加工为 170 余个可直接使用的派生指标——每股指标、盈利能力、偿债能力、营运能力、现金流质量、同比环比增速一应俱全。本文以 agent/src/skills/tushare/references/股票数据/财务数据/财务指标数据.md 为主线完整讲解该接口的权限要求、入参出参、调用方法与数据样例并结合 Vibe-Trading 仓库中 agent/backtest/loaders/tushare_fundamentals.py 的源码实现说明如何在回测中把fina_indicator的 ROE、毛利率、资产负债率等字段以公告日ann_date之后才可见的 PITPoint-in-Time安全方式注入日线行情避免未来函数污染回测结论。读完本文你将能够独立完成从接口调取、字段解读到回测因子接入的完整链路。一、接口概述与权限要求fina_indicator是 Tushare 的财务指标数据接口文档 ID 79描述为获取上市公司财务指标数据。与三大报表接口income、balancesheet、cashflow返回原始会计科目不同该接口直接输出经过计算的财务比率与每股指标减少了研究者自行加工的负担。调用该接口需要满足以下前提积分门槛用户需要至少2000 积分才可以调取积分获取办法可在 Tushare 平台查阅需注册并完成积分任务。单次条数上限为避免服务器压力现阶段每次请求最多返回100 条记录可通过设置日期多次请求获取更多数据。单票查询限制当前接口只能按单只股票获取其历史数据如果需要获取某一季度全部上市公司数据请使用fina_indicator_vip接口参数一致该接口需积攒5000 积分。从仓库源码看Vibe-Trading 的 TushareFundamentalProvider 会优先从项目配置中读取TUSHARE_TOKEN占位符与your-tushare-token会被视为未配置再通过ts.pro_api(token)初始化 API 实例test_default_constructor_uses_project_tushare_token_env测试验证了这一 token 注入链路。二、输入参数详解fina_indicator共支持 4 个输入参数除ts_code外均可选名称类型必选描述ts_codestrYTS 股票代码e.g. 600001.SH / 000001.SZann_datestrN公告日期start_datestrN报告期开始日期end_datestrN报告期结束日期periodstrN报告期每个季度最后一天的日期比如 20171231 表示年报实操建议日期统一使用YYYYMMDD格式与 Tushare 全局约定一致参见 tushare 技能 SKILL.md 中的参数格式说明。ts_code后缀含义SH为上海证券交易所、SZ为深圳证券交易所北交所与创业板代码规则亦遵循 TS 统一代码体系。当不传period时接口返回该股票全部历史报告期数据再叠加 100 条/次的限制因此全历史拉取需要配合start_date/end_date分页循环。从源码调用方式看Vibe-Trading 的 Provider 在_query_pit_cut中以api_method(ts_codecode, periodNone)形式逐票全量拉取再由内存侧完成筛选见 tushare_fundamentals.py与文档按单只股票获取的限制完全一致。三、输出参数全解170 个财务指标分类详解接口输出字段按会计逻辑可分为十一个大类。下面完整列出各字段的名称、类型、默认显示与含义供选股、因子构建和策略研发直接取用。3.1 每股指标Earnings Per Share 系列名称类型默认显示描述epsfloatY基本每股收益dt_epsfloatY稀释每股收益total_revenue_psfloatY每股营业总收入revenue_psfloatY每股营业收入capital_rese_psfloatY每股资本公积surplus_rese_psfloatY每股盈余公积undist_profit_psfloatY每股未分配利润diluted2_epsfloatY期末摊薄每股收益bpsfloatY每股净资产ocfpsfloatY每股经营活动产生的现金流量净额retainedpsfloatY每股留存收益cfpsfloatY每股现金流量净额ebit_psfloatY每股息税前利润fcff_psfloatY每股企业自由现金流量fcfe_psfloatY每股股东自由现金流量q_epsfloatN每股收益单季度3.2 盈利能力指标Profitability名称类型默认显示描述gross_marginfloatY毛利netprofit_marginfloatY销售净利率grossprofit_marginfloatY销售毛利率cogs_of_salesfloatY销售成本率expense_of_salesfloatY销售期间费用率profit_to_grfloatY净利润/营业总收入saleexp_to_grfloatY销售费用/营业总收入adminexp_of_grfloatY管理费用/营业总收入finaexp_of_grfloatY财务费用/营业总收入impai_ttmfloatY资产减值损失/营业总收入gc_of_grfloatY营业总成本/营业总收入op_of_grfloatY营业利润/营业总收入ebit_of_grfloatY息税前利润/营业总收入profit_to_opfloatY利润总额/营业收入rd_expfloatN研发费用q_netprofit_marginfloatN销售净利率单季度q_gsprofit_marginfloatN销售毛利率单季度q_exp_to_salesfloatN销售期间费用率单季度q_profit_to_grfloatN净利润/营业总收入单季度q_saleexp_to_grfloatY销售费用/营业总收入单季度q_adminexp_to_grfloatN管理费用/营业总收入单季度q_finaexp_to_grfloatN财务费用/营业总收入单季度q_impair_to_gr_ttmfloatN资产减值损失/营业总收入单季度q_gc_to_grfloatY营业总成本/营业总收入单季度q_op_to_grfloatN营业利润/营业总收入单季度3.3 收益质量与盈利构成Earnings Quality名称类型默认显示描述extra_itemfloatY非经常性损益profit_dedtfloatY扣除非经常性损益后的净利润扣非净利润op_incomefloatY经营活动净收益valuechange_incomefloatN价值变动净收益profit_prefin_expfloatN扣除财务费用前营业利润non_op_profitfloatN非营业利润opincome_of_ebtfloatN经营活动净收益/利润总额investincome_of_ebtfloatN价值变动净收益/利润总额n_op_profit_of_ebtfloatN营业外收支净额/利润总额tax_to_ebtfloatN所得税/利润总额dtprofit_to_profitfloatN扣除非经常损益后的净利润/净利润salescash_to_orfloatN销售商品提供劳务收到的现金/营业收入ocf_to_orfloatN经营活动产生的现金流量净额/营业收入ocf_to_opincomefloatN经营活动产生的现金流量净额/经营活动净收益capitalized_to_dafloatN资本支出/折旧和摊销op_to_ebtfloatN营业利润/利润总额nop_to_ebtfloatN非营业利润/利润总额ocf_to_profitfloatN经营活动产生的现金流量净额/营业利润q_opincomefloatN经营活动单季度净收益q_investincomefloatN价值变动单季度净收益q_dtprofitfloatN扣除非经常损益后的单季度净利润q_opincome_to_ebtfloatN经营活动净收益/利润总额单季度q_investincome_to_ebtfloatN价值变动净收益/利润总额单季度q_dtprofit_to_profitfloatN扣除非经常损益后的净利润/净利润单季度q_salescash_to_orfloatN销售商品提供劳务收到的现金/营业收入单季度q_ocf_to_salesfloatY经营活动产生的现金流量净额/营业收入单季度q_ocf_to_orfloatN经营活动产生的现金流量净额/经营活动净收益单季度3.4 收益率指标ROE / ROA / ROIC名称类型默认显示描述roefloatY净资产收益率roe_waafloatY加权平均净资产收益率roe_dtfloatY净资产收益率扣除非经常损益roafloatY总资产报酬率nptafloatY总资产净利润roicfloatY投入资本回报率roe_yearlyfloatY年化净资产收益率roa2_yearlyfloatY年化总资产报酬率roe_avgfloatN平均净资产收益率增发条件roa_yearlyfloatY年化总资产净利率roa_dpfloatY总资产净利率杜邦分析roic_yearlyfloatN年化投入资本回报率q_roefloatY净资产收益率单季度q_dt_roefloatY净资产单季度收益率扣除非经常损益q_nptafloatY总资产净利润单季度3.5 偿债能力与资本结构Solvency Capital Structure名称类型默认显示描述current_ratiofloatY流动比率quick_ratiofloatY速动比率cash_ratiofloatY保守速动比率current_exintfloatY无息流动负债noncurrent_exintfloatY无息非流动负债interestdebtfloatY带息债务netdebtfloatY净债务debt_to_assetsfloatY资产负债率assets_to_eqtfloatY权益乘数dp_assets_to_eqtfloatY权益乘数杜邦分析ca_to_assetsfloatY流动资产/总资产nca_to_assetsfloatY非流动资产/总资产tbassets_to_totalassetsfloatY有形资产/总资产int_to_talcapfloatY带息债务/全部投入资本eqt_to_talcapitalfloatY归属于母公司的股东权益/全部投入资本currentdebt_to_debtfloatY流动负债/负债合计longdeb_to_debtfloatY非流动负债/负债合计ocf_to_shortdebtfloatY经营活动产生的现金流量净额/流动负债debt_to_eqtfloatY产权比率eqt_to_debtfloatY归属于母公司的股东权益/负债合计eqt_to_interestdebtfloatY归属于母公司的股东权益/带息债务tangibleasset_to_debtfloatY有形资产/负债合计tangasset_to_intdebtfloatY有形资产/带息债务tangibleasset_to_netdebtfloatY有形资产/净债务ocf_to_debtfloatY经营活动产生的现金流量净额/负债合计ocf_to_interestdebtfloatN经营活动产生的现金流量净额/带息债务ocf_to_netdebtfloatN经营活动产生的现金流量净额/净债务ebit_to_interestfloatN已获利息倍数EBIT/利息费用longdebt_to_workingcapitalfloatN长期债务与营运资金比率ebitda_to_debtfloatN息税折旧摊销前利润/负债合计cash_to_liqdebtfloatN货币资金/流动负债cash_to_liqdebt_withinterestfloatN货币资金/带息流动负债op_to_liqdebtfloatN营业利润/流动负债op_to_debtfloatN营业利润/负债合计3.6 营运能力指标Operating Efficiency名称类型默认显示描述invturn_daysfloatN存货周转天数arturn_daysfloatN应收账款周转天数inv_turnfloatN存货周转率ar_turnfloatY应收账款周转率ca_turnfloatY流动资产周转率fa_turnfloatY固定资产周转率assets_turnfloatY总资产周转率turn_daysfloatY营业周期total_fa_trunfloatN固定资产合计周转率3.7 现金流与估值中间量Cash Flow Valuation Inputs名称类型默认显示描述interst_incomefloatN利息费用daafloatN折旧与摊销ebitfloatY息税前利润ebitdafloatY息税折旧摊销前利润fcfffloatY企业自由现金流量fcfefloatY股权自由现金流量tangible_assetfloatY有形资产working_capitalfloatY营运资金networking_capitalfloatY营运流动资本invest_capitalfloatY全部投入资本retained_earningsfloatY留存收益fixed_assetsfloatY固定资产合计3.8 同比 / 环比增长率指标YoY / QoQ Growth名称类型默认显示描述basic_eps_yoyfloatY基本每股收益同比增长率(%)dt_eps_yoyfloatY稀释每股收益同比增长率(%)cfps_yoyfloatY每股经营活动产生的现金流量净额同比增长率(%)op_yoyfloatY营业利润同比增长率(%)ebt_yoyfloatY利润总额同比增长率(%)netprofit_yoyfloatY归属母公司股东的净利润同比增长率(%)dt_netprofit_yoyfloatY归属母公司股东的净利润-扣除非经常损益同比增长率(%)ocf_yoyfloatY经营活动产生的现金流量净额同比增长率(%)roe_yoyfloatY净资产收益率摊薄同比增长率(%)bps_yoyfloatY每股净资产相对年初增长率(%)assets_yoyfloatY资产总计相对年初增长率(%)eqt_yoyfloatY归属母公司的股东权益相对年初增长率(%)tr_yoyfloatY营业总收入同比增长率(%)or_yoyfloatY营业收入同比增长率(%)equity_yoyfloatY净资产同比增长率q_gr_yoyfloatN营业总收入同比增长率(%)(单季度)q_gr_qoqfloatN营业总收入环比增长率(%)(单季度)q_sales_yoyfloatY营业收入同比增长率(%)(单季度)q_sales_qoqfloatN营业收入环比增长率(%)(单季度)q_op_yoyfloatN营业利润同比增长率(%)(单季度)q_op_qoqfloatY营业利润环比增长率(%)(单季度)q_profit_yoyfloatN净利润同比增长率(%)(单季度)q_profit_qoqfloatN净利润环比增长率(%)(单季度)q_netprofit_yoyfloatN归属母公司股东的净利润同比增长率(%)(单季度)q_netprofit_qoqfloatN归属母公司股东的净利润环比增长率(%)(单季度)3.9 其他元数据字段名称类型默认显示描述ts_codestrYTS 代码ann_datestrY公告日期end_datestrY报告期update_flagstrN更新标识字段使用要点所有百分比类指标如netprofit_margin、roe、各类*_yoy以百分数值返回例如roe15表示 15%这一点在跨数据源对比时尤其需要注意——yfinance 的returnOnEquity返回的是小数0.15两者不能直接混用参见 fundamental-filter 技能 的 Common Pitfalls。单季度字段q_前缀在季度财报集中披露期间更新适合做环比加速acceleration类因子。update_flag表示该行数据是否经过修订可用于识别追溯调整。四、接口用法两种标准调用方式接口支持 Tushare Pro API 的两种调用形态推荐第一种直接属性调用import tushare as ts # 方式一初始化 pro 接口实例后直接调用 pro ts.pro_api() df pro.fina_indicator(ts_code600000.SH)或者使用通用query方法# 方式二query 统一入口可附加日期范围参数 df pro.query(fina_indicator, ts_code600000.SH, start_date20170101, end_date20180801)在 Vibe-Trading 的示例脚本 stock_data_example.py 中还演示了按年度季度获取财务指标的封装其 token 读取路径为get_env_config().data.tushare_token或ts.get_token()def get_financial_data(ts_code, year, quarter): data pro.fina_indicator(ts_codets_code, yearyear, quarterquarter) return data需要注意本仓库示例脚本中的year/quarter参数属于 Tushare 旧版fina_indicator的参数形态而当前 Pro 接口的标准入参是文档所列的ts_code、ann_date、start_date、end_date、period以本文第二节的 4 个参数为准。五、数据样例解读以浦发银行600000.SH为例接口返回的数据结构如下节选ts_code ann_date end_date eps dt_eps total_revenue_ps revenue_ps \ 0 600000.SH 20180830 20180630 0.95 0.95 2.8024 2.8024 1 600000.SH 20180428 20180331 0.46 0.46 1.3501 1.3501 2 600000.SH 20180428 20171231 1.84 1.84 5.7447 5.7447 3 600000.SH 20180428 20171231 1.84 1.84 5.7447 5.7447 4 600000.SH 20171028 20170930 1.45 1.45 4.2507 4.2507 5 600000.SH 20171028 20170930 1.45 1.45 4.2507 4.2507 6 600000.SH 20170830 20170630 0.97 0.97 2.9659 2.9659 7 600000.SH 20170427 20170331 0.63 0.63 1.9595 1.9595 8 600000.SH 20170427 20170331 0.63 0.63 1.9595 1.9595从样例中可以读出三个关键事实报告期与公告期的错位end_date20180630半年报报告期对应的ann_date20180830公告日即财务数据在报告期末之后约两个月才披露。任何不区分ann_date、直接按end_date使用的做法都会引入严重的未来函数。同报告期多行现象end_date20171231年报出现了两行eps完全相同的记录这是数据修订/重复入库造成的end_date20170930三季报同样出现两行。回测系统必须按每个(ts_code, end_date)保留最新一条的规则去重。披露节奏逐期递进每季度财报对应一行最终数据配合ann_date即可构造精确的披露时间线。六、进阶实战在 Vibe-Trading 回测中以 PIT 安全方式使用财务指标以上是接口层面的标准用法。在 Vibe-Trading 的量化回测框架中fina_indicator已被封装为基本面数据 Provider 的标准表之一并实现了完整的公告日可见性PIT控制直接可用于 ROE/毛利率/负债率等因子的无偏回测。6.1 表级 Schema 注册在 agent/backtest/loaders/tushare_fundamentals.py 中fina_indicator以TableSchema形式注册fina_indicator: TableSchema( namefina_indicator, api_namefina_indicator, point_in_time_columnann_date, # 财务指标表以公告日作为可见性依据 columns( ColumnSchema(ts_code, str, requiredTrue), ColumnSchema(ann_date, date, requiredTrue), ColumnSchema(end_date, date, requiredTrue), ColumnSchema(eps, float), ColumnSchema(grossprofit_margin, float), ColumnSchema(netprofit_margin, float), ColumnSchema(roe, float), ColumnSchema(debt_to_assets, float), ), ),可以注意到Provider 为该表选取了eps、grossprofit_margin、netprofit_margin、roe、debt_to_assets五个代表性字段这与接口输出字段一一对应且把ann_date明确为point_in_time_column——即每条指标在ann_date之后才可被回测策略看见。test_query_fundamentals_validates_required_schema_columns测试见 agent/tests/test_tushare_fundamentals_provider.py验证了当接口返回缺少end_date时会抛出SchemaValidationError保证入库数据契约完整。6.2 配置接入fundamental_fields在回测配置中通过fundamental_fields声明需要注入的指标表名→字段列表例如在 fundamental-filter 技能 中给出的配置{ source: tushare, codes: [000001.SZ, 600036.SH, 000858.SZ], start_date: 2023-01-01, end_date: 2024-12-31, fundamental_fields: { income: [total_revenue, n_income], balancesheet: [total_hldr_eqy_exc_min_int], fina_indicator: [roe, debt_to_assets] }, initial_cash: 1000000, commission: 0.001 }回测引擎在 agent/backtest/engines/base.py 的_normalise_fundamental_fields与_maybe_enrich_fundamentals中完成配置校验与注入调用最终在data_map构建阶段同文件第 899 行对每个标的的日线行情执行基本面增强。注入后的列名统一加上表名前缀请求字段信号引擎中可用的列名fina_indicator.roefina_indicator_roefina_indicator.debt_to_assetsfina_indicator_debt_to_assets6.3 PIT 可见性规则与测试验证增强逻辑的核心在enrich_price_frames_with_fundamentalstushare_fundamentals.py其规则包括公告日才可见每条指标仅在其ann_date当日及之后的交易日出现在日线上end_date仅用于标识报告期。test_daily_frames_keep_same_day_visibility验证了日线级别公告日当天即可见的正确性日线信号最早次日开盘成交不存在日内前视。去重规则按(ts_code, end_date)保留有效公告日f_ann_date为空时回退到ann_date最新的一行同一报告期的修订数据覆盖旧值。防回退规则当一份较晚披露的财报覆盖更早报告期旧期重述时快照不会回退到旧报告期避免历史信号被重写。日线级保护fina_indicator的ann_date没有日内时间戳因此默认禁止对分钟级intraday行情注入基本面可通过fundamental_subdaily: next_day显式开启公告日次日可见的保守约定。以上行为均有单元测试覆盖见 test_tushare_fundamentals_provider.py 中的test_t1/test_t2/test_t3系列与test_subdaily_*系列。使用fina_indicator指标构建策略时应依赖该机制而非自行fillna(ffill)前向填充否则会把披露前的数据提前暴露给信号造成回测失真。6.4 一个完整的 ROE 质量过滤示例结合 example_signal_engine.py 中的模式用fina_indicator注入的字段可以这样做基本面质量过滤def _passes_statement_filter(row): revenue _first_number(row, [income_total_revenue, income_revenue]) profit _first_number(row, [income_n_income]) net_assets _first_number(row, [balancesheet_total_hldr_eqy_exc_min_int]) roe _first_number(row, [fina_indicator_roe, roe]) # 单位%如 15 15% # 全部字段缺失 → 不表态None部分缺失 → 不通过False statement_values [revenue, profit, net_assets, roe] if all(pd.isna(v) for v in statement_values): return None if any(pd.isna(v) for v in statement_values): return False return ( revenue 0 and profit 0 and net_assets 0 and roe 8.0 # ROE 质量下限 )这段逻辑的要点在于在 PIT 快照下首份财报披露之前fina_indicator_roe等字段为 NaN必须用None不参与判断与False数据不齐则排除区分处理而不是把 NaN 当成不满足条件粗暴过滤。七、使用注意事项与常见陷阱100 条/次限制全历史拉取必须按start_date/end_date或period分页循环fina_indicator_vip可解决按季度取全市场的需求但需要 5000 积分。单位一致性roe、netprofit_margin、*_yoy等字段返回百分数15 表示 15%与 yfinance 的十进制小数0.15不可直接混算eps等每股指标单位为元。公告日与报告期不可混淆策略因子取值必须挂在ann_date之后end_date只用于标识属于哪个报告期这正是本文所述 Provider 的 PIT 机制解决的问题。披露缺失新上市、退市整理期或 ST 标的可能缺少部分报告期的指标需在因子计算中显式处理 NaN。修订与重述同一报告期可能出现多行含修订值务必按(ts_code, end_date)去重并取最新披露仓库测试test_t1_query_fundamentals_deduplicates_restated_rows即覆盖该场景。权限与配额低于 2000 积分无法调用批量取数前建议用 Tushare 数据工具验证字段与返回条数再落地上游脚本。八、延伸阅读接口文档原始出处财务指标数据.md完整接口清单与分类tushare 技能 SKILL.md同目录下还有利润表、资产负债表、现金流量表、业绩快报、业绩预告、主营业务构成等财务数据接口Provider 源码agent/backtest/loaders/tushare_fundamentals.py测试用例agent/tests/test_tushare_fundamentals_provider.py基本面过滤实战技能agent/src/skills/fundamental-filter/SKILL.md 与 example_signal_engine.py获取数据示例agent/src/skills/tushare/scripts/stock_data_example.py掌握fina_indicator的字段语义与公告日可见性规则你就能在 Vibe-Trading 中构建不掺入未来信息的 ROE 选股、盈利质量过滤、杜邦分解等基本面策略让每一个因子都经得起样本外检验。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考