Vibe-Trading 数据技能指南:Tushare 股票技术面因子专业版 stk_factor_pro 接口全解

原创2026-09-11 18:22:052,858 阅读
文章标签:人工智能AI Agent金融科技后端前端CLI数据分析数据可视化MCP 服务本地部署

Vibe-Trading 数据技能指南:Tushare 股票技术面因子专业版 stk_factor_pro 接口全解

本篇指南围绕 Vibe-Trading 项目中 Tushare 数据技能 的《股票技术面因子(专业版)》参考文档展开,系统拆解 stk_factor_pro 接口的输入输出参数、三大复权体系(不复权/前复权/后复权)以及内置的数十类技术指标默认参数。读完本文,你将掌握如何通过 Tushare 单次调用同时获得行情、估值、股本市值与 MA/MACD/KDJ/RSI/BOLL 等技术因子,并了解该数据在 Vibe-Trading 因子研发与回测流程中的接入方式。

一、接口定位:一次调用拿到“行情 + 估值 + 技术指标”全家桶

stk_factor_pro 是 Tushare 社区自产的专业版股票技术面因子接口,用于跟踪股票的每日走势情况,数据覆盖 A 股全历史。与普通日线接口(pro.daily)只返回 OHLCV 不同,该接口在单条记录内同时打包了三类信息:

  • 行情价格:开高低收及前后复权版本,覆盖 _bfq(不复权)、_qfq(前复权)、_hfq(后复权)三种口径;
  • 估值与股本:PE / PE(TTM) / PB / PS / 股息率、总股本 / 流通股本 / 自由流通股本、总市值 / 流通市值;
  • 技术指标:由 Tushare 社区按各指标的默认参数计算好的 30+ 类常用技术因子(趋势、摆动、波动、量能、通道类一应俱全),同样提供三种复权口径。

这意味着在量化研究场景中,一次 stk_factor_pro 调用即可替代「日线行情 + 每日指标 + 自算技术指标」多次请求的组合,显著降低数据获取成本与本地计算负担。

在接口文档体系中,该接口归类于 股票数据 → 特色数据.md),并在 Tushare 技能 SKILL.md 的数据接口总表 中以 ID 328(接口名 stk_factor_pro)登记注册。

访问约束与积分要求

项目 说明
单次限量 最多返回 10000 条数据,超出的历史区间需通过日期参数分段循环拉取
积分门槛 5000 积分:每分钟可请求 30 次;8000 积分以上:每分钟 500 次
数据时效 每日收盘后更新,用于跟踪当前走势情况
参数定制 各因子默认参数见接口描述;如需特殊参数或更多因子,需联系管理员评估

二、输入参数详解

stk_factor_pro 的输入参数非常精简,四个字段全部为可选参数,可通过「股票代码」或「交易日期」两类维度组合查询:

名称 类型 必选 描述
ts_code str N 股票代码,Tushare 标准格式,如 000001.SZ、600000.SH、430047.BJ
trade_date str N 交易日期,格式 yyyymmdd,如 20250110
start_date str N 开始日期,格式 yyyymmdd
end_date str N 结束日期,格式 yyyymmdd

使用要点:

  • 按单日全市场提取:传入 trade_date 即可获取该交易日全部股票的因子截面,适合做横截面选股/因子暴露分析;
  • 按个股区间提取:传入 ts_code + start_date + end_date 获取单只股票的时间序列,适合做个股策略回测;
  • 分段循环:由于单次上限 10000 条,个股历史较长或多只股票批量拉取时,应以日为单位循环请求再拼接(下文给出参考实现)。

三、输出参数全景

3.1 行情与复权价格

字段 类型 说明
ts_code / trade_date str 股票代码 / 交易日期
open / high / low / close float 开盘价 / 最高价 / 最低价 / 收盘价(不复权)
open_hfq / high_hfq / low_hfq / close_hfq float 后复权价格
open_qfq / high_qfq / low_qfq / close_qfq float 前复权价格
pre_close float 昨收价(前复权),为 daily 接口的 pre_close,按当时复权因子计算,与前一日 close_qfq 存在口径差异,可不用
change / pct_chg float 涨跌额 / 涨跌幅(除权后的涨跌幅)
vol / amount float 成交量(手)/ 成交额(千元)

