API.md

Kronos API 文档

本文档提供有关 Kronos 预测服务的 API 端点的详细信息。

基础 URL

基础 URL 将取决于您的部署环境。

• 本地 Docker: http://localhost:7860
• Hugging Face Spaces: https://<your-space-name>.hf.space

身份验证

所有端点（/api/model-status 除外）都受到保护，需要 API 密钥。密钥必须在请求的 Authorization 头中提供。

• Header: Authorization: Bearer <YOUR_API_KEY>

未能提供有效密钥将导致 401 Unauthorized 错误。

---

端点

1. 获取可用模型列表

获取服务端所有可用模型的详细信息。

• URL: /api/available-models
• 方法: GET
• 身份验证: 不需要。

成功响应 (200 OK)

{
  "kronos-mini": {
    "name": "Kronos-mini",
    "model_id": "NeoQuasar/Kronos-mini",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-2k",
    "context_length": 2048,
    "params": "4.1M",
    "description": "Lightweight model, suitable for fast prediction"
  },
  "kronos-small": {
    "name": "Kronos-small",
    "model_id": "NeoQuasar/Kronos-small",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "24.7M",
    "description": "Small model, balanced performance and speed"
  },
  "kronos-base": {
    "name": "Kronos-base",
    "model_id": "NeoQuasar/Kronos-base",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "102.3M",
    "description": "Base model, provides better prediction quality"
  }
}

2. 获取当前模型状态

检查当前是否有模型被加载到内存中，并返回其详细信息。

• URL: /api/model-status
• 方法: GET
• 身份验证: 不需要。

成功响应 (200 OK)

{
  "status": "loaded",
  "model_key": "kronos-base",
  "model_info": {
    "name": "Kronos-base",
    "model_id": "NeoQuasar/Kronos-base",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "102.3M",
    "description": "Base model, provides better prediction quality"
  }
}

模型未加载响应 (200 OK)

{
  "status": "not_loaded"
}

3. 加载模型

手动将一个指定的模型加载到内存中。

• URL: /api/load-model
• 方法: POST
• 身份验证: 需要。

请求体 (Request Body)

{
  "model_key": "kronos-base",
  "force_reload": false
}

• model_key (可选): 模型的键名。默认为 kronos-base。该值必须是 /api/available-models 端点返回的键之一 (例如, "kronos-mini")。
• force_reload (可选): 如果为 true，即使请求的模型已在内存中，也会强制重新加载。默认为 false。

成功响应 (200 OK)

{
  "status": "Model 'Kronos-base' loaded successfully.",
  "model_info": {
    "name": "Kronos-base",
    "model_id": "NeoQuasar/Kronos-base",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "102.3M",
    "description": "Base model, provides better prediction quality"
  }
}

错误响应 (400 Bad Request) 如果提供了无效的 model_key。

{
  "error": "Invalid model_key. Please choose from the allowed models.",
  "allowed_models": [
    "kronos-mini",
    "kronos-small",
    "kronos-base"
  ]
}

4. 获取预测结果

提交 K 线数据并接收预测结果。

• URL: /api/predict_from_data
• 方法: POST
• 身份验证: 需要。

请求体 (Request Body)

{
  "k_lines": [
    [1711324800000, "18.545", "19.514", "18.385", "19.395", "2080487", ...],
    [1711411200000, "19.397", "20.759", "19.356", "20.032", "3020519", ...],
    [1711497600000, "20.030", "20.211", "19.011", "19.303", "2351359", ...]
  ],
  "prediction_params": {
    "pred_len": 120
  }
}

• k_lines (必需): 代表 K 线数据的数组的数组。格式应与币安 API 标准响应匹配（时间戳, 开盘价, 最高价, 最低价, 收盘价, 成交量, ...）。模型仅使用前 6 列。
• prediction_params (可选): 用于预测参数的字典。
  • pred_len (可选): 要预测的未来时间步数。默认为 120。

成功响应 (200 OK)

{
  "success": true,
  "prediction_params": {
    "pred_len": 120
  },
  "prediction_results": [
    {
      "timestamp": "2024-07-01T00:00:00",
      "open": 150.1,
      "high": 152.3,
      "low": 149.8,
      "close": 151.5,
      "volume": 100000.0
    },
    {
      "timestamp": "2024-07-01T01:00:00",
      "open": 151.5,
      "high": 153.0,
      "low": 151.0,
      "close": 152.8,
      "volume": 120000.0
    }
  ]
}

(注意: prediction_results 是一个示例；实际值会有所不同。)

错误响应 (400 Bad Request) 如果模型尚未加载。

{
  "error": "模型未加载。请先调用 /api/load-model。"
}