SDK 参考

---

源

​

NixtlaClient

 NixtlaClient (api_key:Optional[str]=None, base_url:Optional[str]=None,
               timeout:Optional[int]=60, max_retries:int=6,
               retry_interval:int=10, max_wait_time:int=360)

与 Nixtla API 交互的客户端。

	类型	默认值	详情
api_key	可选	无	用于与 Nixtla API 交互的授权 api_key。 如果未提供，将使用 NIXTLA_API_KEY 环境变量。
base_url	可选	无	自定义 base_url。 如果未提供，将使用 NIXTLA_BASE_URL 环境变量。
超时	可选	60	请求超时时间（秒）。设置为 None 可禁用。
最大重试次数	int	6	在放弃之前调用 API 的最大尝试次数。 它定义了客户端在 API 调用失败时将重试的次数。 默认值为 6，表示客户端总共将尝试调用 API 最多 6 次
重试间隔	int	10	连续重试尝试之间的间隔（秒）。 这是客户端在失败尝试后再次尝试调用 API 之前的等待期。 默认值为 10 秒，表示客户端在重试之间等待 10 秒。
最大等待时间	int	360	客户端在放弃之前所有重试尝试花费的最大总时间（秒）。 这为所有重试尝试的累计等待时间设置了上限。 如果超过此时间，客户端将停止重试并抛出异常。 默认值为 360 秒，表示如果总时间超过 360 秒，客户端将停止重试。 花费在重试上的时间超过 360 秒。 客户端在 60 秒不活动后会抛出 ReadTimeout 错误。如果您想捕获这些错误，请将 max_wait_time 设置得远大于 60。

---

源

​

NixtlaClient.validate_api_key

 NixtlaClient.validate_api_key (log:bool=True)

检查 API 密钥状态。

	类型	默认值	详情
log	bool	True	显示端点的响应。
返回值	bool		API 密钥是否有效。

---

源

​

