CoolFace
Apppublic

yingfeng64/kronos-api

sourceHugging Faceupdated 6mo agoView on Hugging Face
0likes
App README

Kronos Stock Predictor API

基于清华大学 Kronos 金融 K 线基础大模型的 A 股概率预测 REST API。

  • —数据源：Tushare Pro A 股日线，前复权（qfq）
  • —推理方式：蒙特卡洛分批采样，输出预测方向、置信度及 95% 交易区间
  • —异步任务：POST 提交 → 返回 task_id → GET 轮询结果

更新说明（2026-03-16）

  • —请求/响应主字段由 ts_code 统一为 symbol
  • —数据源切换回 Tushare Pro（pro_bar，前复权 qfq）
  • —方向概率 direction.probability 定义为“当前 direction.signal 的概率（0–1）”
  • —推理路径改为分批采样（可通过 MC_BATCH_SIZE 调整批大小）
  • —新增阶段耗时日志（fetch/calendar/infer/build/cache/total）

模型信息

项目值
模型NeoQuasar/Kronos-base
参数量102.3M
架构Decoder-only Transformer
最大上下文512 根 K 线
预训练数据全球 45 个交易所，120 亿根 K 线
推理设备CUDA（若可用）/ CPU fallback

快速开始

1. 提交预测任务

bash
curl -X POST "https://yingfeng64-kronos-api.hf.space/api/v1/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "000063.SZ",
    "lookback": 512,
    "pred_len": 5,
    "sample_count": 30,
    "mode": "simple"
  }'
json
{ "task_id": "550e8400-e29b-41d4-a716-446655440000" }

2. 轮询结果

bash
curl "https://yingfeng64-kronos-api.hf.space/api/v1/predict/550e8400-e29b-41d4-a716-446655440000"

status 为 "pending" 时继续等待，变为 "done" 或 "failed" 后读取结果。

Python 一键轮询版

python
import time, requests

BASE = "https://yingfeng64-kronos-api.hf.space"

resp = requests.post(f"{BASE}/api/v1/predict", json={
    "symbol": "000063.SZ",
    "lookback": 512,
    "pred_len": 5,
    "sample_count": 30,
})
task_id = resp.json()["task_id"]

while True:
    r = requests.get(f"{BASE}/api/v1/predict/{task_id}").json()
    if r["status"] in ("done", "failed"):
        break
    time.sleep(10)

print(r["result"])

API 文档

POST /api/v1/predict — 提交单个预测任务

请求体

字段类型默认值范围说明
symbolstring——A 股代码，支持 "603777" 或 "000063.SZ"
lookbackint51220–512回看历史 K 线根数
pred_lenint51–60预测未来交易日数（建议 ≤ 30）
sample_countint301–100MC 蒙特卡洛采样次数
modestring"simple"simple / advanced返回字段详细程度
include_volumeboolfalse—advanced 模式下是否返回成交量预测

响应（`mode=simple`）

json
{
  "symbol": "000063.SZ",
  "base_date": "2026-03-13",
  "pred_len": 5,
  "confidence": 95,
  "confidence_warning": false,
  "cached": false,
  "cache_expires_at": "2026-03-16 15:00:00 UTC+08:00",
  "direction": {
    "signal": "bearish",
    "probability": 0.5667
  },
  "summary": {
    "mean_close": 36.35,
    "range_low": 30.60,
    "range_high": 40.01,
    "range_width": 9.41
  },
  "bands": [
    {
      "date": "2026-03-16",
      "step": 1,
      "mean_close": 36.10,
      "trading_low": 34.46,
      "trading_high": 37.32,
      "uncertainty": 0.0785
    }
  ]
}

`mode=advanced` 在每个 `bands` 条目中追加

字段说明
mean_open / mean_high / mean_low预测开/高/低价均值
close_ci_low / close_ci_high收盘价 95% 置信区间

当 include_volume: true 时额外返回顶层 volume 数组：

json
"volume": [
  {
    "date": "2026-03-16",
    "mean_volume": 1050000,
    "volume_ci_low": 820000,
    "volume_ci_high": 1280000
  }
]

GET /api/v1/predict/{task_id} — 查询单个任务结果

响应

