# 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.

## Further Reading

* [AI Gateway](https://github.com/spicehq/docs/blob/trunk/features/ai-gateway.md)
* [LLM API reference](https://github.com/spicehq/docs/blob/trunk/api/openai-api.md)
* [Search & Retrieval](https://github.com/spicehq/docs/blob/trunk/features/search-and-retrieval.md)
* [Model Providers](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/README.md)
* [Semantic Models](https://github.com/spicehq/docs/blob/trunk/features/semantic-models.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spice.ai/help/ai-and-models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.