3.2 估值与股本市值

字段 类型 说明
pe / pe_ttm float 市盈率(总市值/净利润,亏损为 null)/ 市盈率 TTM(亏损为 null)
pb float 市净率(总市值/净资产)
ps / ps_ttm float 市销率 / 市销率 TTM
dv_ratio / dv_ttm float 股息率(%)/ 股息率 TTM(%)
total_share / float_share / free_share float 总股本(万股)/ 流通股本(万股)/ 自由流通股本(万)
total_mv / circ_mv float 总市值(万元)/ 流通市值(万元)
adj_factor float 复权因子

3.3 量能与活跃度

字段 类型 说明
turnover_rate / turnover_rate_f float 换手率(%)/ 换手率(自由流通股口径,%)
volume_ratio float 量比
updays / downdays float 连涨天数 / 连跌天数
lowdays / topdays float LOWRANGE(LOW) 当前最低价处于近多少周期最低 / TOPRANGE(HIGH) 当前最高价处于近多少周期最高

3.4 技术指标因子(三种复权口径 × 各类指标)

技术指标字段按 指标名_复权口径 命名,_bfq / _qfq / _hfq 三种后缀各一份,默认参数均标注在字段描述中。完整清单如下:

指标族 字段(每种含 _bfq/_qfq/_hfq 三口径) 默认参数
振动升降 asi、asit OPEN, CLOSE, HIGH, LOW, M1=26, M2=10
真实波幅 atr CLOSE, HIGH, LOW, N=20
多空指标 bbi CLOSE, M1=3, M2=6, M3=12, M4=20
乖离率 bias1、bias2、bias3 CLOSE, L1=6, L2=12, L3=24
布林带 boll_upper、boll_mid、boll_lower CLOSE, N=20, P=2
BRAR 情绪 brar_ar、brar_br OPEN, CLOSE, HIGH, LOW, M1=26
顺势指标 cci CLOSE, HIGH, LOW, N=14
价格动量 cr CLOSE, HIGH, LOW, N=20
平行线差 dfma_dif、dfma_difma CLOSE, N1=10, N2=50, M=10
动向指标 dmi_adx、dmi_adxr、dmi_mdi、dmi_pdi CLOSE, HIGH, LOW, M1=14, M2=6
区间震荡线 dpo、madpo CLOSE, M1=20, M2=10, M3=6
指数移动平均 ema_5、ema_10、ema_20、ema_30、ema_60、ema_90、ema_250 N=5/10/20/30/60/90/250
简易波动 emv、maemv HIGH, LOW, VOL, N=14, M=9
EMA 指数平均 expma_12、expma_50 CLOSE, N1=12, N2=50
KDJ kdj、kdj_k、kdj_d CLOSE, HIGH, LOW, N=9, M1=3, M2=3
肯特纳通道 ktn_upper、ktn_mid、ktn_down CLOSE, HIGH, LOW, N=20, M=10
简单移动平均 ma_5、ma_10、ma_20、ma_30、ma_60、ma_90、ma_250 N=5/10/20/30/60/90/250
MACD macd、macd_dif、macd_dea CLOSE, SHORT=12, LONG=26, M=9
梅斯线 mass、ma_mass HIGH, LOW, N1=9, N2=25, M=6
资金流量 mfi CLOSE, HIGH, LOW, VOL, N=14
动量指标 mtm、mtmma CLOSE, N=12, M=6
能量潮 obv CLOSE, VOL
心理线 psy、psyma CLOSE, N=12, M=6
变动率 roc、maroc CLOSE, N=12, M=6
RSI rsi_6、rsi_12、rsi_24 CLOSE, N=6/12/24
唐安奇通道 taq_up、taq_mid、taq_down HIGH, LOW, 20
三重指数平滑 trix、trma CLOSE, M1=12, M2=20
容量比率 vr CLOSE, VOL, M1=26
威廉指标 wr、wr1 CLOSE, HIGH, LOW, N=10, N1=6
薛斯通道 II xsii_td1、xsii_td2、xsii_td3、xsii_td4 CLOSE, HIGH, LOW, N=102, M=7

