企业官网建设流程全解析

Vibe-Trading 港股分钟行情数据接入实战：基于 Tushare hk_mins 接口的分钟级行情获取指南

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading

本篇技术指南以 Vibe-Trading 项目内置的 Tushare 数据源技能文档 港股分钟行情 为核心骨架，系统讲解港股分钟行情接口hk_mins的完整接入方法：从接口参数、频度定义、输出字段到 Python SDK 调用、分页循环抓取与实战组合策略，并结合仓库内的 Tushare 技能总览、同数据源的港股日线/交易日历等姊妹文档做纵向延伸。读者学完后，可独立完成任意港股标的（如00001.HK）的 1min/5min/15min/30min/60min 行情抓取，并能在 Vibe-Trading 的量化研究与回测链路中直接复用。

一、接口总览：hk_mins 是什么

hk_mins是 Tushare 提供的港股分钟行情数据接口，接口 ID 为 304，在 Tushare 技能总览 的「数据接口列表」中登记为「港股数据」分类。其核心特征如下：

值得说明的是，hk_mins与仓库中同属 Tushare 技能目录的其他分钟类接口（如 A 股 历史分钟stk_mins、指数 指数历史分钟idx_mins、期货 历史分钟行情ft_mins）保持一致的参数风格与输出约定，学习成本可以复用。

受限前提说明：单次请求最多返回 8000 行，且受积分权限限制。这意味着一次请求通常无法覆盖全部历史分钟数据，需要通过「股票代码 × 日期区间」组合循环抓取，下文会给出标准做法。

二、输入参数详解

hk_mins共支持 4 个输入参数，其中前两个为必选：

2.1 ts_code 代码规范

港股代码统一为五位数字 +.HK后缀的形式，例如长江实业（00001.HK）、腾讯控股（00700.HK）。这与仓库内港股系列接口的约定完全一致：

• 港股实时日线rt_hk_k明确强调「ts_code 代码一定要带.HK后缀」；
• 港股日线行情hk_daily、港股复权行情hk_daily_adj同样使用00001.HK形式的代码。

因此调用hk_mins时，ts_code='00001.HK'中的后缀.HK不可省略。

2.2 freq 频度参数说明

freq是决定数据粒度的关键参数，支持五种取值：

在实际量化场景中，选择粒度需要在信号灵敏度与数据体积/噪声之间权衡：1min 数据适合日内高频策略与盘口微观结构分析，但受 8000 行单次限量约束最明显（约 3～4 个交易日的量）；60min 数据则适合做日内趋势过滤或与日线信号叠加，单次可覆盖更长时间段。

2.3 日期时间参数格式

start_date与end_date使用YYYY-MM-DD HH:MM:SS格式（如2023-03-13 09:00:00），与 SKILL.md 中「参数格式说明」约定的日期规范（YYYYMMDD）略有区别——分钟接口要求精确到时分秒。若省略起止时间，接口会按默认区间返回数据；建议总是显式传入时间窗口，以保证结果可复现。

三、输出字段与数据语义

hk_mins返回 pandas DataFrame，字段定义如下：

3.1 数据样例解读

接口文档给出的真实样例数据（2023-03-13 长实集团00001.HK全天分钟行情）如下：

ts_code trade_time open close high low vol amount 0 00001.HK 2023-03-13 16:10:00 48.80 48.75 48.80 48.75 375500.0 18305625.0 1 00001.HK 2023-03-13 16:00:00 48.80 48.80 48.85 48.75 12000.0 585575.0 2 00001.HK 2023-03-13 15:59:00 48.80 48.80 48.80 48.75 12500.0 609825.0 3 00001.HK 2023-03-13 15:58:00 48.85 48.80 48.85 48.75 9500.0 463725.0 4 00001.HK 2023-03-13 15:57:00 48.80 48.80 48.85 48.75 24000.0 1171450.0 .. ... ... ... ... ... ... ... ... 327 00001.HK 2023-03-13 09:34:00 47.40 47.35 47.45 47.35 17000.0 805975.0 328 00001.HK 2023-03-13 09:33:00 47.55 47.40 47.55 47.40 11000.0 521725.0 329 00001.HK 2023-03-13 09:32:00 47.60 47.55 47.70 47.50 52500.0 2497550.0 330 00001.HK 2023-03-13 09:31:00 47.30 47.60 47.60 47.30 44229.0 2097256.7 331 00001.HK 2023-03-13 09:30:00 47.30 47.30 47.30 47.30 469900.0 22298550.0

从样例中可以观察到几个对后续数据处理很有用的细节：

1. 时间方向：接口默认按交易时间倒序返回（16:10 在前，09:30 在后），使用时建议先按trade_time升序排序，再进入指标计算或回测管道，避免前视偏差。
2. 盘中含盘后数据：16:00～16:10 的条目为港股收盘竞价时段（16:00–16:10）的成交记录，建模时需根据策略定义决定是否保留。
3. 成交量单位：vol以「股」为单位（样例中 09:30 开盘分钟成交 46.99 万股），amount以「元（港币）」为单位，与 港股实时日线 的字段语义一致。