`status`含义
pending正在计算
done完成，result 字段包含预测数据
failed失败，error 字段包含错误信息

POST /api/v1/predict/batch — 批量提交

一次提交最多 20 个预测请求，所有子任务并发入队。每个子任务参数与单个预测相同。

bash
curl -X POST "https://yingfeng64-kronos-api.hf.space/api/v1/predict/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"symbol": "000063", "pred_len": 5, "sample_count": 30},
      {"symbol": "600900", "pred_len": 5, "sample_count": 30},
      {"symbol": "000001", "pred_len": 5, "sample_count": 30}
    ]
  }'
json
{
  "batch_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "task_ids": ["aaa...", "bbb...", "ccc..."]
}

GET /api/v1/predict/batch/{batch_id} — 查询批量进度

json
{
  "batch_id": "xxxxxxxx-...",
  "status": "done",
  "total": 3,
  "done": 3,
  "failed": 0,
  "tasks": [
    {
      "task_id": "aaa...",
      "status": "done",
      "result": { ... },
      "error": null
    }
  ]
}
`status`含义
pending仍有子任务在计算
done全部成功
partial部分成功、部分失败
failed全部失败

GET /api/v1/cache — 查看缓存状态

列出有效缓存条目及剩余 TTL。

参数说明
symbol（可选）只返回该股票的缓存，不传则返回全部
bash
# 查某只股票
curl "https://yingfeng64-kronos-api.hf.space/api/v1/cache?symbol=000063"

# 查全部
curl "https://yingfeng64-kronos-api.hf.space/api/v1/cache"
json
{
  "count": 1,
  "entries": [
    {
      "symbol": "000063",
      "lookback": 512,
      "pred_len": 5,
      "sample_count": 30,
      "mode": "simple",
      "include_volume": false,
      "cached_at": "2026-03-16 10:23:00 UTC+08:00",
      "expires_at": "2026-03-16 15:00:00 UTC+08:00",
      "ttl_seconds": 17220
    }
  ]
}

GET /health — 健康检查

json
{ "status": "ok" }

响应字段说明

字段含义
base_date预测所基于的最后一个历史 K 线日期
direction.signal"bullish" / "bearish"，由内部看涨概率是否 >= 0.5 决定
direction.probability当前 direction.signal 的概率（0–1）
trading_low该日预测最低价的 q2.5 分位数（95% 交易区间下沿）
trading_high该日预测最高价的 q97.5 分位数（95% 交易区间上沿）
uncertainty(trading_high − trading_low) / last_close，无量纲不确定性
confidence_warningpred_len > 30 时为 true，表示预测不确定性较大
cached结果是否来自缓存
cache_expires_at缓存失效时间（北京时间）

缓存机制

缓存 key 由 (symbol, lookback, pred_len, sample_count, mode, include_volume) 六元组构成，失效时机为下一个 A 股交易日收盘（15:00 CST）。

请求时间（CST）缓存过期时间
工作日 00:00–15:00当日 15:00 CST
工作日 15:00 后次个工作日 15:00 CST
周末下周一 15:00 CST
法定节假日不特殊处理（节假日无新数据，缓存命中结果正确）

缓存命中时响应时间 < 100ms，无需等待模型推理。

运行配置

环境变量默认值说明
TUSHARE_TOKEN—Tushare 访问令牌（必填）
KRONOS_DIR/app/KronosKronos 源码目录
MC_BATCH_SIZE8蒙特卡洛分批采样大小（越大通常越快，但占用显存/内存更高）
TS_RETRY_COUNT3Tushare 请求重试次数
TS_RETRY_BASE_SLEEP0.8Tushare 重试退避基准秒数（指数退避）

可观测性

服务会在 INFO 日志输出预测阶段耗时，示例：

text
Task <task_id> timing symbol=300065.SZ fetch=...ms calendar=...ms infer=...ms build=...ms cache=...ms total=...ms

性能参考

环境单次采样30 次 MC 总耗时
RTX 3090 (CUDA)~230ms~7s
CPU only~3–5s~2–5min
推荐选用 GPU 硬件以获得实用响应速度。首次冷启动需从 HuggingFace Hub 下载模型权重，约需 1–2 分钟。