Embeddings

Gere vetores de embeddings para busca semântica, classificação e RAG com o modelo urso-embed.

Visão Geral

O endpoint POST /v1/embeddings gera representações vetoriais (embeddings) de texto usando o modelo urso-embed, otimizado para português brasileiro. Embeddings são vetores numéricos que capturam o significado semântico do texto, permitindo busca semântica, classificação, clustering e pipelines de RAG.

Endpoint

POST https://api.polar-ai.com/v1/embeddings

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`model`	string	Sim	—	Modelo de embeddings (`urso-embed`)
`input`	string/array	Sim	—	Texto ou lista de textos para vetorizar
`encoding_format`	string	Não	`float`	Formato de codificação (`float` ou `base64`)
`dimensions`	integer	Não	1024	Número de dimensões do vetor

Exemplo Básico

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.polar-ai.com/v1",
    api_key="pk-your-key-here"
)

response = client.embeddings.create(
    model="urso-embed",
    input="A LGPD regula o tratamento de dados pessoais no Brasil."
)

embedding = response.data[0].embedding
print(f"Dimensões: {len(embedding)}")
print(f"Primeiros 5 valores: {embedding[:5]}")

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.polar-ai.com/v1",
  apiKey: "pk-your-key-here",
});

const response = await client.embeddings.create({
  model: "urso-embed",
  input: "A LGPD regula o tratamento de dados pessoais no Brasil.",
});

const embedding = response.data[0].embedding;
console.log(`Dimensions: ${embedding.length}`);
console.log(`First 5 values: ${embedding.slice(0, 5)}`);

curl

curl -X POST https://api.polar-ai.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pk-your-key-here" \
  -d '{
    "model": "urso-embed",
    "input": "A LGPD regula o tratamento de dados pessoais no Brasil."
  }'

Formato da Resposta

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789, ...]
    }
  ],
  "model": "urso-embed",
  "usage": {
    "prompt_tokens": 14,
    "total_tokens": 14
  }
}

Embeddings em Lote

Envie múltiplos textos em uma única requisição para maior eficiência:

texts = [
    "Direito do consumidor a troca de produto defeituoso",
    "Prazo prescricional para ações trabalhistas",
    "Requisitos para abertura de empresa no Simples Nacional",
    "Direitos do inquilino na Lei do Inquilinato",
    "Procedimento para registro de marca no INPI"
]

response = client.embeddings.create(
    model="urso-embed",
    input=texts
)

for i, data in enumerate(response.data):
    print(f"Texto {i}: {len(data.embedding)} dimensões")

Cálculo de Similaridade

Use similaridade cosseno para comparar embeddings:

import numpy as np
from openai import OpenAI

client = OpenAI(
    base_url="https://api.polar-ai.com/v1",
    api_key="pk-your-key-here"
)

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Gerar embeddings
response = client.embeddings.create(
    model="urso-embed",
    input=[
        "Como funciona o FGTS?",
        "Regras do Fundo de Garantia do Tempo de Serviço",
        "Receita de bolo de chocolate"
    ]
)

emb_query = response.data[0].embedding
emb_similar = response.data[1].embedding
emb_different = response.data[2].embedding

print(f"Similar: {cosine_similarity(emb_query, emb_similar):.4f}")
print(f"Diferente: {cosine_similarity(emb_query, emb_different):.4f}")

Casos de Uso

Busca Semântica

Encontre documentos relevantes pelo significado, não por palavras-chave:

# Indexar documentos
docs = ["Documento 1...", "Documento 2...", "Documento 3..."]
doc_embeddings = client.embeddings.create(
    model="urso-embed",
    input=docs
).data

# Buscar
query = "Quais são os direitos trabalhistas?"
query_embedding = client.embeddings.create(
    model="urso-embed",
    input=query
).data[0].embedding

# Calcular similaridade e ordenar
similarities = [
    cosine_similarity(query_embedding, doc.embedding)
    for doc in doc_embeddings
]

RAG (Retrieval-Augmented Generation)

Combine embeddings com o modelo de chat para respostas fundamentadas:

# 1. Buscar documentos relevantes com embeddings
query = "Qual o prazo para contestar uma ação?"
query_emb = client.embeddings.create(model="urso-embed", input=query).data[0].embedding

# 2. Recuperar os top-k documentos mais similares
# (use seu banco de vetores: Pinecone, Weaviate, pgvector, etc.)
relevant_docs = vector_db.search(query_emb, top_k=3)

# 3. Gerar resposta com contexto
context = "\n\n".join([doc.text for doc in relevant_docs])
response = client.chat.completions.create(
    model="urso-pro",
    messages=[
        {"role": "system", "content": f"Responda com base no contexto:\n\n{context}"},
        {"role": "user", "content": query}
    ]
)

Classificação

Use embeddings para classificar textos em categorias:

categories = {
    "trabalhista": "Questões sobre direito do trabalho, CLT, FGTS",
    "tributário": "Questões sobre impostos, tributos, Simples Nacional",
    "consumidor": "Questões sobre direito do consumidor, CDC",
    "civil": "Questões sobre direito civil, contratos, propriedade"
}

# Embeddings das categorias
cat_embeddings = client.embeddings.create(
    model="urso-embed",
    input=list(categories.values())
).data

# Classificar novo texto
text = "Posso ser demitido sem justa causa durante o período de experiência?"
text_emb = client.embeddings.create(model="urso-embed", input=text).data[0].embedding

similarities = {
    name: cosine_similarity(text_emb, cat.embedding)
    for (name, _), cat in zip(categories.items(), cat_embeddings)
}

best_category = max(similarities, key=similarities.get)
print(f"Categoria: {best_category} (score: {similarities[best_category]:.4f})")

Próximos Passos

Chat Completions — combine embeddings com geração de texto
Structured Output — extraia dados estruturados
Batch API — gere embeddings em lote

On this page