ai_quant_trade 债券大宗交易明细接入实战：Tushare bond_blk_detail 接口全解析

• 金融科技
• 示例工程

债券大宗交易明细是观察机构资金在交易所债券市场动向的核心数据，本文基于 ai_quant_trade 仓库中 tushare skill 包 的债券专题文档，系统讲解bond_blk_detail接口的权限门槛、输入输出参数、调用方式与数据样例，并结合仓库内的工程化示例（Token 管理、HTTP 客户端、流控）给出可直接落地的全量数据提取方案。读完本文，你将能够独立完成债券大宗交易明细的按日/按期/按券查询，并搭建符合积分配额限制的循环抓取流程。

一、接口概览：能拿什么数据、有什么门槛

bond_blk_detail用于获取沪深交易所债券大宗交易明细数据，在 tushare 数据接口列表中登记为 ID 272，归属"债券专题"分类，文档位于 大宗交易明细.md。

使用该接口前必须了解三个关键约束：

重要数据范围说明：本接口目前只包含深交所的大宗交易明细，上交所的明细已经包含在债券大宗交易汇总接口（bond_blk）中，未在此接口单独罗列。因此，要做沪深两市债券大宗交易的全景分析，需要将 债券大宗交易.md 中记录的bond_blk（汇总）接口与本接口（深交所明细）配合使用。从文档注释看，bond_blk与bond_blk_detail的差异在于输出字段：汇总接口不含买卖营业部信息，而明细接口额外提供了buy_dp（买方营业部）与sell_dp（卖方营业部），这正是"明细"二字的含义所在。

二、前置准备：安装与 Token 初始化

参考 SKILL.md 的快速上手章节，本仓库对 tushare 的使用统一遵循如下流程：

1. 安装 Python 运行环境（推荐 Python 3.7+），并从清华 PyPI 镜像安装 tushare：

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 在 Tushare 官网注册账号、获取 Token（需达到 5000 积分才可调用本接口），并配置环境变量：

export TUSHARE_TOKEN=your_token

3. 初始化 pro 接口实例。仓库中的 tushare_demo.py 给出了两种取值方式——从环境变量读取，或使用 tushare 本地记录的 token：

import os import tushare as ts # 读取环境变量中的 token，或者读取本地记录的 token token = os.getenv('TUSHARE_TOKEN') or ts.get_token() # 初始化 pro 接口实例 pro = ts.pro_api(token)

对应仓库 README.md 中也有说明：ts.set_token('你的token')可直接写入本地 token 记录，两种方式均可在本仓库的示例脚本中复用。

三、输入参数详解

bond_blk_detail支持 4 个可选输入参数，全部为非必选（N），但实际使用时建议至少指定一个维度（日期区间或债券代码），否则服务端可能拒绝无筛选条件的请求：

参数设计要点：

• 日期格式统一为 YYYYMMDD：如20210701表示 2021 年 7 月 1 日，这是 tushare 全系接口的通用约定（SKILL.md 的"参数格式说明"一节同样强调了这一点）；
• trade_date 与 start_date/end_date 二选一：指定trade_date可精确提取某一交易日的全部明细；指定start_date/end_date区间可批量提取一段时期的数据。由于单次限量 1000 条，若区间跨度过大，需要配合日期循环分片抓取（见第五部分）；
• ts_code 用于单券追踪：结合trade_date可精确查询某只债券在某一交易日的所有大宗交易笔数，适合对特定发行人的持续跟踪。

四、输出参数详解

接口返回 7 个字段，其中buy_dp与sell_dp是区别于汇总接口的核心字段：

字段使用注意：

• 单位换算：vol的单位会随债券品种不同而变化（万股/万份/万张/万手），amount统一为万元。在做金额聚合或与行情数据对比时，务必先确认对应债券的计量单位，避免数量级错误；
• 营业部字段的文本特性：buy_dp/sell_dp为券商营业部全称文本（如"中国国际金融股份有限公司上海黄浦区湖滨路证券营业部"），也可能是"机构专用"字样，两者直接标识了交易对手性质，可用于机构/游资行为的粗分类。

五、接口调用示例

原文档给出的最简调用方式如下：

pro = ts.pro_api() df = pro.bond_blk_detail(start_date='20210701', end_date='20210930')

在真实工程中，由于单次上限 1000 条且总额不限，推荐使用按交易日循环 + 分批追加的模式来拉取全量数据，例如按自然月逐日遍历：

