CrazyrouterCrazyrouter
Login
Back to Blog
Tutorial API Text-Embedding-3-Small - Guida al Modello di Embedding OpenAI

Tutorial API Text-Embedding-3-Small - Guida al Modello di Embedding OpenAI

C
Crazyrouter Team
January 26, 2026
22 viewsItalianoTutorial
Share:

Stai costruendo un motore di ricerca semantico o un sistema RAG (Retrieval-Augmented Generation)? Text-embedding-3-small è il più recente modello di embedding di OpenAI che converte il testo in vettori numerici, abilitando potenti ricerche per similarità e recupero di contenuti.

In questa guida imparerai:

  • Cosa sono i text embeddings e perché sono importanti
  • Come usare l'API text-embedding-3-small
  • Esempi di codice completi in Python e Node.js
  • Dimensioni personalizzate per uno storage ottimizzato
  • Confronto dei prezzi e ottimizzazione dei costi

Che cos'è Text-Embedding-3-Small?#

Text-embedding-3-small è il modello di embedding compatto di OpenAI rilasciato a gennaio 2024. Converte il testo in vettori a 1536 dimensioni che catturano il significato semantico, consentendo:

  • Ricerca semantica: trova documenti rilevanti in base al significato, non solo alle keyword
  • Sistemi RAG: recupera il contesto per le risposte degli LLM
  • Similarity Matching: confronta la similarità tra testi per raccomandazioni
  • Clustering: raggruppa documenti simili
  • Classificazione: categorizza il testo in base al contenuto

Specifiche del modello#

SpecificationValue
Model Nametext-embedding-3-small
Default Dimensions1536
Custom Dimensions256, 512, 1024, 1536
Max Input Tokens8,191
OutputNormalized vector

Quick Start#

Prerequisiti#

  1. Registrati su Crazyrouter
  2. Ottieni la tua API key dalla dashboard
  3. Python 3.8+ o Node.js 16+

Esempio Python#

python
from openai import OpenAI

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

# Generate embedding for a single text
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Machine learning is transforming industries worldwide."
)

embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")  # Output: 1536
print(f"First 5 values: {embedding[:5]}")

Esempio Node.js#

javascript
import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'your-crazyrouter-api-key',
    baseURL: 'https://crazyrouter.com/v1'
});

async function getEmbedding(text) {
    const response = await client.embeddings.create({
        model: 'text-embedding-3-small',
        input: text
    });

    return response.data[0].embedding;
}

// Usage
const embedding = await getEmbedding('Machine learning is amazing');
console.log(`Dimensions: ${embedding.length}`);  // Output: 1536

Esempio cURL#

bash
curl -X POST https://crazyrouter.com/v1/embeddings \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Hello world"
  }'

Response:

json
{
  "object": "list",
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  },
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.0020785425, -0.049085874, 0.02094679, ...]
    }
  ]
}

Batch Embedding#

Elabora più testi in una singola chiamata API per una migliore efficienza:

python
from openai import OpenAI

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

# Batch embedding - multiple texts at once
texts = [
    "Python is a programming language",
    "JavaScript runs in browsers",
    "Machine learning uses neural networks"
]

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

# Access each embedding
for i, data in enumerate(response.data):
    print(f"Text {i}: {len(data.embedding)} dimensions")

# Output:
# Text 0: 1536 dimensions
# Text 1: 1536 dimensions
# Text 2: 1536 dimensions

Dimensioni personalizzate#

Riduci i costi di storage usando dimensioni più piccole. Il modello supporta la riduzione delle dimensioni mantenendo una buona qualità:

python
# Use 512 dimensions instead of 1536
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Your text here",
    dimensions=512  # Options: 256, 512, 1024, 1536
)

embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")  # Output: 512

Confronto delle dimensioni#

DimensionsStorage (per vector)Use Case
2561 KBApp mobile, storage limitato
5122 KBPerformance bilanciata
10244 KBEsigenze di alta accuratezza
15366 KBMassima accuratezza

Costruire un sistema di ricerca semantica#

Ecco un esempio completo di costruzione di un sistema di ricerca semantica:

python
import numpy as np
from openai import OpenAI

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

def get_embedding(text):
    """Get embedding for a single text"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

def cosine_similarity(a, b):
    """Calculate cosine similarity between two vectors"""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Document database
documents = [
    "Python is great for data science and machine learning",
    "JavaScript is essential for web development",
    "Docker containers simplify deployment",
    "Kubernetes orchestrates container workloads",
    "PostgreSQL is a powerful relational database"
]

# Pre-compute embeddings for all documents
doc_embeddings = [get_embedding(doc) for doc in documents]

# Search function
def search(query, top_k=3):
    query_embedding = get_embedding(query)

    # Calculate similarities
    similarities = [
        cosine_similarity(query_embedding, doc_emb)
        for doc_emb in doc_embeddings
    ]

    # Get top results
    results = sorted(
        zip(documents, similarities),
        key=lambda x: x[1],
        reverse=True
    )[:top_k]

    return results

# Example search
results = search("How to deploy applications?")
for doc, score in results:
    print(f"Score: {score:.4f} - {doc}")

# Output:
# Score: 0.8234 - Docker containers simplify deployment
# Score: 0.7891 - Kubernetes orchestrates container workloads
# Score: 0.6543 - PostgreSQL is a powerful relational database

Integrazione con database vettoriali#

Integrazione con Pinecone#

python
import pinecone
from openai import OpenAI

# Initialize clients
client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1"
)

pinecone.init(api_key="your-pinecone-key")
index = pinecone.Index("your-index")

def embed_and_upsert(texts, ids):
    """Embed texts and store in Pinecone"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )

    vectors = [
        (id, data.embedding)
        for id, data in zip(ids, response.data)
    ]

    index.upsert(vectors=vectors)

