# Embeddings de IA

Transforme texto em vetores para busca e similaridade.

URL base: `https://ai.inovacc.dev`

## Visão geral

Os Embeddings de IA transformam texto em vetores: listas de números cuja distância entre si acompanha o significado do texto. Dois trechos sobre o mesmo assunto ficam próximos mesmo quando não compartilham nenhuma palavra. O endpoint, `POST /v1/embeddings`, fala o formato de comunicação de embeddings da OpenAI, então um cliente da OpenAI já existente pode chamá-lo com a URL base `https://ai.inovacc.dev/v1` e dois cabeçalhos extras.

O problema que ele resolve é a comparação semântica dentro dos seus próprios sistemas. Com vetores você pode buscar por significado, agrupar itens semelhantes, encontrar quase duplicatas ou direcionar uma mensagem para a categoria mais próxima, usando o banco de dados ou o índice que você já opera.

Use os Embeddings de IA quando **você** guarda os vetores. Quando preferir que a Inovacc os guarde, faça a busca e devolva os trechos correspondentes, use o Banco de Dados Vetorial gerenciado de [Conhecimento e busca vetorial](/pt-br/products/knowledge/), que gera os embeddings dos seus documentos por você. Quando precisar de texto gerado em vez de vetores, use o [Chat com IA](/pt-br/products/ai.chat/).

## Conceitos

**Rotas.** Como no chat, você nunca nomeia um modelo. Sua organização recebe rotas de embeddings, ids opacos configurados pela Inovacc. `GET /v1/models` as lista: uma entrada cujo `endpoint` é `/v1/embeddings` é uma rota de embeddings. Envie o id dela como `model`, ou envie `"auto"` (ou nenhum `model`) para usar a rota padrão da sua organização. Uma rota atende um único endpoint; uma rota de chat chamada aqui é recusada.

**Entrada.** `input` é uma string não vazia, ou um array de strings; dentro de um array, uma string vazia é aceita. A resposta traz um vetor por entrada, em `data[]`, cada um com o `index` da entrada a que pertence.

**Os vetores de uma rota pertencem juntos.** Um vetor só é comparável com vetores produzidos pela mesma rota. Guarde o id da rota junto de cada vetor que você armazena, e gere os embeddings dos seus documentos e das suas consultas com a mesma rota.

**Campos opcionais.** `encoding_format` e `dimensions` são repassados ao modelo quando o modelo da rota os suporta e ignorados caso contrário. `user` é aceito como string e substituído, antes de sair da Inovacc, por um valor derivado da sua organização, de modo que duas organizações que enviam o mesmo valor nunca colidem.

**Uso.** O `usage` da resposta contém `prompt_tokens` e `total_tokens`. Este endpoint não traz cabeçalhos `x-usage-*`; a rota que respondeu está em `x-route-id`.

## Como funciona

Toda chamada leva `Authorization: Bearer <key>` e um `X-Operation-Id`. Sua organização vem da chave. O serviço verifica o id de operação e a chave, depois se aquele id de operação já foi usado, e então o corpo: apenas `model`, `input`, `encoding_format`, `dimensions` e `user` são aceitos, e qualquer outro campo é recusado pelo nome. Ele resolve a rota, verifica se a rota atende embeddings, valida `input`, estima o tamanho da entrada (um quarto dos caracteres de cada string de entrada) contra o limite por requisição da sua organização e reserva a chamada contra as cotas da sua organização. Só então o modelo é chamado.

A resposta é `{"object":"list","data":[{"object":"embedding","index":0,"embedding":[...]}],"model":"<route id>","usage":{...}}`. `model` é sempre o id da rota.

Não há transmissão. Uma resposta bem-sucedida é armazenada por 24 horas sob o seu id de operação: o mesmo id enviado de novo devolve os mesmos vetores com `x-idempotent-replay: true`, sem uma segunda chamada nem cobrança. Um erro nunca é armazenado, então uma chamada que falhou pode ser repetida com o mesmo id. O que é medido são os tokens de entrada.

## Primeiros passos

Você precisa de uma chave de API e de uma rota de embeddings habilitada para a sua organização ([Autenticação](/pt-br/guides/authentication/)).

