TabICL¶
The Snowflake Model Registry supports TabICL tabular foundation models
(tabicl.TabICLClassifier and tabicl.TabICLRegressor) as of snowflake-ml-python 2.8.0. TabICL is an
in-context-learning (ICL) model for tabular classification and regression: fit prepares ICL state from labeled
rows rather than learning a separate set of task weights.
You log a TabICL estimator with Registry.log_model. The registry does not treat TabICL as a generic
scikit-learn model, even though the
estimators subclass sklearn.base.BaseEstimator. At log time the registry bundles the TabICL foundation checkpoint
into the model artifact so serving can run offline.
Bound and unbound serving¶
The registry chooses the serving mode from the estimator’s fitted state. There is no explicit toggle.
| Mode | When it applies | What is packaged | predict |
|---|---|---|---|
| Unbound (in-context learning) | You log an unfitted estimator. | Foundation checkpoint and constructor parameters only. Labeled context rows are supplied at inference time. | A partitioned table function. Each partition contains labeled context rows and unlabeled query rows. The output contains only the scored query rows. |
| Bound | You log a fitted estimator. | Foundation checkpoint, constructor parameters, and the training frame. The estimator is re-fit on that frame when the model loads. | A scalar function over named feature columns. One prediction per input row. |
Use unbound serving when you want to log the foundation once and score many different labeled contexts without re-logging. Use bound serving when you have a single fitted task and want sklearn-style row-wise inference.
TabICL’s checkpoint is small enough to run in a Snowflake warehouse. You can also run inference in Snowpark
Container Services. Unbound predict is a partitioned table function, so it has no scalar service endpoint. Use
ModelVersion.run in a warehouse or
ModelVersion.run_batch on a compute pool. Bound
predict is a regular function, so warehouse run and SPCS serving both apply.
Logging options¶
The following additional options can be used in the options dictionary when you call log_model:
| Option | Description |
|---|---|
target_methods | A list of the names of the methods available on the model object. The default target method is predict. |
target_column | Name of the scalar label column. Defaults to |
prediction_type | Python type used to override the scored output column (for example |
cuda_version | CUDA runtime version to use when deploying to a platform with a GPU. Defaults to the registry default. Set
to |
Explainability is not supported for TabICL models. Setting enable_explainability to True raises an error.
The tabicl package is available from PyPI only, so set artifact_repository_map when you log the model, as shown in
the Log an unfitted classifier example below. If you omit this argument, log_model may add the built-in PyPI repository automatically for warehouse targets. That
automatic step doesn’t apply when you pass conda dependencies, and if the repository isn’t accessible, the registry
falls back to conda packaging, which can’t install tabicl. For a private PyPI-compatible repository, see
Use a private PyPI artifact repository.
Unbound serving¶
An unfitted TabICLClassifier or TabICLRegressor is served unbound. The logged predict signature is generic
across feature names and widths:
FEATURES: an OBJECT map from feature name to value per row. Values can mix numeric, string, and boolean types. Rows in a partition must share the same feature keys and types.TARGET(or the name you pass intarget_column): a nullable scalar label. A non-null value marks an in-context example. A null value marks a row to score.- Output:
OUTPUT_FEATURES(the query row’s features, echoed under a distinct name so warehouse table-function invocation doesn’t collide with the inputFEATUREScolumn) andPREDICTION.
predict also accepts these inference parameters (passed as params to run or run_batch):
| Parameter | Description |
|---|---|
target_column | Label column used to split context from query rows. Defaults to the value recorded at log time. |
context_filter | Optional filter that selects context rows instead of using a non-null target. Use comparisons and boolean logic over top-level input columns, such as the target column. Other expressions are rejected. |
prediction_filter | Optional filter that selects query rows instead of using a null target. Same restrictions as
|
You don’t need sample_input_data for unbound logging. If you pass a sample, it must be a pandas DataFrame with
FEATURES and the target column. The registry uses it to smoke-test fit/predict and to refine the scalar types. The
sample must include at least two labeled rows and at least one row with a null target, because the smoke test fits on
the labeled rows and predicts on the null-target rows.
The following examples assume reg is an instance of snowflake.ml.registry.Registry and session is an active
Snowpark session. For information on creating a registry object, see
Snowflake Model Registry.
Log an unfitted classifier¶
At log time, if the estimator doesn’t already point at a local .ckpt file via model_path, the registry
downloads the foundation checkpoint from the Hugging Face hub (jingang/TabICL) and copies it into the artifact.
Serving rebinds that bundled checkpoint with allow_auto_download=False, so inference doesn’t contact the network.
If you log the model from a Snowflake Notebook, attach an external access integration that allows egress to Hugging
Face. For the host list and an example integration, see
Hugging Face pipeline. You can skip that integration by
setting model_path to a checkpoint you already downloaded.
Warehouse inference¶
Pack each row’s features into an OBJECT, put labeled context rows and unlabeled query rows in the same partition,
and call run with partition_column:
Each partition is fit on its context rows (cached by a context fingerprint for repeated calls with the same context) and scores only the query rows.
Batch inference on Snowpark Container Services¶
The same logged model and the same input shape work with run_batch. Pass the partition column and
target_column in InputSpec:
For job configuration and how to read results from the output stage, see Batch inference jobs.
Bound serving¶
Fit the estimator before logging it, and pass the training frame (named feature columns plus the target column) as
sample_input_data. The registry infers a static signature over those feature columns and stores the frame so the
estimator can be re-fit when the model loads.
The output is a DataFrame with a PREDICTION column, one row per input row.
Limitations and considerations¶
- TabICL models don’t support explainability.
- A
snowflake.ml.model.custom_model.CustomModelthat holds a TabICL estimator is handled by the custom model handler, so the bound and unbound behavior on this page doesn’t apply. Log the estimator directly. - Unbound input rows in a partition must share the same feature keys and types. Query rows missing a context feature receive a null for that key rather than failing.
- Unbound
predictreturns only query rows (M:N), not the original context rows. - Logging downloads the foundation checkpoint unless
model_pathalready points at a local.ckptfile.