Hugging Face's logo

Spaces:
fromozu
/
stock-data-api
Running

App Files Community
stock-data-api / README.md
fromozuzhouzzz
feat: add niuone US market + X timeline sources on HF tip
b2ca3f2
preview code
|
Raw
History Blame Contribute Delete
15.7 kB
metadata 
title: Stock Data API
sdk: docker
app_port: 7860
pinned: false

股票数据 API 服务

这个目录是从现有板块轮动、短线交易、龙头股分析技能中抽出来的统一数据服务骨架。

它适合部署到 Hugging Face Docker Space，对外提供统一 HTTP API，并用外部数据库缓存 AKShare、东方财富、同花顺、财联社等在线数据源返回的数据。

本地启动 

cd D:\Andy\coding\gupiao_data\stock_data_api_service
python -m uvicorn app.main:app --host 127.0.0.1 --port 7860

打开：

  • http://127.0.0.1:7860/health
  • http://127.0.0.1:7860/docs
  • http://127.0.0.1:7860/api/v1/catalog

Hugging Face 部署

  1. 创建一个新的 Hugging Face Space。
  2. SDK 选择 Docker。
  3. 把本目录内容作为 Space 根目录提交。
  4. 配置 Secrets：
Secret 说明
DATABASE_URL 外部 MySQL 连接串，例如 mysql+pymysql://user:password@host:3306/dbname?charset=utf8mb4
DATABASE_SSL 可选，云 MySQL 要求 SSL 时设为 true
STOCK_DATA_API_KEY 可选。配置后请求必须带 X-API-Key 或 Authorization: Bearer ...
CACHE_ENABLED 可选，默认 true
CACHE_TABLE_NAME 可选，默认 api_cache；复用已有数据库时建议改成独立表名
SOURCE_TIMEOUT_SECONDS 可选，默认 15
SOURCE_RETRY_ATTEMPTS 可选，默认 1；关键接口可在代码中单独设为 2
SOURCE_RETRY_BACKOFF_SECONDS 可选，默认 0.5
SUPPRESS_SOURCE_OUTPUT 可选，默认 true，压制 AKShare 进度条等控制台输出

Hugging Face Docker Space 默认服务端口用 7860，本 Dockerfile 已经按这个端口启动。

主要接口

所有业务接口默认在 /api/v1 下：

