天勤量化TqSdk实战：30分钟从零跑通期货行情到自动交易

【免费下载链接】tqsdk-python天勤量化开发包, 期货量化, 实时行情/历史数据/实盘交易项目地址: https://gitcode.com/gh_mirrors/tq/tqsdk-python

想象这样一个场景：你盯着一份螺纹钢合约，想监控它的实时价格波动，还想在价差合适时自动开平仓——既不想手动盯盘，又不想从底层写socket、解析行情协议。天勤量化TqSdk正是为这个场景而生的开源Python量化开发包，它把期货实时行情、历史数据、策略回测和模拟/实盘交易打包成一套极简API，让你用十几行代码就能把"看盘→分析→下单"整条链路跑起来。

这篇文章不以"功能清单"的方式罗列接口，而是带你完成一个真实的小目标：从安装环境开始，30分钟内做出一个能监控螺纹钢行情、并在价差达标时自动调仓的程序，最后在历史数据上完成回测验证。每完成一步，你都能看到实实在在的输出，而不是停留在概念上。

上图是天勤量化TqSdk的策略运行界面，左侧是策略文件列表，右侧是策略代码。看完这篇文章，你就能自己写出并运行图中这样的策略程序。

一、开工前的准备清单：三样东西缺一不可

在写第一行代码前，先确认三件事，大约占用你5分钟。

① Python 3.9 及以上版本天勤量化TqSdk基于Python开发，需要3.9以上的解释器。在终端执行python --version可以确认版本；Windows、macOS、Linux 均可运行。

② 用一条命令装好TqSdk打开终端执行：

pip install tqsdk -U

如果下载速度慢，换用清华镜像源会快很多：

pip install tqsdk -U -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host=pypi.tuna.tsinghua.edu.cn

装完后可以顺手验证一下安装是否成功：

python -c "import tqsdk; print(tqsdk.__version__)"

能打印出版本号（例如 3.10.1），说明环境就绪。

③ 一个免费的"快期账户"这是很多人忽略、却最关键的准备工作。天勤量化TqSdk的所有程序（包括只看行情）都要求先登录快期账户，它是连接行情服务器的通行证。注册是免费的，流程很简单：访问天勤量化官网点击"免费注册"，用手机号或邮箱完成验证即可。

💡 小提示：注册后记下账户名和密码。接下来所有代码里的TqAuth("账户", "密码")都要用它们。如果密码涉及特殊字符，建议先在代码里用字符串变量存放，避免混淆。

二、第一段会"说话"的行情代码

装备齐全后，我们来写第一个程序。它的目标只有一个：持续打印螺纹钢合约的最新价。把下面代码保存为quote.py并运行：

from tqsdk import TqApi, TqAuth # 1. 创建API实例，传入你的快期账户 api = TqApi(auth=TqAuth("你的快期账户", "你的账户密码")) # 2. 订阅上期所螺纹钢 rb2610 合约的行情 quote = api.get_quote("SHFE.rb2610") # 3. 进入循环，不断等待并打印最新行情 while True: api.wait_update() print(quote.datetime, quote.last_price)

如果你在非交易时段运行，终端依然会陆续打印出最近一个交易日的最后一笔行情，不会报错。能看到稳定的输出，就意味着「账户登录 + 行情连接 + 数据订阅」这条链路已经全部打通。

拆开来看，这段代码只有三个动作，而它们构成了天勤量化TqSdk所有程序（无论多复杂）的骨架：

关于合约代码的格式，需要多说一句：它是交易所.品种+合约月份的写法。例如SHFE.rb2610表示上海期货交易所的螺纹钢2610合约，DCE.i2609表示大连商品交易所的铁矿石2609合约。不熟悉这种写法时，最容易在这里栽跟头。

三、看懂TqSdk的运行密码：wait_update 数据驱动模型

不少新手在跑通上面的代码后，会尝试写这样的循环：

while True: print(quote.last_price) # 错误示范：这样是打不出持续更新的行情的

结果发现价格纹丝不动，甚至干脆卡住。要理解原因，必须搞懂天勤量化TqSdk的核心运行模型——所有数据变化都由wait_update()驱动。

天勤量化TqSdk的架构可以这样理解：程序与服务器之间通过一条长连接通信，服务器不断推送行情数据包。api.get_quote()等函数返回的不是一份"拷贝"，而是一个指向内存数据的引用。你调用get_quote()之后，内存里的行情数据还是空的，必须进入循环调用api.wait_update()：

1. wait_update()阻塞等待；
2. 收到服务器推送的数据包，内存中的行情对象被刷新；
3. wait_update()返回，此时quote.last_price才是最新值；
4. 循环回到第1步，等待下一个数据包。

所以wait_update()就像一台发动机的曲轴，每一次转动都把最新的数据"泵"进你的程序。任何行情、K线、账户、持仓的读取，都必须发生在某次wait_update()返回之后。这也解释了为什么所有天勤量化TqSdk示例程序都长着"wait_update()+ 读取数据"这个循环模样——它不是惯例，而是机制本身。