import tushare as ts import pandas as pd pro = ts.pro_api() def fetch_bond_blk_detail(start_date: str, end_date: str) -> pd.DataFrame: """按日循环提取债券大宗交易明细，规避单次 1000 条上限""" frames = [] cur = start_date while cur <= end_date: df = pro.bond_blk_detail(trade_date=cur) if df is not None and not df.empty: frames.append(df) # 日期推进到下一天（可用 pandas 或 datetime 实现） cur = (pd.to_datetime(cur) + pd.Timedelta(days=1)).strftime('%Y%m%d') return pd.concat(frames, ignore_index=True) if frames else pd.DataFrame() # 提取 2021 年三季度深交所债券大宗交易明细 df = fetch_bond_blk_detail('20210701', '20210930') print(df)

针对单只债券的追踪式查询则可以写为：

df = pro.bond_blk_detail(ts_code='149642.SZ', start_date='20210701', end_date='20210930')

六、数据样例解读

原文档提供了一段 2021 年 9 月 30 日与 9 月 24 日的实际数据样例，字段结构与语义如下：

trade_date ts_code name price vol amount buy_dp sell_dp 0 20210930 149642.SZ 21长城08 100.07 50.00 5003.50 机构专用 机构专用 1 20210930 149642.SZ 21长城08 100.00 65.00 6500.00 机构专用 机构专用 2 20210930 149641.SZ 21长城07 100.00 100.00 10000.00 机构专用 机构专用 ... 995 20210924 138246.SZ 东道02D1 110.17 26.30 2897.47 中国国际金融股份有限公司上海黄浦区湖滨路证券营业部 机构专用

从样例可以读出三层信息：

1. 同一债券同一交易日可有多笔成交（如 21长城08 在 20210930 出现两笔），说明大宗交易按笔记录，做"单券当日总成交"时需按ts_code + trade_date分组聚合；
2. 成交价与面值的关系：price围绕面值 100 元附近波动（99.82 ~ 110.17），偏离度可用于判断该券大宗交易的折溢价水平；
3. 对手方结构：大量记录买卖双方为"机构专用"，说明深交所债券大宗交易以机构间转让为主；个别记录出现具体券商营业部，可用于识别个别机构的交易行为。

七、与 bond_blk 汇总接口的配合使用

同目录下的 债券大宗交易.md 记录了bond_blk接口，它与bond_blk_detail的对应关系如下：

两接口权限门槛一致（均需 5000 积分、单次 1000 条、总量不限）。做完整分析时，推荐以bond_blk建立全市场成交全景，再用bond_blk_detail对深交所品种进行逐笔明细与营业部维度下钻。

八、工程化落地：流控与轻量 HTTP 客户端

仓库中 tushare_demo.py 提供了两处可直接复用的工程化能力，特别适合应对上述"按日循环拉全量"场景：

1. 分钟级流控：免费用户每分钟最多 80 次请求，每天最多 500 次请求。按日循环拉取一年数据约需 250 次请求，若与其他接口混用很容易触顶。tushare_demo.py中的TushareHttpClient._check_rate_limit实现了滑动窗口计数器，达到每分钟配额时自动休眠到下一分钟再继续，可在循环抓取时显著降低被限流的概率。

2. 轻量 HTTP 客户端：TushareHttpClient不依赖 tushare SDK，直接以requestsPOST 到http://api.tushare.pro，内置超时与错误码检查。它同样可以调用bond_blk_detail，调用方式与 SDK 的pro_api保持一致：

client = TushareHttpClient(token=os.getenv('TUSHARE_TOKEN')) df = client.query('bond_blk_detail', start_date='20210701', end_date='20210930')

这一点在 Docker / PyInstaller / 多虚拟环境等不便强依赖 SDK 的部署场景中尤为实用。

九、典型应用场景

结合 ai_quant_trade 仓库"一站式学习、模拟、实盘平台"的定位，债券大宗交易明细数据的落地场景主要有三类：

• 机构动向跟踪：通过buy_dp/sell_dp识别特定营业部或"机构专用"对手方的买卖行为，辅助判断债券发行主体的机构认可度；
• 折溢价监控：对比大宗成交价与二级市场估值（如结合 可转债行情.md 的cb_daily收盘价），捕捉大额折价/溢价转让信号；
• 因子与语料构建：大宗交易折价率、机构参与度等衍生指标可进入多因子选债流程；逐笔明细文本也可作为大模型语料，用于生成债券市场的资金面分析素材（仓库 大模型语料专题数据 目录下的同类数据即服务于这一方向）。

十、总结

bond_blk_detail是深交所债券大宗交易逐笔明细的唯一标准入口，其核心价值在于buy_dp/sell_dp两个营业部字段。使用时牢记三点：5000 积分权限门槛、单次 1000 条上限、仅覆盖深交所（上交所请走bond_blk）。配合仓库 SKILL.md 的初始化流程与 tushare_demo.py 的流控与 HTTP 客户端能力，即可稳定、合规地完成全量数据的循环提取，为债券市场的资金面研究与量化建模提供数据底座。

• 金融科技
• 示例工程