SDK 状态

Python SDK 正在规划中，目标是减少调用 REST API 的重复代码。目前还没有 PyPI 包，现在请直接通过 HTTP 调用，见下文。

1. 当前可依赖的接口

SDK 发布前，请直接用 HTTP 调用 REST API：POST https://api.sequenxai.com/v1/forecast，历史序列使用 unique_id、ds 和 y。curl、Python 与 JavaScript 的完整示例见快速开始。

forecast-request-shape.json

{
"series": [{"unique_id": "sensor_01", "ds": "2026-09-01T00:00:00Z", "y": 24.5}],
"h": 24,
"freq": "1h",
"level": [80, 90],
"clean_series": true
}

2. SDK 发布的前置条件

公共或受控评估环境可用，并具备真实鉴权与错误响应。
SDK 生成或手写封装与 openapi.yaml 建立版本同步测试。
明确 Pandas、Polars、Arrow 的支持范围与是否发生数据拷贝。
完成 PyPI 发布、版本策略、重试策略与示例的端到端验证。

3. 过渡期方案：免装 SDK，原生 HTTP 调用

在正式客户端库发布前，算法团队无需等待，可通过 Python 现代 HTTP 库（如 httpx 或标准库 urllib.request）直接与接口规范对齐。

以下为基于 httpx（支持同步/异步、自动重试与连接池）的最小封装范例，直接调用真实 API。API 密钥在 SequenxAI 平台创建（免费档即可），历史长度不少于模型最小上下文（见模型与能力上限）：

sequenx_client_minimal.py

import math
import os

import httpx

API_URL = "https://api.sequenxai.com/v1/forecast"
API_KEY = os.environ["SEQUENX_API_KEY"]  # sqx_live_..., created at https://platform.sequenxai.com

# 48 hourly observations: above every model's minimum context.
series = [
  {
      "unique_id": "sensor_01",
      "ds": f"2026-09-{1 + i // 24:02d}T{i % 24:02d}:00:00Z",
      "y": round(24 + 3 * math.sin(2 * math.pi * i / 24), 2),
  }
  for i in range(48)
]
payload = {"model": "hora-1.0", "series": series, "h": 12, "freq": "1h", "level": [80, 90]}

with httpx.Client(timeout=180.0) as client:
  response = client.post(
      API_URL,
      headers={"Authorization": f"Bearer {API_KEY}"},
      json=payload,
  )
  response.raise_for_status()
  result = response.json()

# 解析点预测与置信区间
for item in result["forecast"]:
  y_hat = item["y_hat"]
  p80 = item["intervals"]["80"]
  print(f"[{item['ds']}] 预测值: {y_hat:.2f} (80% 区间: {p80['lo']} ~ {p80['hi']})")

# 检查数据清洗审计报告
quality = result.get("data_quality", {})
print(f"清洗状态: {quality.get('status')}, 填补点数: {quality.get('imputed_points')}")

4. Polars / Arrow 规划

当前 API 接收 JSON 长表负载。Polars 与 Arrow 支持会随 SDK 一起设计，目标是：

长表字段与 DataFrame 列一一对应，可双向转换。
明确序列化格式、内存复制行为与单次负载上限。
在真实数据上对比 Pandas、Polars 与 Arrow 的性能后再确定方案。