Python SDK

使用 Python SDK 快速集成 TimechoAI 时序预测能力到您的应用中。

环境要求

• Python 版本：>= 3.9

安装

pip install timecho-ai

如果您的 API Key 之前可以正常使用，突然无法调用，可尝试执行 pip install --upgrade timecho-ai 升级 SDK 后重试。如果问题仍然存在，欢迎联系我们进一步排查。

请求参数

目前支持的 model_id：Auto · Timer-3.5 · Timer-3.0 · Chronos-2 · AutoARIMA · Holt-Winters

参数名	参数类型	必填	说明	限制
targets	pd.DataFrame	是	目标时间序列数据	数据长度为 [16, 2880]，可不包含时间列
model_id	str	否	模型标识	—
history_covs	pd.DataFrame	否	历史协变量	历史协变量的长度 = 目标变量
future_covs	pd.DataFrame	否	协变量（含未来数据）	长度 = output_length（预测长度），仅数值
output_length	int	否	预测长度	取值范围为 [1, 720]。Timer-3.5 默认 272，其余默认 96
output_start_time	Timestamp | datetime	否	预测起始时间	必须大于历史最大时间
output_interval	datetime.timedelta	否	时间间隔	—
time_col	str	否	时间列名称	指定此参数时，所有输入数据需包含时间列
auto_adapt	bool	否	自动数据适配	默认 True

单变量预测

示例数据 CSV：sample.csv

import pandas as pd
from timecho_ai import TimechoAIClient

# 读取示例数据
raw_df = pd.read_csv("https://ai.timecho.com/data/sample.csv")
print(raw_df.head())

# 任务定义：输入 16 个点，预测 8 个点
INPUT_LENGTH = 16
OUTPUT_LENGTH = 8

# 创建客户端（需替换为您的 API Key）
client = TimechoAIClient(api_key="your_timecho-ai_api_key")

# 构建目标变量 DataFrame
target = raw_df[["time", "target"]][:INPUT_LENGTH]

# 预测 "target" 未来 8 个点
result = client.forecast(
    targets=target,
    output_length=OUTPUT_LENGTH
)

print(result[0])

协变量预测

示例数据 CSV：sample_cov.csv

import pandas as pd
from timecho_ai import TimechoAIClient

# 创建客户端
client = TimechoAIClient(api_key="your_timecho-ai_api_key")

# 任务定义
INPUT_LENGTH = 16
OUTPUT_LENGTH = 8

# 读取数据
raw_df = pd.read_csv("https://ai.timecho.com/data/sample_cov.csv")

# 构建目标变量 DataFrame
target = raw_df[["time", "target"]][:INPUT_LENGTH]

# 构建历史协变量 DataFrame
history_covs = raw_df[["time", "temperature", "humidity"]][:INPUT_LENGTH]

# 执行协变量预测
result = client.forecast(
    targets=target,
    history_covs=history_covs,
    output_length=OUTPUT_LENGTH,
    time_col="time",
    auto_adapt=True
)

print(result[0])

异常处理

SDK 会将服务端返回的 HTTP 错误转换为对应的异常类型，便于您在业务代码中按场景分别处理；网络连接失败、请求超时以及请求发出前的参数校验失败也会抛出独立异常。

异常	触发时机
BadRequestError	HTTP 400 —— 请求格式错误 / 参数非法
AuthenticationError	HTTP 401 —— 缺少或无效的凭证
PermissionDeniedError	HTTP 403 —— 凭证有效但操作被禁止
NotFoundError	HTTP 404 —— 引用的资源（模型 / 文件）不存在
ConflictError	HTTP 409 —— 资源状态冲突（如已存在、未加载）
UnprocessableEntityError	HTTP 422 —— 语义校验失败（如 output_length 越界、目标变量数 ≠ 1）
RateLimitError	HTTP 429 —— 触发限流
InternalServerError	HTTP 500 —— 服务端未捕获异常
ServiceUnavailableError	HTTP 503 —— 服务暂时不可用（通常可重试）
APIError	上述 HTTP 异常的基类，携带 status_code 与 response_body。未列出的 4xx 会抛出 APIError，未列出的 5xx 会抛出 ServerError
ConnectionError	传输层：连接失败
TimeoutError	传输层：请求超时
ValidationError	请求发出前的客户端输入校验失败

下一步

了解更多 Timer 功能：

• REST API →
• 快速开始 →