Fazer deploy
docs

Embeddings e rerank

Gere vetores para busca semântica e RAG com POST /embeddings e reordene documentos pela relevância com POST /rerank na Veloz AI.

Embeddings transformam texto em vetores: textos parecidos viram vetores próximos, o que serve para busca semântica, agrupamento e RAG. O rerank pega uma consulta e uma lista curta de documentos e devolve a lista ordenada pela relevância. Os dois juntos formam a busca da maioria dos sistemas de RAG: o embedding acha os candidatos e o rerank escolhe os melhores.

Os exemplos usam o cliente configurado em Inferência de IA.

Embeddings

Gere vetores com POST /embeddings. O campo input aceita um texto ou uma lista de textos:

resultado = client.embeddings.create(
    model="qwen-qwen3-embedding-8b",
    input=["Como faço um Pix agendado?", "Pix é o pagamento instantâneo do Banco Central."],
)
 
vetor = resultado.data[0].embedding
print(len(vetor))  # 4096
curl https://platform.onveloz.com/api/ai/v1/embeddings \
  -H "Authorization: Bearer $VELOZ_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen-qwen3-embedding-8b", "input": "Como faço um Pix agendado?" }'

Cada item de data traz o embedding e o index do texto na lista enviada. A cobrança é pelos tokens de entrada.

Use o mesmo modelo para gerar os vetores dos documentos e o da consulta: vetores de modelos diferentes não se comparam.

Rerank

Reordene documentos pela relevância para uma consulta com POST /rerank. Os SDKs da OpenAI não têm um método para rerank, então chame a rota direto:

curl https://platform.onveloz.com/api/ai/v1/rerank \
  -H "Authorization: Bearer $VELOZ_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "Qual é o prazo de devolução?",
    "documents": [
      "O frete é grátis acima de R$ 200.",
      "Você pode devolver o produto em até 7 dias após o recebimento.",
      "Aceitamos Pix e cartão de crédito."
    ],
    "top_n": 2
  }'

A resposta lista os documentos em results, cada um com index (a posição na lista enviada) e relevance_score, do mais relevante para o menos relevante. A cobrança é pelos tokens da consulta somados aos dos documentos.

Busca com os dois

Um exemplo completo em Python: gera os vetores, acha os candidatos mais próximos da consulta e usa o rerank para a ordem final. Em produção, você gera os vetores dos documentos uma vez e guarda no seu banco.

import os
import httpx
from openai import OpenAI
 
BASE_URL = "https://platform.onveloz.com/api/ai/v1"
CHAVE = os.environ["VELOZ_AI_KEY"]
client = OpenAI(base_url=BASE_URL, api_key=CHAVE)
 
documentos = [
    "Você pode devolver o produto em até 7 dias após o recebimento.",
    "O frete é grátis acima de R$ 200.",
    "Aceitamos Pix e cartão de crédito.",
]
consulta = "Qual é o prazo de devolução?"
 
# 1. Vetores dos documentos e da consulta, numa chamada só
vetores = client.embeddings.create(model="qwen-qwen3-embedding-8b", input=documentos + [consulta])
*vetores_docs, vetor_consulta = [item.embedding for item in vetores.data]
 
 
def cosseno(a, b):
    produto = sum(x * y for x, y in zip(a, b))
    return produto / ((sum(x * x for x in a) ** 0.5) * (sum(y * y for y in b) ** 0.5))
 
 
# 2. Os candidatos mais próximos da consulta
candidatos = sorted(
    range(len(documentos)),
    key=lambda i: cosseno(vetores_docs[i], vetor_consulta),
    reverse=True,
)[:2]
 
# 3. Rerank dos candidatos para a ordem final
resposta = httpx.post(
    f"{BASE_URL}/rerank",
    headers={"Authorization": f"Bearer {CHAVE}"},
    json={
        "model": "bge-reranker-v2-m3",
        "query": consulta,
        "documents": [documentos[i] for i in candidatos],
    },
)
resposta.raise_for_status()
 
melhor = resposta.json()["results"][0]
print(documentos[candidatos[melhor["index"]]])

O httpx já vem instalado com o SDK da OpenAI.

Modelos

Uso Modelos
Embeddings qwen-qwen3-embedding-8b, nomic-embed-text-v1-5
Rerank qwen-qwen3-reranker-8b, bge-reranker-v2-m3

Preços em Modelos e preços. Um modelo de embeddings em /chat/completions (ou o contrário) responde 400 com o código model_not_supported_for_endpoint.

Com um provedor próprio, /embeddings também chama os modelos de embeddings da OpenAI, do Google ou de uma API compatível, como openai/text-embedding-3-small. A Anthropic não oferece embeddings, e o rerank atende só os modelos do catálogo.