For the complete documentation index, see [llms.txt](https://docs.spice.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spice.ai/help/ai-and-models.md).

# AI & Models

## Overview

Spice.ai provides an **OpenAI-compatible AI Gateway** that lets you access multiple model providers through a unified API. This enables LLM inference, embeddings, vector search, and RAG workflows.

See [AI Gateway](https://github.com/spicehq/docs/blob/trunk/features/ai-gateway.md) for full feature details.

## Supported Model Providers

| Provider     | Documentation                                                                                             |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| OpenAI       | [OpenAI](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/openai.md)            |
| Anthropic    | [Anthropic](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/anthropic.md)      |
| Azure OpenAI | [Azure](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/azure.md)              |
| xAI (Grok)   | [XAI](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/xai.md)                  |
| Hugging Face | [Hugging Face](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/huggingface.md) |
| Perplexity   | [Perplexity](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/perplexity.md)    |
| Spice.ai     | [SpiceAI](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/spiceai.md)          |

See [Model Providers](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/README.md) for the complete list.

## Setting Up AI in Your App

### 1. Add a model provider secret

Store your model provider API key as a [secret](https://github.com/spicehq/docs/blob/trunk/portal/apps/secrets.md) in your app (e.g., `OPENAI_API_KEY`).

### 2. Configure a model in your Spicepod

```yaml
models:
  - from: openai:gpt-4o
    name: my_model
    params:
      openai_api_key: "${secrets:OPENAI_API_KEY}"
```

### 3. Deploy

Deploy your app to make the model available.

### 4. Use the API

Send requests to the [LLM API](https://github.com/spicehq/docs/blob/trunk/api/openai-api.md):

```bash
curl https://data.spiceai.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "model": "my_model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Key Features

### OpenAI-compatible API

The AI Gateway exposes an OpenAI-compatible interface at `https://data.spiceai.io/v1/chat/completions`. You can use any OpenAI-compatible client library — just point it at the Spice.ai endpoint and use your app's API key.

### Custom tools & system prompts

Configure custom tools and system prompts in your model configuration to tailor AI behavior. See [AI Gateway](https://github.com/spicehq/docs/blob/trunk/features/ai-gateway.md) for configuration options.

### Vector search & RAG

Spice supports [vector and hybrid search](https://github.com/spicehq/docs/blob/trunk/features/search-and-retrieval.md) for retrieval-augmented generation (RAG) workflows:

* Configure [embeddings](https://github.com/spicehq/docs/blob/trunk/building-blocks/embeddings/README.md) for your datasets.
* Use the [Search API](https://github.com/spicehq/docs/blob/trunk/api/search.md) for semantic search.

### Observability

All AI requests include full [OpenTelemetry observability](https://github.com/spicehq/docs/blob/trunk/features/observability/README.md) for tracing request flows, latency, and errors.

## Common Issues

### AI chat returns errors

1. **Model not configured** — Ensure a model is defined in your Spicepod and the app is deployed.
2. **Missing secret** — Verify the model provider API key is stored as a secret and referenced correctly with `${secrets:SECRET_NAME}`.
3. **Secret changes require redeployment** — After adding or updating secrets, redeploy the app.

### Model not found

* Check that the model name in your API request matches the `name` field in your Spicepod model configuration.
* Verify the `from` field uses a valid provider and model identifier.

### Rate limits or quota errors

These typically come from the upstream model provider (e.g., OpenAI). Check your provider's usage dashboard and rate limits.