Skip to content

Commit c7b474a

Browse files
Jeadiephillipleblanc
Jeadie
and
phillipleblanc
authored
ML docs (#159)
* draft of ML docs * improvements and POST /predict * code formatting for bash * and JSON * Apply suggestions from code review * Update spiceaidocs/docs/machine-learning/index.md --------- Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>
1 parent 65dd70f commit c7b474a

File tree

7 files changed

+232
-2
lines changed

7 files changed

+232
-2
lines changed

‎spiceaidocs/docs/machine-learning/index.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,28 @@ sidebar_position: 8
1010
The Spice ML runtime is in its early preview phase and is subject to modifications.
1111

1212
:::
13+
14+
Machine learning models can be added to the Spice runtime similarly to datasets. The Spice runtime will load it, just like a dataset.
15+
```yaml
16+
name: my_spicepod
17+
version: v1beta1
18+
kind: Spicepod
19+
20+
models:
21+
- from: file:/model_path.onnx
22+
name: my_model_name
23+
datasets:
24+
- my_inference_view
25+
26+
datasets:
27+
- from: localhost
28+
name: my_inference_view
29+
sql_ref: inference.sql
30+
31+
# All your other datasets
32+
- from: spice.ai/eth.recent_blocks
33+
name: eth_recent_blocks
34+
acceleration:
35+
enabled: true
36+
refresh_mode: append
37+
```

‎spiceaidocs/docs/machine-learning/inference/index.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,101 @@ sidebar_label: 'Machine Learning Inference'
44
description: ''
55
sidebar_position: 2
66
---
7+
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
11+
The Spice ML runtime currently supports prediction via an API in the Spice runtime.
12+
13+
### GET `/v1/models/:name/predict`
14+
```shell
15+
curl "http://localhost:3000/v1/models/my_model_name/predict"
16+
```
17+
Where:
18+
- `name`: References the name provided in the `spicepod.yaml`.
19+
20+
21+
#### Response
22+
<Tabs>
23+
<TabItem value="Success" label="Success" default>
24+
```json
25+
{
26+
"status": "Success",
27+
"model_name": "my_model_name",
28+
"model_version": "1.0",
29+
"lookback": 30,
30+
"prediction": [0.45, 0.50, 0.55],
31+
"duration_ms": 123
32+
}
33+
```
34+
</TabItem>
35+
<TabItem value="Bad Request" label="Bad Request">
36+
```json
37+
{
38+
"status": "BadRequest",
39+
"error_message": "You have me a bad request :(",
40+
"model_name": "my_model_name",
41+
"lookback": 30,
42+
"duration_ms": 12
43+
}
44+
```
45+
</TabItem>
46+
<TabItem value="Internal Error" label="Internal Error">
47+
```json
48+
{
49+
"status": "InternalError",
50+
"error_message": "Oops, the server couldn't predict",
51+
"model_name": "my_model_name",
52+
"lookback": 30,
53+
"duration_ms": 12
54+
}
55+
```
56+
</TabItem>
57+
</Tabs>
58+
59+
### POST `/v1/predict`
60+
It's also possible to run multiple prediction models in parallel, useful for ensembling or A/B testing.
61+
```shell
62+
curl --request POST \
63+
--url http://localhost:3000/v1/predict \
64+
--data '{
65+
"predictions": [
66+
{
67+
"model_name": "drive_stats_a"
68+
},
69+
{
70+
"model_name": "drive_stats_b"
71+
}
72+
]
73+
}'
74+
```
75+
Where:
76+
- Each `model_name` provided references a model `name` in the Spicepod.
77+
78+
####
79+
```json
80+
{
81+
"duration_ms": 81,
82+
"predictions": [{
83+
"status": "Success",
84+
"model_name": "drive_stats_a",
85+
"model_version": "1.0",
86+
"lookback": 30,
87+
"prediction": [0.45, 0.5, 0.55],
88+
"duration_ms": 42
89+
}, {
90+
"status": "Success",
91+
"model_name": "drive_stats_b",
92+
"model_version": "1.0",
93+
"lookback": 30,
94+
"prediction": [0.43, 0.51, 0.53],
95+
"duration_ms": 42
96+
}]
97+
}
98+
```
99+
100+
## Limitations
101+
- Univariate predictions only
102+
- Multiple covariates
103+
- Covariate and output variate must have a fixed time frequency.
104+
- No support for discrete or exogenous variables.

‎spiceaidocs/docs/machine-learning/model-deployment/huggingface.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,37 @@
22
title: "Huggingface"
33
sidebar_label: "Huggingface"
44
sidebar_position: 1
5-
---
5+
---
6+
7+
To define a model component from HuggingFace, specify it in the `from` key.
8+
9+
### Example
10+
```yaml
11+
models:
12+
- from: huggingface:huggingface.co/spiceai/darts:latest
13+
name: hf_model
14+
files:
15+
- model.onnx
16+
datasets:
17+
- taxi_trips
18+
```
19+
20+
### `from` Format
21+
The `from` key follows the following regex format:
22+
```regex
23+
\A(huggingface:)(huggingface\.co\/)?(?<org>[\w\-]+)\/(?<model>[\w\-]+)(:(?<revision>[\w\d\-\.]+))?\z
24+
```
25+
#### Examples
26+
- `huggingface:username/modelname`: Implies the latest version of `modelname` hosted by `username`.
27+
- `huggingface:huggingface.co/username/modelname:revision`: Specifies a particular `revision` of `modelname` by `username`, including the optional domain.
28+
29+
#### Specification
30+
1. **Prefix:** The value must start with `huggingface:`.
31+
2. **Domain (Optional):** Optionally includes `huggingface.co/` immediately after the prefix. Currently no other Huggingface compatible services are supported.
32+
3. **Organization/User:** The HuggingFace organisation (`org`).
33+
4. **Model Name:** After a `/`, the model name (`model`).
34+
5. **Revision (Optional):** A colon (`:`) followed by the git-like revision identifier (`revision`).
35+
36+
37+
### Limitations
38+
- ONNX format support only

‎spiceaidocs/docs/machine-learning/model-deployment/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,19 @@ sidebar_label: 'ML Model Deployment'
44
description: ''
55
sidebar_position: 1
66
---
7+
8+
Models can be loaded from a variety of sources:
9+
- Local filesystem: Local ONNX files.
10+
- HuggingFace: Models Hosted on HuggingFace.
11+
- SpiceAI: Models trained on the Spice.AI Cloud Platform
12+
13+
A model component, within a Spicepod, has the following format.
14+
15+
16+
| field | Description |
17+
| ----------------- | ------------------------------------------------------------------- |
18+
| `name` | Unique, readable name for the model within the Spicepod. |
19+
| `from` | Source-specific address to uniquely identify a model |
20+
| `datasets` | Datasets that the model depends on for inference |
21+
| `files` (HF only) | Specify an individual file within the HuggingFace repository to use |
22+

‎spiceaidocs/docs/machine-learning/model-deployment/local.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Local"
3+
sidebar_label: "Local"
4+
sidebar_position: 3
5+
---
6+
7+
Local models can be used by specifying the file's path in `from` key.
8+
9+
### Example
10+
```yaml
11+
models:
12+
- from: file:/absolute/path/to/my/model.onnx
13+
name: local_model
14+
datasets:
15+
- taxi_trips
16+
```

‎spiceaidocs/docs/machine-learning/model-deployment/spiceai.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,45 @@
22
title: "SpiceAI"
33
sidebar_label: "SpiceAI"
44
sidebar_position: 2
5-
---
5+
---
6+
7+
### Example
8+
To run a model trained on the Spice.AI platform, specify it in the `from` key.
9+
```yaml
10+
models:
11+
- from: spice.ai/taxi_tech_co/taxi_drives/models/drive_stats
12+
name: drive_stats
13+
datasets:
14+
- drive_stats_inferencing
15+
```
16+
17+
This configuration allows for specifying models hosted by Spice AI, including their versions or specific training run IDs.
18+
```yaml
19+
models:
20+
- from: spice.ai/taxi_tech_co/taxi_drives/models/drive_stats:latest # Git-like tagging
21+
name: drive_stats_a
22+
datasets:
23+
- drive_stats_inferencing
24+
25+
- from: spice.ai/taxi_tech_co/taxi_drives/models/drive_stats:60cb80a2-d59b-45c4-9b68-0946303bdcaf # Specific training run ID
26+
name: drive_stats_b
27+
datasets:
28+
- drive_stats_inferencing
29+
```
30+
31+
### `from` Format
32+
The from key must conform to the following regex format:
33+
```regex
34+
\A(?:spice\.ai\/)?(?<org>[\w\-]+)\/(?<app>[\w\-]+)(?:\/models)?\/(?<model>[\w\-]+):(?<version>[\w\d\-\.]+)\z
35+
```
36+
37+
#### Examples
38+
- `spice.ai/lukekim/smart/models/drive_stats:latest`: Refers to the latest version of the drive_stats model in the smart application by the user or organization lukekim.
39+
- `spice.ai/lukekim/smart/drive_stats:60cb80a2-d59b-45c4-9b68-0946303bdcaf`: Specifies a model with a unique training run ID.
40+
41+
#### Specification
42+
1. **Prefix (Optional):** The value must start with `spice.ai/`.
43+
1. **Organization/User:** The name of the organization or user (`org`) hosting the model.
44+
1. **Application Name**: The name of the application (`app`) which the model belongs to.
45+
4. **Model Name:** The name of the model (`model`).
46+
5. **Version (Optional):** A colon (`:`) followed by the version identifier (`version`), which could be a semantic version, `latest` for the most recent version, or a specific training run ID.

‎spiceaidocs/docusaurus.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,7 @@ const config: Config = {
141141
prism: {
142142
theme: prismThemes.github,
143143
darkTheme: prismThemes.dracula,
144+
additionalLanguages: ['bash', 'json'],
144145
},
145146
algolia: {
146147
appId: '0SP8I8JTL8',

0 commit comments

Comments
 (0)