Vibe-Trading 期货仓单日报数据接入指南Tushare fut_wsr 接口详解与实战【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading本指南围绕 Vibe-Trading 开源项目内置的 Tushare 技能库 中「期货数据/仓单日报」参考文档展开系统讲解fut_wsr接口的输入输出参数、调用示例、批量取数策略并结合仓库源码说明如何把仓单数据接入 Vibe-Trading 的行情/数据体系。读完你将掌握仓单日报的字段语义、仓库级仓单变化跟踪方法以及 TUSHARE_TOKEN 在项目中的配置与预检机制能够独立构建「仓单增减 → 商品供需 → 期货信号」的数据链路。仓单日报是什么理解期货交割的底层信号期货仓单Warehouse Receipt简称 WR是交易所认可的、由指定交割仓库或厂库出具的标准化提货凭证。持有仓单意味着实物商品已经入库并完成质检、注册可以在交割环节被期货多头提取。仓单数量因此是衡量现货库存中有多少被锁定在期货交割池里的关键指标直接反映库存压力仓单大量注册说明现货充裕、卖方有强烈交割意愿通常对近月合约价格形成压制供应收缩仓单持续出库、注销说明现货被消耗或被下游提走往往对应现货偏紧期现联动仓单量与基差、月间价差近远月价差存在紧密联动是跨期套利策略的重要输入。Tushare 的fut_wsr接口仓库内对应文档 仓单日报把交易所每日披露的仓单日报结构化粒度精确到单个仓库/厂库是本主题的核心数据源。在 Vibe-Trading 的 Tushare 技能目录中它被归入 期货数据 分类接口 ID 为 140。fut_wsr 接口总览接口文档开篇给出了四个关键约束是调用的前提务必先确认项目说明接口名fut_wsr功能获取仓单日报数据了解各仓库/厂库的仓单变化单次限量单次最大 1000 条总量限制不限制积分门槛用户需要至少 2000 积分才可调取说明积分是 Tushare 平台的账户权限体系具体积分获取与扣减规则以 Tushare 官方积分文档为准仓库文档中引用的链接为 Tushare 官方文档。Vibe-Trading 仓库本身不包含积分获取逻辑仅消费已授权的 token。与同目录其他期货接口相比fut_wsr的单次 1000 条限量意味着当按一个日期拉取时通常一次即可返回当日全部仓库的记录交易所仓单日报的仓库数量远小于 1000但当按start_date/end_date区间拉取多日数据时需要按日期切分循环取数这一点在后面的实战章节会给出完整示例。输入参数详解接口支持 5 个输入参数全部为可选必选列均为 N但实际调用时需要至少给出一个定位维度否则无法确定返回范围。参数表完整继承自 仓单日报文档名称类型必选描述trade_datestrN交易日期symbolstrN产品代码start_datestrN开始日期YYYYMMDD 格式下同end_datestrN结束日期exchangestrN交易所代码各参数的实战理解trade_date指定单个交易日返回该日全市场或配合其他参数缩小范围的仓单明细。文档示例即采用此方式pro.fut_wsr(trade_date20181113, symbolZN)。symbol产品代码如ZN锌、CU铜、C玉米等。注意这里是品种级代码而非具体合约代码如ZN1812因为仓单日报按品种统计与合约信息接口fut_basic返回的fut_code标准合约代码如白银 AG、鲜苹果 AP对应。start_date / end_date区间拉取模式配合 symbol 可以一次获取某品种在一段历史区间内的全部仓单变化。由于单次限量 1000跨多日时需按日循环见下文实战。exchange交易所代码取值与 Tushare 期货系列接口一致可参考 合约信息文档 中的说明CFFEX-中金所、DCE-大商所、CZCE-郑商所、SHFE-上期所、INE-上海国际能源交易中心、GFEX-广州期货交易所。输出参数详解从仓库到品牌的完整字段接口返回 17 个字段覆盖日期 → 品种 → 仓库 → 数量 → 品质 → 折算的完整链路。字段表完整继承自原文档名称类型默认显示描述trade_datestrY交易日期symbolstrY产品代码fut_namestrY产品名称warehousestrY仓库名称wh_idstrN仓库编号pre_volintY昨日仓单量volintY今日仓单量vol_chgintY增减量areastrN地区yearstrN年度gradestrN等级brandstrN品牌placestrN产地pdintN升贴水is_ctstrN是否折算仓单unitstrY单位exchangestrN交易所字段的量化意义解读pre_vol / vol / vol_chg是核心三件套vol_chg vol - pre_vol。vol_chg为负代表该仓库当日出库/注销仓单为正代表新注册入库。逐仓汇总即可得到品种级当日净增减。warehouse / wh_id仓库维度wh_id未默认显示如需按仓库编号做长期去重追踪应在调用时显式通过fields参数请求该列。year / grade / brand / place品质维度用于区分同一品种下不同年份、等级、品牌、产地的仓单结构。铜、铝等金属品种的升贴水pd字段对价差交易尤其重要。is_ct是否折算仓单部分品种允许符合条件的仓单折算入库该字段用于标识此类特殊仓单统计有效库存时需要单独处理。unit单位示例数据中锌为吨不同品种可能为吨、张如纤维板、胶合板等。接口示例与数据形态原文档给出的最小调用示例pro ts.pro_api(your token) df pro.fut_wsr(trade_date20181113, symbolZN)返回df为 pandas DataFrame数据示例2018-11-13锌 ZNtrade_date symbol fut_name warehouse pre_vol vol vol_chg unit 0 20181113 ZN 锌 上海裕强 4960 4960 0 吨 1 20181113 ZN 锌 上港物流 702 702 0 吨 2 20181113 ZN 锌 上港物流苏州 0 0 0 吨 3 20181113 ZN 锌 中储吴淞 0 0 0 吨 4 20181113 ZN 锌 中储大场 0 0 0 吨 5 20181113 ZN 锌 中储晟世 0 0 0 吨 6 20181113 ZN 锌 中金圣源 428 353 -75 吨 7 20181113 ZN 锌 全胜物流 2882 2882 0 吨 8 20181113 ZN 锌 南储仓储 25 25 0 吨 9 20181113 ZN 锌 同盛松江 0 0 0 吨 10 20181113 ZN 锌 国储837处 0 0 0 吨 11 20181113 ZN 锌 国储天威 0 0 0 吨 12 20181113 ZN 锌 国能物流常州 200 200 0 吨 13 20181113 ZN 锌 外运华东张华浜 0 0 0 吨 14 20181113 ZN 锌 宁波九龙仓 0 0 0 吨 15 20181113 ZN 锌 广储830三水西 0 0 0 吨 16 20181113 ZN 锌 康运萧山 0 0 0 吨 17 20181113 ZN 锌 无锡国联 0 0 0 吨 18 20181113 ZN 锌 期晟公司 449 226 -223 吨 19 20181113 ZN 锌 浙江康运 25 25 0 吨 20 20181113 ZN 锌 百金汇物流 0 0 0 吨 21 20181113 ZN 锌 裕强闵行 0 0 0 吨从示例可见三个典型特征按仓库逐行展开每行一个交割库部分仓库当日有增减中金圣源 -75、期晟公司 -223大量仓库保持零或不变。真实的交易信号通常集中在少数几个出现vol_chg ! 0的仓库上。代码实战从单日查询到历史区间批量拉取第一步环境准备与 token 配置Vibe-Trading 中 Tushare 的接入约定记录在 SKILL.md 快速上手安装tushare依赖、注册获取 token、配置环境变量TUSHARE_TOKEN然后通过ts.pro_api(token)初始化。推荐的 token 读取方式兼顾了环境变量与本机缓存import os import tushare as ts # 读取环境变量中的 token或读取本地记录的 token token os.getenv(TUSHARE_TOKEN) or ts.get_token() # 初始化 pro 接口实例 pro ts.pro_api(token) # 获取仓单日报2018-11-13 锌品种 df pro.fut_wsr(trade_date20181113, symbolZN) print(df)在 Vibe-Trading 项目中token 的规范化位置是TUSHARE_TOKEN环境变量配置 schema 在 env_schema.py 中声明为tushare_token: str Field(aliasTUSHARE_TOKEN, default)而 预检模块 preflight.py 的_check_tushare()会检查 token 是否为空或是否停留在占位符your-tushare-token未配置时给出not_configured状态并提示A-share data unavailable。也就是说在 Vibe-Trading 中运行任何依赖 Tushare 的数据任务前预检会先行把关。第二步指定字段控制返回列fut_wsr支持fields参数按需投影。追踪品种级净增减只需核心列df pro.fut_wsr( trade_date20240115, symbolCU, fieldstrade_date,symbol,fut_name,warehouse,pre_vol,vol,vol_chg,unit )注意wh_id、area、pd、is_ct等列默认不显示按需显式声明即可。字段投影还能降低响应体大小在循环取数时显著提升效率。第三步按日循环拉取历史区间规避 1000 条限量由于单次最大 1000 条多日区间建议以每日一个请求的粒度循环并利用 交易日历接口trade_cal过滤非交易日避免无效请求import time def fetch_wsr_history(pro, symbol, start_date, end_date, exchangeNone, sleep0.5): 按交易日逐日拉取某品种的仓单日报返回合并后的 DataFrame。 import pandas as pd # 1. 先取交易日历只对交易日发起请求 cal pro.trade_cal(exchangeexchange, start_datestart_date, end_dateend_date, is_open1) trading_days sorted(cal[cal_date].tolist()) frames [] for day in trading_days: kwargs dict(trade_dateday, symbolsymbol) if exchange: kwargs[exchange] exchange part pro.fut_wsr(**kwargs) if part is not None and not part.empty: frames.append(part) time.sleep(sleep) # 温和限速避免触发平台频控 return pd.concat(frames, ignore_indexTrue) if frames else pd.DataFrame() # 拉取 2023-01 至 2023-03 铜品种的全部仓单日报 df_cu fetch_wsr_history(pro, symbolCU, start_date20230101, end_date20230331)第四步汇总为品种级仓单变化序列逐仓明细是原料策略研究通常需要品种级时序import pandas as pd # 按交易日汇总品种总仓单与净增减 daily df_cu.groupby(trade_date).agg( total_vol(vol, sum), total_pre_vol(pre_vol, sum), total_chg(vol_chg, sum), ).sort_index() # 标记显著异动日净增减超过前 5 日均值 2 倍 daily[chg_ma5] daily[total_chg].rolling(5).mean() daily[signal] daily[total_chg] daily[chg_ma5] * 2把signalTrue的日期作为事件日配合 期货日线行情接口fut_daily与主力合约映射接口fut_mapping即可构建仓单异动 → 价格反应的事件研究或作为跨期套利模型的输入特征。与持仓排名结合双维验证交割博弈仓单变化代表可交割现货的进出而 每日持仓排名接口fut_holding代表期货头寸的多空分布。两者结合可以交叉验证仓单大量注册 前二十席位空头增仓卖方交割力量增强看空信号共振仓单快速注销 多头席位集中增仓现货紧张叠加资金做多趋势信号更可靠同一品种下将fut_wsr的vol_chg与fut_holding的long_chg / short_chg做相关性分析可以识别持仓推动型与现货驱动型行情。# 示例同一交易日锌的仓单净变化与某会员持仓变化对照 wsr pro.fut_wsr(trade_date20181113, symbolZN) hld pro.fut_holding(trade_date20181113, symbolC1905, exchangeDCE) wsr_net wsr[vol_chg].sum() print(fZN 仓单当日净变化: {wsr_net} 吨) print(hld[[broker, vol, long_hld, short_hld]].head())Vibe-Trading 中的 Tushare 接入机制仓单日报文档属于 Tushare 技能库的参考文档而 Vibe-Trading 对 Tushare 的工程化接入体现在三个层面可以作为调用方了解其稳定性设计技能组织fut_wsr在 SKILL.md 数据接口列表 中登记为 ID 140、分类期货数据文档路径 references/期货数据/仓单日报.md。SKILL.md 同时说明所有指向references/的链接以相对文档的形式书写保证人与 Agent 读取的是同一份文件。数据源路由在 market_data.py 的源码中tushare是 A 股等中国市场的默认数据源——当符号无法匹配 Yahoo 等外部源的后缀规则时兜底路由即返回tushare。这意味着仓单等 Tushare 数据在项目中天然与 China 市场的数据链路对接。fallback 适配层tushare_fallbacks.py 展示了项目消费 Tushare 数据的一贯模式通过get_env_config().data.tushare_token读取 token第 22-30 行识别占位符 token与your-tushare-token并抛TushareFallbackUnavailabletest_tushare_fallbacks.py 用内存假客户端验证了字段映射与单位换算如 Tushare 资金流金额以万元为单位、转换为 10k CNY。虽然该适配层目前覆盖的是资金流/龙虎榜/北向/两融工具但其_pro_api()初始化与占位符防护逻辑同样适用于扩展fut_wsr之类的期货数据拉取。预检保护preflight.py 的_check_tushare()在启动阶段即校验 token 是否缺失或停留在占位符未配置时给出not_configured状态而非静默失败从源头避免跑了半天才发现 token 无效的问题。实战要点与常见问题问题处理建议报积分不足错误fut_wsr需要至少 2000 积分确认账户积分达标积分获取方式见 Tushare 官方积分文档原文档所引 积分获取办法。仓库无法代办积分需要自行在 Tushare 平台完成。单次返回被截断单次最大 1000 条多日请求务必按交易日循环避免 start/end 一把梭。symbol 传错使用品种代码如 ZN、CU、C而非带月份的合约代码如 ZN1812合约级明细请参考 合约信息接口 的fut_code语义。需要非默认列wh_id、area、pd、is_ct等默认不显示用fields显式请求。交易日对齐用 trade_cal 过滤出is_open1的日期避免对节假日发起空请求。频控与限速循环取数时加入 sleep 间隔降低触发平台频控的概率。token 配置在 Vibe-Trading 中以环境变量TUSHARE_TOKEN配置避免使用占位符your-tushare-token否则 preflight 会标记为未配置。小结fut_wsr仓单日报接口把交易所的仓单披露结构化到仓库粒度是量化研究可交割库存这一基本面维度的最佳入口之一。本文完整继承了 仓单日报文档 的参数表与示例并补充了字段语义解读、按日循环的批量拉取模板、品种级汇总与事件信号构造以及 Vibe-Trading 项目内的 token 配置、预检与 fallback 机制。将仓单净增减与持仓排名、主力合约映射、日线行情组合使用即可搭建一条完整的库存变化 → 交割博弈 → 期货信号研究流水线。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考