期货仓单日报数据实战指南：基于 ai_quant_trade 仓库 Tushare Skill 的 fut_wsr 接口全解析

• 金融科技
• 示例工程

导读

本文围绕 ai_quant_trade 仓库中 Vibe Trading Tushare Skill 包内的期货数据仓单日报文档，系统讲解 Tushare Profut_wsr接口的调用方式、输入输出参数、数据语义及实战用法。仓单日报是期货基本面分析中观察"可交割库存"变化的核心数据源，读者学完本文后，将能够独立调用该接口获取各仓库/厂库的仓单数据，并结合仓库内同目录下的持仓排名、合约信息、交易日历等接口，搭建一套完整的期货供需与库存监控方案。

一、仓单日报与期货分析的关联

仓单（Warehouse Receipt，简称 WSR）是期货交易所指定的交割仓库或厂库出具的、证明特定数量商品已完成入库并符合交割标准的凭证。期货市场的"仓单日报"即交易所每日公布的、按仓库/厂库维度的仓单数量与变化明细。

仓单数据的核心价值在于：

• 衡量可交割库存压力：仓单量代表市场实际可用于交割的实物库存，仓单激增往往意味着现货供应宽松或空头交割压力加大；
• 辅助判断基差与近远月价差：仓单增减与现货价格、近月合约价格之间存在联动，是期限结构分析的间接佐证；
• 识别地区性供需差异：数据带有area（地区）维度，可观察不同交割库的库存迁移。

在 ai_quant_trade 仓库中，该接口收录于 Vibe Trading Tushare Skill 包 的期货数据分类下（接口 ID 140，接口名fut_wsr，描述为"获取仓单日报数据，了解各仓库/厂库的仓单变化"）。Skill 包通过标准化 API 方式统一数据资产的对外服务方式，便于量化策略与 LLM Agent 直接复用。

二、接口基本信息与调用前提

与同目录下其他期货接口相比，该接口的 2000 积分门槛属于 Tushare 期货专题数据的常规档位——例如每日持仓排名（fut_holding）与期货主力与连续合约（fut_mapping）同为 2000 积分，而期货合约涨跌停价格（ft_limit）则需要 5000 积分。积分的获取通常通过注册、完善资料、充值或社区贡献等方式累积，具体以官网最新规则为准。

调用前需完成 Tushare SDK 与 Token 配置。仓库 SKILL.md 给出的标准流程为：

# 推荐 python3.7+，从清华 pypi 镜像安装 pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple # 官网注册获取 token 后配置环境变量 export TUSHARE_TOKEN=your_token

仓库内的 tushare_demo.py 也给出了读取 Token 并初始化 API 的规范写法：

import os import tushare as ts token = os.getenv("TUSHARE_TOKEN", "").strip() or ts.get_token() pro = ts.pro_api(token)

三、输入参数详解

fut_wsr的输入参数全部可选（必选列均为 N），但实际调用时必须至少给出有效的筛选条件，否则无法定位数据：

组合用法建议：

• 按日快照：trade_date+symbol获取某一交易日某品种的全市场仓单分布，这也是官方示例的用法；
• 按区间序列：symbol+start_date+end_date拉取某品种一段时间内的仓单变化趋势，用于构建库存时序；
• 按交易所：exchange+trade_date获取某交易所当日的全部仓单数据。

日期参数统一遵循仓库 Skill 包约定的YYYYMMDD格式（如20241231）。关于交易所代码的取值，可参考合约信息接口（fut_basic）中列出的枚举：CFFEX（中金所）、DCE（大商所）、CZCE（郑商所）、SHFE（上期所）、INE（上海国际能源交易中心）、GFEX（广州期货交易所）。

四、输出参数详解

关键字段的业务含义：

• pre_vol/vol/vol_chg三者构成仓单变化的核心：vol_chg = vol - pre_vol，正值为当日新增注册仓单，负值为仓单注销或出库；
• area、grade、brand、place用于刻画同一品种在不同交割库的库存分布与货物品质差异，对地域套利、品牌升贴水分析有用；
• pd（升贴水）表示该仓单相对基准交割品的品质升贴水，影响实际交割成本；
• is_ct标记是否折算仓单（某些品种按品质折算标准仓单数量）；
• unit给出计量单位（如"吨"），用于把数量换算为重量口径。

五、接口调用示例

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

pro = ts.pro_api('your token') df = pro.fut_wsr(trade_date='20181113', symbol='ZN')

在此基础上，可以扩展为更贴近实战的写法：

import os import tushare as ts # 1. 初始化 token = os.getenv('TUSHARE_TOKEN') or ts.get_token() pro = ts.pro_api(token) # 2. 单日单品种全仓库快照（与官方示例等价） df = pro.fut_wsr(trade_date='20181113', symbol='ZN') print(df) # 3. 指定字段，控制返回列 df2 = pro.fut_wsr( symbol='CU', start_date='20240101', end_date='20240131', fields='trade_date,symbol,warehouse,pre_vol,vol,vol_chg,unit' ) # 4. 汇总当日全市场仓单总量（按品种聚合） summary = df.groupby('symbol')[['pre_vol', 'vol', 'vol_chg']].sum()

