TA-Lib 中文速查手册

定位

TA-Lib 是技术分析指标计算库;ta-lib-python 是它的 Python 封装。它适合批量计算指标、因子研究、信号原型与行情分析,但不是完整的回测、撮合或交易执行框架。

使用原则

指标是价格与成交量的派生量,不是独立的买卖依据。参数、阈值和信号必须结合品种、周期、交易成本及样本外检验;代码中尤其要防止未来数据泄漏。

1. 简介与适用场景

TA-Lib(Technical Analysis Library)提供 150 多个技术指标与 K 线形态识别函数。ta-lib-python 通过 Cython/NumPy 封装底层 C 库,主要有三种调用方式:

  • Function API:直接向函数传入 NumPy 数组,简单、明确,适合研究和批量计算。
  • Abstract API:统一传入含 open/high/low/close/volume 的字典,并可查看参数、输入、输出和 lookback 元数据,适合指标配置化。
  • Streaming API(实验性):只计算最新值,适合只关心末端结果的流式场景;本文以官方文档重点介绍的前两种 API 为主。

典型组合:pandas/NumPy 做数据处理,TA-Lib 做指标计算,再交给 vectorbtbacktrader、自研回测器或实盘系统。

不负责:行情下载、复权、交易日历、组合管理、回测撮合、手续费/滑点建模、下单执行。

2. 输入数据约定

2.1 字段和顺序

常见字段:

字段含义典型函数
open开盘价K 线形态、BOP
high最高价ADX、ATR、STOCH、SAR
low最低价ADX、ATR、STOCH、SAR
close收盘价均线、MACD、RSI 等大多数单序列指标
volume成交量OBV、AD、ADOSC、MFI

要求:

  • 按时间从旧到新排列;各输入等长、同一时间索引、同一标的与周期。
  • 推荐连续的一维 float64 数组;整数列先转换,避免类型异常或隐式转换差异。
  • high >= max(open, close)low <= min(open, close),成交量单位前后一致。
  • 拆股、分红、合约换月等会制造跳变;先明确是否使用前/后复权数据。
  • 多标的数据必须按标的分组计算,绝不能让窗口跨越两个标的。
close = df["close"].to_numpy(dtype="float64")
high = df["high"].to_numpy(dtype="float64")
low = df["low"].to_numpy(dtype="float64")
volume = df["volume"].to_numpy(dtype="float64")

2.2 缺失值

TA-Lib 输出开头通常有一段由 lookback 造成的 NaN。输入内部出现 NaN 时,不同函数的传播/恢复行为可能不同;不要假定它和 pandas 的 rolling 行为一致。稳妥做法是:

  1. 先按时间排序、去重;
  2. 明确处理输入缺失值;
  3. 分段计算或在合理时限内填充,且记录填充规则;
  4. 计算后统一检查有效区间。
needed = ["open", "high", "low", "close", "volume"]
df = df.sort_index()
assert df.index.is_monotonic_increasing
assert not df.index.has_duplicates
clean = df.dropna(subset=needed).copy()

3. Function API

直接传数组,参数建议全部写成关键字:

import talib
 
sma20 = talib.SMA(close, timeperiod=20)
ema20 = talib.EMA(close, timeperiod=20)
 
macd, signal, hist = talib.MACD(
    close,
    fastperiod=12,
    slowperiod=26,
    signalperiod=9,
)
 
upper, middle, lower = talib.BBANDS(
    close,
    timeperiod=20,
    nbdevup=2,
    nbdevdn=2,
    matype=talib.MA_Type.SMA,
)

输出通常为与输入等长的数组;多输出函数返回 tuple。查询运行环境真正支持的函数:

print(talib.get_functions())
for group, names in talib.get_function_groups().items():
    print(group, names)

4. Abstract API

所有函数统一接收输入字典;所有数组必须等长:

from talib import abstract
 
inputs = {
    "open": df["open"].to_numpy(dtype="float64"),
    "high": df["high"].to_numpy(dtype="float64"),
    "low": df["low"].to_numpy(dtype="float64"),
    "close": df["close"].to_numpy(dtype="float64"),
    "volume": df["volume"].to_numpy(dtype="float64"),
}
 
