Vibe-Trading 数据接入实战用 Tushare sge_daily 接口获取上海黄金交易所现货合约日行情【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading本文以 Vibe-Trading 仓库中 Tushare 技能文档 — 上海黄金现货日行情 为核心系统讲解上海黄金交易所SGE现货合约日线行情的完整获取链路从sge_daily接口的输入/输出参数、限量与积分门槛到与sge_basic基础信息接口的配套使用、分页循环抽取的工程化写法再到该接口在 Vibe-Trading 项目中的 Token 配置、数据路由与频控退避实现。读完本文你将能够在自己的行情研究或量化回测流程中稳定、合规地拿到 Au99.99、Au(TD)、Ag(TD)、mAu(TD) 等黄金白银现货品种的日级 OHLC、加权均价、持仓与交收数据。一、接口概览什么是 sge_dailysge_daily是 Tushare 数据平台中用于获取上海黄金交易所现货合约日线行情的标准化接口在本仓库的 Tushare 技能索引SKILL.md中登记为ID 285归类于「现货数据」专题与 ID 284 的sge_basic上海黄金基础信息互为配套。接口名sge_daily描述获取上海黄金交易所现货合约日线行情限量单次最大 2000 条可循环或分页提取积分门槛用户积 2000 积分可调取返回格式pandasDataFrame与股票类接口不同sge_daily覆盖的是上海黄金交易所的现货及延期交收合约典型品种包括 Au99.95、Au99.99、Au(TD)、mAu(TD)、Ag(TD)、Au(TN1)、Au(TN2)、iAu99.99国际板、PGC30g熊猫金币、NYAuTN06/NYAuTN12沪纽金等。这些品种的价格单位、交易制度与 A 股股票差异极大调用前必须先弄清其数据口径见下一节。二、数据口径与计量规则务必先读原文档在接口描述后特别给出了一条容易被忽略的重要注释直接决定了数据的解读方式数据由当日 9:00 至 15:30 的交易和前一日夜盘的 20:00 至 2:30 数据构成成交量和成交金额为双向计量。这条口径包含两层含义交易日合并规则SGE 实行「日盘 前一夜盘」的连续交易制度。某个trade_date对应的行情实际上是该日白天 9:00–15:30 日盘与前一日 20:00–次日 2:30 夜盘两段交易的合并结果。因此做日线级别研究时不应再把夜盘单独拆分而是要按接口给出的交易日粒度整体使用。双向计量成交量vol与成交金额amount按买卖双向统计即一笔成交在买卖两侧各计一次。这意味着不能直接把amount / vol当作简单单价使用也不要把该成交量与股票成交量直接类比。配套地合约级的交易时段、最小单笔报价量、最大单笔报价量等信息可通过 上海黄金基础信息文档sge_basic查询——例如 Au99.95 白天 9:00 至 15:30、夜间 19:50 至次日 02:30 交易最小 1 手、最大 500 手而 Au(TD) 等延期品种则分为上午、下午、夜间多段交易。三、输入参数详解SGE daily提供 4 个全部可选的过滤参数均使用YYYYMMDD格式的字符串日期名称类型必选描述ts_codestrN合约代码可通过 上海黄金基础信息sge_basic获得trade_datestrN交易日期start_datestrN开始日期end_datestrN结束日期使用要点四个参数均为「非必选」但实际调用时至少应给定一个维度单一交易日或start_dateend_date区间或ts_code限定合约否则会返回全量数据既无必要也容易触及 2000 条的单次上限。trade_date与区间参数二选一使用给trade_date即取单日全市场截面给start_date/end_date即可按区间拉取配合ts_code可精确到「某合约 × 某区间」。日期一律为YYYYMMDD紧凑格式如20220311不要携带-分隔符。ts_code的合法取值以sge_basic返回的ts_code列为准典型值包括Au99.95、Au99.99、Au(TD)、Ag(TD)、mAu(TD)、Au(TN1)、Au(TN2)、Au100g、iAu99.99、PGC30g、NYAuTN06、NYAuTN12、Pt99.95等。注意(TD)等带括号的合约代码在 URL 拼接或 shell 传参时需要留意转义。四、输出字段全解析接口共返回 14 个字段默认全部显示名称类型默认显示描述ts_codestrY现货合约代码trade_datestrY交易日closefloatY收盘点元/克openfloatY开盘点元/克highfloatY最高点元/克lowfloatY最低点元/克price_avgfloatY加权平均价元/克changefloatY涨跌点位元/克pct_changefloatY涨跌幅volfloatY成交量千克amountfloatY成交金额元oifloatY市场持仓settle_volfloatY交收量settle_direstrY持仓方向字段口径解读结合原文档与 SGE 交易制度价格单位是「元/克」open/high/low/close/price_avg/change均以每克人民币计价。从数据样例可以看到 Au99.99 收盘 403.60、Ag(TD) 收盘 5.134符合黄金数百元/克、白银数元/克的真实量级。price_avg是加权平均价区别于简单均值适合作为当日实际成交中枢的代理指标做均价回归、成交成本测算时优先使用。vol单位为千克kgamount单位为元。样例中 Ag(TD) 当日成交量 2,428,664.00 千克、Au(TD) 为 27,196.00 千克均为双向计量后的数值量级与白银延期品种的高成交特征相符。oi为市场持仓对 Au(TD)、Ag(TD)、mAu(TD) 等延期交收品种才有实际意义可用于观察资金留仓意愿。settle_vol交收量与settle_dire持仓方向反映当日延期品种的交收申报情况。settle_dire的典型取值为空支付给多空头方向支付递延费/补偿费给多头样例中 Au(TD)、Ag(TD)、mAu(TD) 当日均为空支付给多而 Au99.95、Au99.99 等现货即时交割品种该列为None。该字段对判断延期市场的多空力量对比、测算递延费流向具有实战价值。五、接口调用示例Python原文档给出的标准调用方式如下直接基于tushare包的 pro 接口import tushare as ts pro ts.pro_api() # 获取单日统计数据全合约截面 df pro.sge_daily(trade_date20220311) # 获取某合约指定日期区间、指定字段输出的数据 df pro.sge_daily( ts_codeAu99.99, start_date20220301, end_date20220311, fieldsts_code,close,open,vol )在此基础上结合 Vibe-Trading 项目的实际工程实践可以扩展出更健壮的写法import os import tushare as ts # 方式一读取环境变量中的 token推荐与项目 TUSHARE_TOKEN 约定一致 token os.getenv(TUSHARE_TOKEN) or ts.get_token() pro ts.pro_api(token) # 方式二直接传入 token 字符串 # pro ts.pro_api(你的tushare_token) # 1) 按合约 × 区间拉取并筛选需要的字段 df pro.sge_daily( ts_codeAu(TD), start_date20220301, end_date20220311, fieldsts_code,trade_date,open,high,low,close,price_avg,vol,amount,oi,settle_dire ) # 2) 字段过滤会显著减小响应体节省积分与网络开销 # 3) 返回结果为 pandas DataFrame可直接继续做数据分析 print(df.dtypes) print(df.head())分页/循环抽取超过 2000 条的区间由于接口单次最大返回 2000 条当区间跨度过长时需要按日循环或按月分片拉取后合并。一个通用模板import pandas as pd pro ts.pro_api(os.getenv(TUSHARE_TOKEN)) frames [] for trade_date in date_list: # date_list 为 YYYYMMDD 格式的交易日序列 one pro.sge_daily(trade_datetrade_date, fieldsts_code,trade_date,close,open,vol) if one is not None and not one.empty: frames.append(one) df_all pd.concat(frames, ignore_indexTrue)若以trade_date为循环键单日全合约数量不足 20 个现货合约远低于 2000 上限可以一次性取回当日全市场截面是最省积分、最不易触频控的做法。六、数据样例解读原文档给出了 2022-03-11 的完整数据样例节选如下ts_code trade_date close open high low vol settle_dire 0 Au99.95 20220311 403.3000 403.2000 403.3000 403.2000 24.00 None 1 Au99.99 20220311 403.6000 405.9700 408.0000 402.8000 13667.66 None 2 Au(TD) 20220311 403.2200 405.0100 407.7000 402.5300 27196.00 空支付给多 3 Pt99.95 20220311 227.0400 228.0000 228.0000 226.3000 384.00 None 4 Ag(TD) 20220311 5.1340 5.1820 5.1850 5.1090 2428664.00 空支付给多 5 Au100g 20220311 403.0300 405.4500 406.0000 402.3600 29.40 None 6 Au(TN1) 20220311 405.7000 408.0000 408.0000 402.2000 21.80 None 7 Au(TN2) 20220311 408.1000 411.0000 414.5000 408.0500 91.20 None 8 mAu(TD) 20220311 403.4400 406.6200 407.7500 402.7500 4367.80 空支付给多 9 iAu99.99 20220311 405.3400 406.3000 408.0000 405.0000 2.06 None 10 PGC30g 20220311 409.3200 410.0000 410.0000 408.9000 0.36 None 11 NYAuTN06 20220311 404.5500 407.8500 408.8000 404.0000 15.80 None 12 NYAuTN12 20220311 409.0500 413.8500 413.8500 408.9000 214.40 None从样例中可以读出几个关键事实同一交易日、同一标的的多合约价差结构Au99.99 收盘 403.60 与 Au(TD) 收盘 403.22、mAu(TD) 收盘 403.44 之间的细微价差正是现货与延期品种间期现结构升贴水的直观体现可用于跨品种价差研究。流动性分层明显Ag(TD)242 万千克与 Au(TD)2.7 万千克是绝对主力而 PGC30g0.36 千克、iAu99.992.06 千克等品种流动性极低做流动性约束或回测容量分析时必须区分对待。settle_dire的形态验证延期品种(TD)系列返回空支付给多现货即时品种返回None与第四节字段口径完全一致。七、在 Vibe-Trading 中的落地方式1. Token 配置环境变量约定Vibe-Trading 将 tushare 凭证统一收敛到环境变量TUSHARE_TOKEN见 env_schema.py 中的定义tushare_token: str Field(aliasTUSHARE_TOKEN, default)也就是说在项目环境下无需在代码里硬编码 tokenexport TUSHARE_TOKENyour_token之后既可以在 Tushare 技能文档 的示例模式下os.getenv(TUSHARE_TOKEN)读取也可以由项目的数据层通过配置访问器src.config.accessor.get_env_config().data.tushare_token自动注入。2. 数据源路由中的位置在项目的行情数据路由体系data-routing/SKILL.md中tushare 被列为 A 股、基金、期货、宏观数据的重要来源需要TUSHARE_TOKEN鉴权属于「中国网络」环境下的数据通道market_data.py 的符号路由逻辑则把无法被其它专门通道识别的代码默认回退到 tushare。sge_daily/sge_basic的现货行情正是经由该 tushare 通道对外提供。3. 频控与重试加载器层的工程保障tushare 加载器实现 对 Tushare 各接口共有的「每分钟/每天抽取频率」限制做了专门的容错处理对sge_daily这类受积分与频控双重约束的接口同样适用通过_RATE_LIMIT_MARKERS匹配「每分钟」「每天」「抽取」「频率」「rate limit」「too many requests」等关键词识别频控拒绝而不是普通失败命中频控后按(5s, 20s, 40s)的退避序列重试等待窗口跨过一分钟配额周期普通异常如合约代码错误、日期越界则立即抛出不做无谓等待。这提醒我们在自行编写sge_daily循环抽取脚本时务必为每分钟频控预留退避机制否则长区间分页拉取很容易触发限流。4. 与 sge_basic 的配套使用ts_code的合法取值来自 上海黄金基础信息 的sge_basic接口pro ts.pro_api() # 获取全部现货合约基础信息 df pro.sge_basic() # 或按合约代码查询 df pro.sge_basic(ts_codeAu99.95)ts_code、ts_name如 Au99.99 → 黄金9999、t_unit交易单位克/手、min_change、min_vol/max_vol、margin_rate保证金比例、trade_time交易时段等字段可作为sge_daily行情的元数据字典用于生成合约清单、计算单笔名义价值与保证金占用。注意sge_basic的积分门槛为 5000 积分高于sge_daily的 2000 积分调用权限需按实际账户积分规划。八、实战建议与注意事项日期格式统一所有入参日期使用YYYYMMDD如20220311区间参数与单日参数不可混用。按日循环最稳现货合约数量少不足 20 个以trade_date为键逐日拉取既可规避 2000 条上限又便于对每日结果做增量入库或断点续传。字段按需裁剪fields参数可显著减小响应体研究场景下通常只需要ts_code,trade_date,open,high,low,close,price_avg,vol,amount,oi,settle_dire等核心列。区分现货与延期品种oi、settle_vol、settle_dire主要对(TD)系列延期品种有意义Au99.99 等现货即时交割品种这些字段为None不要将其误读为缺失数据。口径注意行情为「当日日盘 前一夜盘」的合并结果vol/amount双向计量与股票、期货主力合约的统计口径均不相同跨品种对比或数据落库时务必记录口径元信息。频控友好长区间拉取配合指数退避重试加载器层实现 中的 5s/20s/40s 退避序列可以直接复用。权限分级sge_daily需 2000 积分sge_basic需 5000 积分两接口权限不同集成前先在 Tushare 账户确认积分档位。延伸阅读本文核心依据上海黄金现货日行情sge_daily配套合约元数据上海黄金基础信息sge_basic数据源总览与 Token 配置Tushare 技能 SKILL.md凭证环境变量定义env_schema.py频控退避与加载器实现backtest/loaders/tushare.py数据路由与 tushare 通道定位data-routing/SKILL.md、market_data.py【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考