Vibe-Trading 实战:Tushare 指数技术面因子 idx_factor_pro 接口全解析与量化因子应用
Vibe-Trading 实战:Tushare 指数技术面因子 idx_factor_pro 接口全解析与量化因子应用
本篇技术指南聚焦 Tushare 专业版接口 idx_factor_pro(指数技术面因子),讲解其在个人交易 Agent 项目 Vibe-Trading 中用于指数走势跟踪、行业轮动分析与量化因子建模的具体用法。读完你将掌握该接口的权限门槛、输入输出参数、60 余个技术面因子的含义与参数来源,以及如何在 Python 中接入 Tushare Pro API 批量拉取大盘指数、申万行业指数与中信指数的每日因子数据,并与项目内已有的指数行情加载体系相互印证。
一、接口定位:指数层面的"预计算技术因子库"
idx_factor_pro 是 Tushare 提供的指数每日技术面因子接口,数据由 Tushare 社区自产,覆盖全历史。与需要自行调用行情后逐个计算指标的做法不同,该接口将指数行情(OHLCV)与大量经典技术指标预先计算并打包返回,一次请求即可同时获得:
- 指数基础行情:开高低收、昨收、涨跌额、涨跌幅、成交量、成交额;
- 趋势类因子:MA/EMA/EXPMA/BIAS/MACD/DFMA/DPO/MTM/ROC/TRIX 等;
- 摆动与超买超卖类因子:KDJ/RSI/CCI/WR/BOLL/ATR 等;
- 量能与情绪类因子:OBV/VR/MFI/PSY/BRAR/EMV/MASS 等;
- 通道与区间类因子:肯特纳通道(KTN)、唐安奇/海龟通道(TAQ)、薛斯通道(XSII)、区间极值(topdays/lowdays)等。
覆盖指数范围包括三类:大盘指数、申万行业指数、中信指数。该接口在项目技能文档中的登记信息位于 agent/src/skills/tushare/SKILL.md,接口 ID 为 358,分类归入"指数专题",接口描述与本文档一致。
权限与限量(务必先确认积分)
| 项目 | 限制 |
|---|---|
| 单次请求最大返回 | 8000 条记录 |
| 5000 积分 | 每分钟可请求 30 次 |
| 8000 积分以上 | 每分钟可请求 500 次 |
| 数据范围 | 覆盖全历史 |
| 复权口径 | 输出参数带 _bfq 后缀表示不复权 |
这里有一个与股票版接口的显著差异值得注意:股票技术面因子 stk_factor_pro 同时提供 _bfq/_qfq/_hfq 三套口径(见 股票技术面因子(专业版).md.md)),而指数版 idx_factor_pro 仅提供不复权(_bfq)口径。这符合指数本身的特性:指数点位是其成分股价格按权重合成的连续序列,天然跨越成分股除权除息日,因此无需再套用复权因子。
二、输入参数详解
接口支持按代码、按日期范围、按单日三种维度查询:
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| ts_code | str | N | 指数代码(大盘指数、申万指数、中信指数) |
| start_date | str | N | 开始日期 |
| end_date | str | N | 结束日期 |
| trade_date | str | N | 交易日期(单日查询用) |
所有日期均为 YYYYMMDD 格式字符串。由于单次最大返回 8000 条,对于覆盖全历史的批量任务,应通过设置 start_date/end_date 分片循环拉取,避免超出单次上限。指数代码可以通过 指数基本信息 接口(index_basic)查询,例如申万指数市场代码为 SW,返回如 801010.SI(农林牧渔)这类 xxxxxx.SI 格式的代码;大盘指数则形如 000001.SH、399300.SZ。
三、输出参数全表(完整字段清单)
以下按功能分组整理全部输出字段,均为 float 类型且默认显示(Y)。前 11 个字段为基础行情,其余为技术因子。注意:因子描述中给出的参数(如 M1=26, M2=10)即 Tushare 计算该因子的默认传参,如需特殊参数或更多因子需联系管理员评估,无法通过接口参数自定义。
3.1 指数基础行情
| 名称 | 描述 |
|---|---|
| ts_code | 指数代码 |
| trade_date | 交易日期 |
| open | 开盘价 |
| high | 最高价 |
| low | 最低价 |
| close | 收盘价 |
| pre_close | 昨收价 |
| change | 涨跌额 |
| pct_change | 涨跌幅(未复权;如需要复权口径请使用通用行情接口) |
| vol | 成交量(手) |
| amount | 成交额(千元) |
3.2 趋势与均线类因子
| 名称 | 描述 |
|---|---|
| ma_bfq_5 / ma_bfq_10 / ma_bfq_20 / ma_bfq_30 / ma_bfq_60 / ma_bfq_90 / ma_bfq_250 | 简单移动平均,N=5/10/20/30/60/90/250 |
| ema_bfq_5 / ema_bfq_10 / ema_bfq_20 / ema_bfq_30 / ema_bfq_60 / ema_bfq_90 / ema_bfq_250 | 指数移动平均,N=5/10/20/30/60/90/250 |
| expma_12_bfq / expma_50_bfq | EMA 指数平均数指标,N1=12, N2=50 |
| bias1_bfq / bias2_bfq / bias3_bfq | BIAS 乖离率,L1=6, L2=12, L3=24 |
| macd_bfq / macd_dif_bfq / macd_dea_bfq | MACD 指标,SHORT=12, LONG=26, M=9 |
| dfma_dif_bfq / dfma_difma_bfq | 平行线差指标,N1=10, N2=50, M=10 |
| dpo_bfq / madpo_bfq | 区间震荡线,M1=20, M2=10, M3=6 |
| mtm_bfq / mtmma_bfq | 动量指标,N=12, M=6 |
| roc_bfq / maroc_bfq | 变动率指标,N=12, M=6 |
| trix_bfq / trma_bfq | 三重指数平滑平均线,M1=12, M2=20 |
| bbi_bfq | BBI 多空指标,M1=3, M2=6, M3=12, M4=20 |
3.3 摆动与超买超卖类因子
| 名称 | 描述 |
|---|---|
| kdj_k_bfq / kdj_d_bfq / kdj_bfq | KDJ 指标,N=9, M1=3, M2=3 |
| rsi_bfq_6 / rsi_bfq_12 / rsi_bfq_24 | RSI 指标,N=6/12/24 |
| cci_bfq | 顺势指标(CCI),N=14 |
| wr_bfq / wr1_bfq | W&R 威廉指标,N=10, N1=6 |
| atr_bfq | 真实波动 N 日平均值(ATR),N=20 |
| boll_upper_bfq / boll_mid_bfq / boll_lower_bfq | BOLL 布林带,N=20, P=2 |
| asi_bfq / asit_bfq | 振动升降指标,M1=26, M2=10 |
| dmi_pdi_bfq / dmi_mdi_bfq / dmi_adx_bfq / dmi_adxr_bfq | 动向指标(DMI),M1=14, M2=6 |
| downdays / updays | 连跌天数 / 连涨天数 |
| lowdays / topdays | 当前最低/最高价是近多少周期内的极值(LOWRANGE/TOPRANGE) |
3.4 量能与情绪类因子
| 名称 | 描述 |
|---|---|
| obv_bfq | 能量潮指标(OBV),CLOSE, VOL |
| vr_bfq | VR 容量比率,M1=26 |
| mfi_bfq | MFI 指标(成交量的 RSI),N=14 |
| psy_bfq / psyma_bfq | 投资者心理情绪指标,N=12, M=6 |
| brar_ar_bfq / brar_br_bfq | BRAR 情绪指标,M1=26 |
| emv_bfq / maemv_bfq | 简易波动指标,N=14, M=9 |
| mass_bfq / ma_mass_bfq | 梅斯线(MASS),N1=9, N2=25, M=6 |
| cr_bfq | CR 价格动量指标,N=20 |
3.5 通道与区间类因子
| 名称 | 描述 |
|---|---|
| ktn_upper_bfq / ktn_mid_bfq / ktn_down_bfq | 肯特纳交易通道,N=20(选 20 日),M=10(ATR 选 10 日) |
| taq_up_bfq / taq_mid_bfq / taq_down_bfq | 唐安奇通道(海龟交易指标),HIGH, LOW, 20 |
| xsii_td1_bfq / xsii_td2_bfq / xsii_td3_bfq / xsii_td4_bfq | 薛斯通道 II,N=102, M=7 |
四、Python 调用示例
在 Vibe-Trading 项目中,Tushare 的 token 统一通过环境变量 TUSHARE_TOKEN 管理(见 agent/src/config/env_schema.py 中 tushare_token 字段的定义),也可借助项目配置访问器读取。以下代码同时演示了三种查询方式:
import os
import tushare as ts
# 方式一:环境变量(与项目 env_schema 中的 TUSHARE_TOKEN 对齐)
token = os.getenv("TUSHARE_TOKEN")
# 方式二:tushare 本地记录的 token
token = token or ts.get_token()
# 初始化 pro 接口实例
pro = ts.pro_api(token)
# 1) 按指数代码 + 日期范围查询(上证指数历史技术因子)
df = pro.idx_factor_pro(
ts_code="000001.SH",
start_date="20240101",
end_date="20241231",
)
print(df.head())
# 2) 按单日 trade_date 查询截面(如某交易日全部申万行业指数因子)
df_sw = pro.idx_factor_pro(trade_date="20241231")
# 3) 只取需要的字段,节省流量
df_sub = pro.idx_factor_pro(
ts_code="399300.SZ", # 沪深300
start_date="20240101",
end_date="20241231",
fields="ts_code,trade_date,close,pct_change,macd_dif_bfq,macd_dea_bfq,ma_bfq_20,rsi_bfq_14" or None,
)
需要特别说明:第 3 个示例中的 fields 参数是否可用以实际接口文档为准;如果接口不支持字段筛选,可先全量拉取再用 DataFrame 的列索引切片(df[["ts_code","trade_date","macd_dif_bfq","ma_bfq_20"]])。由于单次上限 8000 条,且指数数量(申万与中信行业指数合计数百只)× 全历史交易日远超该限制,批量任务必须按代码与日期窗口双重分片,同时注意 5000 积分档每分钟 30 次的频率上限。
五、因子数据与项目行情体系的印证
Vibe-Trading 的回测系统已内置 Tushare 数据加载器 agent/backtest/loaders/tushare.py,其指数处理逻辑与本文档存在多处相互印证,可用于理解因子数据的口径:
- 指数不复权:loader 中
_fetch_daily_frame对指数(_is_index判定的000xxx.SH/399xxx.SZ代码)走index_daily接口,且注释明确"指数点位在成分股除权除息日之间本来就是连续的",因此adjust = None不做复权——这正是idx_factor_pro仅提供_bfq口径的底层原因; - 单位约定:
vol单位为"手"、amount单位为"千元",loader 中同时把vol重命名为volume供引擎统一消费,并标注 A 股volume_units = {"a_share": "lots"}; - 频率控制:loader 实现了基于错误文案识别的限频退避重试机制(
_RATE_LIMIT_MARKERS与_call_with_backoff,退避节奏 5s/20s/40s),说明 Tushare 接口的"每分钟次数"配额是实际开发中必须处理的约束,idx_factor_pro的积分档位同样适用; - 代码路由:loader 通过代码前缀区分股票(
daily)、ETF(fund_daily)、指数(index_daily)、港股(hk_daily),而指数技术因子接口覆盖的大盘/申万/中信指数分别对应index_daily、申万行情(sw_daily)、中信行情(ci_daily)三大行情通道,因子数据可视为这三类行情的"增强列"。
六、实战应用建议
- 趋势跟踪:用
ma_bfq_20/60与macd_dif_bfq判断大盘与行业指数趋势方向;ema_bfq_250作为长期牛熊分界线。 - 超买超卖择时:
rsi_bfq_6/12、kdj_bfq、cci_bfq可在指数层面刻画短期情绪极值,用于仓位调节而非个股择股。 - 波动率管理:
atr_bfq(N=20)直接给出指数 20 日平均真实波幅,可作为风险预算或止盈止损距离的参考基准。 - 行业轮动:批量拉取申万一级行业指数(
801xxx.SI)的pct_change与mfi_bfq(量价结合),可量化行业强度排名与资金活跃度,支撑轮动打分。 - 区间突破:
taq_up_bfq/taq_down_bfq(海龟 20 日通道)与ktn_upper_bfq/ktn_down_bfq可用于定义指数级别的趋势突破信号。
需要再次强调的注意事项:因子全部为不复权口径,比较不同时期数值时注意指数点位本身的连续性;因子参数为服务端固定默认值,特殊需求需联系管理员评估;数据由社区自产,用于研究分析时请遵守 Tushare 的数据使用条款,避免商业性再分发。
七、关联资料
- 接口在技能体系中的登记:agent/src/skills/tushare/SKILL.md(ID 358,指数专题)
- 指数代码来源:指数基本信息(
index_basic,申万市场代码 SW) - 指数日线行情:指数日线行情(
index_daily) - 同系列对比:股票技术面因子(专业版).md)(
stk_factor_pro,含 qfq/hfq 口径) - 项目侧数据接入:agent/backtest/loaders/tushare.py
- 通用代码示例:股票数据获取示例(展示 token 初始化与 pro 接口调用范式)