四、接口用法：Python SDK 实战

4.1 标准调用示例

根据接口文档，最基础的调用方式如下：

import tushare as ts pro = ts.pro_api() df = pro.hk_mins( ts_code='00001.HK', freq='1min', start_date='2023-03-13 09:00:00', end_date='2023-03-13 19:00:00', ) print(df)

4.2 初始化带 Token 的 pro 实例

文档中的ts.pro_api()会隐式读取本地缓存的 token。在 Vibe-Trading 项目中，更规范的初始化方式是显式读取环境变量中的 token。参照 Tushare 技能 SKILL.md 中的快速上手示例：

import os import tushare as ts # 读取环境变量中的 token，或读取本地记录的 token token = os.getenv('TUSHARE_TOKEN') or ts.get_token() # 初始化 pro 接口实例 pro = ts.pro_api(token) # 获取港股分钟行情 df = pro.hk_mins( ts_code='00001.HK', freq='5min', start_date='2023-03-13 09:00:00', end_date='2023-03-13 19:00:00', )

仓库内的实际示例脚本 stock_data_example.py 也采用了同样的模式：token = get_env_config().data.tushare_token or ts.get_token()，即优先读取项目环境配置中的 tushare_token，其次回退到 tushare 本地 token 缓存，然后再创建pro实例。这说明在 Vibe-Trading 中，数据源凭据统一走环境配置通道，TUSHARE_TOKEN环境变量是推荐的注入方式。

4.3 HTTP Restful API 方式

hk_mins同时支持 HTTP Restful API。Tushare 通用 POST 请求模型为：向接口地址提交api_name=hk_mins与参数体，返回 JSON 结构中的data即行情数据。由于单次请求与 SDK 方式共享同一套参数与限量规则，实际项目中选择哪种方式主要取决于调用端技术栈：Python 后端首选 SDK，跨语言服务（如前端或脚本）则用 Restful API。

五、突破 8000 行限量：循环分页抓取

单次最大 8000 行是hk_mins的硬性限量（文档明确「可以通过股票代码和日期循环获取」）。对日频策略需要的完整历史分钟数据，标准做法是按日期分片 + 循环累加：

import tushare as ts import pandas as pd pro = ts.pro_api() codes = ['00001.HK', '00700.HK'] # 多标的 freq = '1min' frames = [] # 按交易日逐日抓取，避开 8000 行上限 for code in codes: for day in ['2023-03-13', '2023-03-14', '2023-03-15']: df = pro.hk_mins( ts_code=code, freq=freq, start_date=f'{day} 09:00:00', end_date=f'{day} 16:30:00', ) if df is not None and not df.empty: frames.append(df) result = pd.concat(frames, ignore_index=True) result = result.sort_values('trade_time').reset_index(drop=True) # 升序排列

三个工程要点：

1. 交易日来源：循环中的交易日清单建议由 港股交易日历hk_tradecal接口生成（is_open=1才是交易日），避免对休市日（如台风休市、公众假期）发起无效请求并白白消耗积分额度。
2. 去重：若分片区间存在重叠，合并后需按ts_code + trade_time去重。
3. 时间范围：港股交易时段为 09:30–12:00、13:00–16:00，另含 16:00–16:10 收盘竞价，抓取窗口设为 09:00–16:30 已能覆盖全部分钟记录。

六、港股分钟数据在 Vibe-Trading 中的典型应用组合

hk_mins在仓库的 Tushare 数据源技能体系中属于「港股数据」板块，可与同板块接口组成完整的研究链路：

关于数据口径的一致性，仓库在 SKILL.md 的「参数格式说明」中统一了各接口约定：日期用YYYYMMDD（分钟接口内部精确到秒）、股票代码统一ts_code格式、返回统一为 pandas DataFrame。因此把hk_mins的输出接入仓库内的因子计算或回测引擎时，只需做常规的排序、去空值与类型转换，无需额外的适配层。

七、常见问题与最佳实践

7.1 常见问题排查

7.2 最佳实践清单

• 始终显式传时间窗口：start_date/end_date精确到分钟，保证结果确定性与可复现性；
• 先升序排序再建模：避免接口倒序输出进入回测导致的前视偏差；
• 按交易日历循环：用hk_tradecal生成抓取日期，控制积分消耗；
• 选择合适 freq：数据量敏感场景优先用 5min/60min，微观结构研究再上 1min；
• 复用仓库技能文档：更多港股接口细节可查阅 港股日线行情、港股复权因子 等文档，与hk_mins配合构成完整数据底座。

结语

hk_mins为港股分钟级量化研究提供了标准化的数据入口。结合本文的接口参数说明、SDK 调用示例与循环分页方案，配合 Vibe-Trading 仓库内 Tushare 数据源技能体系的 SKILL.md 总览文档，开发者可以快速构建从「港股分钟行情抓取」到「日内策略回测」的完整数据链路。需要特别提醒的是：正式权限、积分门槛与数据版权均以 Tushare 官方权限说明为准，请在使用前确认账号权限与数据合规要求。

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading