把时间序列真正用起来：TimechoAI 使用与时序分析实战

文章目录

- 一、为什么时序数据需要专门的模型
- [二、TimechoAI 能做什么](#二、TimechoAI 能做什么)
- - [1. 趋势预测](#1. 趋势预测)
  - [2. 协变量预测](#2. 协变量预测)
  - [3. 异常检测](#3. 异常检测)
  - [4. 缺失值填补](#4. 缺失值填补)
- [三、最快的体验方式：Web 控制台](#三、最快的体验方式：Web 控制台)
- [四、使用 Python SDK 接入预测服务](#四、使用 Python SDK 接入预测服务)
- - [1. 安装环境](#1. 安装环境)
  - [2. 单变量预测](#2. 单变量预测)
  - [3. 加入历史协变量](#3. 加入历史协变量)
  - [4. 用留出集评估预测效果](#4. 用留出集评估预测效果)
- [五、使用 REST API 接入任意技术栈](#五、使用 REST API 接入任意技术栈)
- [六、私有化路径：TimechoDB + AINode](#六、私有化路径：TimechoDB + AINode)
- - [1. 部署前提](#1. 部署前提)
  - [2. 解压与配置](#2. 解压与配置)
  - [3. 启动和检查](#3. 启动和检查)
  - [4. 直接用 SQL 做单变量预测](#4. 直接用 SQL 做单变量预测)
  - [5. 使用历史与未来协变量](#5. 使用历史与未来协变量)
- 七、时序分析效果怎么判断
- - [1. 先和简单基线比较](#1. 先和简单基线比较)
  - [2. 按业务选择指标](#2. 按业务选择指标)
  - [3. 防止时间穿越](#3. 防止时间穿越)
  - [4. 观察不同时间段](#4. 观察不同时间段)
- 八、落地时最容易踩的坑
- 九、我更推荐的接入顺序

一、为什么时序数据需要专门的模型

大语言模型处理的是词元之间的关系，时间序列模型面对的却是连续数值、采样频率、周期、趋势、噪声和突变。

一组设备温度数据看起来只是一列数字，但模型实际需要理解很多隐含信息：

每 5 分钟采一次，还是每小时采一次；
白天升高、夜间下降是不是正常周期；
温度缓慢抬升是季节变化，还是设备老化；
某个尖峰是故障、操作动作，还是传感器抖动；
负载、环境温度和节假日是否会改变目标曲线。

传统方案通常要按场景选模型、做特征工程、训练和调参。换一批设备、换一种采样粒度，原模型未必还能工作。时序大模型的思路是先在跨领域、大规模时间序列上预训练，再通过零样本预测或少量微调适配具体任务。

TimechoAI 的核心来自 Timer 系列模型。官方资料显示，Timer 采用面向时序数据的 Transformer 架构，可用于预测、异常检测和缺失值填补等任务。其价值不只是"模型更大"，而是希望把不同场景中重复出现的周期、趋势和依赖关系，沉淀为可迁移的通用能力。

这并不意味着传统模型失去价值。数据量小、规律稳定、解释要求明确时，ARIMA、Holt-Winters 仍然很好用。TimechoAI 更适合以下情况：

测点数量多，不希望为每条序列单独维护模型；
历史规律复杂，同时存在长周期、短周期和非平稳变化；
需要快速验证预测效果，不想先搭建完整训练流水线；
希望把预测能力接入现有系统，而不是维护另一套算法平台；
数据已经存放在 TimechoDB，希望直接在库内调用模型。

二、TimechoAI 能做什么

1. 趋势预测

预测是目前最直接、文档也最完整的能力。

输入一段历史序列后，模型输出未来若干时间点的预测值。官方云服务允许将预测长度设置为 1 到 720 步，具体的"一步"由数据采样间隔决定：小时级数据预测 24 步，通常表示未来 24 小时；分钟级数据预测 60 步，则表示未来 60 分钟。

常见场景包括：

电网与园区负荷预测；
商品销量和订单量预测；
设备温度、压力、振动趋势预测；
网络流量与资源使用率预测；
电池状态和城市用水量预测。

预测结果不能替代业务决策。更稳妥的做法，是把它作为提前量：预测值接近安全边界时触发检查，预测负荷上升时提前安排资源，而不是让模型直接控制关键设备。

2. 协变量预测

只看目标变量，有时会漏掉真正影响结果的因素。

例如预测商场用电量，历史用电是目标变量，气温和湿度是历史协变量，未来天气预报则属于已知未来协变量。预测销量时，价格、促销、节假日也可以作为协变量。

TimechoAI 官方文档将预测分为三类：

只输入目标变量；
输入目标变量和历史协变量；
在前两者基础上，再加入未来已知协变量。

后两种方式未必总能提高精度。协变量必须与目标存在稳定关系，并且时间戳、长度和采样频率要正确对齐。把大量无关指标塞进模型，通常只会增加噪声。

3. 异常检测

异常检测关注的不是未来，而是当前数据是否偏离正常模式。

固定阈值只能识别"超过 80℃"这类明显问题，却很难处理动态基线。例如某设备白天运行在 70℃属于正常，夜间停机后仍保持 70℃就可能异常。时序模型可以结合前后文、周期和变化速度判断偏离程度。

在实际系统中，异常检测适合分成两层：

规则层负责硬边界，例如压力不得超过安全上限；
模型层负责发现缓慢漂移、周期破坏和多指标联动异常。

两层并用比完全依赖模型更可靠。

4. 缺失值填补

网络抖动、传感器离线和采集程序重启都会造成数据缺口。简单线性插值适合短缺口，但遇到明显周期或较长缺失区间时，结果往往过于平滑。

Timer 系列模型可根据缺口前后的上下文进行预测式填补。这个能力适合数据清洗、报表修复和模型训练前的数据准备，但不应该悄悄覆盖原始记录。建议保留三列：原始值、填补值和填补标记，后续审计时才能分清真实数据与模型生成数据。

三、最快的体验方式：Web 控制台

第一次接触 TimechoAI，没必要急着写代码。可以先登录官方控制台，新建预测会话，用一份小数据验证效果。

控制台支持三种输入方式：

直接在画布上绘制曲线，适合快速试验；
粘贴时间戳和数值；
上传 CSV 或 TsFile 文件。

上传文件后，需要标注每一列的角色：时间、目标变量、历史协变量、含未来数据的协变量，或者忽略。随后选择模型和预测长度并执行预测。

CSV 可以整理成下面这样：

csv 复制代码

time,load,temperature,holiday
2026-08-01 00:00:00,312.5,27.1,0
2026-08-01 01:00:00,298.2,26.8,0
2026-08-01 02:00:00,287.9,26.5,0
2026-08-01 03:00:00,281.3,26.2,0

这里有几个容易忽略的细节：

时间戳格式要统一，不能一部分是字符串，一部分是 Unix 毫秒；
数据最好等间隔采样；
不要把设备编号、备注等文本列误标成目标变量；
先用较短预测窗口验证，再逐步拉长；
评估时要保留一段真实数据作为测试集，不要只看曲线是否"顺眼"。

如果 Web 端结果基本符合预期，再进入 API 集成，会省掉不少排查时间。

四、使用 Python SDK 接入预测服务

1. 安装环境

官方 SDK 当前要求 Python 3.10 及以上、3.13 以下。

bash 复制代码

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install timecho-ai pandas

Windows PowerShell 激活虚拟环境的命令是：

powershell 复制代码

.\.venv\Scripts\Activate.ps1

API Key 建议放入环境变量，不要直接写进代码仓库。

Linux 或 macOS：

bash 复制代码

export TIMECHO_AI_API_KEY="替换为你的API-Key"

Windows PowerShell：

powershell 复制代码

$env:TIMECHO_AI_API_KEY="替换为你的API-Key"

2. 单变量预测

下面的例子读取一份小时级设备温度数据，并预测未来 24 个点。

python 复制代码

import os

import pandas as pd
from timecho_ai import TimechoAIClient

api_key = os.environ["TIMECHO_AI_API_KEY"]
client = TimechoAIClient(api_key=api_key)

data = pd.read_csv("bearing_temperature.csv")
data["time"] = pd.to_datetime(data["time"])
data = data.sort_values("time").drop_duplicates("time")

target = data[["time", "temperature"]].tail(720)

result = client.forecast(
    targets=target,
    model_id="Auto",
    output_length=24,
    time_col="time",
    auto_adapt=True,
)

forecast = result[0]
print(forecast)
forecast.to_csv("bearing_temperature_forecast.csv", index=False)

model_id="Auto" 适合第一次调用，由平台选择预测策略。官方 SDK 文档当前列出的模型还包括 Timer-3.5、Timer-3.0、Chronos-2、AutoARIMA 和 Holt-Winters。

不要一开始就执着于某个大模型。先用同一测试集比较 Auto、Timer 与传统模型的 MAE、RMSE 或 MAPE，再决定生产方案。

3. 加入历史协变量

假设要预测园区用电负荷，同时有温度和湿度数据：

python 复制代码

import os

import pandas as pd
from timecho_ai import TimechoAIClient

client = TimechoAIClient(
    api_key=os.environ["TIMECHO_AI_API_KEY"]
)

data = pd.read_csv("park_load.csv", parse_dates=["time"])
data = data.sort_values("time")
history = data.tail(24 * 30)

target = history[["time", "load"]]
history_covs = history[["time", "temperature", "humidity"]]

result = client.forecast(
    targets=target,
    history_covs=history_covs,
    model_id="Chronos-2",
    output_length=24,
    time_col="time",
    auto_adapt=True,
)

print(result[0])

官方文档要求历史协变量长度与目标变量长度一致。若显式指定 time_col，各输入表都应包含时间列。

auto_adapt=True 能处理部分长度不一致问题，但生产环境不应把它当成数据治理工具。时间对齐、缺失处理和采样频率检查最好在调用前完成，否则模型可能正常返回结果，业务含义却已经错位。

4. 用留出集评估预测效果

只跑一次未来预测，很难判断模型好不好。下面是一个简单的时间切分评估方法：把最后 24 个真实点留作测试集，用更早的数据预测它们。

python 复制代码

import numpy as np
import pandas as pd

HORIZON = 24

data = pd.read_csv("bearing_temperature.csv", parse_dates=["time"])
data = data.sort_values("time")

train = data.iloc[:-HORIZON][["time", "temperature"]]
test = data.iloc[-HORIZON:][["time", "temperature"]]

prediction = client.forecast(
    targets=train.tail(720),
    model_id="Auto",
    output_length=HORIZON,
    time_col="time",
)[0]

actual = test["temperature"].to_numpy()
predicted = prediction["temperature"].to_numpy()

mae = np.mean(np.abs(actual - predicted))
rmse = np.sqrt(np.mean((actual - predicted) ** 2))

print(f"MAE: {mae:.4f}")
print(f"RMSE: {rmse:.4f}")

真实项目还应做滚动回测。例如每隔一天截取一次历史窗口，预测未来 24 小时，连续评估数周。单次切分可能刚好遇到平稳区间，容易高估效果。

五、使用 REST API 接入任意技术栈

如果业务系统不是 Python，直接调用 REST API 更方便。

官方预测接口为：

text 复制代码

POST https://ai.timecho.com/ai/api/v1/forecast

下面使用 cURL 提交 16 个温度点，并预测未来 8 个点：

bash 复制代码

curl -X POST "https://ai.timecho.com/ai/api/v1/forecast" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TIMECHO_AI_API_KEY}" \
  -d '{
    "targets": [
      {
        "columns": ["time", "temperature"],
        "data": [
          ["2026-08-01T00:00:00", 36.2],
          ["2026-08-01T01:00:00", 36.5],
          ["2026-08-01T02:00:00", 36.8],
          ["2026-08-01T03:00:00", 37.1],
          ["2026-08-01T04:00:00", 37.4],
          ["2026-08-01T05:00:00", 37.7],
          ["2026-08-01T06:00:00", 38.0],
          ["2026-08-01T07:00:00", 38.3],
          ["2026-08-01T08:00:00", 38.6],
          ["2026-08-01T09:00:00", 38.9],
          ["2026-08-01T10:00:00", 39.2],
          ["2026-08-01T11:00:00", 39.5],
          ["2026-08-01T12:00:00", 39.8],
          ["2026-08-01T13:00:00", 40.1],
          ["2026-08-01T14:00:00", 40.4],
          ["2026-08-01T15:00:00", 40.7]
        ]
      }
    ],
    "output_length": [8],
    "time_col": ["time"]
  }'

生产接入时，至少要处理这些状态：

401：API Key 缺失或无效；
422：输入长度、预测长度或字段语义不符合要求；
429：请求触发限流；
500、503：服务端异常或暂时不可用。

对 429 和 503 可以做带上限的指数退避重试，但不要无限重试。预测请求最好携带业务任务编号，并在调用端保存输入摘要、模型、参数和响应，方便追查结果来自哪一次调用。

六、私有化路径：TimechoDB + AINode

云服务适合快速试用和轻量集成。数据不能出内网、已有大量数据存放在 TimechoDB，或者希望通过 SQL 统一调用模型时，可以考虑 AINode。

AINode 是独立部署的 TimechoDB 原生 AI 节点。ConfigNode 负责集群管理，DataNode 负责数据存储与查询，AINode 负责模型管理和推理。三者连通后，SQL 查询结果可以直接进入模型。

1. 部署前提

根据官方 V2.0.8 部署文档：

建议使用 Linux 或 macOS；
TimechoDB 版本需不低于 V2.0.8；
AINode 使用独立安装包；
联网环境首次启动时可自动下载内置模型权重；
离线环境需要提前获取权重并放到指定目录；
安装包和权重获取、授权激活需联系官方团队。

因此，AINode 不是执行一条公开 Docker 命令就能完成的社区版体验。下面展示的是官方安装包到位后的核心步骤。

2. 解压与配置

bash 复制代码

unzip timechodb-<version>-ainode-bin.zip
cd timechodb-<version>-ainode-bin

编辑 conf/iotdb-ainode.properties：

properties 复制代码

cluster_name=defaultCluster
ain_seed_config_node=10.0.0.11:10710

ain_cluster_ingress_address=10.0.0.12
ain_cluster_ingress_port=6667
ain_cluster_ingress_username=root
ain_cluster_ingress_password=请替换为实际密码

ain_rpc_address=10.0.0.13
ain_rpc_port=10810
ain_system_dir=/data/timecho/ainode/system
ain_models_dir=/data/timecho/ainode/models

不要在真实环境继续使用默认密码。配置文件权限也应限制到运行账号。

离线环境需要把官方提供的模型权重放到：

text 复制代码

<TIMECHO_AINODE_HOME>/data/ainode/models/builtin

3. 启动和检查

Linux 后台启动：

bash 复制代码

bash sbin/start-ainode.sh -d

进入 IoTDB CLI 后检查节点：

sql 复制代码

SHOW CLUSTER;

看到 ConfigNode、DataNode 和 AINode 均为 Running 后，再检查模型：

sql 复制代码

SHOW MODELS;

不同版本内置模型会变化。官方文档当前展示的模型包括 timer_xl、sundial、chronos2 和 toto 等。模型状态为 active 才能用于推理。

4. 直接用 SQL 做单变量预测

假设 factory.bearing_metrics 表中保存了设备轴承温度：

sql 复制代码

SELECT *
FROM FORECAST(
  MODEL_ID => 'sundial',
  TARGETS => (
    SELECT time, temperature
    FROM factory.bearing_metrics
    WHERE device_id = 'bearing_01'
    ORDER BY time DESC
    LIMIT 720
  ) ORDER BY time,
  OUTPUT_LENGTH => 24,
  OUTPUT_INTERVAL => 1h
);

这段 SQL 从数据库中取最近 720 个点，预测未来 24 个小时。实际使用前需按当前 TimechoDB 表结构、字段类型和版本语法调整。

AINode 的优势在这里很明显：数据不用先导出到外部服务，查询、预处理和推理可以在同一套数据链路中完成。

5. 使用历史与未来协变量

下面预测园区负荷，并加入历史温湿度和未来天气预报：

sql 复制代码

SELECT *
FROM FORECAST(
  MODEL_ID => 'chronos2',
  TARGETS => (
    SELECT time, load
    FROM energy.park_metrics
    WHERE park_id = 'park_a'
      AND time < 2026-08-17T00:00:00+08:00
    ORDER BY time DESC
    LIMIT 720
  ) ORDER BY time,
  HISTORY_COVS => '
    SELECT time, temperature, humidity
    FROM energy.park_metrics
    WHERE park_id = ''park_a''
      AND time < 2026-08-17T00:00:00+08:00
    ORDER BY time DESC
    LIMIT 720
  ',
  FUTURE_COVS => '
    SELECT time, temperature, humidity
    FROM energy.weather_forecast
    WHERE park_id = ''park_a''
      AND time >= 2026-08-17T00:00:00+08:00
    ORDER BY time
    LIMIT 24
  ',
  OUTPUT_LENGTH => 24,
  OUTPUT_INTERVAL => 1h,
  AUTO_ADAPT => true
);

官方文档对协变量有明确约束：历史协变量时间戳应与目标变量对齐；未来协变量名称应属于历史协变量集合；未来协变量长度应与预测长度一致。SQL 中还应明确数据库名称，避免跨库取数产生歧义。

七、时序分析效果怎么判断

"曲线看着挺像"不是评估标准。

1. 先和简单基线比较

至少准备两类基线：

朴素预测：下一个点等于上一个点，或等于上一周期同一位置；
传统模型：AutoARIMA、Holt-Winters 等。

如果时序大模型不能稳定超过简单基线，就没有必要为了"大模型"三个字增加系统复杂度。

2. 按业务选择指标

MAE 对所有误差线性计分，比较直观；RMSE 会放大大误差，适合对尖峰偏差敏感的场景；MAPE 容易受接近零的真实值影响，使用前要检查数据范围。

业务指标往往更重要。例如：

负荷预测是否降低备用资源成本；
温度预测是否提前发现过热风险；
异常检测每天产生多少误报；
缺失填补是否影响后续统计结果。

3. 防止时间穿越

时序任务必须按时间划分训练集和测试集，不能随机打乱。协变量也要检查在预测时刻是否真的可获得。

拿实际发生后的天气作为"未来协变量"回测，结果会很好看，但上线时只能拿到天气预报，精度通常会下降。评估数据必须模拟真实生产条件。

4. 观察不同时间段

平均误差可能掩盖风险。建议分别统计工作日与周末、白天与夜间、平稳期与高峰期、正常设备与老化设备。模型在大部分时间准确，却总在业务高峰失效，仍然不能投入关键流程。

八、落地时最容易踩的坑

输入越长不一定越好

长历史能提供更多周期信息，也可能带入已经失效的旧规律。设备改造、价格调整、产线换型之后，过早的数据甚至会误导模型。历史窗口应通过回测选择。

预测越远，误差通常越大

预测未来 24 个点和 720 个点不是一回事。长预测窗口适合看方向，不适合把每个点都当成精确计划。可以采用"短期高频重算、长期只看区间"的策略。

自动适配不能替代数据质量检查

时间戳重复、采样间隔变化、单位切换、传感器校准都会影响预测。接口成功返回，只说明格式通过，不说明数据可信。

异常分数不等于故障结论

模型发现的是"与历史模式不同"，原因可能是故障，也可能是工况切换、节假日或维修后的正常变化。异常结果需要结合事件记录和设备知识确认。

模型版本必须留痕

无论使用云服务还是 AINode，都应记录模型 ID、服务版本、输入时间范围、预测参数和生成时间。模型升级后，同一批数据可能得到不同结果，没有版本记录就无法复现。

九、我更推荐的接入顺序

如果团队还没有时序模型经验，可以按下面的顺序推进：

从一个业务问题开始，例如预测未来 24 小时负荷，不要同时铺开十种任务；
在 Web 控制台上传脱敏样本，判断基本可行性；
用 Python SDK 做滚动回测，并与朴素预测、AutoARIMA 比较；
明确误差如何转化为业务收益或风险；
小流量接入 API，只提供辅助建议；
数据不能出域或已经使用 TimechoDB 时，再评估 AINode 私有化部署；
运行一段时间后检查数据漂移、误报率和模型版本变化。

这条路径看起来保守，却比直接把模型接进生产控制系统稳妥得多。

企业版官方链接：https://timecho.com

时序大模型 TimechoAI：https://ai.timecho.com/