Vibe-Trading 股权质押明细数据接入指南基于 Tusharepledge_detail接口的 A 股质押风险分析实战【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading股权质押是 A 股上市公司大股东融资的重要渠道质押比例过高往往意味着平仓风险与股价承压是量化研究与基本面尽调中不可忽视的指标。本文以 Vibe-Trading 仓库内 Tushare 技能文档 股权质押明细数据 为核心系统讲解pledge_detail接口的调用方式、字段语义与数据口径并结合仓库中 tushare 数据接入层的真实实现说明如何在回测、研究流程中正确获取与使用质押明细数据帮助你构建可落地的股权质押风险监测与因子分析方案。接口概述pledge_detail能提供什么pledge_detail是 Tushare 提供的股票质押明细数据接口返回的是每一笔股权质押登记的明细记录而非汇总统计。它记录的是「谁股东、在什么时候、把多少股票、质押给了谁」这类逐笔交易信息粒度细到单次质押行为因此非常适合用于逐笔核对上市公司公告中披露的质押事项跟踪重要股东质押-解押的完整时间轴计算单笔质押占总股本比例评估平仓风险敞口结合回购标记is_buyback识别大股东「质押-回购」循环操作。在 Vibe-Trading 的 tushare 技能体系中该接口与同目录下的 股权质押统计数据接口名pledge_stat形成互补pledge_stat给出的是按截止日期聚合的质押次数、无限售/限售质押数量与质押比例而pledge_detail提供的是支撑这些统计数字的原始逐笔记录。两者可通过 SKILL.md 中「数据接口列表」定位pledge_detail对应 ID 111pledge_stat对应 ID 110。调用限制以仓库内文档为准项目说明接口名pledge_detail数据范围股票质押明细数据单次最大返回1000 条权限要求用户至少需要500 积分方可调取积分获取办法详见 Tushare 官方积分说明文档doc_id13。文档中的「限量单次最大 1000」意味着当单只股票历史质押笔数较多时一次调用可能取不完需要在应用层做分页或按时间切片处理。输入参数按股票代码精确查询pledge_detail的输入参数非常简洁仅需一个必选参数名称类型必选描述ts_codestrY股票代码Tushare 统一代码格式如000014.SZ、600000.SH需要注意的要点ts_code采用「6 位数字 交易所后缀」的 Tushare 标准格式这与仓库中 tushare loader 处理的代码体系一致000001.SZ深圳、600000.SH上海该接口按代码精确查询不支持按日期区间批量拉取全市场因此做全市场质押扫描时需要先通过股票列表接口如stock_basic获取全部ts_code再循环调用日期格式遵循 Tushare 约定YYYYMMDD如20180106这与仓库 SKILL.md 中「参数格式说明」一节的规定完全一致。输出字段详解13 个字段的语义与用途pledge_detail共返回 13 个字段分为「质押事件信息」和「持股与比例信息」两组。理解这些字段的准确含义是正确使用数据的前提。字段类型描述关键用途ts_codestrTS 股票代码关联股票维度ann_datestr公告日期事件的信息披露时点是判断信息可用性的关键holder_namestr股东名称识别质押主体大股东/实控人/机构pledge_amountfloat质押数量万股本次质押的股份数量start_datestr质押开始日期质押登记起始日end_datestr质押结束日期质押到期日is_releasestr是否已解押判断该笔质押当前状态release_datestr解押日期实际解押时间点pledgorstr质押方接收质押的质权人券商/银行/信托等holding_amountfloat持股总数万股质押时点该股东总持股pledged_amountfloat质押总数万股该股东累计质押股数p_total_ratiofloat本次质押占总股本比例单笔质押的稀释/风险权重h_total_ratiofloat持股总数占总股本比例股东持股集中度is_buybackstr是否回购0 否 1 是识别「质押式回购」融资行为字段语义的三个易错点公告日ann_date≠ 质押开始日start_dateann_date是公司对外披露的日期start_date是质押登记生效的日期。文档的数据示例中见下文ann_date20180106的记录对应start_date20171114两者相差近两个月说明质押登记在先、公告披露在后。在做回测或事件研究时必须用ann_date作为信息可得时点否则会引入严重的前视偏差。数量单位是万股不是股pledge_amount、holding_amount、pledged_amount三个字段的单位均为万股。例如文档示例中pledge_amount500.0000表示本次质押 500 万股而非 500 股。换算成股本占比时需要与总股本也按万股计保持单位一致。解押状态is_release与解押日期release_date可能为空尚未解押的质押记录release_date字段通常为空is_release用于标记「是否已解押」不能仅凭release_date是否为空来判断。接口使用两种等价调用方式按照 股权质押明细数据.md 文档调用方式有两种等价且均返回 pandas DataFrame方式一通过pro_api实例直接调用import tushare as ts pro ts.pro_api() # 或者显式传入 token # pro ts.pro_api(your token) df pro.pledge_detail(ts_code000014.SZ)方式二通过通用query方法调用import tushare as ts pro ts.pro_api() df pro.query(pledge_detail, ts_code000014.SZ)在 Vibe-Trading 中的标准接入姿势结合仓库内 stock_data_example.py 的写法更符合本项目规范的做法是从环境配置中读取 tokenimport tushare as ts from src.config.accessor import get_env_config # 读取环境变量 TUSHARE_TOKEN或本地已记录的 token token get_env_config().data.tushare_token or ts.get_token() pro ts.pro_api(token) df pro.pledge_detail(ts_code000014.SZ) print(df.head())其中TUSHARE_TOKEN是仓库 env_schema.py 中定义的配置项tushare_token: str Field(aliasTUSHARE_TOKEN, default)可在环境变量中配置export TUSHARE_TOKENyour_token数据示例解读文档给出了000014.SZ沙河股份的真实返回示例前 7 行如下ts_code ann_date holder_name pledge_amount start_date \ 0 000014.SZ 20180106 中科汇通(深圳)股权投资基金有限公司 500.0000 20171114 1 000014.SZ 20180106 中科汇通(深圳)股权投资基金有限公司 922.0055 20171114 2 000014.SZ 20171221 中科汇通(深圳)股权投资基金有限公司 600.0000 20171114 3 000014.SZ 20171216 中科汇通(深圳)股权投资基金有限公司 300.0000 20171114 4 000014.SZ 20171111 中科汇通(深圳)股权投资基金有限公司 2321.9955 20151127 5 000014.SZ 20170616 中科汇通(深圳)股权投资基金有限公司 0.0100 20151127 6 000014.SZ 20060927 深圳市沙河实业(集团)有限公司 1936.3698 20050119从示例中可以观察到的数据特征同一公告日出现多条记录2018-01-06 当天同一股东披露了两笔质押500 万股与 922.0055 万股说明一个公告可能包含多笔质押明细单日数据需要按记录逐笔处理不能按公告日去重同一股东长期多次质押中科汇通(深圳)股权投资基金有限公司自 2015 年起反复质押同一标的质押日期跨度超过两年是典型的连续质押行为可作为「高质押滚动续作」的研究样本历史数据覆盖久远示例中最早的记录可追溯到 2006 年start_date20050119说明该接口具备长历史数据支撑能力可用于长周期质押行为研究。结合 Vibe-Trading 数据层的源码级扩展pledge_detail属于 Tushare 的参考数据类接口与行情、财务类接口不同它不直接参与 Vibe-Trading 回测引擎的 K 线获取链路。但仓库的 tushare 接入层可以为你提供「如何在项目里正确调用、容错处理 Tushare 接口」的成熟范式1. Token 管理与可用性判定仓库 tushare loader 中DataLoader.is_available()通过检查TUSHARE_TOKEN是否为空或占位符your-tushare-token来决定数据源是否可用这一判定逻辑同样适用于质押明细等所有 Tushare 接口TUSHARE_TOKEN_PLACEHOLDERS {, your-tushare-token} def is_available(self) - bool: from src.config.accessor import get_env_config return get_env_config().data.tushare_token.strip() not in TUSHARE_TOKEN_PLACEHOLDERS在编写质押数据采集任务前先用同样的方式校验 token 配置可以避免「积分不足」「token 无效」之外的配置类误用。2. 频率限制限流与退避重试质押明细接口与仓库 loader 中调用的daily、hk_daily等接口一样受 Tushare 积分频率限制约束。仓库在 tushare.py 中实现了成熟的限流识别与指数退避策略可以直接复用到质押明细的批量抓取中通过_RATE_LIMIT_MARKERS如「每分钟」「频率」「rate limit」「too many requests」识别异常消息中的限流特征而非把所有异常都当作硬失败通过_call_with_backoff按(5s, 20s, 40s)的退避序列重试总时长约 65 秒可跨过一个限流窗口关键设计只有限流才重试普通失败如代码不存在、字段错误立即抛出避免把坏请求变成数秒级的静默卡顿。批量拉取全市场质押明细时务必控制并发与调用节奏并为限流预留退避逻辑。3. 字段与数据类型的规范化处理仓库 loader 在拿到 Tushare 返回后统一做排序、索引与数值化处理pd.to_numeric(..., errorscoerce)。对于质押明细数据pledge_amount、holding_amount、pledged_amount、p_total_ratio、h_total_ratio等数值字段同样建议做类型强制转换避免因缺失值或字符串污染导致后续计算失败。此外ann_date、start_date、end_date、release_date建议统一转为datetime类型并显式处理空解押日期。4. 与基本面数据提供器的时序保护思路对齐仓库 tushare_fundamentals.py 为财务数据建立了「point-in-time」时点保护机制强调必须用公告日如f_ann_date/ann_date而非报告期对齐事件。这一设计哲学对质押明细同样成立任何基于质押数据的回测都应使用ann_date作为信息可得时点防止把未来披露的质押信息引入历史信号造成前视偏差。实战基于pledge_detail的质押风险分析示例以下示例完整演示「获取单只股票质押明细 → 清洗 → 计算质押风险指标」的全流程可直接在 Vibe-Trading 环境中运行import tushare as ts import pandas as pd # 1. 初始化优先使用环境配置中的 token from src.config.accessor import get_env_config token get_env_config().data.tushare_token or ts.get_token() pro ts.pro_api(token) # 2. 拉取质押明细 df pro.pledge_detail(ts_code000014.SZ) # 3. 数据清洗数值化 日期化 for col in [pledge_amount, holding_amount, pledged_amount, p_total_ratio, h_total_ratio]: df[col] pd.to_numeric(df[col], errorscoerce) for col in [ann_date, start_date, end_date, release_date]: df[col] pd.to_datetime(df[col], format%Y%m%d, errorscoerce) # 4. 当前仍在质押、且未解押的记录is_release 语义N 或 0 表示未解押 active df[df[is_release] ! Y].copy() print(f历史质押记录总数{len(df)}当前未解押记录{len(active)}) # 5. 按股东聚合累计质押股数与占总股本比例 grouped active.groupby(holder_name).agg( pledge_total(pledge_amount, sum), p_total_ratio_max(p_total_ratio, max), holding_amount(holding_amount, max), ).reset_index() print(grouped.sort_values(pledge_total, ascendingFalse))提示示例中的is_release判断逻辑需以实际返回值为准文档字段描述为「是否已解押」实践中可先print(df[is_release].value_counts())确认取值后再写过滤条件。p_total_ratio为「本次质押占总股本比例」若要计算「累计质押占总股本比例」需用pledged_amount / 总股本自行计算总股本可通过daily_basic等接口获取。进阶将质押比例纳入因子研究质押数据天然适合构建风险类因子例如高质押占比因子按pledged_amount / 总股本计算累计质押比例作为个股信用风险的截面特征质押-解押事件因子基于ann_dateis_release构造「新增质押」「解押完成」两类事件做事件驱动研究回购循环识别利用is_buyback标记识别大股东「质押-回购」滚动融资行为结合 股权质押统计数据 的pledge_count质押次数交叉验证质押强度。这类参考数据与仓库的行情数据如 历史日线 接口daily按ts_code对齐后即可纳入 Vibe-Trading 的回测与因子分析流程。使用限制与注意事项积分门槛pledge_detail需要至少 500 积分批量全市场抓取对积分消耗较高建议聚焦重点标的池如持仓股、高质押风险股票池而非全市场循环。单次 1000 条上限历史质押笔数较多的股票可能一次取不完需自行实现翻页或按时间切片的补偿逻辑。单位换算所有数量字段均为万股与daily_basic等接口的股本字段换算时需注意单位一致性。信息时点回测与事件研究一律以ann_date公告日期作为信息可得时点规避前视偏差。数据口径字段的具体取值尤其is_release、is_buyback的取值方式建议先对实际返回数据做取值分布检查再写入过滤逻辑。总结pledge_detail是 Vibe-Trading 的 tushare 技能库中获取 A 股股权质押逐笔明细的核心接口与pledge_stat统计数据互补共同构成完整的质押风险数据视图。本文完整覆盖了接口的调用限制、输入输出参数、两种调用方式、真实数据样例解读并结合仓库中 tushare loader、tushare_fundamentals.py 与 env_schema.py 的实现给出了 token 管理、限流退避、字段规范化、公告日对齐等生产级实践建议。掌握这些要点后你就可以在 Vibe-Trading 环境中搭建自己的股权质押风险监测与因子分析流程。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考