Embeddings

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 (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

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"
  }'

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);

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 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:

{
  "model": "openai/text-embedding-3-small",
  "input": "The food was delicious",
  "dimensions": 256
}

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:

{
  "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:

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"
    ]
  }'

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));

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 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.
Cache: requisições de embedding idênticas podem ser atendidas a partir do cache. Consulte Cache.
Orçamentos: o tráfego de embedding conta para os Orçamentos, 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.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Visão geral

Início rápido

Provedores e modelos

Seleção de modelo e dimensões

Envio em lote e uso de tokens

Embeddings e Knowledge Bases

Fallbacks, cache, orçamentos e observabilidade

​Visão geral

​Início rápido

​Provedores e modelos

​Seleção de modelo e dimensões

​Envio em lote e uso de tokens

​Embeddings e Knowledge Bases

​Fallbacks, cache, orçamentos e observabilidade

Visão geral

Início rápido

Provedores e modelos

Seleção de modelo e dimensões

Envio em lote e uso de tokens

Embeddings e Knowledge Bases

Fallbacks, cache, orçamentos e observabilidade