Vibe-Trading 研报数据实战：基于 Tushare research_report 接口构建券商研究报告语料与投研信号管道
【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading
本指南围绕 Tushare 的research_report（券商研究报告）接口展开，系统讲解其权限与限量、输入/输出参数、Python 调用方式、按日期与券商循环批量提取的完整方法，并结合开源仓库 Vibe-Trading 中的实际落地（Agent 工具、MCP 服务、投委会多 Agent 编排与测试用例），说明如何把券商研报文本数据转化为可被大模型检索、引用的高质量语料与投研信号源。读完本文，你将能够独立完成该接口的鉴权接入、增量抓取与研报字段清洗，并理解研报数据在 AI 投资助手体系中的典型用法。
接口概览：券商研究报告数据从哪里来、怎么用
research_report是 Tushare Pro 平台提供的大模型语料专题数据接口（接口 ID 为 415），用于获取券商研究报告的元数据——包括个股研报与行业研报的标题、摘要、发布机构、分析师、发布日期、股票/行业归属及下载链接。在仓库中，该接口被归类于agent/src/skills/tushare/references/大模型语料专题数据/目录下，与 上市公司公告.md、新闻联播文字稿.md、新闻快讯(短讯).md.md) 等文本类数据接口并列，定位即为面向大模型训练的金融文本语料源。从仓库的 tushare 技能索引 可以看到其完整描述：
获取券商研究报告-个股、行业等，历史数据从20170101开始提供，增量每天两次更新。
关键使用约束（依据 券商研究报告.md）：
| 维度 | 说明 |
|---|---|
| 数据起始 | 2017-01-01 起的历史研报 |
| 更新频率 | 增量每天两次更新 |
| 单次限量 | 单次最大 1000 条 |
| 总量限制 | 每天总量不限制，可根据日期或券商名称代码循环提取 |
| 权限要求 | 需单独开通权限（与积分无关） |
前置准备：安装与 Token 鉴权
在调用research_report之前，需要完成 Tushare 环境初始化。根据仓库 tushare/SKILL.md 的快速上手说明，推荐使用 Python 3.7+ 环境，并优先从清华 PyPI 镜像安装：
pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple随后在 Tushare 官网注册账号、获取 token 并配置为环境变量：
export TUSHARE_TOKEN=your_token仓库示例脚本 stock_data_example.py 展示了更贴近本项目的 token 读取方式——优先从项目配置读取，其次回退到本地记录 token：
import tushare as ts from src.config.accessor import get_env_config token = get_env_config().data.tushare_token or ts.get_token() pro = ts.pro_api(token)Tushare 接口的参数格式约定如下（见 SKILL.md）：
- 日期：
YYYYMMDD格式（如20241231）； - 股票代码：
ts_code格式（如000001.SZ、600000.SH）； - 返回格式：pandas
DataFrame。
需要特别提醒的是，research_report接口属于单独开通权限的接口，权限与账号积分无关，未开通前调用会直接失败，这一点区别于普通行情类接口。
输入参数详解
research_report支持 7 个输入参数，全部为可选，可根据实际需求组合过滤：
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| trade_date | str | N | 研报日期（格式：YYYYMMDD，下同） |
| start_date | str | N | 研报开始日期 |
| end_date | str | N | 研报结束日期 |
| report_type | str | N | 研报类别：个股研报/行业研报 |
| ts_code | str | N | 股票代码 |
| inst_csname | str | N | 券商名称 |
| ind_name | str | N | 行业名称 |
各参数的选取逻辑可归纳为三类过滤维度：
- 时间维度：
trade_date精确到单日；start_date与end_date组合给出日期区间。三者叠加使用即可构造"某段时间内的全部研报"查询。 - 标的维度：
ts_code（股票代码，格式如600519.SH）精确锁定某只股票的研报；ind_name（行业名称）锁定行业研报的归属行业。 - 来源维度：
report_type区分"个股研报/行业研报"；inst_csname以券商名称（如"东吴证券""中国银河"）过滤指定券商发布的研报。
由于单次最多返回 1000 条，对于全市场或长区间的抓取，官方建议"根据日期或券商名称代码循环提取"——即以日为单位或按券商切分请求，循环累积数据，每天总量不受限制。
输出参数详解
接口每次返回 9 个字段，覆盖研报的"内容元信息"与"下载定位"：
| 名称 | 类型 | 默认显示 | 描述 |
|---|---|---|---|
| trade_date | str | Y | 研报发布时间 |
| abstr | str | Y | 研报摘要 |
| title | str | Y | 研报标题 |
| report_type | str | Y | 研报类别 |
| author | str | Y | 作者 |
| name | str | Y | 股票名称 |
| ts_code | str | Y | 股票代码 |
| inst_csname | str | Y | 机构简称 |
| ind_name | str | Y | 行业名称 |
| url | str | Y | 下载链接 |
对研报语料建设而言，几个字段的用途值得展开：
- title / abstr：标题与摘要构成研报的核心文本语料，可用于标题级主题聚类、摘要级观点抽取；
- trade_date / author / inst_csname：构成研报的"发布三元组"，用于按时间轴追踪机构观点、统计分析师覆盖度；
- ts_code / name / ind_name：将研报与个股、行业建立关联键，便于与行情、财务数据做 join；
- url：研报原文 PDF 下载链接，可作为深度语料抓取的入口。
基础用法与数据样例
接口的调用方式非常直接，初始化pro后按命名参数传值即可：
import tushare as ts pro = ts.pro_api() # 获取2026年1月21日券商研报数据 df = pro.research_report(trade_date='20260121', fields='trade_date,file_name,author,inst_csname') print(df)注意上例中的fields参数只选取了 4 个字段以减小返回体积；不传fields时返回全部输出字段。原文档数据样例中返回的列名为file_name，这与输出参数表中的title字段存在命名差异，从字段内容看二者均指研报文件名/标题，实际以接口当前返回为准。样例数据（节选，共 85 行）：
trade_date file_name author inst_csname 0 20260121 东吴证券_2025年业绩预增点评：α与β共振，验证金融信息服务龙头高弹性_20260121.pdf 孙婷,张良卫,武欣姝 东吴证券 1 20260121 世纪证券_TMT行业周报（1月第2周）：阿里巴巴举办千问产品发布会_20260121.pdf 李时樟,罗晴 世纪证券 2 20260121 中银证券_收购DFS大中华区业务，携手LVMH，全面深化国际业务布局_20260121.pdf 李小民,宋环翔 中银证券 3 20260121 国金证券_收购DFS大中华区业务，战略合作LVMH_20260121.pdf 于健,谷亦清 国金证券 4 20260121 太平洋_东星医疗：微创外科平台型小巨人，多元布局促发展_20260121.pdf 谭紫媚,李啸岩 太平洋 .. ... ... ... ... 80 20260121 中国银河_商业航天系列报告之一：仰望星空，向天突围_20260121.pdf 李良,胡浩淼 中国银河 81 20260121 腾景数研_2025年全球清洁电器发展报告：市场成长长期向好 行业进化值得期待_2026012... 马佳 腾景数研 82 20260121 太平洋_农业周报：猪价旺季反弹，产能持续去化_20260121.pdf 程晓东 太平洋 83 20260121 东吴证券_2025年业绩预告点评：负极盈利拐点已现，多业务板块持续向好_20260121.pdf 曾朵红,阮巧燕,岳斯瑶 东吴证券 84 20260121 中国银河_携手DFS+LVMH，高端复苏+国货出海平台逻辑强化_20260121.pdf 顾熹闽 中国银河从样例可以观察到研报命名的通用范式——券商_主题_日期.pdf，覆盖个股点评（业绩预增/预告点评）、行业周报（TMT、农业）、深度系列（商业航天）与事件点评（收购 DFS 大中华区业务）等多种类型，单日单券商可同时发布多份研报，作者列支持多作者逗号分隔。
批量循环提取：突破单次 1000 条限制
由于接口单次上限为 1000 条，而每天总量不限，工程化的抓取策略应以"循环"为核心。官方明确支持两种切分循环方式：
1. 按日期循环——用于全市场全量抓取。逐日（或逐区间）调用，每天的数据量天然可控：
import tushare as ts pro = ts.pro_api() start, end = '20260101', '20260121' frames = [] for trade_date in _trade_days(start, end): # 用交易日历生成日期序列 df = pro.research_report(trade_date=trade_date) if not df.empty: frames.append(df) result = pd.concat(frames, ignore_index=True)2. 按券商名称循环——用于定向追踪重点机构的观点动向，配合inst_csname参数：
brokers = ['东吴证券', '中银证券', '中国银河'] for broker in brokers: df = pro.research_report(inst_csname=broker, start_date='20260101', end_date='20260121') # 逐家券商持久化，避免单次请求超限在实践中通常将两种方式组合：外层按日期切片保证每次请求落在 1000 条以内，内层按report_type（个股/行业）或ts_code进一步收敛，并为每次请求做错误重试与断点续抓。由于接口每日增量更新两次，可设计为定时任务在两次更新时间点之后触发增量抓取，落库时以(trade_date, ts_code, inst_csname, title)作为去重键。
仓库落地：Vibe-Trading 中的研报数据管道
研报数据在本仓库中并非孤立存在，而是被封装为 AI Agent 可直接调用的工具链，这为理解"券商研报如何服务大模型应用"提供了直接参照。
工具封装：get_research_reports
仓库在 src/tools/research_reports_tool.py 中实现了ResearchReportsTool（工具名get_research_reports），将东财 reportapi 的研报列表与同花顺的一致预期 EPS 拼接为一个 JSON 信封。该工具的入参设计与research_report接口精神一致但面向 Agent 简化：code（必选，如600519.SH）、limit（1–50，默认 20）、beginTime/endTime（YYYYMMDD，默认近两年窗口）。其中关键的工程约束包括：
- 仅支持 A 股（
.SH/.SZ/.BJ），其他市场返回错误信封（见 research_reports_tool.py）； - 日期窗口颠倒会被主动拒绝，避免"空结果被误判为无研报覆盖"的虚假结论（research_reports_tool.py）；
- 研报行无标题且无发布日期时被丢弃，单条坏数据不中断整批解析（research_reports_tool.py）。
MCP 服务注册
在 mcp_server.py 中，get_research_reports被注册为 MCP 工具，通过registry.execute("get_research_reports", params)走统一工具注册表执行，使得任何接入 MCP 的 LLM 客户端都能以标准方式请求研报数据。
多 Agent 投研编排
研报工具被挂载进investment_committee（投委会）Swarm 预设的多个角色中。在 agent/src/swarm/presets/investment_committee.yaml 中，bull_advocate、bear_advocate等多空研究员角色均将get_research_reports列入可用工具清单（见该文件第 47-49 行附近），用于在辩论环节获取"consensus currently believes"（当前市场共识）与研报评级信号，作为基本面论证的证据来源之一。
测试保障
仓库为研报工具提供了完整的单元测试 tests/test_research_reports_tool.py，覆盖成功信封组装、limit截断、同花顺故障降级、非 A 股拒绝、日期窗口校验、近两年默认窗口、乱序窗口拦截等路径，测试全部通过 mock 完成、不触达真实网络。这些测试同时可作为理解研报字段映射关系（predictThisYearEps→eps_forecast.this_year等）的参考。
此外，仓库的 eastmoney 券商研报技能文档 给出了与 Tushare 接口互补的另一路研报数据源（东财 reportapi + 同花顺一致预期），其字段映射表对构建统一研报 schema 具有直接参考价值。
研报数据的典型应用场景
结合"大模型语料专题数据"的定位，research_report数据在 Vibe-Trading 这类 AI 投研体系中的价值主要体现在：
- 大模型文本语料：研报标题与摘要属于高质量金融文本，可用于指令微调、检索增强生成（RAG）语料库建设，为 Agent 提供带时效与来源的卖方观点上下文；
- 情绪与预期信号：按券商、按日统计研报发布频次与主题词，可构建机构关注度、观点分歧度等另类情绪指标，作为投委会多空辩论的输入；
- 观点追踪与一致性校验：利用
inst_csname+ts_code的关联键，追踪同一标的多家券商的评级与盈利预测变化，识别预期差。
使用注意事项
- 权限独立：该接口需单独申请权限，与积分体系无关，未开通时调用返回错误，需先在 Tushare 平台确认权限状态；
- 限量与节奏：单次 1000 条、每日两次增量更新的约束决定了抓取任务应按日期/券商切片并定时触发，避免单次超限；
- 字段版本差异：输出字段在不同阶段可能存在命名差异（如
file_name与title），建议在fields中显式声明所需字段并以实际返回为准； - 数据版权：研报内容版权归属各券商机构，用于个人研究与模型训练时需遵循数据来源方的使用条款，商业化使用前应确认授权边界。
【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
