API de Embeddings — Documentación de TokSpan

Endpoint

http
POST https://api.tokspan.com/v1/embeddings

Parámetros de la Solicitud

Parámetro	Tipo	Requerido	Descripción
model	string	Sí	ID del modelo de embedding (ej., `text-embedding-3-large`, `text-embedding-3-small`, `voyage-3`)
input	string / array	Sí	Texto a incrustar. Pase una cadena para un solo embedding o un array de cadenas para lote (hasta 2048 elementos por solicitud).
dimensions	integer	No	Reduzca las dimensiones de salida para ahorrar almacenamiento y mejorar la velocidad de búsqueda. Compatible con modelos text-embedding-3. Debe ser ≤ la dimensión máxima del modelo.
encoding_format	string	No	`"float"` (predeterminado) o `"base64"` para transferencia compacta.
user	string	No	Identificador de usuario final para monitoreo de abuso.

Embedding Individual

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokspan.com/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Your text string for embedding",
    dimensions=1024,  # Optional: reduce dimensions
)

embedding = response.data[0].embedding
print(f"Vector dimension: {len(embedding)}")

Embedding por Lote

Envíe hasta 2048 entradas en una sola solicitud para máximo rendimiento. La respuesta conserva el orden de entrada — response.data[0] corresponde a input[0].

python
# Batch embedding — process up to 2048 inputs per request
texts = ["First document", "Second document", "Third document"]

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=texts,
    dimensions=1024,
)

for i, data in enumerate(response.data):
    print(f"Text {i}: vector[:5] = {data.embedding[:5]}...")

Reducción de Dimensiones

Modelos como text-embedding-3-large (máx. 3072 dimensiones) y text-embedding-3-small (máx. 1536) admiten la reducción de dimensiones de salida mediante el parámetro dimensions.

¿Por qué reducir dimensiones?

Menor almacenamiento: Un vector con 256 dimensiones usa 12× menos espacio que 3072 dims
Búsqueda más rápida: Menos dimensiones = cálculo de similitud coseno más rápido
Calidad suficiente: Para la mayoría de casos de uso, 256–512 dimensiones retienen ~95%+ de la calidad semántica

Dimensiones	Almacenamiento (por 1M vectores)	Calidad	Ideal Para
256	~1 GB	Buena	Búsqueda a gran escala, apps sensibles al costo
512	~2 GB	Muy buena	RAG de propósito general y búsqueda semántica
1024	~4 GB	Excelente	Búsqueda de alta precisión, agrupamiento
3072	~12 GB	Máxima	Máxima precisión, corpus pequeños

Receta de Búsqueda Semántica

python
import numpy as np

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

# Embed your document corpus (do this once, store results)
doc_embeddings = client.embeddings.create(model="text-embedding-3-large", input=documents)

# Embed a search query
query_embedding = client.embeddings.create(model="text-embedding-3-large", input="How do I reset my password?")

# Find most similar documents
scores = [cosine_similarity(query_embedding.data[0].embedding, d.embedding) for d in doc_embeddings.data]
top_idx = np.argmax(scores)
print(f"Best match: {documents[top_idx]} (score: {scores[top_idx]:.3f})")

Consejo profesional: Para RAG en producción, combine embeddings con Rerank para un pipeline de dos etapas: recuperación gruesa con embeddings (rápido + económico), luego reranking de precisión sobre los 20–50 resultados principales.

Modelos Disponibles

Modelo	Proveedor	Dim. Máx.	Ideal Para
text-embedding-3-large	OpenAI	3072	Máxima precisión, reducción de dimensión flexible
text-embedding-3-small	OpenAI	1536	Eficiente en costo, buena calidad
Cohere Embed v3	Cohere	1024	Multilingüe, alto rendimiento en búsqueda
Voyage AI	Voyage	1024 / 2048	Embeddings para código y documentos legales
BGE-M3	BAAI	1024	Código abierto, multilingüe, apto para auto-hosting

Consulte la página de Modelos para el catálogo completo con precios actuales por token.