Embeddings

Un embedding es una lista de números que captura el significado de un fragmento de texto. Los textos con significados similares obtienen vectores cercanos entre sí, y eso es lo que hace posible la búsqueda semántica, la generación aumentada por recuperación (RAG), las recomendaciones, el clustering y la deduplicación.

POST /v1/embeddings sigue el formato de OpenAI, así que client.embeddings.create y todos los frameworks basados en él funcionan sin cambios.

Crear embeddings

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.inferray.com/v1", apiKey: process.env.INFERRAY_API_KEY });

const result = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: ["How do I reset my password?", "Where can I change my login details?"],
});

const [a, b] = result.data.map((item) => item.embedding);

result = client.embeddings.create(
    model="text-embedding-3-small",
    input=["How do I reset my password?", "Where can I change my login details?"],
)
vectors = [item.embedding for item in result.data]

curl https://api.inferray.com/v1/embeddings \
  -H "Authorization: Bearer $INFERRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": "The quick brown fox"}'

Parámetros

Parámetro	Qué hace
`model`	Obligatorio. Un modelo de embeddings, por ejemplo `text-embedding-3-small`, `text-embedding-3-large`, `gemini-embedding-001`, `qwen3-embedding-8b` o `bge-m3`.
`input`	Obligatorio. Un string, o un array de strings para generar embeddings en una sola solicitud. Algunos modelos también aceptan IDs de tokens.
`dimensions`	Un vector más corto, en los modelos que lo admiten. Los vectores más pequeños son más baratos de almacenar y de buscar.
`encoding_format`	`float` (predeterminado) o `base64`, que ocupa menos al transmitirse.

La respuesta

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0023, -0.0094, 0.0158] },
    { "object": "embedding", "index": 1, "embedding": [0.0019, -0.0101, 0.0149] }
  ],
  "usage": { "prompt_tokens": 16, "total_tokens": 16 }
}

index coincide con la posición en input. Los embeddings se cobran solo por los tokens de entrada; no hay salida. usage también incluye los cost cobrados; consulta uso y costos.

Comparar vectores

La similitud coseno es la medida habitual: los valores cercanos a 1 indican un significado similar.

const cosine = (a, b) => {
  let dot = 0, na = 0, nb = 0;
  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] ** 2; nb += b[i] ** 2; }
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
};

Consejos

Usa el mismo modelo para tus documentos y para tus consultas. Los vectores de modelos distintos (o con distinto dimensions) no son comparables.
Agrupa muchos textos en una sola solicitud en lugar de enviarlos uno por uno.
Divide los documentos largos en pasajes de unos cientos de tokens y genera un embedding para cada uno; la recuperación funciona mejor que con un solo vector por documento.
Para reordenar los resultados por relevancia después de una búsqueda vectorial, agrega reranking.