> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddings

> Crie embeddings vetoriais por meio do AI Gateway com qualquer modelo de embedding compatível. Gere embeddings para busca semântica, clustering e ingestão de RAG.

**Casos de uso**

* Busca semântica e recuperação em uma coleção de documentos.
* Clustering, classificação e detecção de anomalias em texto.
* Ingestão de vetores em um banco de dados vetorial próprio ou de terceiros.
* Criação de pipelines de RAG em que a recuperação acontece fora do gateway.

***

## Visão geral

O **AI Gateway** expõe `POST /embeddings` na URL base da [API compatível com OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md) (`https://router.toqan.ai/eu/v3/router`). Envie texto e receba embeddings vetoriais de qualquer modelo de embedding habilitado, com o mesmo formato de requisição e resposta da OpenAI Embeddings API. Fallbacks, orçamentos, cache e observabilidade se aplicam às chamadas de embedding exatamente como às chat completions.

## Início rápido

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/embeddings \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "The food was delicious"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const embedding = await client.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: "The food was delicious",
});

console.log(embedding.data[0].embedding);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

embedding = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input="The food was delicious",
)

print(embedding.data[0].embedding)
```

## Provedores e modelos

Os provedores com suporte a embeddings incluem AWS Bedrock, Azure, Cohere, Vertex AI, Google AI, Jina AI, Mistral, Nebius, OpenAI, Scaleway, Tencent e TensorX. Consulte [Modelos compatíveis](/docs/pt-BR/ai-gateway/supported-models.md) para ver o catálogo completo de modelos de embedding.

## Seleção de modelo e dimensões

Escolha um modelo com base nos idiomas que ele aceita, no custo e na qualidade da saída. Para conteúdo em vários idiomas, use um modelo multilíngue como `cohere/embed-multilingual-v3.0` ou `jina/jina-embeddings-v3`. Para conteúdo somente em inglês, `openai/text-embedding-3-small` é menor e mais barato.

Passe `dimensions` para solicitar um número específico de dimensões de saída:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "openai/text-embedding-3-small",
  "input": "The food was delicious",
  "dimensions": 256
}
```

> [!TIP]
>
> Modelos que aceitam tamanhos de saída configuráveis (por exemplo, `openai/text-embedding-3-small` e `openai/text-embedding-3-large`) retornam vetores do tamanho solicitado, o que reduz o custo de armazenamento e de processamento com uma pequena perda na qualidade da recuperação. Modelos com tamanho de saída fixo retornam vetores com a sua dimensão fixa.

Defina `encoding_format` como `base64` para receber os embeddings como strings codificadas em base64 em vez de arrays JSON de floats, o que deixa a resposta menor:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "openai/text-embedding-3-small",
  "input": "The food was delicious",
  "encoding_format": "base64"
}
```

## Envio em lote e uso de tokens

O campo `input` aceita uma única string, um array de strings ou arrays de tokens. Agrupe textos relacionados em uma única requisição em vez de enviar uma requisição por texto. Uma única ida e volta é mais rápida do que muitas:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/embeddings \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": [
      "The food was delicious",
      "And the waiter was friendly"
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const batch = await client.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: [
    "The food was delicious",
    "And the waiter was friendly",
  ],
});

console.log(batch.data.map((item) => item.embedding.length));
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

batch = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=[
        "The food was delicious",
        "And the waiter was friendly",
    ],
)

print([len(item.embedding) for item in batch.data])
```

A resposta retorna um embedding por entrada no array `data`, na mesma ordem da entrada. O uso de tokens segue o formato da OpenAI: `usage.prompt_tokens` informa os tokens de entrada consumidos e `usage.total_tokens`, o total da requisição.

## Embeddings e Knowledge Bases

As [Knowledge Bases](/docs/pt-BR/ai-gateway/features/knowledge-bases.md) cuidam internamente do embedding e da recuperação: dividem os documentos de origem em chunks, geram seus embeddings com um modelo de embedding configurado e injetam o contexto recuperado na chamada ao modelo. Prefira uma Knowledge Base quando o objetivo for RAG dentro do gateway, porque ela lida com a ingestão e a recuperação automaticamente.

Chame o endpoint de embeddings diretamente quando o pipeline precisar de um controle que uma Knowledge Base não oferece:

* Armazenar vetores em um banco de dados vetorial externo, como Pinecone ou um banco vetorial próprio.
* Usar chunking personalizado, um modelo de embedding personalizado ou embeddings para tarefas que não são de recuperação, como clustering e classificação.
* Executar a recuperação fora do gateway e manter a geração dentro dele.

## Fallbacks, cache, orçamentos e observabilidade

As chamadas de embedding aceitam os mesmos controles do gateway que as chat completions:

* **Fallbacks**: passe um array de `fallbacks` para rotear para modelos de reserva quando o modelo principal falhar. Consulte [Fallbacks](/docs/pt-BR/ai-gateway/features/retries.md#fallbacks).
* **Cache**: requisições de embedding idênticas podem ser atendidas a partir do cache. Consulte [Cache](/docs/pt-BR/ai-gateway/features/cache.md).
* **Orçamentos**: o tráfego de embedding conta para os [Orçamentos](/docs/pt-BR/ai-gateway/budgets.md), com limites aplicados por workspace, chave de API ou provedor.
* **Observabilidade**: as chamadas de embedding aparecem em Traces com modelo, uso de tokens e latência. Passe o campo de nível superior `name`, por exemplo `"name": "semantic-search-embed"`, para rotular a chamada no trace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.