期货量化历史 K 线区间与实时串：get_kline_data_series 和 serial 分工
前言
用天勤 TqSdk 写国内期货量化策略时，K 线数据有两个典型用法：一是启动或研究阶段，要拉去年一整年螺纹钢 5 分钟线，估算均线周期、做参数扫描；二是实盘主循环里，每来一根新 bar 用已收盘 K 线（常取iloc[-2]）算双均线金叉死叉，再TargetPosTask调仓。有人用get_kline_serial把data_length设得巨大扛历史，有人又在while True: wait_update()里每分钟调区间接口，结果内存爆、流量超限、或历史末 bar 和实时首 bar 接不上。
天勤把两件事拆成两个 API：get_kline_serial管随wait_update更新的滚动序列；get_kline_data_series管指定起止日期的静态 DataFrame（专业版）。下面说明边界、衔接方式与常见误用。
一、两个接口各自是什么
| 接口 | 返回类型 | 是否随 wait_update 更新 | 典型用途 |
|---|---|---|---|
get_kline_serial(symbol, duration_seconds, data_length=...) | 类 DataFrame 的 K 线表 | 是 | 盘中信号、指标计算 |
get_kline_data_series(symbol, duration_seconds, start_dt, end_dt) | pandas DataFrame | 否，一次性 | 历史研究、冷启动填充 |
get_kline_data_series文档写明：返回对象不会更新，不建议在循环内调用；且仅限专业版用户（以官网购买说明为准）。get_kline_serial则绑定在TqApi生命周期内，每次wait_update()后表尾可能追加或更新。
二、get_kline_serial 的使用要点
klines=api.get_kline_serial("SHFE.rb2510",60*5,data_length=800)duration_seconds：周期秒数，5 分钟为 300。data_length：向服务器要的根数缓冲，不是均线周期；估法见 data_length 专题。- 新 bar 判定：对
klines.iloc[-1]["datetime"]或[-2]配合is_changing(klines.iloc[-1], "datetime")。 - 指标应对已收盘 bar 用
iloc[-2]，避免信号闪烁。
三、get_kline_data_series 的使用要点
fromdatetimeimportdate df=api.get_kline_data_series("SHFE.rb2510",60*5,date(2024,1,1),date(2024,12,31),)start_dt/end_dt可为date（交易日）或带时区的datetime。- 返回列含
datetime、open、high、low、close、volume、open_oi、close_oi等。 - 适合离线算参数、画长期曲线、检验样本外；算完应落盘，不必常驻内存。
四、历史与实时如何衔接
推荐模式：
- 研究阶段：用
get_kline_data_series或DataDownloader拉全历史，本地 parquet/csv 存盘。 - 实盘启动：
- 若已有本地历史，直接读文件预热指标状态；或
- 用
get_kline_serial订足够长的data_length预热。
- 盘中只维护
get_kline_serial一张表，不再调get_kline_data_series。
切忌在while True: api.wait_update()里每圈调get_kline_data_series，既浪费流量，又拿不到更新。
衔接检查：对比历史末行datetime与serial倒数第二根datetime是否连续；若有缺口，补下载或增大data_length重新订阅。
五、与回测环境的关系
TqBacktest下get_kline_serial按回测时钟推进；get_kline_data_series在回测中的行为以你本地版本文档为准，研究链路更常直接用回测内置数据。保持「回测用一套加载、实盘用 serial」的环境分离，可减少上线时字段不一致。
六、内存与流量粗算
data_length=800的 5 分钟线，单合约内存占用通常可接受；若 50 个品种各 8000 根，DataFrame 会明显吃内存。研究阶段用get_kline_data_series拉完落盘释放；实盘只保留交易品种 serial。专业版区间拉取按流量计费时，避免在循环里重复拉同一段历史。
七、冷启动三种模式对比
| 模式 | 做法 | 优点 | 缺点 |
|---|---|---|---|
| A 大 data_length | serial 一次要够长 | 简单 | 占带宽 |
| B 本地文件预热 | DataDownloader 落盘 | 可控 | 要维护文件 |
| C data_series 一次性 | 专业版区间 | 精确 | 权限/费用 |
上线推荐 B+A：夜间 downloader 更新，盘前 serial 订 500～1000 根衔接。
八、常见衔接 bug
历史末 bar 的close与 serial 第一根open跳空：可能是换月或数据源拼接；不要用历史文件最后一个 close 直接当 serial 指标初值，应在 serial 预热满data_length后再交易。多合约对齐时，各 serial 的datetime可能差几秒，信号应各算各的，不要强行 merge 成一张宽表除非策略需要。
总结
天勤把「拉一段固定历史」和「维护一根实时 K 线序列」分成get_kline_data_series与get_kline_serial：前者静态、适合研究落盘；后者动态、适合wait_update主循环。专业版才能用区间接口，免费场景可依赖data_length预热或DataDownloader。程序上做到启动预热一次、盘中只更新 serial，历史与实盘信号才能在同一套指标代码下对齐，也避免在循环里误用不更新的 DataFrame 导致信号僵死。
FAQ
1）没有专业版怎么办？
加大get_kline_serial的data_length，或用DataDownloader夜间批量拉历史到本地。
2）多合约每个都要 serial 吗？
交易合约必须订；纯研究合约可离线文件，不占实时订阅。
3）datetime 是纳秒吗？
K 线表datetime为纳秒时间戳，与quote.datetime一致，比较时注意单位。
4）主连 KQ.m@ 能用 data_series 吗？
可以传主连代码，但实盘下单仍要映射到具体月份，别混用。
本文基于天勤 TqSdk 公开 API 整理，不构成投资建议。