sma = abstract.SMA(inputs, timeperiod=20)              # 默认 close
sma_open = abstract.SMA(inputs, timeperiod=20, price="open")
slowk, slowd = abstract.STOCH(inputs)                  # 默认 high/low/close

动态构造与自省:

fn = abstract.Function("MACD")
print(fn.info)          # 名称、分组、输入、参数、输出
print(fn.parameters)
print(fn.input_names)
print(fn.output_names)
print(fn.lookback)      # 当前参数下需要预热的观测数
 
fn.set_parameters({"fastperiod": 12, "slowperiod": 26, "signalperiod": 9})
result = fn.run(inputs)

适合用 Abstract API 的情况:指标名称/参数来自 YAML、数据库或 UI,或需要统一遍历多个指标。注意 Function 对象会记住已设置的参数与输入;共享实例时要防止旧状态污染下一次计算。

5. 函数分类总览

官方分组代表函数用途
Overlap StudiesSMA、EMA、WMA、BBANDS、KAMA、SAR趋势/平滑/包络
Momentum IndicatorsMACD、ADX、RSI、STOCH、CCI、MOM、WILLR动量、趋势强度、超买超卖
Volatility IndicatorsATR、NATR、TRANGE波动与真实波幅
Volume IndicatorsOBV、AD、ADOSC价量关系与资金累积
Price TransformAVGPRICE、MEDPRICE、TYPPRICE、WCLPRICEOHLC 合成价格
Cycle IndicatorsHT_*Hilbert Transform 周期/相位/趋势模式
Pattern RecognitionCDL*K 线形态识别
Statistic FunctionsSTDDEV、VAR、CORREL、BETA、LINEARREG、TSF滚动统计与回归
Math TransformSQRT、LN、LOG10、SIN 等逐元素数学变换
Math OperatorsMAX、MIN、SUM、ADD、DIV 等窗口或逐元素运算

Tip

ADXMACD 在官方分类中属于 Momentum Indicators;为便于实战,本手册也在“趋势指标”一节讲解它们。

6. 常用趋势指标

6.1 SMA / EMA / WMA

sma = talib.SMA(close, timeperiod=20)
ema = talib.EMA(close, timeperiod=20)
wma = talib.WMA(close, timeperiod=20)
  • SMA:窗口内等权平均;直观但滞后较大。
  • EMA:近期权重更高;响应更快,初始种子会影响预热区附近值。
  • WMA:通常按线性递增权重强调近期数据。

相关:DEMATEMATRIMAT3、自适应 KAMA/MAMA、统一入口 MAMAmatype 可用 talib.MA_Type,不要把任意数字当作周期:

ma = talib.MA(close, timeperiod=20, matype=talib.MA_Type.EMA)

6.2 MACD

macd, signal, hist = talib.MACD(
    close, fastperiod=12, slowperiod=26, signalperiod=9
)
# hist 在 TA-Lib 中等于 macd - signal

常见解释:macd 上穿 signal 表示动量改善;hist 体现两者差值。不要把不同软件里可能经过倍数缩放的“MACD 柱”直接与 TA-Lib 数值比较。

  • MACD:经典三参数版本。
  • MACDEXT:快线、慢线、信号线可分别指定均线类型。
  • MACDFIX:快慢周期固定为 12/26,只调整信号周期。

6.3 ADX / +DI / -DI

adx = talib.ADX(high, low, close, timeperiod=14)
plus_di = talib.PLUS_DI(high, low, close, timeperiod=14)
minus_di = talib.MINUS_DI(high, low, close, timeperiod=14)

ADX 衡量趋势强度而非方向;方向通常结合 PLUS_DIMINUS_DI。诸如 20/25 的阈值只是惯例,不是跨市场定律。ADX、ADXR、DX、DI/DM 系列在官方文档中标有 unstable period,应预留额外预热数据并做稳定性验证。

6.4 Parabolic SAR

sar = talib.SAR(high, low, acceleration=0.02, maximum=0.2)

SAR 常用于趋势跟踪与移动止损参考。acceleration 越大越敏感、越容易反转;震荡行情容易出现反复信号。SAREXT 提供多空方向分别设置加速参数的扩展版本。

7. 动量指标

7.1 RSI

rsi = talib.RSI(close, timeperiod=14)

范围通常为 0–100。70/30 是常见参考,但强趋势下 RSI 可长期停留在高/低区;更适合结合趋势过滤、背离或区间规则。官方将 RSI 标注为 unstable period。

