Skip to content

HTTP_API.md

Latest commit

 

History

History
555 lines (457 loc) · 11.9 KB

HTTP_API.md

File metadata and controls

555 lines (457 loc) · 11.9 KB
Raw

Kronos HTTP 模型服务 API 文档

服务信息

  • 基础地址: http://localhost:16888
  • 协议: HTTP/1.1
  • 数据格式: JSON
  • 字符编码: UTF-8

接口列表

方法 端点 说明
GET /health 健康检查
POST /models/load 加载模型
POST /models/switch 切换模型
GET /models/list 列出已加载模型
POST /models/unload 卸载模型
POST /predict 执行预测
GET /params/default 获取默认参数

1. 健康检查

端点

GET /health

请求参数

无

响应示例

{
  "status": "ok",
  "models": {
    "2k_mini": {
      "tokenizer": "2k",
      "model": "mini",
      "device": "auto",
      "load_time": "2026-06-11T15:30:00.123456",
      "use_count": 5
    }
  },
  "active_model": {
    "key": "2k_mini",
    "tokenizer": "2k",
    "model": "mini",
    "device": "auto"
  },
  "max_models": 3
}

响应字段说明

字段 类型 说明
status string 服务状态，固定为 "ok"
models object 已加载模型列表
active_model object/null 当前活跃模型信息
max_models int 最大支持模型数量

2. 加载模型

端点

POST /models/load

请求参数

参数 类型 必填 默认值 说明
tokenizer string 否 2k 分词器类型：2k / base
model string 否 mini 模型类型：mini / small / base

注意：运行设备固定为 auto，不支持手动指定。

请求示例

{
  "tokenizer": "2k",
  "model": "mini"
}

响应示例

{
  "status": "success",
  "message": "模型加载成功"
}

错误响应

{
  "detail": "模型加载失败"
}

3. 切换模型

端点

POST /models/switch

请求参数

参数 类型 必填 默认值 说明
tokenizer string 否 2k 分词器类型
model string 否 mini 模型类型

请求示例

{
  "tokenizer": "2k",
  "model": "small"
}

响应示例

{
  "status": "success",
  "message": "模型切换成功"
}

4. 列出已加载模型

端点

GET /models/list

请求参数

无

响应示例

{
  "models": {
    "2k_mini": {
      "tokenizer": "2k",
      "model": "mini",
      "device": "auto",
      "load_time": "2026-06-11T15:30:00.123456",
      "use_count": 5
    },
    "2k_small": {
      "tokenizer": "2k",
      "model": "small",
      "device": "auto",
      "load_time": "2026-06-11T15:35:00.123456",
      "use_count": 2
    }
  },
  "active": {
    "key": "2k_mini",
    "tokenizer": "2k",
    "model": "mini",
    "device": "auto"
  },
  "count": 2,
  "max_models": 3
}

响应字段说明

字段 类型 说明
models object 已加载模型字典
models.{key}.tokenizer string 分词器类型
models.{key}.model string 模型类型
models.{key}.device string 运行设备（固定 auto）
models.{key}.load_time string 加载时间（ISO格式）
models.{key}.use_count int 使用次数
active object/null 当前活跃模型信息
count int 当前模型数量
max_models int 最大支持模型数量

5. 卸载模型

端点

POST /models/unload

请求参数

参数 类型 必填 默认值 说明
tokenizer string 否 2k 分词器类型
model string 否 mini 模型类型

请求示例

curl -X POST "http://localhost:16888/models/unload?tokenizer=2k&model=mini"

响应示例

{
  "status": "success",
  "message": "模型已卸载"
}

6. 执行预测

端点

POST /predict

请求参数

顶层参数

参数 类型 必填 默认值 说明
code string 是 - 股票/基金/期货/指数代码
start_date string 否 null 开始日期，格式 YYYYMMDD
end_date string 否 null 结束日期，格式 YYYYMMDD
adjusted boolean 否 true 是否前复权
params object 否 null 预测参数对象
tokenizer string 否 null 指定分词器类型（不指定则使用默认模型）
model string 否 null 指定模型类型（不指定则使用默认模型）

注意：运行设备固定为 auto，不支持手动指定。

params 对象参数

参数 类型 默认值 范围 说明
lookback int 512 1-1024 回溯窗口长度
pred_len int 5 1-20 预测步数
t float 0.6 0.1-2.0 温度参数
top_p float 0.8 0.1-1.0 核采样参数
sample_count int 5 1-20 采样次数

请求示例

基础请求

{
  "code": "000001"
}

完整请求（使用默认模型）

{
  "code": "000001",
  "start_date": "20250101",
  "end_date": "20260610",
  "adjusted": true,
  "params": {
    "lookback": 512,
    "pred_len": 5,
    "t": 0.6,
    "top_p": 0.8,
    "sample_count": 5
  }
}

指定模型请求

{
  "code": "000001",
  "tokenizer": "2k",
  "model": "small",
  "params": {
    "lookback": 256,
    "pred_len": 10
  }
}

不复权请求

{
  "code": "000001",
  "adjusted": false
}

curl 示例

# 基础预测
curl -X POST http://localhost:16888/predict \
  -H "Content-Type: application/json" \
  -d '{"code":"000001"}'