NixtlaClient.forecast

 NixtlaClient.forecast (df:~AnyDFType, h:typing.Annotated[int,Gt(gt=0)],
                        freq:Union[str,int,pandas._libs.tslibs.offsets.Bas
                        eOffset,NoneType]=None, id_col:str='unique_id',
                        time_col:str='ds', target_col:str='y',
                        X_df:Optional[~AnyDFType]=None,
                        level:Optional[list[Union[int,float]]]=None,
                        quantiles:Optional[list[float]]=None,
                        finetune_steps:typing.Annotated[int,Ge(ge=0)]=0,
                        finetune_depth:Literal[1,2,3,4,5]=1, finetune_loss
                        :Literal['default','mae','mse','rmse','mape','smap
                        e']='default',
                        finetuned_model_id:Optional[str]=None,
                        clean_ex_first:bool=True,
                        hist_exog_list:Optional[list[str]]=None,
                        validate_api_key:bool=False,
                        add_history:bool=False, date_features:Union[bool,l
                        ist[Union[str,Callable]]]=False, date_features_to_
                        one_hot:Union[bool,list[str]]=False, model:Literal
                        ['azureai','timegpt-1','timegpt-1-long-
                        horizon']='timegpt-1', num_partitions:Optional[Ann
                        otated[int,Gt(gt=0)]]=None,
                        feature_contributions:bool=False)

使用 TimeGPT 预测您的时间序列。

	类型	默认值	详情
df	AnyDFType		函数将操作的 DataFrame。预期至少包含以下列： - time_col df 中包含时间序列时间索引的列名。这通常是一个日期时间 列，具有规律的间隔，例如每小时、每日、每月的数据点。 - target_col df 中包含时间序列目标变量的列名，即我们 希望预测或分析的变量。 此外，您可以传入多个时间序列（堆叠在 dataframe 中），考虑使用一个附加列： - id_col df 中标识唯一时间序列的列名。此列中的每个唯一值 对应一个唯一的时间序列。
h	Annotated		预测范围。
freq	Union	无	时间戳的频率。如果为 None，将自动推断。 参见 pandas 可用的频率列表。
id_col	str	unique_id	标识每个时间序列的列。
time_col	str	ds	标识每个时间步的列，其值可以是时间戳或整数。
target_col	str	y	包含目标变量的列。
X_df	可选	无	包含 [unique_id, ds] 列和 df 未来外生变量的 DataFrame。
level	可选	无	用于预测区间的置信水平，介于 0 到 100 之间。
quantiles	可选	无	要预测的分位数，列表，介于 (0, 1) 之间。 level 和 quantiles 不应同时使用。 输出 dataframe 将包含分位数列， 每个 q 的格式为 TimeGPT-q-(100 * q)。 100 * q 表示百分位数，但我们选择这种表示法 以避免列名中出现点号。
finetune_steps	Annotated	0	用于在新数据上微调 TimeGPT 学习的步数。 新数据。
finetune_depth	Literal	1	微调的深度。使用 1 到 5 的范围，其中 1 表示微调程度较低， 5 表示整个模型都进行了微调。
finetune_loss	Literal	default	用于微调的损失函数。选项包括：default, mae, mse, rmse, mape, 和 smape。
finetuned_model_id	可选	无	要使用的先前微调模型的 ID。
clean_ex_first	bool	True	在使用 TimeGPT 进行预测之前清理外生信号。
hist_exog_list	可选	无	历史外生特征的列名。
validate_api_key	bool	False	如果为 True，在发送请求前验证 api_key。
add_history	bool	False	返回模型的拟合值。
date_features	Union	False	从日期计算出的特征。 可以是 pandas 日期属性，或以日期为输入的函数。 如果为 True，将自动添加 df 频率下最常用的日期特征。 df 的频率。
date_features_to_one_hot	Union	False	对这些日期特征应用独热编码。 如果 date_features=True，则所有日期特征将 默认进行独热编码。
model	Literal	timegpt-1	要使用的模型（字符串）。选项包括：timegpt-1 和 timegpt-1-long-horizon。 如果希望预测超出数据频率一个季节性 周期以上的时间，我们建议使用 timegpt-1-long-horizon 进行预测。 根据您的数据频率确定的周期。
num_partitions	可选	无	使用的分区数量。 如果为 None，分区数量将等于 分布式环境中可用的并行资源。
feature_contributions	bool	False
返回值	AnyDFType		包含 TimeGPT 点预测和概率预测（如果 level 不为 None）的 DataFrame 预测 (如果 level 不为 None)。

---

源

​

NixtlaClient.cross_validation

 NixtlaClient.cross_validation (df:~AnyDFType,
                                h:typing.Annotated[int,Gt(gt=0)], freq:Uni
                                on[str,int,pandas._libs.tslibs.offsets.Bas
                                eOffset,NoneType]=None,
                                id_col:str='unique_id', time_col:str='ds',
                                target_col:str='y', level:Optional[list[Un
                                ion[int,float]]]=None,
                                quantiles:Optional[list[float]]=None,
                                validate_api_key:bool=False, n_windows:typ
                                ing.Annotated[int,Gt(gt=0)]=1, step_size:O
                                ptional[Annotated[int,Gt(gt=0)]]=None, fin
                                etune_steps:typing.Annotated[int,Ge(ge=0)]
                                =0, finetune_depth:Literal[1,2,3,4,5]=1, f
                                inetune_loss:Literal['default','mae','mse'
                                ,'rmse','mape','smape']='default',
                                finetuned_model_id:Optional[str]=None,
                                refit:bool=True, clean_ex_first:bool=True,
                                hist_exog_list:Optional[list[str]]=None,
                                date_features:Union[bool,list[str]]=False,
                                date_features_to_one_hot:Union[bool,list[s
                                tr]]=False, model:Literal['azureai','timeg
                                pt-1','timegpt-1-long-
                                horizon']='timegpt-1', num_partitions:Opti
                                onal[Annotated[int,Gt(gt=0)]]=None)

使用 TimeGPT 对您的时间序列执行交叉验证。

	类型	默认值	详情
df	AnyDFType		函数将操作的 DataFrame。预期至少包含以下列： - time_col df 中包含时间序列时间索引的列名。这通常是一个日期时间 列，具有规律的间隔，例如每小时、每日、每月的数据点。 - target_col df 中包含时间序列目标变量的列名，即我们 希望预测或分析的变量。 此外，您可以传入多个时间序列（堆叠在 dataframe 中），考虑使用一个附加列： - id_col df 中标识唯一时间序列的列名。此列中的每个唯一值 对应一个唯一的时间序列。
h	Annotated		预测范围。
freq	Union	无	时间戳的频率。如果为 None，将自动推断。 参见 pandas 可用的频率列表。
id_col	str	unique_id	标识每个时间序列的列。
time_col	str	ds	标识每个时间步的列，其值可以是时间戳或整数。
target_col	str	y	包含目标变量的列。
level	可选	无	用于预测区间的置信水平，介于 0 到 100 之间。
quantiles	可选	无	要预测的分位数，列表，介于 (0, 1) 之间。 level 和 quantiles 不应同时使用。 输出 dataframe 将包含分位数列， 每个 q 的格式为 TimeGPT-q-(100 * q)。 100 * q 表示百分位数，但我们选择这种表示法 以避免列名中出现点号。
validate_api_key	bool	False	如果为 True，在发送请求前验证 api_key。
n_windows	Annotated	1	要评估的窗口数量。
step_size	可选	无	每个交叉验证窗口之间的步长。如果为 None，将等于 h。
finetune_steps	Annotated	0	用于微调 TimeGPT 的步数，用于 新数据。
finetune_depth	Literal	1	微调的深度。使用 1 到 5 的范围，其中 1 表示微调程度较低， 5 表示整个模型都进行了微调。
finetune_loss	Literal	default	用于微调的损失函数。选项包括：default, mae, mse, rmse, mape, 和 smape。
finetuned_model_id	可选	无	要使用的先前微调模型的 ID。
refit	bool	True	在每个窗口中微调模型。如果为 False，仅在第一个窗口中进行微调。 仅当 finetune_steps > 0 时使用。
clean_ex_first	bool	True	在使用 TimeGPT 进行预测之前清理外生信号。
hist_exog_list	可选	无	历史外生特征的列名。
date_features	Union	False	从日期计算出的特征。 可以是 pandas 日期属性，或以日期为输入的函数。 如果为 True，将自动添加 df 频率下最常用的日期特征。 df 的频率。
date_features_to_one_hot	Union	False	对这些日期特征应用独热编码。 如果 date_features=True，则所有日期特征将 默认进行独热编码。
model	Literal	timegpt-1	要使用的模型（字符串）。选项包括：timegpt-1 和 timegpt-1-long-horizon。 如果希望预测超出数据频率一个季节性 周期以上的时间，我们建议使用 timegpt-1-long-horizon 进行预测。 根据您的数据频率确定的周期。
num_partitions	可选	无	使用的分区数量。 如果为 None，分区数量将等于 分布式环境中可用的并行资源。
返回值	AnyDFType		包含交叉验证预测结果的 DataFrame。

---

源

​

NixtlaClient.detect_anomalies

 NixtlaClient.detect_anomalies (df:~AnyDFType,
                                freq:Union[str,int,pandas._libs.tslibs.off
                                sets.BaseOffset,NoneType]=None,
                                id_col:str='unique_id', time_col:str='ds',
                                target_col:str='y',
                                level:Union[int,float]=99,
                                finetuned_model_id:Optional[str]=None,
                                clean_ex_first:bool=True,
                                validate_api_key:bool=False,
                                date_features:Union[bool,list[str]]=False,
                                date_features_to_one_hot:Union[bool,list[s
                                tr]]=False, model:Literal['azureai','timeg
                                pt-1','timegpt-1-long-
                                horizon']='timegpt-1', num_partitions:Opti
                                onal[Annotated[int,Gt(gt=0)]]=None)

使用 TimeGPT 检测您的时间序列中的异常。

	类型	默认值	详情
df	AnyDFType		函数将操作的 DataFrame。预期至少包含以下列： - time_col df 中包含时间序列时间索引的列名。这通常是一个日期时间 列，具有规律的间隔，例如每小时、每日、每月的数据点。 - target_col df 中包含时间序列目标变量的列名，即我们 希望预测或分析的变量。 此外，您可以传入多个时间序列（堆叠在 dataframe 中），考虑使用一个附加列： - id_col df 中标识唯一时间序列的列名。此列中的每个唯一值 对应一个唯一的时间序列。
freq	Union	无	时间戳的频率。如果为 None，将自动推断。 参见 pandas 可用的频率列表。
id_col	str	unique_id	标识每个时间序列的列。
time_col	str	ds	标识每个时间步的列，其值可以是时间戳或整数。
target_col	str	y	包含目标变量的列。
level	Union	99	用于检测异常的置信水平，介于 0 到 100 之间。
finetuned_model_id	可选	无	要使用的先前微调模型的 ID。
clean_ex_first	bool	True	在使用 TimeGPT 进行预测之前清理外生信号。 使用 TimeGPT。
validate_api_key	bool	False	如果为 True，在发送请求前验证 api_key。
date_features	Union	False	从日期计算出的特征。 可以是 pandas 日期属性，或以日期为输入的函数。 如果为 True，将自动添加 df 频率下最常用的日期特征。 df 的频率。
date_features_to_one_hot	Union	False	对这些日期特征应用独热编码。 如果 date_features=True，则所有日期特征将 默认进行独热编码。
model	Literal	timegpt-1	要使用的模型（字符串）。选项包括：timegpt-1 和 timegpt-1-long-horizon。 如果希望预测超出数据频率一个季节性 周期以上的时间，我们建议使用 timegpt-1-long-horizon 进行预测。 根据您的数据频率确定的周期。
num_partitions	可选	无	使用的分区数量。 如果为 None，分区数量将等于 分布式环境中可用的并行资源。
返回值	AnyDFType		包含 TimeGPT 标记的异常的 DataFrame。

---

源

​

NixtlaClient.usage

 NixtlaClient.usage ()

查询已消耗的请求数和限制

---

源

​

NixtlaClient.finetune

 NixtlaClient.finetune
                        (df:Union[pandas.core.frame.DataFrame,polars.dataf
                        rame.frame.DataFrame], freq:Union[str,int,pandas._
                        libs.tslibs.offsets.BaseOffset,NoneType]=None,
                        id_col:str='unique_id', time_col:str='ds',
                        target_col:str='y',
                        finetune_steps:typing.Annotated[int,Ge(ge=0)]=10,
                        finetune_depth:Literal[1,2,3,4,5]=1, finetune_loss
                        :Literal['default','mae','mse','rmse','mape','smap
                        e']='default', output_model_id:Optional[str]=None,
                        finetuned_model_id:Optional[str]=None, model:Liter
                        al['azureai','timegpt-1','timegpt-1-long-
                        horizon']='timegpt-1')

将 TimeGPT 微调到您的时间序列。

	类型	默认值	详情
df	Union		函数将操作的 DataFrame。预期至少包含以下列： - time_col df 中包含时间序列时间索引的列名。这通常是一个日期时间 列，具有规律的间隔，例如每小时、每日、每月的数据点。 - target_col df 中包含时间序列目标变量的列名，即我们 希望预测或分析的变量。 此外，您可以传入多个时间序列（堆叠在 dataframe 中），考虑使用一个附加列： - id_col df 中标识唯一时间序列的列名。此列中的每个唯一值 对应一个唯一的时间序列。
freq	Union	无	时间戳的频率。如果为 None，将自动推断。 参见 pandas 可用的频率列表。
id_col	str	unique_id	标识每个时间序列的列。
time_col	str	ds	标识每个时间步的列，其值可以是时间戳或整数。
target_col	str	y	包含目标变量的列。
finetune_steps	Annotated	10	用于在新数据上微调 TimeGPT 学习的步数。
finetune_depth	Literal	1	微调的深度。使用 1 到 5 的范围，其中 1 表示微调程度较低， 5 表示整个模型都进行了微调。
finetune_loss	Literal	default	用于微调的损失函数。选项包括：default, mae, mse, rmse, mape, 和 smape。
output_model_id	可选	无	要分配给微调模型的 ID。如果为 None，则使用 UUID。
finetuned_model_id	可选	无	用作基础的先前微调模型的 ID。
model	Literal	timegpt-1	要使用的模型（字符串）。选项包括：timegpt-1 和 timegpt-1-long-horizon。 如果希望预测超出数据频率一个季节性 周期以上的时间，我们建议使用 timegpt-1-long-horizon 进行预测。 根据您的数据频率确定的周期。
返回值	str		微调模型的 ID

---

源

​

NixtlaClient.finetuned_models

 NixtlaClient.finetuned_models (as_df:bool=False)

列出微调模型

	类型	默认值	详情
as_df	bool	False	将微调模型作为 pandas dataframe 返回
返回值	Union		可用微调模型的列表。

---

源

​

NixtlaClient.finetuned_model

 NixtlaClient.finetuned_model (finetuned_model_id:str)

获取微调模型的元数据

	类型	详情
finetuned_model_id	str	要获取元数据的微调模型的 ID。
返回值	FinetunedModel	微调模型的元数据。

---

源

​

NixtlaClient.delete_finetuned_model

 NixtlaClient.delete_finetuned_model (finetuned_model_id:str)

删除先前微调的模型

	类型	详情
finetuned_model_id	str	要删除的微调模型的 ID。
返回值	bool	删除是否成功。

---

源

​

NixtlaClient.plot

 NixtlaClient.plot (df:Union[pandas.core.frame.DataFrame,polars.dataframe.
                    frame.DataFrame,NoneType]=None, forecasts_df:Union[pan
                    das.core.frame.DataFrame,polars.dataframe.frame.DataFr
                    ame,NoneType]=None, id_col:str='unique_id',
                    time_col:str='ds', target_col:str='y', unique_ids:Unio
                    n[list[str],NoneType,numpy.ndarray]=None,
                    plot_random:bool=True, max_ids:int=8,
                    models:Optional[list[str]]=None,
                    level:Optional[list[Union[int,float]]]=None,
                    max_insample_length:Optional[int]=None,
                    plot_anomalies:bool=False,
                    engine:Literal['matplotlib','plotly','plotly-
                    resampler']='matplotlib',
                    resampler_kwargs:Optional[dict]=None, ax:Union[Forward
                    Ref('plt.Axes'),numpy.ndarray,ForwardRef('plotly.graph
                    _objects.Figure'),NoneType]=None)

绘制预测值和样本内值。

	类型	默认值	详情
df	Union	无	函数将操作的 DataFrame。预期至少包含以下列： - time_col df 中包含时间序列时间索引的列名。这通常是一个日期时间 列，具有规律的间隔，例如每小时、每日、每月的数据点。 - target_col df 中包含时间序列目标变量的列名，即我们 希望预测或分析的变量。 此外，您可以传入多个时间序列（堆叠在 dataframe 中），考虑使用一个附加列： - id_col df 中标识唯一时间序列的列名。此列中的每个唯一值 对应一个唯一的时间序列。
forecasts_df	Union	无	包含 [unique_id, ds] 列和模型的 DataFrame。
id_col	str	unique_id	标识每个时间序列的列。
time_col	str	ds	标识每个时间步的列，其值可以是时间戳或整数。
target_col	str	y	包含目标变量的列。
unique_ids	Union	无	要绘制的时间序列。 如果为 None，时间序列将随机选择。
plot_random	bool	True	随机选择要绘制的时间序列。
max_ids	int	8	要绘制的最大 ID 数量。
models	可选	无	要绘制的模型列表。
level	可选	无	如果传入，要绘制的预测区间列表。
max_insample_length	可选	无	要绘制的最大训练/样本内观测值数量。
plot_anomalies	bool	False	为每个预测区间绘制异常。
engine	Literal	matplotlib	用于绘图的库。'matplotlib'、'plotly' 或 'plotly-resampler'。
resampler_kwargs	可选	无	要传递给 plotly-resampler 构造函数的 Kwargs。 如需进一步自定义 (“show_dash”)，请调用该方法， 存储绘图对象并将额外参数添加到 其 show_dash 方法中。
ax	Union	无	将添加绘图的对象。