Embeddings

Un embedding è un elenco di numeri che rappresenta il significato di un testo. Due testi che dicono la stessa cosa con parole diverse hanno vettori vicini: è quello che serve per costruire una ricerca semantica nel tuo software, trovare duplicati o raggruppare richieste simili.

POST /embeddings lo calcola. Serve una chiave con il permesso Embedding: le chiavi personali ce l’hanno sempre, quelle dell’area di lavoro solo se è stato scelto alla creazione.

La richiesta

curl https://api.userbot.ai/api/eu/v1/embeddings \
  -H "Authorization: Bearer $USERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": ["Il listino 2026 è in vigore da gennaio.", "Prezzi aggiornati dal primo dell'\''anno."]
  }'

Con l’SDK OpenAI per Python:

result = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["Il listino 2026 è in vigore da gennaio.", "Prezzi aggiornati dal primo dell'anno."],
)
vettori = [row.embedding for row in result.data]

La risposta

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] },
    { "object": "embedding", "index": 1, "embedding": [0.0119, -0.0441, 0.0802] }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": { "prompt_tokens": 22, "total_tokens": 22 }
}

Un elemento di data per ogni testo mandato, nello stesso ordine: index ti dice a quale corrisponde. I vettori veri sono molto più lunghi di quelli dell’esempio. Le chiamate di embedding si pagano solo sui token in ingresso.

Come usarli bene

Usa sempre lo stesso modello. Vettori calcolati con modelli diversi, o con dimensions diverse, non si possono confrontare fra loro. Se cambi modello, ricalcola tutto l’archivio.

Manda i testi in gruppo. Una lista di stringhe in una sola chiamata costa quanto le chiamate separate, ma pesa molto meno sul limite di richieste al minuto. → Limiti e quote

Calcola una volta, conserva. Il vettore di un documento non cambia finché non cambia il testo: salvalo insieme al documento e ricalcolalo solo quando serve.

Un modello di completamento usato su questo endpoint viene rifiutato come modello sconosciuto: 400 su Global, 451 su EU. Lo stesso vale al contrario.