7.2 STOCH / STOCHF / STOCHRSI

slowk, slowd = talib.STOCH(
    high, low, close,
    fastk_period=5,
    slowk_period=3,
    slowk_matype=talib.MA_Type.SMA,
    slowd_period=3,
    slowd_matype=talib.MA_Type.SMA,
)
 
fastk, fastd = talib.STOCHF(high, low, close, fastk_period=5, fastd_period=3)
srsi_k, srsi_d = talib.STOCHRSI(close, timeperiod=14, fastk_period=5, fastd_period=3)

STOCHRSI 是“对 RSI 再做随机指标”,不是直接对价格做 STOCH;它通常比 RSI 更敏感。

7.3 CCI / MOM / WILLR

cci = talib.CCI(high, low, close, timeperiod=14)
mom = talib.MOM(close, timeperiod=10)       # close[t] - close[t-10]
willr = talib.WILLR(high, low, close, timeperiod=14)
  • CCI:价格相对统计均值的偏离强度;±100 是常用参考区间。
  • MOM:绝对动量,受价格量级影响,不宜直接横向比较不同资产。
  • WILLR:通常处于 -100–0;接近 0 表示靠近窗口高位,接近 -100 表示靠近低位。

7.4 变化率系列

roc = talib.ROC(close, timeperiod=10)       # ((x/x_n)-1)*100
rocp = talib.ROCP(close, timeperiod=10)     # (x-x_n)/x_n
rocr = talib.ROCR(close, timeperiod=10)     # x/x_n
rocr100 = talib.ROCR100(close, timeperiod=10)  # (x/x_n)*100

8. 波动指标

8.1 TRANGE / ATR / NATR

tr = talib.TRANGE(high, low, close)
atr = talib.ATR(high, low, close, timeperiod=14)
natr = talib.NATR(high, low, close, timeperiod=14)

真实波幅考虑当期高低差以及相对前收盘的跳空。ATR 保留价格单位,适合止损距离和仓位波动尺度;NATR 将其归一化为百分比尺度,更便于跨资产比较。ATR/NATR 在官方文档中标有 unstable period。

8.2 BBANDS

upper, middle, lower = talib.BBANDS(
    close, timeperiod=20, nbdevup=2, nbdevdn=2,
    matype=talib.MA_Type.SMA,
)
 
bandwidth = (upper - lower) / middle
percent_b = (close - lower) / (upper - lower)

默认参数以实际安装版本的函数签名为准;研究中常用 20 期、上下 2 倍标准差。价格触及轨道不是自动反转信号;趋势中可能持续“贴轨”。分母可能为 0,派生指标应先防护。

9. 成交量指标

obv = talib.OBV(close, volume)
ad = talib.AD(high, low, close, volume)
adosc = talib.ADOSC(high, low, close, volume, fastperiod=3, slowperiod=10)
  • OBV:按收盘涨跌方向累加/扣减成交量;重点看走势与背离,绝对起点意义有限。
  • AD(Chaikin A/D Line):依据收盘在当日高低区间的位置加权成交量。
  • ADOSC:A/D Line 快慢指数平滑之差。

数据注意:部分市场只有成交额、手数或 tick volume;必须确认 volume 的真实含义。若 high == low,资金流乘数的解释也会失去信息。

10. 价格变换与统计函数

10.1 价格变换

avgprice = talib.AVGPRICE(open_, high, low, close)  # (O+H+L+C)/4
medprice = talib.MEDPRICE(high, low)                # (H+L)/2
typprice = talib.TYPPRICE(high, low, close)         # (H+L+C)/3
wclprice = talib.WCLPRICE(high, low, close)         # (H+L+2C)/4

10.2 统计/回归

std = talib.STDDEV(close, timeperiod=20, nbdev=1)
var = talib.VAR(close, timeperiod=20, nbdev=1)
corr = talib.CORREL(asset_a, asset_b, timeperiod=30)
beta = talib.BETA(asset_a, asset_b, timeperiod=5)
slope = talib.LINEARREG_SLOPE(close, timeperiod=14)
angle = talib.LINEARREG_ANGLE(close, timeperiod=14)
forecast = talib.TSF(close, timeperiod=14)