注:接口文档中 bbi 的 _bfq/_hfq/_qfq 三口径分别记录了 M4=20/21/22 的默认传参,使用时应以接口文档最新描述为准;如需自定义周期或更多因子,需联系管理员评估开通。

四、三大复权口径的语义与选型

复权是 A 股数据使用中最容易出错的一环。stk_factor_pro 将价格与指标同时按三种口径输出,便于不同场景直接取用:

  • 不复权(_bfq):真实成交价格,适合计算真实涨跌幅、成交量价关系分析;
  • 前复权(_qfq):以最新价为基准向前调整历史价格,历史价格序列连续,适合技术指标计算与回测——当前价格不受历史除权事件影响,避免了指标因分红送转产生虚假跳变;
  • 后复权(_hfq):以上市首日价为基准向后累乘复权因子,总回报连续可叠加,适合长期收益率测算;
  • adj_factor:复权因子本身。后复权价 ≈ 不复权价 × 复权因子,前复权价则在此基础上按最新一期因子归一化。

需要特别留意文档中关于 pre_close 的提示:该字段直接取自 daily 接口的 pre_close,其计算基于当时的复权因子,因此可能与前一日的 close_qfq 对不上,若对复权价格序列的连续性有严格要求,建议不要依赖该字段。

五、实战调用示例

5.1 初始化 Tushare 客户端

Vibe-Trading 的 Tushare 技能 SKILL.md 给出了标准的接入方式:安装依赖、配置 token、初始化 pro 接口。

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple
export TUSHARE_TOKEN=your_token
import os
import tushare as ts

# 优先读取环境变量 token,也支持 ts.get_token() 本地缓存
token = os.getenv('TUSHARE_TOKEN') or ts.get_token()
pro = ts.pro_api(token)

在 Vibe-Trading 项目中,token 的统一读取路径是配置访问器:源码 tushare_fallbacks.py 中通过 get_env_config().data.tushare_token 获取,并对空占位符(""、"your-tushare-token")做了未配置拦截;日常脚本也可参考 stock_data_example.py 的写法。

5.2 按单日提取全市场因子截面

import tushare as ts

pro = ts.pro_api(os.getenv('TUSHARE_TOKEN'))

# 提取某交易日全市场股票的估值 + 技术因子
df = pro.stk_factor_pro(
    trade_date='20250110',
    fields='ts_code,trade_date,close,pe_ttm,pb,total_mv,'
           'macd_dif,macd_dea,macd,kdj_k,kdj_d,'
           'ma_5,ma_10,ma_20,ema_5,ema_20,rsi_6,rsi_12,rsi_24'
)
print(df.head())

字段按需裁剪可以显著降低响应体积,尤其在 10000 条上限约束下,fields 白名单是高效拉取的关键手段。

5.3 按个股区间循环拉取全历史

import tushare as ts

pro = ts.pro_api(os.getenv('TUSHARE_TOKEN'))

ts_code = '000001.SZ'
start_date, end_date = '20200101', '20250110'

# 单次最多 10000 条,历史较长时按自然日循环拼接
frames = []
cur = start_date
while cur <= end_date:
    chunk = pro.stk_factor_pro(
        ts_code=ts_code,
        start_date=cur,
        end_date=end_date,
    )
    if chunk is None or chunk.empty:
        break
    frames.append(chunk)
    # 以已获取的最大交易日期 +1 天作为下一次起点,保证边界不重不漏
    cur = str(int(chunk['trade_date'].max()) + 1)
    # 注意控制请求频率,5000 积分档位为每分钟 30 次

