天勤量化 TqSdk 技术指标与序列计算函数实战指南:tqsdk.ta 与 tqsdk.tafunc 从入门到源码

原创2026-10-13 12:31:401,882 阅读
文章标签:金融科技数据分析

天勤量化 TqSdk 技术指标与序列计算函数实战指南:tqsdk.ta 与 tqsdk.tafunc 从入门到源码

本文聚焦 TqSdk(tqsdk-python)量化开发包中的 tqsdk.ta 技术指标模块与 tqsdk.tafunc 序列计算函数模块,讲解如何基于 get_kline_serial() 获取的 K 线序列快速计算 MACD、BOLL、KDJ、RSI 等经典指标,并深入底层源码解析移动平均、条件穿越、期权定价等函数的实现原理。读完本文,你将能够直接在策略中调用 50 余种技术指标与 30 余个序列计算函数,并理解其返回结构、参数含义与边界行为。

一、模块总览:ta 与 tafunc 的分工协作

在 TqSdk 中,技术指标计算被拆分为两个相互配合的模块:

  • tqsdk.ta(技术指标模块):包含大量常用技术指标。每个指标是一个函数,函数名为全大写(如 MACD、KDJ、BOLL),第一个参数总是 K 线序列(pandas.DataFrame 格式),并以 pandas.DataFrame 格式返回计算结果。对应实现文件为 tqsdk/ta.py。
  • tqsdk.tafunc(序列计算函数模块):包含一批序列计算函数,它们是构成技术指标的基础原子操作,参数与返回值基本保持为 pandas.Series 类型(源码文件头注释明确说明:"函数基本保持 参数为pandas.Series类型则返回值为pandas.Series类型")。对应实现文件为 tqsdk/tafunc.py。

