ML Models

Define, train, and run time-series forecasting ML models on Spice Cloud, and get predictions in the Playground or by API.

Spice Models enable the training and use of ML models natively on the Spice platform.

The platform currently supports time-series forecasting models, with other categories of models planned.

Hosted models have first-class access to co-located data for training and inferencing including: Spice managed datasets, user managed datasets, and custom datasets and views. To read training and inference data faster, accelerate the datasets with Data Acceleration.

Defining a Model

Models are defined using a model manifest YAML file. Model details such as data requirements, architecture, training parameters, and other important hyperparameters are defined in the model.yaml.

Add a model.yaml file to the repository path /models/[model_name]/model.yaml of a GitHub connected Spice app, replacing [model_name] with the desired model name.

Refer to the Models YAML specification for all available configuration options.

For example model manifests, see the models samples repo.

Training a Model

In the spice.ai Portal, navigate to the Models tab of the Spice app.

model.yaml files committed to the connected repository will be automatically detected and imported as Spice Models.

The Models tab of the my-first-app project lists three models on the main branch: gas_fees, gas_fees_v2, and uniswap_v3_eth_usdt. Each row shows a commit SHA and a commit message. The gas_fees_v2 row has an 'accelerated by Firecache' badge.

Spice Models defined in model.yaml files automatically detected and imported in the Portal.

Navigating to a specific Model will show detailed information as defined in the model.yaml.

A training run can be started using the Train button.

The Model tab for gas_fees/v0.1 shows the linked GitHub commit, the path models/gas_fees, the family gas_fees, and the model type xgb_gasfees. An Inference API panel holds a curl command that sends a POST request to /v1/predictions. The Train button is at the bottom, in the Training runs section.

Details for a specific Model.

Training runs in progress will be shown and updated, along with historical training runs.

The Training Runs tab for the gas_fees model lists five runs, newest first. The newest run, created a few seconds ago, is in progress. Of the older runs, two show Complete and two show Failed with a 'could not fetch data' error.

A model training with status "Running".

The Training Status will be updated to Complete for successfully completed training runs. Details and the Training Report, are available on the Training Run page.

The training run page for gas_fees/v0.1 shows a training duration of 55 seconds. A Weights section shows the artifact CID and a curl command for the Inference API. The Training Report section shows a Training Loss chart with two curves, one labeled MAE.

A successfully completed Model training run with status "Complete".

Running Model Predictions

A successfully trained model can be used to make predictions.

The lookback data (inferencing data) is automatically provided by the platform and wired up to the inference, enabling a prediction to be made using a simple API call.

AI Predictions in the Playground

Navigate to AI Predictions in the Playground.

Successfully trained models will be available for selection from the model selector drop down on the right.

Clicking Predict will demonstrate calling the predictions API using lookback data within the Spice platform. A graph of the predicted value(s) along with the lookback data will be displayed.

The Explore page under AI Predictions shows V0.1 Predictions for xgb_gasfees, with v0.1 in the model selector on the right. Below the Predict button, a line chart plots lookback values up to a marker labeled 'now'. A dashed line marks the predicted value.

The AI Predictions playground.

Predictions by API

The Training Runs page provides training details including a copyable curl command to make a prediction from the command line.

For details on the API, see Prediction Documentation.

A terminal window over the training run page runs the same curl command as the Inference API panel. The JSON response holds one forecast point with a value of about 16.03. The response also reports a duration_ms of 135.

Detailed training run page with the predictions API