接口 说明 默认缓存
GET /stocks/{code}/quote 个股最新行情 5 分钟
GET /stocks/{code}/daily?days=60 个股日 K 200 天
GET /stocks/{code}/technical?days=120&history_days=10 技术指标 6 小时
GET /stocks/{code}/chip 筹码分布（精算版 CYQ，换手率衰减模型） 1 天
GET /stocks/{code}/chip-simple?lookback_days=60 筹码估算（简化版，成交量加权） 1 天
GET /stocks/{code}/fund-flow?days=10 个股资金流 1 小时
GET /stocks/{code}/margin?days=30 个股融资融券 4 小时
GET /stocks/{code}/shareholders?limit=12 股东户数历史 12 小时
GET /stocks/{code}/shareholder-top 前十大股东 12 小时
GET /fund-flow/rank?indicator=5日 个股资金排名 30 分钟
GET /market/limit-up 涨停池 10 分钟
GET /market/limit-down 跌停池 10 分钟
GET /market/breadth 市场宽度 30 分钟
GET /market/temperature 市场温度 15 分钟
GET /market/margin?limit=50 全市场融资融券汇总 4 小时
GET /market/northbound?days=30 北向资金历史日线 1 小时
GET /market/northbound/realtime 北向资金实时分钟 2 分钟
GET /market/northbound/holdings?stock_code=600519 北向资金持股明细 30 分钟
GET /market/shenwan-industry?limit=31 申万一级行业（含PE/PB分位） 15 分钟
GET /market/fund-holdings?date=20260331 基金重仓股 4 小时
GET /market/fund-structure 基金持仓结构 12 小时
GET /boards/concepts/flow 概念板块资金 30 分钟
GET /boards/industries/flow 行业板块资金 30 分钟
GET /news/global 全市场财经新闻 1 小时
GET /stocks/{code}/news 个股新闻 1 小时
GET /stocks/{code}/notices 个股公告 6 小时
GET /stocks/{code}/financial?kind=abstract 财务摘要 / 指标 / 预告 / 快报 2 天
GET /stocks/{code}/income?kind=ytd 利润表（年初至今 / 单季） 2 天
GET /stocks/{code}/balancesheet?limit=10 资产负债表（总资产、负债、权益等） 2 天
GET /stocks/{code}/cashflow?kind=ytd 现金流量表（年初至今 / 单季） 2 天
GET /stocks/{code}/dividends?kind=main 分红与配股方案 2 天
GET /stocks/{code}/equity-history 股本变动历史 2 天
GET /stocks/{code}/freeholders 十大流通股东 2 天
GET /stocks/{code}/daily-basic?days=30 每日基础指标（PE、PB、PS、市值、换手率） 6 小时
GET /etfs/premium?sort=abs ETF 折溢价率列表 30 分钟
GET /etfs/{code}/premium 单只 ETF 折溢价率 5 分钟
GET /hk/stocks/{code}/short-selling 港股沽空记录（日度序列） 6 小时
GET /market/trade-calendar A 股交易日历 1 天
GET /macro/china/{indicator} 中国宏观数据 2 天
GET /macro/chinabond/yield-curve 中债国债收益率曲线 1 天
GET /us/indices 美股三大指数（道指/纳指/标普） 2 分钟
GET /us/sectors 美股行业/主题 ETF 映射（A 股映射） 15 分钟
GET /us/market-summary 隔夜美股盘面摘要（策略语气+指引） 5 分钟
GET /us/stocks/{symbol}/quote 美股个股报价（AAPL、^DJI 等） 2 分钟
GET /us/stocks/{symbol}/daily 美股个股日 K 6 小时
GET /social/x/timeline X/Twitter 关注账号时间线 5 分钟
POST /search LLM 金融搜索（Grok/OpenAI 兼容） 1 小时
GET /search?q=... LLM 金融搜索（简易 GET） 1 小时
POST /ai-search-hub/search 多平台 AI 聚合搜索 30 分钟
GET /ai-search-hub/search?q=... 多平台 AI 聚合搜索（简易 GET） 30 分钟
GET /ai-search-hub/sites 查看可用搜索平台 —

股票类 code 支持 600519、600519.SH、sh600519、000001.SZ 等格式。ETF / 基金代码不要走 /stocks/...，应使用 /etfs/... 或 /funds/...；否则会返回 400 invalid_symbol。

返回格式 

{
  "ok": true,
  "data": {},
  "meta": {
    "endpoint": "stock_quote",
    "source": "akshare.stock_zh_a_spot_em",
    "generated_at": "2026-06-06T09:20:00+00:00",
    "cache": {
      "hit": false,
      "stale": false,
      "key": "stock_quote:...",
      "ttl_seconds": 300
    },
    "attempts": []
  }
}

如果实时数据源全部失败，但数据库里有过期缓存，会返回 cache.stale=true。这能让上层应用选择“展示旧数据并提示”或“直接失败”。

已纳入的数据来源