如果你希望判断"某个对象刚刚是否真的变化过"，可以用api.is_changing(obj)：

while True: api.wait_update() if api.is_changing(quote): print("行情更新了:", quote.last_price)

这比"无脑打印"高效得多，尤其在后面写交易策略时，is_changing()是避免重复下单的关键工具。

四、给行情装上"刻度尺"：一分钟拿到K线数据

实时tick数据适合精细监控，但做策略分析时，我们通常更关心K线。天勤量化TqSdk获取K线同样只要一行代码：

from tqsdk import TqApi, TqAuth api = TqApi(auth=TqAuth("你的快期账户", "你的账户密码")) # 获取 rb2610 的 60秒K线，默认保留最近200根 klines = api.get_kline_serial("SHFE.rb2610", 60) while True: api.wait_update() # 只有最后一根K线收盘价变化时才打印，避免刷屏 if api.is_changing(klines.iloc[-1], "close"): print("最新K线收盘价:", klines.close.iloc[-1])

这里有两个值得注意的点：

• get_kline_serial()返回的是一个pandas.DataFrame对象，除了close（收盘价），还包含open、high、low、volume、open_interest等常用字段，可以直接用klines.close.iloc[-1]这种 pandas 语法取数。
• K线序列同样遵循上一节的数据驱动模型，会随wait_update()自动增量更新。第二个参数是K线周期（秒），60即1分钟线；改成10就是10秒线，非常灵活。

is_changing(klines.iloc[-1], "close")的意思是"最后一根K线的收盘价是否刚变化"，这能精确捕捉到新K线生成或价格跳动的瞬间——后续所有基于K线的策略信号，几乎都会用到这个判断。

五、让策略自己动手：从下单到目标持仓

数据能拿到之后，就该让程序"动手"了。天勤量化TqSdk 的下单接口同样直接，最基础的用法是api.insert_order()：

# 以限价3800买入开仓2手 rb2610 order = api.insert_order(symbol="SHFE.rb2610", direction="BUY", offset="OPEN", volume=2, limit_price=3800) # 下单后继续驱动循环，wait_update 时订单请求才会真正发出 while True: api.wait_update() if api.is_changing(order): print("订单状态:", order.status, "已成交:", order.volume_orign - order.volume_left)

⚠️ 特别注意：insert_order()只是把下单请求加入发送队列，实际报单发生在下一次wait_update()时。所以下单后绝不能立刻退出程序，必须继续跑主循环。

不过，在真实策略里自己管理"判断→下单→盯成交→撤单→改价"这一整套流程相当繁琐。天勤量化TqSdk 为此提供了一个更省心的工具：TargetPosTask（目标持仓任务）。它的哲学是：你只管告诉它"我希望持有多少手"，中间的指令拆解、撮合、追单全部由它自动完成。

下面的程序演示了一个经典的跨期价差监控场景：同时监控近月和远月两个螺纹钢合约，价差过大时做空近月、做多远月，价差回落时清仓。这也正是项目官方示例tqsdk/demo/tutorial/t80.py的思路：

from tqsdk import TqApi, TqAuth, TargetPosTask api = TqApi(auth=TqAuth("你的快期账户", "你的账户密码")) # 订阅近月和远月合约行情 quote_near = api.get_quote("SHFE.rb2610") quote_far = api.get_quote("SHFE.rb2612") # 创建两个目标持仓任务，负责把仓位调整到目标手数 target_near = TargetPosTask(api, "SHFE.rb2610") target_far = TargetPosTask(api, "SHFE.rb2612") while True: api.wait_update() if api.is_changing(quote_near) or api.is_changing(quote_far): spread = quote_near.last_price - quote_far.last_price print("当前价差:", spread) if spread > 250: print("价差过高 → 空近月，多远月") target_near.set_target_volume(-1) # 负数表示空头 target_far.set_target_volume(1) # 正数表示多头 elif spread < 200: print("价差回落 → 清空持仓") target_near.set_target_volume(0) target_far.set_target_volume(0)

注意set_target_volume()的语义：正数是多头手数，负数是空头手数，0是空仓。你只描述"目标状态"，至于怎么分步开仓、怎么处理挂单，TargetPosTask全包了。运行后如果账户里没有任何持仓，程序也不会报错——因为它本来就是"逐步把当前仓位调整到目标仓位"。

上图展示了一个策略在实时环境中的运行状态：上方是账户权益和可用资金，中间是实时K线，下方是策略日志。你自己运行价差策略时，看到的就是类似的画面。

六、上实盘前的免费模拟考：用历史数据回测

直接拿真金白银去验证一个刚写好的策略，显然不明智。天勤量化TqSdk 提供了一套内置回测机制，只改一行代码，就能让你的策略在指定时间段的历史数据上"重跑一遍"，并自动给出收益、回撤等统计指标。

改造方式非常简单，在创建TqApi时传入一个TqBacktest对象：

