# 时序预测回归零样本直推 #### 功能介绍 使用行业大规模时序数据进行预训练，获得能够捕捉时序特征的预置模型。在推理阶段，该预置模型根据输入的历史时序特征，对未来时序进行预测，最多支持1024个时间点的预测。 直推模式支持： 1. **单目标推理：**支持单变量时序预测。 2. **多目标推理：**支持多变量时序预测。 3. **历史与未来协变量推理：**支持协变量输入的时序预测。协变量分为两类：当前信息不可知的历史协变量，如传感器数据等信息；当前信息可知的已知协变量，如销量预测中的假期、天气等信息。 4. **分位数预测：**支持分位数预测，即模型可以输出多个分位数的预测结果，而不仅仅是单一的点预测。分位数预测有助于评估预测的不确定性，提供更全面的预测区间。 直推限制： - **列名一致性要求：**单次批处理请求中，所有数据条目必须保持列名完全一致。 - **显式指定预测长度：**批请求需新增字段 prediction_len，用于指定期望的预测时序长度。 - **支持自动识别上下文长度：** 无需指定上下文长度（context_len），支持根据输入序列窗口长度自动识别。若在请求体中明确指定上下文长度（context_len），则输入序列窗口的长度必须**大于或等于**指定的上下文长度。若指定序列长度（context_len）小于实际序列长度时，以指定的上下文长度（context_len）为准，并取序列最后部分作为上下文内容。例如若输入序列长度为100且指定的上下文长度（context_len）为80时，取序列的最后80个数据作为上下文。 - **输入序列长度对齐：**同一批次请求中的所有时序数据，目标列/历史协变量列的序列长度（target_col_length）必须相同；已知协变量列需等于目标列/历史协变量列的序列长度+预测长度（target_col_length + prediction_len）。 - **显示指定预测的目标列、历史协变量列、以及已知协变量列：** 分别以target_cols，past_cov_cols，known_cov_cols承载，都可取空值。若为空值，默认取值符合优先级规则target_cols\>past_cov_cols\>known_cov_cols，具体情况见下表。为了预测的精确性，建议使用时最好三者都指定。 表1预测列名取值规则 | target_cols（目标列） | past_cov_cols（历史协变量列） | known_cov_cols（已知协变量列） | 取值规则 | |:---|:---|:---|:---| | × | × | × | 所有列均为target_cols，past_cov_cols和known_cov_cols均为空值。 | | √ | × | × | 除去target_cols指定列，剩余所有列均为past_cov_cols，known_cov_cols为空值 | | × | √ | × | 除去past_cov_cols指定列，剩余所有列均为target_cols，known_cov_cols为空值 | | × | × | √ | 除去known_cov_cols指定列，剩余所有列均为target_cols，past_cov_cols为空值 | | √ | √ | × | 除去target_cols以及past_cov_cols指定列，剩余所有列known_cov_cols。且输入的target_cols以及past_cov_cols不可有交集 | | × | √ | √ | 除去past_cov_cols以及known_cov_cols指定列，剩余所有列target_cols。且输入的past_cov_cols以及known_cov_cols不可有交集 | | √ | × | √ | 除去target_cols以及known_cov_cols指定列，剩余所有列past_cov_cols。且输入的target_cols以及known_cov_cols不可有交集 | | √ | √ | √ | 三者为输入指定列。 需满足： 1. 三者输入无交集 2. 三者并集严格等于所有列名（all_cols） | #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/productdesc-pangulm/pangulm_01_0020.html)。 #### URI POST / 获取URI方式请参见[请求URI](https://support.huaweicloud.com/api-pangulm/pangulm_05_0004.html)。 #### 请求参数 使用[Token认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section94702116509)方式的请求Header参数见[表2]。 表2请求Header参数（Token认证） | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释：** 用户Token。 用于获取操作API的权限。如[图4](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__fig10797003103)中响应消息头中X-Subject-Token的值即为Token。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | Content-Type | 是 | String | **参数解释：** 发送的实体的MIME类型。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** application/json | 使用[API Key认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section148602501261)方式的请求Header参数见[表3]。 表3请求Header参数（API Key认证） | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Apig-AppCode | 是 | String | **参数解释：** API Key值。 用于获取操作API的权限。[API Key认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section148602501261)响应消息头中X-Apig-AppCode的值即为API Key。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | Content-Type | 是 | String | **参数解释：** 发送的实体的MIME类型。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** application/json | 表4请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | data | 是 | Array | **参数解释：** 时序数据请求的批处理队列。 **约束限制：** 盘古时序预测回归任务的输入数据内容，用字典承载。输入数据字典中，键对应特征列名，值为序列数据具体内容。 **取值范围：** 目标列仅支持数值型（int/float）取值，过去以及已知协变量支持数值型取值以及类别特征（int/float/string）取值。 目标列限制：List\[int/float\] 协变量列限制：List\[int/float/str\] **默认取值：** 不涉及，此为必须填写字段。 | | context_len | 否 | int | **参数解释：** 时序任务的历史窗口大小，该参数主要服务于支持多尺度窗口的模型的推理。 **约束限制：** 填写时需要保证输入序列长度大于等于该值。 **取值范围：** - min：1 - max：建议不超过8192 **默认取值：** 若不填写，支持根据输入序列窗口长度自动识别。 | | prediction_len | 是 | int | **参数解释：** 时序预测输出的窗口长度。数值越大输出预测的时间范围越大，但相应的显存占用会增加以及模型预测精度可能会下降。 **约束限制：** 无。 **取值范围：** - min：1 - max：1024。 **默认取值：** 不涉及，此为必须填写字段。 | | target_cols | 否 | List\[str\] | **参** **数解释：** 时序预测的目标列列名，表示预测的目标列。 **约束限制：** 列名需包含于输入数据字典的键值中。详细取值规则见[表1]。 **取值范围：** 不涉及 **默认取值：** 详细取值规则见[表1]。 | | past_cov_cols | 否 | List\[str\] | **参** **数解释：** 时序预测的过去协变量列列名，表示待预测时刻的列信息不可预知的列，如传感器数据等信息。 **约束限制：** 列名需包含于输入数据字典的键值中。详细取值规则见[表1]。 **取值范围：** 不涉及 **默认取值：** 详细取值规则见[表1]。 | | known_cov_cols | 否 | List\[str\] | **参** **数解释：** 时序预测的已知协变量列列名，表示待预测时刻的列信息可获取的列，如节假日、天气等信息。 **约束限制：** 列名需包含于输入数据字典的键值中。详细取值规则见[表1]。 **取值范围：** 不涉及 **默认取值：** 详细取值规则见[表1]。 | | quantile_levels | 否 | List\[float\] | **参** **数解释：** 模型支持分位数预测。为了防止返回体过大，若此字段不指定，默认仅返回中位数结果，以"prediction"字段承载。若指定返回的分位数信息，例如\[0.1, 0.5, 0.9\](返回10%， 50%， 90%)分位数，以字段"prediction_{quantile_level}"承载，其中quantile_level取值范围为\[0.1, ..., 0.9\]。 **约束限制：** 需取\[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9\]的子集。 **取值范围：** 需取\[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9\]的子集。 **默认取值：** None, 默认仅返回中位数结果。 | #### 响应参数 **状态码： 200** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | data | LIST\ | **参数解释：** 时序预测结果的列表。若请求字段未指定quantile_levels，则默认仅返回中位数结果以字段"prediction"承载；若请求字段指定quantile_levels，则同时返回分位数结果，以字段"prediction_{quantile_level}"承载。例如\[0.1, 0.9\](返回10%， 90%)分位数，以字段"prediction_0.1"和"prediction_0.9"承载。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | time_cost | JSON | **参数解释：** 当启动服务时，本次请求服务各阶段耗时情况。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | 表6OutputMeta格式说明 | 参数名称 | **参数类型** | **说明** | |:---|:---|:---| | prediction | JSON | **参数解释：** 时序预测的输出结果，具体见样例调用示例。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | prediction_{quantile_level} | JSON | **参数解释：** 若请求字段指定quantile_levels，则同时返回分位数结果，以字段"prediction_{quantile_level}"承载。例如\[0.1, 0.9\](返回10%， 90%)分位数，以字段"prediction_0.1"和"prediction_0.9"承载。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | **状态码： 400** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码。 | | error_msg | String | 错误信息。 | #### 请求示例 ``` { "prediction_len": 96, "target_cols": ["fetaure_0"], "past_cov_cols": ["fetaure_1", "feature_2"], "known_cov_cols": ["fetaure_3"], "data": [ { "context": { "feature_0": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], "feature_1": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], "feature_2": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], "feature_3": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...] } }, { "context": { "feature_0": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], "feature_1": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], "feature_2": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], "feature_3": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...] } }, {...}, {...} ] } ``` #### 响应示例 ``` ## 若指定计算模式为返回异常分（option∈["重构误差"，"重构方差", "重构误差+方差"]） { "data": [ { # 预测结果 "prediction":{ "feature_0": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], }, # 预测结果(10%分位数) "prediction_0.1":{ "feature_0": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], }, ... # 预测结果(90%)分位数 "prediction_0.9":{ "feature_0": [ 864.1618041992188, 493.91827392578125, 252.7724151611328，...], } }, {...}, {...}, {...} ], "time_cost": { "infer_cost_time": "82.609 ms", "postprocess_cost_time": "0.29 ms", "preprocess_cost_time": "0.1332 ms", "service_cost_total_time": "84.965 ms" } } ``` #### 状态码 请参见[状态码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0019.html)。 #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0020.html)。