Level-2全推行情Python SDK部署避坑：多市场订阅与版本对齐

简介《同花顺level-2全推行情Python API操作手册》面向高频交易与量化开发者尤其适合做涨停板、盘口异动类策略的研究与工程人员用来解决Level-2行情如何借助Python稳定接入、按字段准确解析的落地问题。资料是单个PDF文档压缩包约850KB轻便易查。内容以版本修订表开篇逐条梳理V2.0.0至V2.1.9的演进单连接改多连接、上证逐笔委托接入、级联模式与异步订阅接口、极速盘口与内外盘字段、数据类型由int改float的精度修正并注明各市场域名端口的默认配置。随后介绍TDS的C/S架构、Level-1与Level-2数据范围、64位双核8GB内存与Python3.5以上的运行环境、安装命令以及初始化实例、注册六类行情回调、set_env环境参数、断线通知与重连的处理方式。五档十档快照、逐笔成交与委托、委托队列的字段说明也一并列出。已有2846人学习适合需要对照接口联调、排查堵包与重连问题的开发者随手查阅。1. 装完只收到半个市场Level-2 全推行情 SDK 的坑多半不在装有次排查一个现场L2-tdsapi-python的 tar.gz 用 pip 装完import datafeed不报错登录也返回 0可跑一整晚只有沪市快照深市一条都没有。这套 Level-2 全推行情 Python API 的安装难点从来不在装而在版本和参数对齐。V2.0.0 把 SDK 从单连接改成多连接要求按市场分别注册域名和端口V2.1.3 又加了 -1018 版本过低还把消息通知回调的入参从 int 换成 dict。手里拿着旧教程装新包或者拿新包跑旧代码都会翻车。机器要求其实不高64 位双核、8G 内存、100Mb 下行Windows 7 以上和 CentOS 7 都能跑真正卡人的是 Python 位数、回调签名和订阅市场号这三样。常在量化侧盯涨停板封单变化、排队撤单和逐笔成交的人最容易被这几个点拖住。2. 装前清单Python 位数、安装包形态与 Linux 下的 root 权限装这套行情 SDK 之前先把三件事定死机器够不够、解释器是不是 64 位、包用什么方式落地。这三件事任何一件没对齐后面调参数都是白费功夫——尤其 Python 位数坑得最隐蔽因为 32 位解释器装包时也可能一声不吭地成功。2.1 硬件与系统基线8G 内存是下限不是舒适线官方给的最低配置是 CPU 64 位双核及以上、内存 8G 及以上、互联网下行带宽 100Mb 及以上系统侧 Windows 7 及以上、CentOS 7 等常用 Linux 发行版都支持软件侧要求 Python 3.564 位及以上。这套数值得理解成能跑起来而不是跑得舒服。全推行情意味着一个回调里data_list可能塞着几百上千条 dict每条证券快照光十档买卖价量就是四十来个字段再叠上委托笔数、内外盘、撤单统计Python 对象的开销比字段表看起来大得多。内存 8G 是给单实例准备的如果还要在同一个进程里落库或做因子计算16G 更稳妥。带宽同理。100Mb 下行是接入的最低门槛一旦上到级联分发主 SDK 那个节点要同时喂多个从节点出口带宽得按实例数乘上去。我一般会在上线前用iftop或系统自带的流量统计盯十分钟峰值确认余量在 30% 以上再谈别的。项目最低要求我实际部署时的取值CPU64 位双核4 核以上留出回调线程余量内存8G16G落库场景再往上加下行带宽100Mb单实例 100Mb级联主节点按从节点数叠加操作系统Windows 7 / CentOS 7 等CentOS 7 / Windows Server 均可Python3.564 位及以上3.83.10 的 64 位解释器2.2 解释器必须是 64 位一行命令先自查32 位 Python 在这套 SDK 上几乎是必翻车的典型表现是装完 import 就异常或者登录后跑一阵子直接 MemoryError。装之前先自查别靠我记得我装的是 64 位# 打印解释器版本与位数calcsize(P) 返回指针字节数 python -c import struct, sys; print(sys.version); print(64位 if struct.calcsize(P) * 8 64 else 32位必须换)如果机器上有多个 Python先确认 pip 到底绑在哪个解释器上。常见的错法是裸敲pip install结果装进了系统默认的 Python 2 或者另一个 32 位环境而脚本用python3跑自然 import 不到# Windows 看重名解释器的安装路径Linux 看全部候选 where python which -a python3 python # 明确指定解释器安装避免 pip 绑错 python3 -m pip install ./L2-tdsapi-python-X.X.X-XXXXXXXX.tar.gz用虚拟环境的话python -m venv l2env建完之后一定要用 2.2 第一条命令在 venv 里再验一次位数。venv 继承的是基底解释器的架构基底错了venv 跟着错而且 venv 里报错信息往往更含糊。2.3 两种落地方式pip 装 tar.gz 和解包跑 setup.pySDK 给的是 tar.gz 源码包两种路子都行效果一样区别在于你想不想留一份解包后的目录方便看示例。# 方式一直接让 pip 处理 tar.gz适合一台机器装一次 python3 -m pip install ./L2-tdsapi-python-X.X.X-XXXXXXXX.tar.gz # 方式二解包后本地安装方便对照包内示例和字段模板 tar -xzf L2-tdsapi-python-X.X.X-XXXXXXXX.tar.gz cd L2-tdsapi-python-X.X.X-XXXXXXXX python3 setup.py installLinux 下如果不用虚拟环境而是装到系统目录需要 root 权限sudo -i切过去再执行Windows 下则要注意用管理员身份打开终端否则可能因为目录写入权限半途失败。装完必须验一步而且要验装到哪个解释器里了这一步比有没有报错重要# 导入并打印包路径路径指向哪个 Python 的 site-packages就是装进哪个解释器 python3 -c import datafeed; print(datafeed.__file__)打印出路径、没有异常安装这一关才算过。如果打印的路径和你跑脚本的解释器不是同一个别急着往下走先把sys.path和解释器对应关系理清楚不然后面所有登录失败回调不触发的排查都会跑偏。3. 环境参数配置set_env 里那几个必须先定下来的键set_env是整套 API 的闸门创建实例之后、注册登录之前必须先调它不调直接 login 会失败或者行为异常。它同时干两件事注册回调函数、设定连接与重连参数。多数人只记得注册回调把连接参数全用默认值等到跨市场或者网络抖动时才回头补代价很高。3.1 回调注册六个行情回调加断线通知签名随版本变过行情和事件通知全部走回调回调签名不对是最难查的一类问题——主程序不报错只是收不到数据因为异常发生在 SDK 的回调线程里。from datafeed.tds_api import TDS tds TDS() # 行情回调固定三个参数数据列表、条数、链路时间戳 def fnc_data(data_list: list, count: int, stats: dict): param data_list: 订阅到的行情数据可能多条 param count: data_list 中的条数 param stats: 数据包经过各节点的时间戳字典 produce_time / send_time / recv_timeunix 微秒 pass # 断线通知回调V2.1.3 起入参由 int 改为 dict def func_notify(msg_notify): param msg_notify: {code: int, msg: str} code 1 网络断开2 网卡不正常3 重复登录被踢 收到即代表多次重连均失败SDK 已停止工作需要重新 Login 并重新订阅 print(disconnect! notify: {}.format(msg_notify[msg])) # 订阅结果回调V2.1.6 起参数有调整注意与本机装的版本对齐 def func(data_type, op_type, market, code_list, statuscode, callback_type): print(statuscode) tds.set_env( fnctickstockfnc_data, # 证券快照 fnctickindexfnc_data, # 指数快照 fnctransactionfnc_data, # 逐笔成交 fncorderdatafnc_data, # 逐笔委托 fncorderqueuefnc_data, # 委托队列 fncsuperstockfnc_data, # 极速盘口需另开产品权限 fncnotifyfunc_notify, # 断线通知 fucsubscribefunc, # 异步订阅结果回调 )六个行情回调的参数签名完全一样都是(data_list, count, stats)所以可以共用一个函数在内部按data_list[0][market]或者业务需要分流。stats里的三个时间戳是排查延迟的抓手recv_time - send_time是服务端发出到你收到的链路耗时send_time - produce_time是 SDK 内部的加工耗时两者分开看能快速判断慢在哪儿。func_notify的msg_notify参数类型是个版本分水岭。V2.1.3 之前它是 int之后是 dict老代码里写print(msg_notify)看不出问题写if msg_notify 1就直接失效了。同理订阅回调在 V2.1.6 增加过参数如果你手里的示例代码参数个数和包版本对不上回调线程会持续抛异常。提示回调函数里不要做耗时操作。落库、复杂计算、写文件都扔进队列交给独立线程回调里只做入队。这是导致行情堵包最常见的原因而且现象是逐渐变慢不是一下子断掉很难定位。3.2 连接与重连参数m_connectmarket 与 m_timeout 怎么取值set_env的可选参数全部有默认值但默认值不一定适合你的场景。下面几个是我每次都会显式写出来的参数类型默认值含义与取舍m_heartbeat_intervalint系统默认心跳间隔单位秒最小 1小于 1 走默认m_reconn_countint系统默认断线重试次数小于 1 表示不重连m_reconn_intervalint系统默认重连间隔秒数小于 1 表示立即重连m_timeoutint5000同步请求超时单位毫秒m_connectmarketstrUSH;USZ连接市场可只填USH或USZ单市场m_logpathstrdatafeed 包安装目录日志输出路径m_loglevelstrwarn日志级别m_connectsubscribeint默认关闭置 1 则断线重登后自动重发订阅m_versionstr一般不用设版本标识m_connectmarket是最容易出事的一个。V2.0.0 把单连接改成多连接之后不同市场走不同的域名和端口只填一个市场就只连一个市场——这就是第 1 章里只收到半个市场的根因。做沪深全推就必须保留USH;USZ除非你明确只要单边。m_timeout默认 5000ms对同步查询接口get_tick_stock、get_code_list这类够用。但如果代码里习惯在开盘瞬间一次性拉全市场快照建议压到 20003000ms让超时早点暴露而不是卡住主线程五秒。反过来网络条件差的机器可以放宽到 8000ms但别无限放宽——同步接口卡住时你的策略循环也就卡住了。重连参数我是这么配的m_reconn_count给 1020m_reconn_interval给 3 秒。连续重连太频繁会被服务端判成异常连接间隔太短反而更容易被拒。# 沪深双市场 明确重连策略 断线自动重发订阅 tds.set_env( fnctickstockfnc_data, fnctransactionfnc_data, fncnotifyfunc_notify, m_connectmarketUSH;USZ, # 双市场缺一个就少一半数据 m_timeout3000, # 同步请求 3 秒超时 m_reconn_count15, # 重试 15 次 m_reconn_interval3, # 间隔 3 秒 m_connectsubscribe1, # 重登后自动重发订阅省掉手工补订阅 )m_connectsubscribe置 1 这一项在长时间运行的程序里基本属于必开。不开的话每次断线重连成功、登录成功之后之前所有sub的订阅都失效了而你的程序还以为在收数据。3.3 日志路径先把黑匣子打开m_logpath默认是 datafeed 包的安装目录m_loglevel默认warn。这两个默认值在 Linux 上很容易出问题包可能装在系统 site-packages 里普通用户对该目录没有写权限日志写不进去又不报错出问题时你手上什么都没有。# 日志单独指到有写权限的目录级别先放宽到 info跑稳了再收紧 tds.set_env( fnctickstockfnc_data, m_logpath/data/log/tds, # Windows 下写成 rD:\log\tds m_loglevelinfo, )路径对应的目录要提前建好权限给足。级别方面调试期用info能看清连接、登录、订阅每一步的返回上线稳定运行一两周后再降到warn减少磁盘写入。这个顺序别反了——先warn后调问题等于蒙着眼修车。4. 登录与订阅从 login 返回码到 sub、async_sub 与级联模式环境参数配好接下来是登录、查代码表、订阅三件事。这一段的坑几乎全在返回码和参数对应关系上接口本身不难。4.1 登录返回值-1004、-1018 和 1 分别指向什么login(username, password)成功返回 0失败返回负数个别情况返回正数。文档里列了完整返回码实际排错时高频出现的就那么几个返回值含义现场处理0成功继续订阅1版本过低请及时更新升级 SDK别硬撑-1002超时无响应查网络、查m_timeout-1003IP 禁止访问找服务方报备出口 IP-1004用户名密码错误先确认账号是否含空格-1005无法连接至服务器查域名端口、查防火墙-1007错误市场检查m_connectmarket-1015级联模式下必须是同一局域网主从节点网络划分有问题-1016重复登录同账号别开多实例-1018版本太低请更新程序与返回 1 同源两个都要判注意 1 和 -1018 都指向版本问题不同版本分支下可能命中不同分支判断逻辑里两个都要覆盖别只写if ret 0。ret tds.login(your_account, your_password) if ret 0: print(login ok) elif ret in (1, -1018): raise SystemExit(SDK 版本过低先升级再跑) else: print(login failed, code , ret) # 其余按返回码表逐项排查4.2 市场号对照与同步订阅少写一个市场就少一半数据订阅之前得先知道市场号怎么分。沪深两边的编号规律一致但名字不同混用会直接返回错误市场市场号对应市场市场号对应市场USHI上海指数USZI深圳指数USHA上海 A 股USZA深圳 A 股USHB上海 B 股USZB深圳 B 股USHD上海债券USZD深圳债券USHJ上海基金USZJ深圳基金USHP上海退市整理USZP深圳退市整理USHT上海风险警示板注意上证 A 股实际还包含 USHT风险警示板。做全市场扫描时只订阅 USHAST 类标的就漏了而这恰恰是涨停板策略最关注的一批代码。同步订阅有四个接口语义要分清sub是清掉该市场该类型的全部订阅再重新订阅unsub是取消全部add_sub是增量加代码del_sub是增量减代码。把sub当增量接口用是新手最常见的误操作——每次调sub加一只票前面订阅的全被冲掉了。# 查询获取 USHI 全部指数代码再拉全市场指数快照 codes tds.get_code_list(USHI) index_ticks tds.get_tick_index(USHI, []) # [] 表示全市场 # 同步订阅先清空 USHA 的证券快照订阅再按新列表重订 tds.sub(stock, USHA, [600000, 600519]) # 增量再加两只不影响已有订阅 tds.add_sub(stock, USHA, [601318]) # 增量取消只去掉一只 tds.del_sub(stock, USHA, [601318]) # 整类取消USHA 的证券快照订阅全部清掉 tds.unsub(stock, USHA)data_type的取值是固定的几个字符串index、stock、queue、order、trans、superstock。极速盘口对应的superstock需要另开产品权限没权限时订阅会返回失败码别把它当成接口写错了。4.3 异步订阅与 fucsubscribe订阅结果不靠返回值靠回调async_sub是为高频调订阅场景准备的返回码只表示请求发出去了真正的订阅结果通过fucsubscribe注册的回调返回。def on_subscribe(data_type, op_type, market, code_list, statuscode, callback_type): param op_type: 1 全新订阅 2 取消订阅 3 增加订阅代码 4 取消订阅代码 param statuscode: 0 成功其余失败 param callback_type: 1 异步订阅请求触发2 重连或重登后自动重发触发 if statuscode ! 0: print(sub failed, data_type, market, code_list, statuscode) tds.set_env(fnctickstockfnc_data, fucsubscribeon_subscribe) # op_type1 全新订阅op_type3 增加代码op_type2 取消订阅 tds.async_sub(stock, 1, USZA, []) tds.async_sub(trans, 3, USZA, [000001])callback_type这个参数很有用值为 2 说明是断线重连后 SDK 自动重发的订阅结果看到它就说明刚才断过一次线可以据此在监控里打个点。把m_connectsubscribe置 1 之后这类回调会明显变多属正常现象。4.4 级联模式tool.ini 的 master 与 socket_port需要在一台机器上跑多个 SDK 实例时用级联主 SDK 连行情服务器从 SDK 连主 SDK。切换靠一个本地配置文件tool.iniPython 版本放在与程序文件同级的位置。# 主 SDK 的 tool.ini mastertrue socket_port9999 # 从 SDK 的 tool.ini同一台机器上端口必须错开 masterfalse socket_port9998两个字段的语义master区分主从默认truesocket_port是本 SDK 的监听端口同机多实例必须各不相同。文档里专门强调了一句——端口号后面要接换行符否则可能读取失败。这个细节极其容易被忽略用脚本生成配置文件时如果没有结尾换行级联就起不来而且报错信息不会指向配置文件。从 SDK 侧还要在登录之前调用register_addr注册主节点地址# 从 SDK先注册主节点地址再登录 tds.register_addr(master, 192.168.1.10, 9999) tds.login(your_account, your_password) # 账号密码需与主 SDK 一致market参数固定填masteraddr是主 SDK 所在机器的 IPport与主 SDK 的socket_port一致。调用顺序不能反register_addr必须在登录前而且主 SDK 得先登录成功从 SDK 才连得上。5. 避坑排查装完连不上、收不到数据的五个现场下面五条是我在实际部署里重复遇到过的按现象、原因、解决记遇到同类问题时可以对着症状直接跳过去看。5.1 现象import 成功一调后续接口就失败现象很典型import datafeed不报错TDS()也能创建实例但一调login就返回失败或者干脆抛异常。原因是漏了set_env。这个接口的定位是必须先调用才能调用后续的注册、登录它不只设参数还承担了内部初始化。很多示例代码把set_env和login写在一起抄的时候只抄了后半段。解决方式是固定成模板创建实例、set_env、login三步一条链中间不插别的逻辑。写代码时我会把这行注释直接挂在TDS()上面避免下次又忘。另外set_env有返回值成功True失败False一定要判——返回False还往下走后面所有报错都是误导。5.2 现象登录一直返回 -1005防火墙也没拦明明账号密码没问题返回码却是 -1005 无法连接至服务器本机 telnet 行情端口也不通。原因多半在版本与连接模式的组合上。V2.0.0 之前是单连接一个域名一个端口改成多连接之后不同市场要注册各自的域名和端口。V2.0.1 起 Linux 版本已经把各市场的默认域名端口写进默认配置正常情况下不用手工配但如果你的环境是从旧版本升级上来的残留的旧配置文件会覆盖掉新的默认值表现就是连不上。解决升级时把旧的配置文件清干净让 SDK 重新生成默认配置m_connectmarket显式写成USH;USZ别留空也别只写一个。升级前先备份旧配置出问题能对比着看。5.3 现象回调函数里异常不断行情时快时慢程序日志里零星出现回调异常行情延迟越来越高但连接一直没断。原因基本可以锁定在回调里干了重活。回调运行在 SDK 的接收线程上一旦这里阻塞后面的数据包就在缓冲区排队。落库、写文件、复杂计算、同步 HTTP 请求全都不该出现在回调里。解决回调只做一件事——把data_list和stats塞进queue.Queue业务逻辑放独立线程消费。队列要设上限满了就丢弃并计数宁可丢几条也不能堵同时把丢包计数打到监控里它是判断消费能力是否够用的直接指标。5.4 现象级联模式起不来从 SDK 连不上主 SDKtool.ini按文档写了register_addr也调了从 SDK 就是连不上返回负值。三个原因里至少有一个中招一是socket_port那一行结尾没换行配置读取失败SDK 认为自己在默认端口上二是主从实例在同一台机器上却用了同一个端口三是register_addr在login之后才调或者主 SDK 自己还没登录成功。解决用cat -A tool.ini或十六进制编辑器确认文件末尾有换行同机多实例的端口从 9999 往下依次错开把调用顺序硬性固定为主 SDK 登录成功 → 从 SDKregister_addr→ 从 SDKlogin。另外级联要求主从在同一局域网内跨网段会直接返回 -1015这条限制没法绕。5.5 现象字段解析报类型错误撤单金额变成整数代码按老模板解析证券快照某天开始对沪市的撤单字段报TypeError或者金额明显被截断。原因是 V2.0.6 改过数据类型withdraw_buyturnover和withdraw_sellturnover由int改成float目的是提高数据精度。如果你的解析逻辑里写死了int(...)或者用结构体偏移的方式读二进制就会踩上。解决字段解析一律走取值 类型转换 异常兜底不要假设类型。落库时金额字段统一用浮点或定点小数别在 ORM 里声明成整型。升级 SDK 之前把用到的字段逐个对一遍版本变更说明——V2.0.6 是类型变化V2.1.4 是新增字段V2.1.9 是逐笔委托增加委托序号每一类对下游的影响都不一样。6. 跑通验证先用离线回放走一遍再切实时全推上线前我固定跑两步验证顺序不能颠倒先离线调试模式确认回调链路通再切实时确认市场覆盖全。跳过第一步直接连实时等于拿生产流量当测试用例。6.1 离线调试用本地 CSV 驱动整条链路离线调试模式读取本地数据文件驱动 SDK 运行登录不连线上网关直接返回成功。调用时机很严格实例创建之后、登录之前已经登录再调不生效。文件命名是硬约束SDK 靠文件名判断数据类型命名不规范的文件直接不读stock.csv、index.csv、order.csv、queue.csv、trans.csv、superstock.csv、codelist.ini。CSV 表头字段名参照模板列顺序不强制。from datafeed.tds_api import TDS tds TDS() def callback_stock(data, count, stats): print(receive count:, count) # 拿第一条看字段是否齐全比逐条打印安全 print(first record:, data[0] if count else None) tds.set_env(fnctickstockcallback_stock) # 数据目录、要回放的文件类型、推送间隔(ms)、单次条数、遍历次数 tds.start_offline_debug( path/data/offline, # Windows 下用 rD:\datafeed subtype[stock, index, order, queue, trans, superstock], push_space3000, # 每 3 秒推一批 push_count5000, # 每批 5000 条 playback_times1, # 文件遍历 1 遍 ) # 离线模式下 login 不连服务器直接返回成功 tds.login(your_account, your_password)几个参数的实际影响push_space决定回放速度设得太小会一次把队列灌满看不出消费能力push_count决定单批条数设成和实盘回调的量级接近才有参考价值。回放期间如果某批数据里不含你订阅的代码回调可能不触发——这跟实时行情的机制一致不是 bug。级联模式下只有父节点支持离线调试子节点调这个函数无效。6.2 上线前的四项验证离线跑通之后切实时我按下面四项依次确认每项都要有明确的通过标准验证项方法通过标准市场覆盖统计回调里market字段的去重值沪深两边都出现且包含 USHT订阅生效调sub后看fucsubscribe回调statuscode全部为 0链路延迟用stats算recv_time - send_time稳定在毫秒级无明显毛刺断线恢复手动断网 10 秒再恢复重连成功callback_type2的订阅回调出现第一项最容易出问题也最容易被忽略——程序不报错就是少了一半数据跑一天才发现。我会在启动脚本里加一行统计把出现的市场集合打印出来跟预期集合做比对对不上直接退出。从那以后我每次装这套 SDK都强制走一遍位数自查 → import 验路径 → 离线回放 → 双市场确认这四步宁可多花十分钟也不在盘中去猜为什么少了一半行情。希望帮到你。本文还有配套的精品资源点击获取