def search_pinecone(query, top_k=5):
    """Search Pinecone with query embedding"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=query
    )

    results = index.query(
        vector=response.data[0].embedding,
        top_k=top_k
    )

    return results

Integrazione con ChromaDB#

python
import chromadb
from openai import OpenAI

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

# Initialize ChromaDB
chroma_client = chromadb.Client()
collection = chroma_client.create_collection("documents")

def get_embeddings(texts):
    """Get embeddings for multiple texts"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [data.embedding for data in response.data]

# Add documents
documents = ["doc1 content", "doc2 content", "doc3 content"]
embeddings = get_embeddings(documents)

collection.add(
    embeddings=embeddings,
    documents=documents,
    ids=["doc1", "doc2", "doc3"]
)

# Query
query_embedding = get_embeddings(["search query"])[0]
results = collection.query(
    query_embeddings=[query_embedding],
    n_results=3
)

Modelli di embedding disponibili#

Crazyrouter fornisce accesso a diversi modelli di embedding OpenAI:

ModelDimensionsPrice RatioBest For
text-embedding-3-small15360.01Uso generale, miglior rapporto qualità/prezzo
text-embedding-3-large30720.065Esigenze di alta precisione
text-embedding-ada-00215360.05Compatibilità legacy

Confronto dei prezzi#

ProviderModelPrice per 1M tokens
OpenAI Officialtext-embedding-3-small$0.020
Crazyroutertext-embedding-3-small$0.002
OpenAI Officialtext-embedding-3-large$0.130
Crazyroutertext-embedding-3-large$0.013

Pricing Disclaimer: Prices shown are for demonstration and may change. Actual billing is based on real-time prices at request time.

Esempio di risparmio sui costi:

Per un sistema RAG che elabora 10M di token/mese:

  • OpenAI Official: $200/mese
  • Crazyrouter: $20/mese
  • Risparmio: 90%

Best Practices#

1. Effettua richieste in batch#

python
# Good - single API call for multiple texts
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["text1", "text2", "text3"]  # Up to 2048 texts
)

# Bad - multiple API calls
for text in texts:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )

2. Metti in cache gli embeddings#

python
import hashlib
import json

embedding_cache = {}

def get_embedding_cached(text):
    # Create cache key
    cache_key = hashlib.md5(text.encode()).hexdigest()

    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )

    embedding = response.data[0].embedding
    embedding_cache[cache_key] = embedding

    return embedding

3. Usa dimensioni appropriate#

  • 256 dimensions: app mobile, dispositivi IoT
  • 512 dimensions: applicazioni web con vincoli di storage
  • 1024 dimensions: applicazioni standard
  • 1536 dimensions: requisiti di massima accuratezza

Domande frequenti#

Qual è la differenza tra text-embedding-3-small e text-embedding-3-large?#

Text-embedding-3-small produce vettori a 1536 dimensioni ed è ottimizzato per l'efficienza dei costi. Text-embedding-3-large produce vettori a 3072 dimensioni con maggiore accuratezza ma a un costo 6,5 volte superiore. Per la maggior parte delle applicazioni, text-embedding-3-small offre risultati eccellenti.

Posso ridurre le dimensioni dopo aver generato gli embeddings?#

Sì, puoi usare il parametro dimensions per generare direttamente vettori più piccoli. È più efficiente che generare vettori completi e poi troncarli.

Quanti testi posso elaborare in una singola richiesta?#

Puoi elaborare fino a 2048 testi in una singola richiesta API. Per dataset di grandi dimensioni, esegui il batch delle richieste in gruppi da 2048.

Gli embeddings sono normalizzati?#

Sì, text-embedding-3-small restituisce vettori normalizzati (lunghezza unitaria), quindi puoi usare il dot product invece della cosine similarity per un calcolo più veloce.

Per iniziare#

  1. Registrati su Crazyrouter
  2. Ottieni la tua API key dalla dashboard
  3. Installa l'SDK: pip install openai o npm install openai
  4. Inizia a generare embeddings con gli esempi di codice sopra

Articoli correlati:

Per domande, contatta support@crazyrouter.com

Available in other languages:

العربيةDanskDeutschEnglishEspañolFrançaisBahasa Indonesia日本語Қазақша한국어Bahasa MelayuNederlandsNorskPolskiPortuguêsРусскийไทยTürkçeTiếng Việt中文

Related Articles

Guida all'uso di Gemini CLI - Google AI nel tuo terminaleTutorial

Guida all'uso di Gemini CLI - Google AI nel tuo terminale

Guida completa per installare e configurare Gemini CLI, lo strumento AI open source a riga di comando di Google. Impara a configurare il proxy, usare gli strumenti integrati e automatizzare i flussi di lavoro con Gemini 2.5 Pro.

Jan 24
Come accedere a GPT-5 e GPT-5.2 via API - Guida completa per sviluppatoriTutorial

Come accedere a GPT-5 e GPT-5.2 via API - Guida completa per sviluppatori

Scopri come accedere ai più recenti modelli GPT-5, GPT-5.2 e o3-pro di OpenAI tramite un'unica API. Guida passo passo con esempi in Python, Node.js e curl.

Jan 23
I migliori generatori musicali AI 2026: confronto tra Suno, Udio e Stable AudioTutorial

I migliori generatori musicali AI 2026: confronto tra Suno, Udio e Stable Audio

Scegliere il giusto generatore musicale AI può essere complicato. Questa guida confronta i migliori strumenti di musica AI disponibili nel 2026

Jan 23