期货量化历史 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 接不上。天勤把两件事拆成两个 APIget_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 的使用要点klinesapi.get_kline_serial(SHFE.rb2510,60*5,data_length800)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 dfapi.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_length800的 5 分钟线单合约内存占用通常可接受若 50 个品种各 8000 根DataFrame 会明显吃内存。研究阶段用get_kline_data_series拉完落盘释放实盘只保留交易品种 serial。专业版区间拉取按流量计费时避免在循环里重复拉同一段历史。七、冷启动三种模式对比模式做法优点缺点A 大 data_lengthserial 一次要够长简单占带宽B 本地文件预热DataDownloader 落盘可控要维护文件C data_series 一次性专业版区间精确权限/费用上线推荐 BA夜间 downloader 更新盘前 serial 订 5001000 根衔接。八、常见衔接 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 导致信号僵死。FAQ1没有专业版怎么办加大get_kline_serial的data_length或用DataDownloader夜间批量拉历史到本地。2多合约每个都要 serial 吗交易合约必须订纯研究合约可离线文件不占实时订阅。3datetime 是纳秒吗K 线表datetime为纳秒时间戳与quote.datetime一致比较时注意单位。4主连 KQ.m 能用 data_series 吗可以传主连代码但实盘下单仍要映射到具体月份别混用。本文基于天勤 TqSdk 公开 API 整理不构成投资建议。