# 指定模型预测
curl -X POST http://localhost:16888/predict \
  -H "Content-Type: application/json" \
  -d '{"code":"000001","tokenizer":"2k","model":"small"}'

# 不复权预测
curl -X POST http://localhost:16888/predict \
  -H "Content-Type: application/json" \
  -d '{"code":"000001","adjusted":false}'

响应参数

参数 类型 说明
code string 代码
name string 名称
timestamp string 报告生成时间（ISO格式）
last_trade_date string 最后交易日
model string 使用的模型标识（如: 2k_mini）
lookback int 回溯窗口长度
pred_len int 预测步数
adjusted boolean 是否前复权
summary object 预测摘要
summary.current_price float 当前价格
summary.predicted_price float 预测价格
summary.change_pct float 涨跌幅（百分比）
summary.trend string 趋势：看涨 📈 / 看跌 📉 / 震荡 ➡️
summary.low float 预测区间最低价
summary.high float 预测区间最高价
recent array 最近30个交易日K线
recent[].d string 日期
recent[].o float 开盘价
recent[].h float 最高价
recent[].l float 最低价
recent[].c float 收盘价
recent[].v int 成交量
recent[].a float 成交额
predicted array 未来N个交易日预测K线
predicted[].d string 预测日期
predicted[].o float 预测开盘价
predicted[].h float 预测最高价
predicted[].l float 预测最低价
predicted[].c float 预测收盘价
predicted[].v int 预测成交量
predicted[].a float 预测成交额

响应示例

{
  "code": "000001",
  "name": "平安银行",
  "timestamp": "2026-06-11T15:30:00.123456",
  "last_trade_date": "2026-06-10",
  "model": "2k_mini",
  "lookback": 512,
  "pred_len": 5,
  "adjusted": true,
  "summary": {
    "current_price": 11.20,
    "predicted_price": 11.35,
    "change_pct": 1.34,
    "trend": "看涨 📈",
    "low": 11.10,
    "high": 11.50
  },
  "recent": [
    {
      "d": "2026-06-04",
      "o": 11.05,
      "h": 11.15,
      "l": 11.00,
      "c": 11.10,
      "v": 1000000,
      "a": 11100000
    },
    {
      "d": "2026-06-05",
      "o": 11.12,
      "h": 11.20,
      "l": 11.08,
      "c": 11.15,
      "v": 980000,
      "a": 10900000
    }
  ],
  "predicted": [
    {
      "d": "2026-06-11",
      "o": 11.22,
      "h": 11.38,
      "l": 11.15,
      "c": 11.30,
      "v": 1020000,
      "a": 11500000
    },
    {
      "d": "2026-06-12",
      "o": 11.31,
      "h": 11.45,
      "l": 11.25,
      "c": 11.35,
      "v": 1050000,
      "a": 11900000
    }
  ]
}

错误响应

404 - 未找到数据

{
  "detail": "未找到数据"
}

500 - 服务器错误

{
  "detail": "数据加载失败: 文件不存在"
}
{
  "detail": "预测失败: 模型未加载"
}

7. 获取默认参数

端点

GET /params/default

请求参数

无

响应示例

{
  "lookback": 512,
  "pred_len": 5,
  "t": 0.6,
  "top_p": 0.8,
  "sample_count": 5,
  "tokenizer": "2k",
  "model": "mini"
}

模型管理说明

多模型支持

  • 最多支持同时加载 3 个模型
  • 模型标识格式：{tokenizer}_{model}
  • 默认模型：2k_mini
  • 超过数量限制时，自动移除最旧的（非活跃）模型

模型操作流程

┌─────────────────────────────────────────────────────────────┐
│                     模型管理流程                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 加载模型 → POST /models/load                            │
│           ↓                                                 │
│  2. 查看模型 → GET /models/list                             │
│           ↓                                                 │
│  3. 切换模型 → POST /models/switch                          │
│           ↓                                                 │
│  4. 执行预测 → POST /predict                                │
│           ↓                                                 │
│  5. 卸载模型 → POST /models/unload                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

K线字段缩写对照表

缩写 全称 说明
d date 日期
o open 开盘价
h high 最高价
l low 最低价
c close 收盘价
v volume 成交量
a amount 成交额

错误码说明

状态码 说明
200 成功
404 资源未找到（数据不存在）
422 请求参数验证失败
500 服务器内部错误（模型加载失败、预测失败等）

启动服务

# 基本启动
python server.py --host 0.0.0.0 --port 16888

# 预加载默认模型
python server.py --host 0.0.0.0 --port 16888 --preload

# 开发模式（热重载）
python server.py --host 0.0.0.0 --port 16888 --reload

测试客户端

项目提供了测试客户端 server_test.py：

# 健康检查
python server_test.py --action health

# 加载模型
python server_test.py --action load --tokenizer 2k --model mini

# 列出模型
python server_test.py --action list

# 切换模型
python server_test.py --action switch --model small

# 预测
python server_test.py --action predict --code 000001

# 指定模型预测
python server_test.py --action predict --code 000001 --tokenizer 2k --model small

# 获取默认参数
python server_test.py --action params