国内期货历史 tick 与 K 线批量下载：DataDownloader 组织方式
前言
期货量化研究常需要比“实时订阅几分钟 K 线”更长的历史：例如 2017–2024 年螺纹钢 5 分钟线做回测，或国债期货 tick 盘口做微观结构研究。手动截图或零散 CSV 难以维护。天勤 TqSdk 提供DataDownloader（数据下载工具，文档标明属于专业版能力，需按官网申请或购买），可把期货、期权等历史数据落到 CSV，支持 K 线任意周期 与 tick（dur_sec=0）。
下面说明DataDownloader的参数含义、多合约对齐、增量写入，以及和实时get_kline_serial的分工。需如实说明：DataDownloader 属于天勤专业版能力，未开通时应以实时订阅与TqBacktest为主，勿把下载工具当成默认免费功能。
一、DataDownloader 解决什么问题
实时策略用wait_update+get_kline_serial只保留有限data_length缓冲。研究侧若要数年历史，应用下载器拉本地 CSV，再在 Pandas 里做特征、或喂给TqBacktest之外的离线框架。
官方示例要点：
dur_sec：周期秒数；日线 86400；1 分钟 60；tick 为 0。symbol_list：一个或多个合约；多合约时按第一个合约的交易时间对齐（不对齐的时段填 N/A）。start_dt/end_dt：可为 date（交易日）或 datetime（具体时刻，默认北京时间）。write_mode：w覆盖写（写表头）；a追加不写表头，便于增量。
二、最小示例（K 线与 tick）
fromdatetimeimportdate,datetimefromcontextlibimportclosingfromtqsdkimportTqApi,TqAuthfromtqsdk.toolsimportDataDownloader api=TqApi(auth=TqAuth("快期账户","密码"))tasks={}tasks["rb_5m"]=DataDownloader(api,symbol_list="KQ.m@SHFE.rb",dur_sec=5*60,start_dt=date(2020,1,1),end_dt=date(2024,12,31),csv_file_name="rb_5m.csv",)tasks["tick"]=DataDownloader(api,symbol_list="CFFEX.T2509",dur_sec=0,start_dt=datetime(2025,3,1),end_dt=datetime(2025,3,31),csv_file_name="T_tick.csv",)withclosing(api):whilenotall(t.is_finished()fortintasks.values()):api.wait_update()下载过程仍要wait_update驱动；用closing(api)确保结束释放连接。
三、组织方式建议
| 实践 | 说明 |
|---|---|
| 按品种分目录 | data/SHFE/rb/5m.csv |
| 任务字典 | 多合约多周期tasks[name]=DataDownloader(...) |
| 增量 | 新时间段用write_mode="a"，注意不重复表头 |
| 主连研究 | KQ.m@适合长历史；实盘映射另表记录 |
| 元数据 | 记录下载日、dur_sec、复权 adj_type（股票用） |
期货主力换月导致主连拼接，研究结论要知悉与具体月实盘的差异（见主连专题）。
四、与实时策略衔接
研究 CSV 算出的信号规则，迁到实盘应改get_kline_serial+datetime触发，不要长期混用“读 CSV 最后一行”和“读 serial [-2]”两套索引语义。
五、权限与预期
文档写明 DataDownloader 为专业版功能；无权限时向官网申请。下载速度与区间长度、网络有关，宜分批按年下载。
总结
DataDownloader 的价值不止于把历史数据“下载下来”，更在于让研究流程拥有可复现的时间轴、文件规范与增量策略。数据层组织得越清楚，后面的特征研究、回测对照和实盘迁移越能保持同一口径：你能追溯每个 CSV 是何时、用什么 dur_sec 与区间生成的，也能避免把不同时间范围或不同订阅口径的结论混在一起。把这套规范固化到项目目录与脚本里，最终你拿到的不是“看起来能跑的代码”，而是一套研究到执行能自然衔接的工程体系。
FAQ
1）无专业版怎么办？
用回测、实时缓存、或第三方数据，勿编造下载 API。
2）多品种对齐 N/A？
文档说明非交易时段另一合约为 N/A，分析时要知道。
3）主连能否 tick 下载？
以 symbol 是否支持为准，先小区间试。
4）下完如何增量？
追加write_mode="a"，start_dt 接上次 end_dt 之后。
风险提示
本文介绍数据工具，不构成投资建议。