result = pd.concat(frames, ignore_index=True).drop_duplicates('trade_date')
print(result.shape)

六、在 Vibe-Trading 项目中的接入与应用

6.1 作为 Agent 数据技能接入

Vibe-Trading 将 Tushare 以「标准化技能」的形式暴露给 Agent 使用:技能根目录的 SKILL.md 登记了完整的接口索引表,stk_factor_pro(ID 328)被归类到股票数据 → 特色数据,并与指数版本 idx_factor_pro(ID 358)、基金版本 fund_factor_pro(ID 359)、可转债版本 cb_factor_pro(ID 392)形成同一「专业版因子」系列。从源码结构看,Agent 在策略研究任务中通过该技能目录即可检索到本接口的输入输出契约,进而编排数据获取流程。

6.2 与项目现有 Tushare 数据链路的关系

仓库中对 Tushare 数据源的底层封装集中体现在两处,可作为接入本接口时的代码风格参照:

  • tushare_fallbacks.py:提供资金流向、龙虎榜、北向资金、融资融券等工具的 Tushare 备用通道,展示了 token 校验、ts.pro_api() 初始化、DataFrame.to_dict('records') 标准化输出、日期窗口(_date_window)处理等通用模式;
  • alpha_bench_tool.py:构建 CSI300 基准时调用 pro.daily + pro.adj_factor 获取前复权价格(源码见 alpha_bench_tool.py),这正对应 stk_factor_pro 内置 close_qfq 与 adj_factor 字段的用途——若改用本接口,可一次取回复权价与估值因子,减少往返请求。

此外,仓库回测引擎(如 china_a.py)与因子库(agent/src/factors,包含 477 个 Python 因子实现文件)构成了完整的数据 → 因子 → 回测链路,stk_factor_pro 输出的估值字段与技术指标字段可直接作为该链路的输入来源之一。

6.3 典型应用场景

  • 横截面选股:按 trade_date 一次拉取全市场 pe_ttm、pb、total_mv、turnover_rate、volume_ratio,构建低估值/小市值/高换手等因子组合;
  • 技术面策略信号:直接使用 macd_dif/macd_dea、kdj_k/kdj_d、rsi_6/12/24、boll_upper/mid/lower 等字段生成金叉死叉、超买超卖、通道突破信号,免去本地重复实现指标公式;
  • 连涨连跌统计:updays / downdays / lowdays / topdays 可用于动量与反转因子的构造;
  • 复权一致性校验:close_qfq 与本地 daily × adj_factor 计算结果交叉验证,确保因子库价格口径统一。

七、使用注意事项

  1. 限量与频率:单次 10000 条、5000 积分档每分钟 30 次、8000 积分以上每分钟 500 次,批量任务务必加入频率控制与重试;
  2. 数据完整期:接口覆盖全历史,但社区自产数据可能存在个别日期缺失,建议与 daily、daily_basic 等接口交叉校验;
  3. 复权口径一致性:同一策略内应固定使用同一复权口径(推荐 _qfq),避免 _bfq 与 _qfq 混用导致指标失真;pre_close 字段存在口径偏差,谨慎使用;
  4. 字段裁剪:接口字段超过 200 个,默认全量返回会放大单次请求体积,生产环境应始终通过 fields 白名单按需提取;
  5. 自定义参数:如需非默认周期的指标参数(例如 N=30 的 ATR 或自定义 BOLL 带宽),需联系 Tushare 管理员评估,本地则建议基于 _bfq/_qfq 价格自算。

八、延伸阅读

  • 本接口参考文档:股票技术面因子(专业版).md)
  • 同系列专业版因子接口:指数技术面因子(专业版).md)、基金技术面因子(专业版).md)、可转债技术面因子(专业版).md)
  • 估值字段对照接口:每日指标 daily_basic
  • 技能总览与全部接口索引:Tushare SKILL.md
  • 示例脚本:股票数据获取示例
登录后查看全文
Vibe-Trading