数据类型 主来源 备用来源
个股实时行情 sina.hq.realtime eastmoney.push2.stock.quote / tencent.qt.quote / akshare.stock_zh_a_spot_em / stock_zh_a_hist / stock_zh_a_daily / yahoo.chart.quote
个股历史 K 线 yahoo.chart.daily / eastmoney.push2his.stock_kline tencent.ifzq.fqkline / stock_zh_a_hist.eastmoney / stock_zh_a_daily.sina / baostock.query_history_k_data_plus
个股资金流 stock_individual_fund_flow eastmoney.push2his.stock_fflow
个股资金排名 eastmoney.push2delay.stock_fund_flow_rank eastmoney.push2.stock_fund_flow_rank / stock_individual_fund_flow_rank / stock_main_fund_flow / ths.stock_fund_flow_individual
涨跌停池 stock_zt_pool_em / stock_zt_pool_dtgc_em ths.limit_up_pool.direct / 过期缓存兜底
概念板块 eastmoney.push2delay.board_flow.concept eastmoney.push2.board_flow.concept / stock_fund_flow_concept / stock_board_concept_name_em
行业板块 eastmoney.push2delay.board_flow.industry eastmoney.push2.board_flow.industry / stock_fund_flow_industry / stock_board_industry_name_em
Legacy 板块龙头/埋伏/频率文本 eastmoney.push2delay.board_flow.combined.legacy eastmoney.push2delay.board_flow.concept/industry / stock_fund_flow_concept / stock_fund_flow_industry
市场宽度 stock_board_industry_summary_ths stock_zh_a_spot_em
新闻 stock_info_global_cls / stock_news_em stock_info_global_em / stock_info_global_sina / stock_info_global_futu / stock_info_global_ths / 过期缓存兜底
公告 stock_notice_report 过期缓存兜底
财务 stock_financial_abstract_ths / stock_financial_analysis_indicator / stock_financial_analysis_indicator_em / stock_yjyg_em / stock_yjkb_em eastmoney.f10.* / 过期缓存兜底
F10 细分表 eastmoney.f10.income/cashflow/balance/dividend/equity/freeholders akshare.stock_balance_sheet_by_report_em / akshare.stock_main_stock_holder
宏观 Jin10 中国宏观直连 / AKShare 中国宏观系列接口 chinabond.government_bond.history_query / 过期缓存兜底
ETF 折溢价率 eastmoney.push2delay.etf_premium eastmoney.push2.etf_premium / akshare.fund_etf_spot_em
港股沽空记录 eastmoney.hk.sellshort.html 过期缓存兜底
融资融券 eastmoney.push2his.stock_rrg akshare.stock_margin_detail_sse / akshare.stock_margin_detail_szse
北向资金 akshare.stock_hsgt_hist_em eastmoney.push2his.kamt_kline
股东户数 akshare.stock_zh_a_gdhs_detail_em eastmoney.datacenter.freeholdersnum
前十大股东 akshare.stock_main_stock_holder eastmoney.f10.freeholders
A 股交易日历 akshare.tool_trade_date_hist_sina 过期缓存兜底
申万行业 eastmoney.push2.sw_industry akshare.index_realtime_sw
基金重仓股 akshare.fund_report_stock_cninfo eastmoney.datacenter.rpt_fund_main_position
基金持仓结构 akshare.fund_hold_structure_em scrapling.eastmoney.fund_structure

AI-Search-Hub 多平台搜索

集成 AI-Search-Hub，可同时查询多个 AI 平台获取不同数据生态的搜索结果：

平台 数据生态
Gemini Google Search、全球网页
Grok X/Twitter 实时搜索、社交趋势
豆包 抖音、头条、中文热点
元宝 微信公众号、微信生态
LongCat 中文知识、本地生活、大众点评
通义千问 中文网页搜索、淘宝数据
MiniMax 中文问答、B站
Kimi 长文档、研究资料

前置条件

  1. 克隆 AI-Search-Hub 仓库：
    git clone https://github.com/minsight-ai-info/AI-Search-Hub ~/AI-Search-Hub
cd ~/AI-Search-Hub && pip install -r requirements.txt
  2. 安装 Playwright 浏览器驱动：playwright install chromium
  3. 在目标 AI 平台提前登录（首次使用需要手动登录保存 Cookie）

环境变量

变量 说明 默认值
AI_SEARCH_HUB_REPO_PATH AI-Search-Hub 仓库路径 自动检测 ~/AI-Search-Hub
AI_SEARCH_HUB_TIMEOUT 单平台超时秒数 120
AI_SEARCH_HUB_DEFAULT_SITES 默认搜索平台（逗号分隔） gemini,grok,doubao
AI_SEARCH_HUB_HEADLESS 是否无头模式运行 false
AI_SEARCH_HUB_MAX_CONCURRENT 最大并发平台数 3

调用示例 

# 查询所有默认平台
curl -X POST http://127.0.0.1:7860/api/v1/ai-search-hub/search \
  -H "Content-Type: application/json" \
  -d '{"query": "贵州茅台最近有什么重大新闻", "sites": ["grok", "doubao", "yuanbao"]}'

# GET 方式
curl "http://127.0.0.1:7860/api/v1/ai-search-hub/search?q=A股市场情绪分析&sites=grok,gemini"

# 查看可用平台
curl http://127.0.0.1:7860/api/v1/ai-search-hub/sites

