Kairos-23M输入输出与超参数完全指南：context、patch、quantiles一次讲清
【免费下载链接】kairos_23m-npu项目地址: https://ai.gitcode.com/atlasleong/kairos_23m-npu
面对一个只有 2300 万参数的时间序列预测模型，新手往往最先被它的输入输出形状绕晕：past_target到底是什么？context_length该设多少？输出的 9 个通道是什么意思？别担心，这篇Kairos-23M 输入输出与超参数指南会带你从零上手，把context、patch、quantiles三大核心概念一次讲清，让你能快速读懂模型并跑通自己的第一次零样本时序预测。
一、Kairos-23M 是什么：一个为时序预测而生的基础模型
Kairos-23M 是一个 2300 万参数的时间序列基础模型，核心能力是零样本（zero-shot）时间序列预测——也就是说，不需要针对你的数据重新训练，直接喂入历史观测值，它就能输出未来一段时间的预测，并且以9 分位数（quantile）的形式给出预测的不确定性区间。
它的架构是 T5 风格的 encoder-decoder，配合动态分块（dynamic patching）、MoE tokenizer 和实例级 RoPE 位置编码，属于时序基础模型（TSFM）家族的最新实践。模型本体代码位于 modeling_kairos.py，配置定义在 configuration_kairos.py，推理入口脚本是 inference.py。
二、模型输入详解：past_target 与 context_length
Kairos-23M 的输入非常简洁，核心只有一个张量past_target，也就是你手中那段历史时间序列。
输入的形状
past_target: (batch_size, context_length) float32- batch_size：一次预测多少个序列，默认取 1。
- context_length：喂入的历史窗口长度，也就是上下文长度。
- dtype：全程float32（昇腾 NPU 不支持 fp64，不要改成 float64）。
context_length 超参数怎么设置？
配置里的默认值是context_length=2048，这是模型支持的最大上下文上限；超过上限的输入会被自动截断为末尾 2048 个点（在 modeling_kairos.py 的 encode 方法中处理）。而实际交付的推理入口默认使用CONTEXT_LENGTH = 512（见 _job_bootstrap.py），这是一个兼顾速度与精度的折中选择。
新手建议：先用 512 起步，跑通流程后再根据任务复杂度调整。context 越长，模型能看到的历史规律越多，但显存和耗时也会上升。
输入还可以带掩码
除了past_target，前向函数还接受可选的past_is_pad（padding 标记）和past_observed_values（有效值标记）。简单说：序列中的 NaN 会被自动视为缺失值，模型会用有效观测做预测，这在真实工业数据中非常实用。
三、patch 超参数：input_patch_size 与 input_patch_stride
Kairos-23M 不像传统方法那样直接处理每一个时间点，而是把输入序列切分成一个个 patch（块），再交给模型。这能显著降低计算量并提升对局部模式的捕捉能力。
两个关键配置
| 超参数 | 默认值 | 含义 |
|---|---|---|
input_patch_size | 128 | 每个 patch 包含多少个时间点 |
input_patch_stride | 128 | patch 之间的滑动步长 |
当stride == size时，patch 之间没有重叠，512 个点的输入会被切成 4 个 patch。此外，模型内部使用**动态分块（DynamicPatch）**机制（见 modeling_kairos.py 中的DynamicPatch类）：MoE 路由会决定哪些 patch 需要进一步细分，从而自适应地处理不同"粒度"的时序模式，这就是它擅长时间序列预测的原因之一。
四、模型输出详解：9 分位数预测的结构
模型前向的输出是KairosOutput对象，其中最核心的字段是prediction_outputs。
输出的形状
prediction_outputs: (batch_size, num_quantiles=9, prediction_length)例如实际推理日志里的PREDICTION_SHAPE=1,9,64，含义就是：
- batch = 1：1 个样本；
- 9：9 个分位数通道；
- 64：预测未来 64 个时间点（即
prediction_length=64）。
每个通道代表什么？
模型预测的不是一条线，而是 9 条分位数曲线，对应quantiles=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]：
- q=0.1：未来值有 10% 概率低于此线（下界）；
- q=0.9：未来值有 90% 概率低于此线（上界）；
- q=0.5（索引 4）：中位数预测，通常作为最终的点预测结果。
两条分位数曲线之间的宽度，就是模型给出的不确定性区间——区间越窄，模型越有把握。实际推理时，inference.py 正是取索引 4（q=0.5）的中位数通道作为 FORECAST 输出。
五、quantiles 超参数：按需定制你的预测区间
quantiles列表本身也是一个可配置超参数，定义在 configuration_kairos.py 中。默认是 0.1 到 0.9 的 9 等分，但你完全可以自定义，比如想要更细的尾部风险分析，可以改为[0.05, 0.1, ..., 0.9, 0.95]。
训练损失也用 quantiles
模型训练时使用分位数损失（quantile loss）：每个分位数的预测误差会按对应权重惩罚，这让每个通道都"各司其职"地学会刻画不同概率水平。因此量化输出的覆盖度（比如 0.1~0.9 区间实际应覆盖约 80% 的真实未来值）是评估模型质量的重要指标。
六、其他关键超参数速查表
除了三大主角，下面这些超参数也值得了解（完整清单见 model/config.json）：
| 超参数 | 默认值 | 说明 |
|---|---|---|
d_model | 384 | 隐藏层维度 |
d_ff | 1536 | 前馈网络维度 |
num_layers/num_decoder_layers | 4 / 4 | encoder / decoder 层数 |
num_heads | 8 | 注意力头数 |
num_decoder_segments | 2 | 解码分段数，决定单次最大预测长度 |
n_activated_experts | 3 | MoE 激活专家数 |
dtype | float32 | 全模型精度 |
一个容易踩坑的点：单次生成的最大预测长度是num_decoder_segments × prediction_length = 2 × 64 = 128。如果你需要的预测长度超过 128，模型内部会自动把中位数预测回填到输入、进行自回归续推（见 modeling_kairos.py 的_autoregressive_generate），超出的部分会打印 warning，不影响运行。
七、真实运行示例：输入输出一次看懂
以仓库自带的 inference.py 在昇腾 NPU（Ascend 910B4）上的实际输出为例：
INPUT_DEVICE=npu:0 MODEL_DEVICE=npu:0 OUTPUT_DEVICE=npu:0 CPU_FALLBACK=false PREDICTION_SHAPE=1,9,64 TEST_INPUT=context_len=512,last_observed=1.062244 FORECAST=-0.086745,-0.254155,-0.401681,-0.506220,-0.554450,... EXIT_CODE=0对照本指南就能轻松解读：输入是 512 个时间点的历史序列（最后一个观测值 1.062244），输出是(1, 9, 64)的 9 分位数预测，FORECAST显示的是中位数（q=0.5）通道的前 8 个预测值。整个前向在 NPU 上中位耗时约114ms。
八、新手避坑清单 🧭
- 保持 float32：模型全程 float32，改为 float64 会在昇腾 NPU 上报错；
- 固定 transformers 版本：Kairos 建模代码依赖 transformers 4.56.x（详见 README 注意事项），升级到 5.x 会因 API 移除而失败；
- context 别超上限：超过
context_length会自动截断，取的是末尾部分，记得把最新数据放在序列尾部； - NaN 用掩码处理：不要手动删除缺失点，把缺失位置留 NaN 即可，模型自动忽略；
- 中位数通道是索引 4：取点预测结果时认准 q=0.5（索引 4）通道。
总结：一张图记住输入输出
最后帮你把全文浓缩成一句话：输入(batch, context)的历史序列，模型输出(batch, 9, prediction_length)的 9 分位数预测，其中context_length决定看多长历史，input_patch_size/stride决定怎么切分，quantiles决定预测的粒度与不确定性。掌握这三点，你就能自信地使用 Kairos-23M 开启自己的零样本时间序列预测之旅了。🎯
【免费下载链接】kairos_23m-npu项目地址: https://ai.gitcode.com/atlasleong/kairos_23m-npu
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