BETA/CORREL 只接受两条对齐序列。价格水平的回归/相关常受非平稳性影响;金融研究通常还应比较收益率序列。LINEARREG_ANGLE 会受价格尺度影响,不应无归一化地跨资产比较。

其他:MAX/MIN/SUM 为滚动窗口运算;ADD/SUB/MULT/DIV 为两数组逐元素运算;LN/LOG10/SQRT 等是逐元素数学变换,需自行保证定义域合法。

11. 周期指标(Hilbert Transform)

dcperiod = talib.HT_DCPERIOD(close)
dcphase = talib.HT_DCPHASE(close)
inphase, quadrature = talib.HT_PHASOR(close)
sine, leadsine = talib.HT_SINE(close)
trendmode = talib.HT_TRENDMODE(close)
trendline = talib.HT_TRENDLINE(close)
函数输出含义
HT_DCPERIOD估计主导周期长度
HT_DCPHASE估计主导周期相位
HT_PHASOR同相与正交分量
HT_SINESine 与 Lead Sine
HT_TRENDMODE趋势/周期模式标记
HT_TRENDLINE瞬时趋势线

Hilbert Transform 系列需要较长预热,对噪声、采样频率和市场状态敏感;官方文档将这些函数标注为 unstable period。不要把估计周期误当成确定、稳定的未来周期。