from datetime import date from tqsdk import TqApi, TqAuth, TqBacktest api = TqApi( backtest=TqBacktest(start_dt=date(2024, 1, 1), end_dt=date(2024, 6, 1)), auth=TqAuth("你的快期账户", "你的账户密码") ) # 下面接上节价差策略的代码，无需任何修改 quote_near = api.get_quote("SHFE.rb2610") quote_far = api.get_quote("SHFE.rb2612") # ...策略主体保持不变...

回测时，wait_update()会按历史K线的时间顺序逐根推进，TargetPosTask的调仓逻辑也会照常执行，但所有下单都作用于虚拟的模拟账户。你可以把上面价差策略的SHFE.rb2610/SHFE.rb2612换成历史上真实存在的合约，就能立刻看到策略在过去几个月里的表现。

更直观的方式是开启内置的Web图形界面，在创建TqApi时加一个web_gui=True参数，程序运行后浏览器会自动打开一个网页，展示回测过程中的实时K线、成交点、资金曲线和完整回测报告。

图中正是Web界面下的回测效果：顶部是K线图，左侧是资金曲线，底部给出了总收益率、年化夏普率等关键指标，点击"查看完整回测报告"还能看到更细粒度的统计。这套可视化能力对验证策略逻辑、排查异常交易非常有帮助。

💡 小提示：回测是免费的模拟考试，强烈建议每个策略在上实盘（或模拟盘）之前都先过一遍回测。天勤量化TqSdk 还支持历史行情变速复盘（tqsdk/backtest/replay.py），可以像放录像一样逐笔回看当时的盘口变化。

七、新手最容易踩的4个坑

把前面几步走完，你已经超过大多数刚接触天勤量化TqSdk的用户了。再帮你排掉几个高频雷区，免得卡在奇怪的地方。

① 报错无法连接服务器/ 登录失败先检查TqAuth("账户", "密码")里的账户名和密码是否与注册信息完全一致（注意大小写）。其次确认网络能正常访问外网。如果公司内网有限制，换手机热点通常能立刻定位问题。

② 报错无效的合约代码合约代码必须写成交易所.品种月份的完整格式，例如SHFE.rb2610。常见的错误包括漏掉交易所前缀、写了带空格的代码、或者拼错了品种缩写。想确认一个代码是否存在，可以在get_quote()之前先print(api.get_quote("SHFE.rb2610"))观察返回内容，或在tqsdk/demo/tutorial/下翻翻官方示例里用过的合约代码。

③ 行情打印不出来 / 数据不更新回想第三节的机制：任何数据读取都必须在wait_update()返回之后。如果你的循环里只有print(quote.last_price)而没有wait_update()，数据永远不会更新。另外，如果你只取了一次数据就退出了主循环，连接会被立刻关闭，自然看不到持续输出。

④ 程序一退出，持仓和成交记录全没了如果你没有显式传入账户对象（例如只写了TqApi(auth=...)），天勤量化TqSdk 会默认使用一个临时模拟账户TqSim。它的记录只存在于当前进程内，程序一结束就清零。想要长期保存模拟资金和持仓，可以用TqKq换取一个与快期APP互通的长期模拟账户：

from tqsdk import TqApi, TqAuth, TqKq api = TqApi(TqKq(), auth=TqAuth("你的快期账户", "你的账户密码"))

八、下一步往哪走

到这里，你已经完成了从环境搭建、实时行情获取、K线分析，到自动调仓与历史回测的完整闭环——这恰好就是天勤量化TqSdk 官方快速入门文档（doc/quickstart.rst）的主线，也覆盖了tqsdk/demo/tutorial/下 t10、t30、t60、t80 等核心示例的全部技能点。

接下来值得探索的方向，按性价比排序：

1. 把策略跑上模拟盘：用上一条提到的TqKq长期模拟账户，让价差策略在真实时间线上连续运行几天，观察它的实盘行为是否与回测一致；
2. 研究更丰富的策略示例：项目在tqsdk/demo/目录下内置了几十个可运行的策略，从双均线、网格交易到跨期套利一应俱全，逐个阅读源码是最好的进阶教材；
3. 引入技术指标库：tqsdk/ta.py内置了 MACD、KDJ、BOLL 等上百个技术指标函数，配合K线数据可以快速搭建信号系统；
4. 学习风险管理：查看tqsdk/risk_rule.py，了解如何用现成的风控规则限制下单频率、持仓规模，这是从"能跑"走向"靠谱"的关键一步。

最后给你一个务实建议：先用模拟环境把整套流程跑熟，再考虑实盘。天勤量化TqSdk 的临时模拟账户、长期模拟账户和实盘账户之间只差一个参数，把模拟阶段踩过的坑都填平了，实盘阶段你会从容得多。现在就去运行第一节那段行情代码吧——看到价格滚动打印出来的那一刻，你的量化交易之旅就算正式开始了。

【免费下载链接】tqsdk-python天勤量化开发包, 期货量化, 实时行情/历史数据/实盘交易项目地址: https://gitcode.com/gh_mirrors/tq/tqsdk-python