1. **Encontre a sua rota de embeddings.** Chame `GET /v1/models` e escolha uma entrada cujo `endpoint` seja `/v1/embeddings`.
2. **Gere embeddings de dois trechos.** Chame `POST /v1/embeddings` com essa rota como `model`, um array `input` com duas strings e um `X-Operation-Id` novo (veja [os exemplos](#example)). A resposta tem duas entradas em `data`, com `index` 0 e 1, e `model` é o id da sua rota.
3. **Compare-os.** Calcule a similaridade de cosseno dos dois vetores no seu código. Gere o embedding de um terceiro trecho sobre outro assunto e compare de novo: a pontuação dele contra o primeiro é menor.
4. **Repita.** Envie o passo 2 novamente com o mesmo id de operação; os vetores são idênticos e a resposta traz `x-idempotent-replay: true`.

## Casos de uso

**Busca no seu próprio banco de dados.** Um catálogo de produtos guarda um vetor por descrição de produto no banco de dados que já usa. A pergunta de um comprador tem o embedding gerado com a mesma rota no momento da consulta, e os produtos mais próximos são exibidos, inclusive aqueles cuja descrição usa palavras diferentes.

**Detecção de quase duplicatas.** Um sistema de chamados gera o embedding de cada novo chamado e o compara com os abertos; uma pontuação acima de um limiar que você calibra vincula o chamado ao caso existente em vez de abrir um segundo.

**Direcionamento por similaridade.** Um pequeno conjunto de mensagens de exemplo por equipe tem o embedding gerado uma única vez. Cada mensagem recebida tem o embedding gerado e é enviada à equipe cujos exemplos estão mais próximos, sem nenhuma chamada de modelo por mensagem além do embedding.

## Limites e preços

| Limite | Valor |
|---|---|
| Corpo da requisição | 1 MiB por padrão; sua organização pode ser configurada entre 1 KiB e 20 MiB |
| Tokens de entrada por requisição | o limite da sua organização (`400 input_too_large` acima dele) |
| Tempo até a primeira resposta do modelo | 60 segundos |
| Resposta armazenada para repetição | 24 horas |
| Requisições, tokens, custo, simultaneidade, orçamentos diários | conforme definido para a sua organização |

**Preços:** sob consulta. A unidade de preço é **tokens**.

## Erros

| Status | Código | O que significa e o que fazer |
|---|---|---|
| 400 | `missing_operation_id`, `invalid_operation_id` | Envie um `X-Operation-Id` válido. |
| 400 | `unsupported_field` | Um campo diferente de `model`, `input`, `encoding_format`, `dimensions`, `user`; remova-o. |
| 400 | `invalid_body` | JSON malformado, `input` com formato errado, ou um `user` que não é string. |
| 400 | `model_not_allowed` | `model` não é um id de rota válido. |
| 400 | `input_too_large` | A entrada excede o seu limite por requisição; divida-a em várias chamadas. |
| 401 | `missing_credentials`, `invalid_credentials` | Envie uma chave válida. |
| 403 | `route_forbidden` | A rota não é sua, está desativada, ou não atende embeddings. |
| 403 | `key_disabled`, `organization_disabled` | Verifique a chave. |
| 409 | `operation_in_progress` | Esse id de operação ainda está em execução; aguarde e tente novamente. |
| 413 | `request_too_large` | O corpo excede o seu limite de tamanho. |
| 429 | `rate_limited`, `budget_exhausted` | Aguarde os segundos de `Retry-After`. |
| 429 | `quota_exceeded`, `concurrency_limited` | Uma cota se esgotou; sem `Retry-After`. |
| 502, 503, 504 | `upstream_error`, `service_unavailable`, `timeout_error` | Tente novamente com o mesmo id de operação e espera crescente. |

Veja [Erros](/pt-br/guides/errors/) para o envelope.

## Boas práticas

- **Agrupe as entradas**: envie muitos trechos em um único array `input`, dentro dos seus limites de tamanho e de tokens, em vez de uma chamada por trecho.
- **Guarde o id da rota junto com o vetor**, e gere novamente todos os embeddings se trocar de rota: vetores de duas rotas não são comparáveis.
- **Divida documentos longos** em trechos de alguns parágrafos antes de gerar os embeddings; um único vetor para um documento inteiro dilui o seu significado.
- **Derive o id de operação do conteúdo** (por exemplo, um hash do lote) para que uma tarefa reiniciada repita a resposta em vez de pagar de novo.
- **Repita `502`, `503` e `504` com o mesmo id de operação**; aguarde `Retry-After` em `429 rate_limited`.
- **Calibre os limiares com os seus próprios dados**: as pontuações de similaridade são relativas, não probabilidades.

## Relacionados

- [Conhecimento e busca vetorial](/pt-br/products/knowledge/): o Banco de Dados Vetorial gerenciado que gera os embeddings e faz a busca por você
- [Chat com IA](/pt-br/products/ai.chat/)
- [Autenticação](/pt-br/guides/authentication/), [Erros](/pt-br/guides/errors/), [Limites](/pt-br/guides/limits/)

## Endpoints

- POST /v1/embeddings

## Exemplo

```sh
curl -X POST "https://ai.inovacc.dev/v1/embeddings" -H "Authorization: Bearer $INOVACC_API_KEY" -H "X-Operation-Id: $(uuidgen)" -H "Content-Type: application/json" -d '{}'
```