两者的使用关系非常直接:ta 中的高级指标内部大量调用 tafunc 的基础函数完成计算。例如 tqsdk/ta.py 中 MACD 的实现(见 tqsdk/ta.py#L227-L269)就调用了 tqsdk.tafunc.ema;ATR 的实现(tqsdk/ta.py#L18-L54)调用了 tqsdk.tafunc.ma;MA、SMA、EMA、EMA2、TRMA 等指标则直接是对 tafunc 同名函数的 DataFrame 包装(见 tqsdk/ta.py#L2339-L2492)。因此理解 tafunc 是掌握整个指标体系的钥匙。

原文档给出了最简单的 MACD 用法示例:

from tqsdk.ta import MACD

klines = api.get_kline_serial("SHFE.cu2607", 60)   # 提取SHFE.cu2607的分钟线
result = MACD(klines, 12, 26, 9)                   # 计算MACD指标
print(result["diff"])                              # MACD指标中的diff序列

tqsdk.ta 与 tqsdk.tafunc 中提供的完整函数详表,由 Sphinx 从源码 docstring 自动生成,见 doc/reference/tqsdk.ta.rst 与 doc/reference/tqsdk.tafunc.rst。

二、快速上手:在策略中计算技术指标

2.1 MACD:三步完成指标计算

以原文档的 MACD 为例,完整的调用流程是:

from tqsdk import TqApi, TqAuth, TqSim
from tqsdk.ta import MACD

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
klines = api.get_kline_serial("CFFEX.IF1903", 24 * 60 * 60)   # 获取日线序列
macd = MACD(klines, 12, 26, 9)                                 # 计算MACD
print(list(macd["diff"]))                                      # 离差值
print(list(macd["dea"]))                                       # DIFF的指数加权移动平均线
print(list(macd["bar"]))                                       # MACD柱状线
api.close()

需要注意 MACD 返回值的一个细节陷阱:pandas.DataFrame 本身有 diff() 方法,因此获取该指标后,"diff" 字段必须使用 macd<a href="https://link.gitcode.com/i/2a2f177111b299f08c4bd219e67fdae2" target="_blank">"diff"] 方式取值,而不能写成 macd.diff(源码 docstring 中专门以注释标注了这一点,见 [tqsdk/ta.py#L243)。

从源码看,MACD(df, short, long, m) 的计算逻辑(tqsdk/ta.py#L263-L269)为:

new_df["diff"] = tqsdk.tafunc.ema(df["close"], short) - tqsdk.tafunc.ema(df["close"], long)
new_df["dea"]  = tqsdk.tafunc.ema(new_df["diff"], m)
new_df["bar"]  = 2 * (new_df["diff"] - new_df["dea"])

即先用收盘价的短周期 EMA 减去长周期 EMA 得到 diff,再对 diff 做 m 周期 EMA 得到 dea,柱状线 bar 取两倍差值。可见经典参数 (12, 26, 9) 只是推荐值,你可以按策略需要自由调整。

2.2 统一约定:第一参数是 K 线序列

所有 tqsdk.ta 指标函数都遵循同样的约定:第一参数 df 是 api.get_kline_serial() 返回的 pandas.DataFrame 格式 K 线序列。源码中每个指标 docstring 均标注了 df (pandas.DataFrame): Dataframe格式的K线序列。指标内部直接读取 df["open"]、df["high"]、df["low"]、df["close"]、df["volume"]、df["close_oi"] 等标准列,因此你只需要保证传入的是 TqSdk K 线序列即可,无需手动构造数据。

三、tqsdk.ta 技术指标全览

tqsdk.ta 目前提供 50 余个技术指标(以 tqsdk/ta.py 实际实现为准),覆盖趋势、摆动、量能、通道、期权五大类。下表按源码顺序整理了全部指标及其返回列,方便检索:

指标函数 中文名 返回列(DataFrame 列名)
ATR(df, n) 平均真实波幅 tr(真实波幅)、atr(平均真实波幅)
BIAS(df, n) 乖离率 bias
BOLL(df, n, p) 布林线 mid(中轨)、top(上轨)、bottom(下轨)
DMI(df, n, m) 动向指标 atr、pdi(上升方向线)、mdi(下降方向线)、adx、adxr
KDJ(df, n, m1, m2, flat_value=0) 随机指标 k、d、j
MACD(df, short, long, m) 异同移动平均线 diff、dea、bar
SAR(df, n, step, max) 抛物线指标 sar
WR(df, n) 威廉指标 wr
RSI(df, n) 相对强弱指标 rsi
ASI(df) 振动升降指标 asi
VR(df, n) 容量比率 vr
ARBR(df, n) 人气意愿指标 ar(人气指标)、br(意愿指标)
DMA(df, short, long, m) 平均线差 ddd、ama
EXPMA(df, p1, p2) 指数加权移动平均线组合 ma1、ma2
CR(df, n, m) CR 能量 cr、crma
CCI(df, n) 顺势指标 cci
OBV(df) 能量潮 obv
CDP(df, n) 逆势操作 ah、al、nh、nl
HCL(df, n) 均线通道 mah、mal、mac
ENV(df, n, k) 包络线(Envelopes) upper、lower
MIKE(df, n) 麦克指标 wr、mr、sr、ws、ms、ss(三级压力与三级支撑)
PUBU(df, m) 瀑布线 pb
BBI(df, n1, n2, n3, n4) 多空指数 bbi
DKX(df, m) 多空线 b、d
BBIBOLL(df, n, m) 多空布林线 bbiboll、upr、dwn
ADTM(df, n, m) 动态买卖气指标 adtm、adtmma
B3612(df) 三减六日乖离率 b36、b612
DBCD(df, n, m, t) 异同离差乖离率 dbcd、mm
DDI(df, n, n1, m, m1) 方向标准离差指数 ddi、addi、ad
KD(df, n, m1, m2) 随机指标(K/D) k、d
LWR(df, n, m) 威廉指标(LWR) lwr
MASS(df, n1, n2) 梅斯线 mass
MFI(df, n) 资金流量指标 mfi
MI(df, n) 动量指标 a、mi
MICD(df, n, n1, n2) 异同离差动力指数 dif、micd
MTM(df, n, n1) MTM 动力指标 mtm、mtmma
PRICEOSC(df, long, short) 价格震荡指数 priceosc
PSY(df, n, m) 心理线 psy、psyma
QHLSR(df) 阻力指标 qhl5、qhl10
RC(df, n) 变化率指数 arc
RCCD(df, n, n1, n2) 异同离差变化率指数 dif、rccd
ROC(df, n, m) 变动速率 roc、rocma
SLOWKD(df, n, m1, m2, m3) 慢速 KD k、d
SRDM(df, n) 动向速度比率 srdm、asrdm
SRMI(df, n) MI 修正指标 a、mi
ZDZB(df, n1, n2, n3) 筑底指标 b、d
DPO(df) 区间震荡线 dpo
LON(df) 长线指标 lon、ma1
SHORT(df) 短线指标 short、ma1
MV(df, n, m) 均量线 mv1、mv2
WAD(df, n, m) 威廉多空力度线 a、b、e
AD(df) 累积/派发指标 ad
CCL(df) 持仓异动 ccl
CJL(df) 成交量 vol、opid
OPI(df) 持仓量 opi
PVT(df) 价量趋势指数 pvt
VOSC(df, short, long) 移动平均成交量指标 vosc
VROC(df, n) 量变动速率 vroc
VRSI(df, n) 量相对强弱 vrsi
WVAD(df) 威廉变异离散量 wvad
MA(df, n) 简单移动平均线 ma
SMA(df, n, m) 扩展指数加权移动平均 sma
EMA(df, n) 指数加权移动平均线 ema
EMA2(df, n) 线性加权移动平均(WMA) ema2
TRMA(df, n) 三角移动平均线 trma
BS_VALUE(df, quote, r=0.025, v=None) 期权 BS 模型理论价格 bs_price
OPTION_GREEKS(df, quote, r=0.025, v=None) 期权希腊指标 delta、theta、gamma、vega、rho
OPTION_VALUE(df, quote) 期权内在价值/时间价值 intrins、time
OPTION_IMPV(df, quote, r=0.025) 期权隐含波动率 impv
VOLATILITY_CURVE(df, quotes, underlying, r=0.025) 期权隐含波动率曲面 各行权价列为列名

3.1 典型指标使用示例

仓库自带演示脚本 tqsdk/demo/ta.py 一次性展示了多种指标在 10 秒 K 线上的用法:

from tqsdk import TqApi, TqAuth
from tqsdk.ta import *

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
klines = api.get_kline_serial("SHFE.cu1910", 10, data_length=3000)

print("ATR", ATR(klines, 26))
print("BIAS", BIAS(klines, 6))
print("BOLL", BOLL(klines, 3, 5))
print("DMI", DMI(klines, 14, 6))
print("KDJ", KDJ(klines, 9, 3, 3))
print("MA", MA(klines, 3))
print("MACD", MACD(klines, 20, 35, 10))
print("SAR", SAR(klines, 4, 0.02, 0.2))
api.close()

这里 data_length=3000 指定了提取 3000 根 K 线——对于周期类指标(如周期 35 的 MACD),充足的序列长度可以避免早期数值为 NaN。

几个有代表性的指标实现要点:

  • ATR(tqsdk/ta.py#L46-L54):先比较 high-low、|pre_close-high|、|pre_close-low| 三组差值,取最大者为真实波幅 tr,再用 tafunc.ma(tr, n) 得到平均真实波幅 atr。
  • BOLL(tqsdk/ta.py#L120-L126):中轨为 n 周期简单移动平均,上下轨为中轨加减 p 倍标准差,即 top = mid + p * std、bottom = mid - p * std。
  • KDJ(tqsdk/ta.py#L217-L224):先计算 RSV,再通过 tafunc.sma 平滑得到 K、D,最后 j = 3k - 2d。注意它带有一个 flat_value=0 参数,用于处理"最高价等于最低价"的极端 K 线(源码用 np.where(hv == lv, flat_value, ...) 规避除零)。
  • SAR(tqsdk/ta.py#L313-L349):内部通过独立的 _sar() 函数以循环方式逐根推进计算加速因子与极值点,属于唯一带状态迭代的指标。
  • CCL 持仓异动(tqsdk/ta.py#L2107-L2113):返回值不是数值而是字符串标签,如 "多头增仓"、"空头减仓" 等,适合直接用于复盘分析。

四、tqsdk.tafunc 序列计算函数详解

4.1 原文档核心例子:对任意序列做移动平均

tafunc 最大的价值在于灵活组合。技术指标 MA 总是按收盘价计算,但如果你需要最高价的均线,可以直接使用 tafunc.ma 作用于任意 pandas.Series:

from tqsdk.tafunc import ma

klines = api.get_kline_serial("SHFE.cu2607", 60)   # 提取SHFE.cu2607的分钟线
result = ma(klines.high, 9)                        # 按K线的最高价序列做9分钟移动平均
print(result)                                      # 移动平均结果

ma(series, n) 的底层实现(tqsdk/tafunc.py#L79-L108)是 series.rolling(n).mean(),即 n 周期窗口内等权平均。源码注释给出了精确公式:ma(x, 5) = (x(1) + x(2) + x(3) + x(4) + x(5)) / 5,并强调"简单移动平均线将设定周期内的值取平均值,其中各元素的权重都相等"。

4.2 函数分类与实现原理

tqsdk.tafunc 中的序列计算函数(tqsdk/tafunc.py)可归纳为以下几类:

移动平均与平滑类

函数 说明 底层实现
ma(series, n) 简单移动平均 series.rolling(n).mean()
sma(series, n, m) 扩展指数加权移动平均(需 n > m) series.ewm(alpha=m/n, adjust=False).mean()
ema(series, n) 指数加权移动平均(n >= 1) series.ewm(span=n, adjust=False).mean()
ema2(series, n) 线性加权移动平均 WMA rolling(n).apply(average, raw=True),权重 1..n
trma(series, n) 三角移动平均 对 MA 再做一次 MA(ma(ma(series, n1), n2))
harmean(series, n) 调和平均 n / ((1/series).rolling(n).sum())
numpow(series, n, m) 自然数幂方和 sum((n-i)**m * series.shift(i))

以 ema 为例(tqsdk/tafunc.py#L143-L172),其递推公式为 ema(x, n) = 2 * x / (n + 1) + (n - 1) * ema(x, n).shift(1) / (n + 1),即"对距离当前较近的 K 线赋予了较大的权重"。

极值与统计类

函数 说明 底层实现
hhv(series, n) n 周期内最高值 series.rolling(n).max()
llv(series, n) n 周期内最低值 series.rolling(n).min()
std(series, n) n 周期标准差 series.rolling(n).std()
median(series, n) n 周期中位数 series.rolling(n).median()
avedev(series, n) 平均绝对偏差 rolling(n).apply(mad),其中 `mad =
abs(series) 绝对值 np.absolute(series)
min(series1, series2) / max(series1, series2) 两个序列逐元素取最小/最大 np.minimum / np.maximum

条件判断与信号类

函数 说明
ref(series, n) 序列位移 n 个周期(series.shift(n)),n=0 返回原序列
crossup(a, b) a 从下方向上穿越 b 时为 1,否则 0((a > b) & (a.shift(1) <= b.shift(1)))
crossdown(a, b) a 从上方向下穿越 b 时为 1,否则 0((a < b) & (a.shift(1) >= b.shift(1)))
count(cond, n) 统计 n 周期内条件成立次数;n=0 时从第一个有效值开始累计
exist(cond, n) n 周期内条件至少成立一次为 1,否则 0
every(cond, n) n 周期内条件全部成立为 1,否则 0
barlast(cond) 返回从上一次条件成立到当前的周期数(此前无成立返回 -1,成立当期为 0)

其中 crossup/crossdown 是双均线策略最常见的信号来源。源码实现(tqsdk/tafunc.py#L210-L257)通过 np.where 判断"当前 a 在 b 上方且上一周期 a 不在 b 上方"来精确捕捉穿越当根 K 线,返回 0/1 标志序列,可直接与 count、exist 等函数串联使用。

4.3 时间转换辅助函数

除行情序列计算外,tafunc 还提供了一组时间转换函数,用于处理 TqSdk 特有的纳秒级时间戳(K 线 datetime 字段是自 Unix Epoch 以来的纳秒数):

  • time_to_ns_timestamp(input_time):将 str(%Y-%m-%d %H:%M:%S.%f 格式)、秒级/纳秒级时间戳、datetime.datetime 统一转为纳秒级时间戳;
  • time_to_s_timestamp(input_time):转为秒级时间戳;
  • time_to_str(input_time):转为 %Y-%m-%d %H:%M:%S.%f 格式字符串;
  • time_to_datetime(input_time):转为 datetime.datetime 类型。

例如 tqsdk/api.py#L706-L713 中的示例展示了把最后一根 K 线的纳秒时间转换为 datetime.datetime 的用法:

from tqsdk import tafunc

klines = api.get_kline_serial("DCE.jd2001", 10)
kline_time = tafunc.time_to_datetime(klines.iloc[-1]["datetime"])
print(kline_time.year, kline_time.month, kline_time.day, kline_time.hour, kline_time.minute, kline_time.second)

五、指标的数据源:get_kline_serial 关键约定

技术指标的第一参数来自 api.get_kline_serial(),理解其返回结构是用好指标的前提。完整签名见 tqsdk/api.py#L621-L715:

def get_kline_serial(self, symbol, duration_seconds, data_length=200, adj_type=None, **kwargs) -> pd.DataFrame

要点如下(详见 doc/usage/mddatas.rst#L185-L237):

  • symbol:单个合约代码字符串,或合约代码列表(列表形式会按时间向第一个合约对齐生成多合约 K 线,副合约字段名追加数字后缀,如 open1、close2);
  • duration_seconds:以秒为单位的周期,如 60 为 1 分钟线、3600 为 1 小时线、86400 为日线;日线以内可任意填写,日线以上只能是 86400 的整数倍,最大 28 天;
  • data_length:返回的序列长度,默认 200 根,每个序列最大支持 10000 个数据;
  • adj_type:复权类型,"F" 前复权、"B" 后复权,仅对股票和基金合约有效,且暂不支持多合约 K 线复权。

返回的 pandas.DataFrame 包含标准列:id(K 线序列号)、datetime(K 线起点时间的纳秒数)、open、high、low、close、volume、open_oi、close_oi。常见用法是 klines.iloc[-1].close(最后一根 K 线收盘价)与 klines.close(收盘价 Series,可直接作为 tafunc 的输入)。

六、进阶:期权定价与希腊字母指标

ta 与 tafunc 还内置了一整套基于 Black-Scholes 模型的期权计算能力,这在回测与实盘期权策略中非常实用。

6.1 tafunc 层的期权原子函数

  • get_t(df, expire_datetime):由 K 线序列与到期日计算年化到期时间序列(默认按一年 360 天折算);
  • get_his_volatility(df, quote):计算合约的历史波动率,日线按 250 个交易日年化;非日线周期且存在交易日历时会依据 quote.trading_time 折算实际交易时长(tqsdk/tafunc.py#L938-L948);
  • get_bs_price(series, k, r, v, t, option_class):BS 模型理论价格,v(波动率)、t(年化到期时间)、option_class("CALL"/"PUT")均可传入 float 或与 series 等长的 pandas.Series;
  • get_delta / get_gamma / get_theta / get_vega / get_rho:五个标准希腊字母;
  • get_impv(series, series_option, k, r, init_v, t, option_class):隐含波动率,采用牛顿迭代逼近,初始值可用历史波动率 init_v;
  • 另有 get_ticks_info(df)(计算 tick 开平方向:多开/空开/多平/空平/双开/双平等)与 get_sharp / get_sortino / get_calmar(年化夏普率、索提诺比率、卡玛比率)等绩效函数。

6.2 ta 层的期权封装指标

tqsdk.ta 在此基础上提供了更高层的封装,只需传入 K 线与 Quote 对象即可使用:

  • BS_VALUE(df, quote, r=0.025, v=None):期权理论价格,要求 quote 是 df 对应标的合约的期权(否则返回全 nan),v=None 时自动计算历史波动率;
  • OPTION_GREEKS(df, quote, r=0.025, v=None):希腊指标,要求 df 是多合约 K 线(期权在前、标的在后),v=None 时自动用隐含波动率计算;
  • OPTION_VALUE(df, quote):内在价值与时间价值;
  • OPTION_IMPV(df, quote, r=0.025):隐含波动率;
  • VOLATILITY_CURVE(df, quotes, underlying, r=0.025):由一批期权合约的批量行情构建隐含波动率曲面。

仓库自带的完整期权示例见 tqsdk/demo/ta_option.py:

from tqsdk import TqApi, TqAuth, tafunc
from tqsdk.ta import *

api = TqApi(auth=TqAuth("快期账户", "账户密码"))

underlying_quote = api.get_quote("SHFE.cu2009")
klines = api.get_kline_serial('SHFE.cu2009', 24 * 60 * 60, 20)
v = tafunc.get_his_volatility(klines, underlying_quote)          # 历史波动率
print("历史波动率:", v)

quote = api.get_quote("SHFE.cu2009C44000")
bs_serise = BS_VALUE(klines, quote, 0.025)                       # BS 理论价
print("理论价:", list(round(bs_serise['bs_price'], 2)))

klines2 = api.get_kline_serial(["SHFE.cu2009C44000", "SHFE.cu2009"], 24 * 60 * 60, 20)
values = OPTION_VALUE(klines2, quote)                            # 内在价值/时间价值
impv = OPTION_IMPV(klines2, quote, 0.025)                        # 隐含波动率
greeks = OPTION_GREEKS(klines2, quote, 0.025, impv['impv'])      # 希腊字母
print("delta:", list(greeks["delta"]))
print("theta:", list(greeks["theta"]))
print("gamma:", list(greeks["gamma"]))
print("vega:", list(greeks["vega"]))
print("rho:", list(greeks["rho"]))
api.close()

注意 OPTION_GREEKS 的多合约 K 线要求期权合约在前、标的合约在后(get_kline_serial(<a href="https://link.gitcode.com/i/964fbdcd4df8c327d99ba1fae623883d" target="_blank">"期权", "标的"], ...)),此时返回的 DataFrame 中期权价格为 close1、标的价格为 close(见 [tqsdk/ta.py#L2563-L2626 的字段校验逻辑)。

七、组合实战:从序列函数到完整信号

tafunc 的"乐高"式设计让你可以按需拼装出文档中没有的指标。例如,构建一个基于"5 周期均线上穿 10 周期均线"的开仓信号:

from tqsdk.tafunc import ma, crossup

klines = api.get_kline_serial("SHFE.cu2607", 60)
ma5 = ma(klines.close, 5)
ma10 = ma(klines.close, 10)
signal = crossup(ma5, ma10)                      # 上穿当期为 1,其余为 0
print(list(signal))

再比如原文档中提到的统计用法——统计从申请到行情数据以来 5 周期均线上穿 10 周期均线的次数(tqsdk/tafunc.py#L280-L282):

from tqsdk.tafunc import crossup, ma, count

count = count(crossup(ma(klines.close, 5), ma(klines.close, 10)), 0)  # n=0 表示从头累计
print(list(count))

这里 count(cond, 0) 触发源码中的特殊分支(tqsdk/tafunc.py#L284-L288):pd.Series(np.where(cond, 1, 0).cumsum()),即从第一个有效值开始做累计求和,而不是按窗口滚动统计。仓库内 tqsdk/demo/example/ 下的 40 余个策略示例(如 doublema.py、RSI.py、pivot_point.py、hull.py 等)大量使用了这两个模块,是学习组合用法的直接素材。

八、注意事项与最佳实践

  1. 序列长度要充足:所有滚动窗口类函数(rolling(n))在序列前 n-1 个位置返回 NaN。因此计算长周期指标时应为 get_kline_serial 指定足够大的 data_length,或对结果做 dropna()/ffill() 处理。
  2. 不要修改原始 K 线序列:get_kline_serial 返回的对象会随行情自动更新,源码 docstring 特别提醒"获取后的 kline 对象请不要修改/重命名原始的 kline 序列,可能会导致后续的 kline 数据不更新"(tqsdk/api.py#L646-L647)。
  3. 字段访问方式:ta 指标返回 DataFrame,用列名索引(如 macd["diff"])取值;tafunc 返回 Series,可直接参与 pandas 运算(如 klines.close - pre_close)。
  4. 参数边界:sma 要求 n > m,ema 要求 n >= 1,ref 在序列元素不足 n + 1 个时返回 NaN 序列,barlast 在条件从未成立时返回 -1——这些边界行为在源码 docstring 中均有明确说明。
  5. 进一步阅读:完整的函数签名与示例可查看 doc/usage/ta.rst、doc/reference/tqsdk.ta.rst、doc/reference/tqsdk.tafunc.rst,以及 K 线数据获取说明 doc/usage/mddatas.rst;直接阅读 tqsdk/ta.py 与 tqsdk/tafunc.py 可获得每个函数最精确的公式与边界行为定义。
登录后查看全文
tqsdk-python