12. K 线形态识别(CDL*

所有形态函数基本都接收 OHLC:

engulfing = talib.CDLENGULFING(open_, high, low, close)
doji = talib.CDLDOJI(open_, high, low, close)
morning = talib.CDLMORNINGSTAR(open_, high, low, close, penetration=0.3)

返回与输入等长的整数数组:

  • 0:该位置未识别出该形态。
  • 正数:看涨方向;负数:看跌方向。
  • 常见强度是 +100/-100,但某些函数可能返回其他非零幅度(例如吞没形态在边界条件可见 ±80)。不要把所有 CDL* 硬编码成只会返回 ±100。
  • 数值表示 TA-Lib 对该形态的方向/强度编码,不是胜率、涨跌幅或置信概率。

常用函数:

函数中文名称方向提示
CDLDOJI十字星犹豫;需结合位置与趋势
CDLHAMMER锤头常被视为下跌后的潜在看涨反转
CDLHANGINGMAN上吊线常被视为上涨后的潜在看跌反转
CDLINVERTEDHAMMER倒锤头下跌后的潜在看涨反转
CDLSHOOTINGSTAR射击之星上涨后的潜在看跌反转
CDLENGULFING吞没形态正值看涨、负值看跌
CDLHARAMI孕线正/负值分别表示看涨/看跌版本
CDLHARAMICROSS十字孕线孕线的十字星版本
CDLPIERCING刺透形态潜在看涨反转
CDLDARKCLOUDCOVER乌云盖顶潜在看跌反转;有 penetration 参数
CDLMORNINGSTAR早晨之星潜在看涨反转;有 penetration 参数
CDLEVENINGSTAR黄昏之星潜在看跌反转;有 penetration 参数
CDL3WHITESOLDIERS三白兵看涨延续/反转语境
CDL3BLACKCROWS三只乌鸦看跌延续/反转语境
CDLMARUBOZU光头光脚强实体方向
CDLSPINNINGTOP纺锤线多空犹豫

列出本机所有形态函数:

patterns = talib.get_function_groups()["Pattern Recognition"]
print(patterns)

批量识别:

pattern_cols = {}
for name in talib.get_function_groups()["Pattern Recognition"]:
    fn = getattr(talib, name)
    values = fn(open_, high, low, close)
    if np.any(values != 0):
        pattern_cols[name] = values
 
pattern_df = pd.DataFrame(pattern_cols, index=df.index)

Caution

多个形态可能在同一根 K 线上同时触发。形态识别还会使用 TA-Lib 的蜡烛设置与历史平均实体/影线规则,因此不是只看一根 K 线的固定比例判断。务必结合前置趋势、成交量、波动率和样本外统计。

13. pandas 实用模板

13.1 单标的批量计算

import numpy as np
import pandas as pd
import talib
 
df = df.sort_index().copy()
o = df["open"].to_numpy(dtype="float64")
h = df["high"].to_numpy(dtype="float64")
l = df["low"].to_numpy(dtype="float64")
c = df["close"].to_numpy(dtype="float64")
v = df["volume"].to_numpy(dtype="float64")
 
df["sma20"] = talib.SMA(c, timeperiod=20)
df["ema50"] = talib.EMA(c, timeperiod=50)
df["rsi14"] = talib.RSI(c, timeperiod=14)
df["atr14"] = talib.ATR(h, l, c, timeperiod=14)
df[["macd", "macd_signal", "macd_hist"]] = np.column_stack(
    talib.MACD(c, fastperiod=12, slowperiod=26, signalperiod=9)
)
df[["bb_upper", "bb_middle", "bb_lower"]] = np.column_stack(
    talib.BBANDS(c, timeperiod=20, nbdevup=2, nbdevdn=2)
)

13.2 多标的分组(防止窗口串线)

def add_indicators(g: pd.DataFrame) -> pd.DataFrame:
    g = g.sort_values("date").copy()
    c = g["close"].to_numpy(dtype="float64")
    h = g["high"].to_numpy(dtype="float64")
    l = g["low"].to_numpy(dtype="float64")
    g["sma20"] = talib.SMA(c, timeperiod=20)
    g["rsi14"] = talib.RSI(c, timeperiod=14)
    g["atr14"] = talib.ATR(h, l, c, timeperiod=14)
    return g
 
result = (
    df.groupby("symbol", group_keys=False)
      .apply(add_indicators)
      .reset_index(drop=True)
)

13.3 生成交易信号且避免同根收盘成交假设

df["trend_ok"] = df["close"] > df["sma20"]
df["cross_up"] = (df["macd"] > df["macd_signal"]) & (
    df["macd"].shift(1) <= df["macd_signal"].shift(1)
)
df["raw_signal"] = df["trend_ok"] & df["cross_up"]
 
# 若指标由本根收盘数据计算,最早通常只能在下一根执行
df["position"] = df["raw_signal"].shift(1).fillna(False).astype(int)

14. lookback、NaN 与 unstable period

14.1 lookback

lookback 是当前参数下产生第一个有效输出前所需的历史观测数。Function API 会以开头的 NaN 对齐输出;多级平滑函数的 lookback 通常不等于表面上的单个周期。

from talib import abstract
 
f = abstract.Function("MACD")
f.set_parameters({"fastperiod": 12, "slowperiod": 26, "signalperiod": 9})
print(f.lookback)

规则:

  • 不要手工猜测每个函数的有效起点,优先读取 lookback 或检查有限值。
  • 多指标合并后,以所有必要列均有效的第一行作为策略起点。
  • 训练/回测前多取一段 warm-up 数据;不要把 warm-up 行当真实信号。
feature_cols = ["sma20", "rsi14", "atr14", "macd_signal"]
valid = np.isfinite(df[feature_cols]).all(axis=1)
features = df.loc[valid].copy()

14.2 unstable period

官方文档为 EMA、KAMA、MAMA、T3、ADX、ADXR、CMO、DX、MFI、DI/DM、RSI、STOCHRSI、ATR、NATR 及多个 HT_* 函数标注 unstable period。含义是:即使越过最小 lookback,早期输出也可能对初始条件较敏感。

实践建议:为此类指标额外取数并丢弃一段预热区;预热长度通过收敛测试确定,而非机械使用一个固定倍数。

15. 参数注意事项

  • timeperiod 是“bar 数”,20 根日线与 20 根 5 分钟线含义完全不同。
  • fastperiod 通常应小于 slowperiod;TA-Lib 可能接受某些组合,但经济解释要由你保证。
  • matype 使用 talib.MA_Type.SMA/EMA/WMA/DEMA/TEMA/TRIMA/KAMA/MAMA/T3,提高可读性。
  • BBANDSnbdevup/nbdevdn 是标准差倍数;上下可不对称。
  • SAR 的加速因子越大越敏感;参数含义不是百分比止损距离。
  • 星形类、乌云盖顶等的 penetration 是实体穿透比例;不同函数默认值可能不同,明确写出参数。
  • 价格和收益率量纲不同:ATR/MOM/STDDEV 等绝对值不宜直接跨资产比较;考虑 NATR、收益率或标准化。
  • 阈值不应在全样本上挑选后再汇报同一时期绩效;使用滚动或样本外验证。

16. 常见坑清单

  1. 输入没按时间升序:结果表面正常,含义完全错误。
  2. 多标的直接拼接计算:窗口跨标的污染。
  3. 将 NaN 全部填 0:制造假价格、假波动和假交叉。
  4. 忽略复权和换月:公司行动/主力切换被误判为动量或波动。
  5. 把当根收盘指标用于当根收盘成交:产生未来数据泄漏。
  6. 误解 MACD 柱缩放:不同行情软件可能显示 2 × (DIF-DEA);TA-Lib 的 macdhist = macd - signal
  7. 将 ADX 当方向指标:ADX 只描述强度;方向看 DI 或价格结构。
  8. 将 K 线返回值当概率:±100 是编码,不是 100% 概率。
  9. 假设所有 CDL 只有 ±100:部分模式存在其他非零强度。
  10. 只按最短 lookback 截断 unstable 指标:初始值仍可能不稳定。
  11. 依赖位置参数:长签名极易错位;优先关键字参数。
  12. 把技术指标库当策略:必须另行定义入场、退出、仓位、成本和风险规则。

17. 常用函数速查表

函数输入常用参数输出关键提示
SMAclosetimeperiod=30real等权均线
EMAclosetimeperiod=30real近期权重更高;unstable
WMAclosetimeperiod=30real线性加权
KAMAclosetimeperiod=30real自适应;unstable
MACDclose12,26,9macd, signal, histhist=macd-signal
ADXH,L,Ctimeperiod=14real趋势强度;unstable
PLUS_DIH,L,Ctimeperiod=14real正方向指标
MINUS_DIH,L,Ctimeperiod=14real负方向指标
SARH,Lacceleration, maximumreal趋势跟踪/止损参考
RSIclosetimeperiod=14real0–100;unstable
STOCHH,L,C5,3,MA,3,MAslowk, slowd慢速随机指标
STOCHRSIclose14,5,3,MAfastk, fastdRSI 的随机指标;unstable
CCIH,L,Ctimeperiod=14real常看 ±100
MOMclosetimeperiod=10real绝对变化量
ROCclosetimeperiod=10real百分比变化率
WILLRH,L,Ctimeperiod=14real通常 -100–0
MFIH,L,C,Vtimeperiod=14real价量动量;unstable
TRANGEH,L,Creal单根真实波幅
ATRH,L,Ctimeperiod=14real价格单位;unstable
NATRH,L,Ctimeperiod=14real归一化波动;unstable
BBANDScloseperiod, up, dn, matypeupper, middle, lower轨道不是自动反转信号
OBVclose,Vreal方向累积成交量
ADH,L,C,VrealChaikin A/D Line
ADOSCH,L,C,Vfast=3, slow=10realA/D 快慢振荡器
AVGPRICEO,H,L,CrealOHLC 均价
TYPPRICEH,L,Creal典型价格
STDDEVrealperiod, nbdevreal滚动标准差
CORRELreal0,real1timeperiod=30realPearson 相关
LINEARREG_SLOPErealtimeperiod=14real回归斜率,受尺度影响
HT_DCPERIODclosereal主导周期;unstable
CDLENGULFINGO,H,L,Cinteger正看涨、负看跌、0 未识别
CDLDOJIO,H,L,Cinteger十字星识别

表内参数是常见/官方签名默认示例,不代表策略最佳值。精确签名以当前安装版本的 help(talib.函数名) 或 Abstract API 的 .info 为准。

18. 自检模板

import numpy as np
import talib
from talib import abstract
 
required = {"SMA", "EMA", "MACD", "RSI", "ATR", "CDLENGULFING"}
available = set(talib.get_functions())
assert required <= available
 
assert all(len(inputs[k]) == len(inputs["close"]) for k in inputs)
assert np.isfinite(inputs["close"]).all()
 
macd_fn = abstract.Function("MACD")
macd_fn.set_parameters({"fastperiod": 12, "slowperiod": 26, "signalperiod": 9})
print("MACD lookback:", macd_fn.lookback)
print(macd_fn.info)

19. 官方资料与延伸阅读


文档说明

本手册依据上述官方资料整理,侧重 Python 实战速查。TA-Lib 与 Python 封装会更新;安装方式、支持函数和默认参数应以你安装版本的运行时自省及官方仓库为最终依据。