注意：单次请求最大返回 1000 条。若单日全市场数据超过该上限，应按symbol或exchange拆分请求；区间查询时，可结合交易日历接口（trade_cal）先确定有效交易日，再逐日或分段拉取，避免超出限量。

六、返回数据示例解读

原文档提供了trade_date='20181113', symbol='ZN'（锌）的返回样例，节选如下：

从数据中可以观察出三层信息：

1. 总量视角：锌当日总仓单量约为各仓库vol之和，多数仓库持平，说明整体库存相对稳定；
2. 变化视角：中金圣源（-75 吨）、期晟公司（-223 吨）出现仓单净减少，可能反映仓单注销或提货出库，属于库存边际下降信号；
3. 结构视角：同一天不同仓库的仓单绝对量差异悬殊（上海裕强 4960 吨 vs 浙江康运 25 吨），体现交割库的地理集中度，对判断交割瓶颈与地区升贴水有参考意义。

七、实战：构建期货库存与持仓监控链路

仓单数据单独使用价值有限，将其与仓库内其他期货数据接口联动，可以形成完整的期货供需监控方案。以下为仓库 vibe_trading_skills/tushare 下可组合的接口矩阵：

一个典型的多因子监控伪代码如下：

def check_warehouse_and_position(symbol, trade_date): # 1. 仓单日报：库存变化 wsr = pro.fut_wsr(trade_date=trade_date, symbol=symbol) total_chg = wsr['vol_chg'].sum() # 2. 持仓排名：主力多空变化（可进一步计算净持仓） holding = pro.fut_holding(trade_date=trade_date, symbol=symbol) net_chg = (holding['long_chg'].fillna(0) - holding['short_chg'].fillna(0)).sum() # 3. 主力合约映射：确定当日主力月合约 mapping = pro.fut_mapping(trade_date=trade_date, ts_code=f'{symbol}.SHF') # 交易所后缀按品种调整 return {'仓单增减': total_chg, '主力净持仓变化': net_chg, '主力映射': mapping}

从源码结构看，仓库 stock_data_example.py 展示的"环境变量读取 Token → 初始化 pro 接口 → 带 try/except 的逐接口封装"模式，可以直接迁移到期货数据场景：将各期货接口封装为独立函数，再在main()中按交易日循环调度，即可构建可维护的数据采集层。

八、在 ai_quant_trade 项目中的落地位置

ai_quant_trade 项目定位为"股票 AI 操盘手：一站式学习、模拟、实盘平台"，覆盖股票基础、策略、大模型、因子挖掘、ML/DL/RL、图网络、高频交易等主题。本接口所在的 vibe_trading_skills（源自 HKUDS Vibe-Trading 项目的 skill 包）是其大模型技能体系的一部分：将 Tushare 数百个数据接口以标准化文档 + 示例脚本的形式组织为 Skill，供 LLM Agent 按需检索与调用。

对读者而言，仓库中该文档的价值在于：

• API 契约清晰：输入/输出参数表、限量与积分要求一目了然，可直接作为编程依据；
• 可组合性强：与同目录 13 个期货数据文档（日线行情、持仓排名、结算参数、主力映射、周月线等）构成完整期货数据家族；
• 上手门槛低：参考 SKILL.md 的"快速上手"三步（安装、注册 Token、查询接口文档）即可运行官方示例。

九、注意事项与常见问题

1. 限量与积分：单次 1000 条上限意味着"按日全市场"查询可能被截断，务必按symbol或exchange拆分；2000 积分门槛是硬性要求，积分不足会直接报错；
2. 参数格式：日期必须为YYYYMMDD，不要混用YYYY-MM-DD；
3. 数据口径：pre_vol为昨日仓单量而非"前一日结算量"，首日出现时可能为 0，注意vol_chg的基准含义；is_ct（是否折算仓单）字段只对存在折算规则的品种有意义，使用时需结合品种特性；
4. 交易所后缀：exchange字段取值为交易所代码（如DCE、SHFE），与股票数据的SH/SZ后缀体系不同，切勿混用；
5. Token 安全：建议沿用仓库示例的做法——通过环境变量TUSHARE_TOKEN或ts.get_token()读取本地 token，不要把 token 硬编码进策略代码。

结语

fut_wsr仓单日报接口是 Tushare 期货数据家族中观察实物库存变化的高性价比入口。本文基于 ai_quant_trade 仓库内 仓单日报.md 的接口契约，完整梳理了参数语义、调用示例与实战解读方法，并将其与持仓排名、主力映射等接口串联为可落地的期货监控链路。后续开发中，可直接以仓库内该 Skill 包文档为数据字典，快速搭建属于自己的期货库存与资金监控系统。

• 金融科技
• 示例工程