Spaces:
Running
Running
| title: Stock Data API | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # 股票数据 API 服务 | |
| 这个目录是从现有板块轮动、短线交易、龙头股分析技能中抽出来的统一数据服务骨架。 | |
| 它适合部署到 Hugging Face Docker Space，对外提供统一 HTTP API，并用外部数据库缓存 AKShare、东方财富、同花顺、财联社等在线数据源返回的数据。 | |
| ## 本地启动 | |
| ```powershell | |
| 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`。 | |
| ## 返回格式 | |
| ```json | |
| { | |
| "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](https://github.com/minsight-ai-info/AI-Search-Hub)，可同时查询多个 AI 平台获取不同数据生态的搜索结果： | |
| | 平台 | 数据生态 | | |
| |---|---| | |
| | Gemini | Google Search、全球网页 | | |
| | Grok | X/Twitter 实时搜索、社交趋势 | | |
| | 豆包 | 抖音、头条、中文热点 | | |
| | 元宝 | 微信公众号、微信生态 | | |
| | LongCat | 中文知识、本地生活、大众点评 | | |
| | 通义千问 | 中文网页搜索、淘宝数据 | | |
| | MiniMax | 中文问答、B站 | | |
| | Kimi | 长文档、研究资料 | | |
| ### 前置条件 | |
| 1. 克隆 AI-Search-Hub 仓库： | |
| ```bash | |
| 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` | | |
| ### 调用示例 | |
| ```bash | |
| # 查询所有默认平台 | |
| 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` 时，保持原本本地行为。 | |
| 详细说明见 [原技能远程优先接入说明](docs/原技能远程优先接入说明.md)。 | |
| <!-- rebuild 2026-06-20 16:27:31 --> | |
| ## 美股与 X/Twitter 数据（参考 niuone 项目补充） | |
| 参考开源项目 [kunkundi/niuone](https://github.com/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 兜底。 | |
| ```bash | |
| # 美股三大指数 | |
| 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` 时，保持原本本地行为。 | |
| 详细说明见 [原技能远程优先接入说明](docs/原技能远程优先接入说明.md)。 | |
| <!-- rebuild 2026-06-20 16:27:31 --> | |