免费 MySQL 建议

Hugging Face 免费 Space 会睡眠，本地文件缓存不可靠，建议使用外部 MySQL。可以用支持公网连接的免费或低价云 MySQL / PlanetScale 兼容 MySQL 服务 / Aiven MySQL 试用实例等。

数据库只需要一个表 api_cache，服务启动时会自动创建。MySQL 用户需要 CREATE TABLE、SELECT、INSERT、DELETE 权限。

后续迁移技能

原技能脚本已经接入远程优先模式：

  • 设置 STOCK_DATA_API_BASE_URL 后，脚本优先请求本服务。
  • 远程失败、超时或结构异常时，自动回退本地 AKShare。
  • 未设置 STOCK_DATA_API_BASE_URL 时，保持原本本地行为。

详细说明见 原技能远程优先接入说明。

美股与 X/Twitter 数据（参考 niuone 项目补充）

参考开源项目 kunkundi/niuone 的数据覆盖，新增了美股行情/盘面摘要与 X 关注列表时间线两组能力。这些接口复用了本项目已有的多源轮换（run_sources）+ 缓存架构。

美股数据

接口 说明 数据源顺序（自动轮换）
GET /us/indices 道指/纳指/标普三大指数 tencent.qt.us_indices → sina.hq.us_indices → yahoo.chart.us_indices
GET /us/sectors 美股行业/主题 ETF（半导体、软件、军工、生物科技等，含 A 股映射） yahoo.chart.us_sector_etfs
GET /us/market-summary 隔夜美股盘面摘要：风险语气（进攻/平衡/中性/谨慎/防守）+ 指数/板块映射 + 今日指引 组合 us_indices + us_sectors
GET /us/stocks/{symbol}/quote 美股个股/指数报价（如 AAPL、^DJI、TSLA） yahoo.chart.us_quote → sina.hq.us_quote
GET /us/stocks/{symbol}/daily 美股日 K yahoo.chart.us_daily

美股与 A 股是两套独立符号体系：/stocks/... 走 A 股（需 .SH/.SZ），/us/stocks/... 走美股（Yahoo/腾讯/新浪代码）。

X / Twitter 时间线

GET /social/x/timeline?accounts=elonmusk,OpenAI&limit=5

  • 参数 accounts：X 账号，逗号分隔（可带或不带 @）。
  • 参数 limit：每个账号最多抓取条数（1-10）。
  • 参数 hydrate：是否用帖子链接补充正文/媒体直链，默认 true。
  • 数据源顺序：openai_compatible.x_watchlist（复用 /search 的 Grok/OpenAI 兼容模型，实时检索 X）→ x.com.html.timeline（模型未配置时，直接抓取 X 公开 HTML 兜底，能拿到帖子 ID 与页面标题，但正文受反爬限制）。
  • 模型检索需要配置 SEARCH_API_BASE_URL + SEARCH_API_KEY（与 /search 共用）；未配置时自动降级到 HTML 兜底。
# 美股三大指数
curl "http://127.0.0.1:7860/api/v1/us/indices?limit=3"

# 隔夜美股盘面摘要
curl "http://127.0.0.1:7860/api/v1/us/market-summary"

# 美股个股报价
curl "http://127.0.0.1:7860/api/v1/us/stocks/AAPL/quote"

# X 关注账号时间线
curl "http://127.0.0.1:7860/api/v1/social/x/timeline?accounts=elonmusk&limit=3"

免费 MySQL 建议

Hugging Face 免费 Space 会睡眠，本地文件缓存不可靠，建议使用外部 MySQL。可以用支持公网连接的免费或低价云 MySQL / PlanetScale 兼容 MySQL 服务 / Aiven MySQL 试用实例等。

数据库只需要一个表 api_cache，服务启动时会自动创建。MySQL 用户需要 CREATE TABLE、SELECT、INSERT、DELETE 权限。

后续迁移技能

原技能脚本已经接入远程优先模式：

  • 设置 STOCK_DATA_API_BASE_URL 后，脚本优先请求本服务。
  • 远程失败、超时或结构异常时，自动回退本地 AKShare。
  • 未设置 STOCK_DATA_API_BASE_URL 时，保持原本本地行为。

详细说明见 原技能远程优先接入说明。