7Scegliere il modello: online o sul tuo computer

Ogni agente di CrewAI ragiona grazie a un LLMLLM: Large Language Model, grande modello linguistico: un programma addestrato su enormi quantità di testo che, data una frase, prevede le parole che seguono. È il motore di ChatGPT, Claude, Gemini. glossario: senza, la squadra ha il nome, il ruolo e i compiti, ma non ha il cervello. Scegliere il ModelloModello: Il file (o il servizio online) che contiene un LLM già addestrato. Ogni modello ha un nome, per esempio gpt-4o o qwen2.5:7b. glossario è come decidere come spostarsi in città: puoi chiamare un taxi (paghi a corsa, arrivi veloce, ma qualcun altro guida e sa dove vai) oppure usare la tua bicicletta (gratis e privata, ma più lenta e fai tu la fatica).

In questo capitolo vedi le due famiglie di modelli, impari a gestire le chiavi e le impostazioni senza metterle nel codice, e installi Ollama per usare un modello gratuito sul tuo computer. È la configurazione che il corso usa per tutti gli output reali che vedrai.

Online o sul tuo computer#

I modelli online girano sui server di un ProviderProvider: L'azienda o il servizio che offre il modello: OpenAI, Anthropic, Google, oppure Ollama sul tuo computer. In CrewAI si scrive come prefisso: openai/gpt-4o. glossario. Tre dei più noti, tutti supportati direttamente dal framework, sono OpenAI (i modelli GPT), Anthropic (i modelli Claude) e Google (i modelli Gemini). Il tuo script manda la richiesta via internet attraverso l'APIAPI: Application Programming Interface: una "porta" con regole precise attraverso cui un programma chiede un servizio a un altro. I modelli online si usano via API. glossario del provider e riceve la risposta. Paghi in base ai TokenToken: Il pezzetto di testo con cui ragiona un modello: una parola corta, un pezzo di parola o un segno di punteggiatura. Secondo le stime di OpenAI, in inglese un token vale in media circa ¾ di parola. I servizi a pagamento contano (e fanno pagare) i token. glossario usati.

Un modello localeModello locale: Un modello che gira sul tuo computer invece che sui server di un'azienda. Privacy e costo zero, ma di solito più lento e meno capace. glossario invece gira sul tuo computer. Il programma più semplice per farlo è OllamaOllama: Programma gratuito che scarica ed esegue modelli linguistici sul tuo computer, senza chiavi e senza costi a consumo. glossario: scarica il modello una volta, poi risponde senza internet, senza chiavi e senza costi a consumo. Il prezzo lo paga il tuo computer, in tempo di calcolo e memoria.

Nessuna delle due strade è migliore in assoluto. Ecco il confronto in sintesi:

La chiave API#

Per usare un modello online il provider deve sapere chi sei e a chi addebitare i costi. Per questo ti dà una chiave APIChiave API: Una lunga password personale che identifica chi usa un'API e a chi addebitare i costi. Va tenuta segreta: mai pubblicarla o condividerla. glossario: una lunga sequenza di caratteri che il tuo script invia insieme a ogni richiesta. È come la tessera di un distributore di carburante: chi la possiede fa il pieno a tuo nome.

Il percorso per ottenerla è simile per tutti i provider:

1. Crei un account nella console per sviluppatori del provider, cioè il sito riservato a chi programma (non è lo stesso abbonamento della chat per il pubblico: si pagano separatamente).
2. Aggiungi, se richiesto, un metodo di pagamento o del credito prepagato.
3. Nella sezione delle chiavi crei una chiave nuova, le dai un nome che ricordi a cosa serve (per esempio «corso-crewai») e la copi subito in un posto sicuro.

Dove si trovano le pagine ufficiali:

Il corso non riporta prezzi: cambiano spesso e dipendono dal modello. Controllali sulle pagine ufficiali prima di iniziare. Tieni presente che una crew fa molte richieste per un solo lavoro (ogni agente può ragionare in più giri), quindi consuma più token di una singola domanda in chat.

Variabili d'ambiente e file .env#

Se la chiave non va nel codice, dove la metti? In una variabile d'ambienteVariabile d'ambiente: Un valore con un nome (per esempio OPENAI_API_KEY) che i programmi leggono dal sistema invece che dal codice. Serve a tenere i segreti fuori dai file di codice. glossario: un valore con un nome che il sistema passa al programma quando parte. Il codice chiede «dammi il valore di OPENAI_API_KEY» senza sapere quale sia. Così lo stesso script funziona per te con la tua chiave e per un collega con la sua, e puoi condividerlo senza rischi.

Scrivere le variabili a mano in ogni terminale sarebbe scomodo. Per questo si usa un file .envFile .env: File di testo nella cartella del progetto con le variabili d'ambiente, una per riga: NOME=valore. Non va mai condiviso né caricato online. glossario: un file di testo nella cartella di progetto, con una variabile per riga. Quando lanci uv run --env-file .env nome.py, uv legge il file e passa le variabili allo script. Le regole del formato sono poche:

• Una variabile per riga, nella forma NOME=valore. Il nome si scrive in maiuscolo, come vuole la documentazione.
• Scrivi il valore subito dopo l'uguale, senza virgolette e senza spazi: è la forma che tutti i programmi capiscono.
• Le righe che iniziano con # sono commenti; le righe vuote vengono ignorate.

MODEL e il prefisso del provider#

La variabile più importante per CrewAI è MODEL. Il suo valore ha sempre la forma provider/modello: prima il nome del provider in minuscolo, poi una barra, poi il nome del modello. Scrivilo sempre: la documentazione indica openai/gpt-4 come corretto e gpt-4 come sbagliato. È il prefisso che dice a CrewAI a chi mandare la richiesta: senza, CrewAI prova a indovinare dal nome, e per esempio qwen2.5:7b senza ollama/ finirebbe a OpenAI (verificato con CrewAI 1.15.21).

Ecco un .env per OpenAI. openai/gpt-4.1-mini è il modello che CrewAI 1.15.21 usa quando non ne indichi nessuno, ed è quello predefinito negli script del corso.

# Modello: provider/nome-del-modello
MODEL=openai/gpt-4.1-mini
# La tua chiave personale (questa è finta)
OPENAI_API_KEY=sk-la-tua-chiave
# Niente dati di utilizzo a CrewAI (capitolo 6)
CREWAI_DISABLE_TELEMETRY=true

Per Anthropic e per Google cambiano il prefisso, il nome del modello e il nome della variabile con la chiave. I nomi dei modelli qui sotto sono quelli usati negli esempi della documentazione di CrewAI; i provider ne pubblicano di nuovi spesso, quindi controlla l'elenco aggiornato nella loro documentazione.

MODEL=anthropic/claude-sonnet-4-6
ANTHROPIC_API_KEY=sk-ant-la-tua-chiave
CREWAI_DISABLE_TELEMETRY=true

MODEL=gemini/gemini-3.6-flash
GEMINI_API_KEY=la-tua-chiave
CREWAI_DISABLE_TELEMETRY=true

Anthropic e Gemini vogliono un pacchetto in più#

OpenAI è incluso in CrewAI. Per Anthropic e Gemini, invece, serve un'aggiunta al pacchetto. Se la dimentichi, appena CrewAI prova a usare il modello ricevi un errore come questi, ottenuti davvero con CrewAI 1.15.21:

ImportError: Anthropic native provider not available, to install: uv add "crewai[anthropic]"
ImportError: Google Gen AI native provider not available, to install: uv add "crewai[google-genai]"

Il messaggio suggerisce uv add, che vale per i progetti completi. Negli script del corso basta aggiungere il nome tra le parentesi quadre nell'intestazione, separato da una virgola. Per Anthropic la riga delle dipendenze diventa così (per Gemini scrivi google-genai al posto di anthropic):

# /// script
# requires-python = ">=3.10,<3.14"
# dependencies = ["crewai[tools,anthropic]==1.15.21"]
# ///

Alla prossima esecuzione uv scarica anche il pacchetto di Anthropic e l'errore sparisce. Lo abbiamo verificato con entrambe le aggiunte: CrewAI crea il collegamento al modello senza errori.

Tenere il .env fuori dai guai#

Il file .env contiene i tuoi segreti, quindi non deve mai finire online. Il rischio più comune è pubblicare la cartella del progetto su GitHub con Git, il programma che tiene la storia delle versioni dei file. Per evitarlo si crea nella cartella un file .gitignore.gitignore: File di testo con l'elenco dei file che Git non deve salvare né pubblicare. Ci si scrive .env perché le chiavi non finiscano online per sbaglio. glossario con l'elenco dei file da escludere. Anche se oggi non usi Git, crearlo costa dieci secondi:

# file con chiavi e impostazioni personali: non va mai pubblicato
.env

Se vuoi condividere il progetto con qualcuno, puoi aggiungere un file .env.example con gli stessi nomi di variabile ma valori finti: così l'altra persona sa cosa deve compilare.

Ollama passo passo#

Ora la strada gratuita. Tutti gli output reali di questo corso sono stati prodotti così, con Ollama e i modelli qwen2.5:7b e qwen2.5:3b, su un computer senza scheda video.

1. Installa Ollama#

Vai su ollama.com/download e scegli il tuo sistema. Per macOS e Windows scarichi un normale programma di installazione, da aprire e seguire. Per Linux la pagina mostra un comando da incollare nel terminale.

# solo Linux: il comando mostrato sulla pagina ufficiale
curl -fsSL https://ollama.com/install.sh | sh

Dopo l'installazione Ollama resta attivo in sottofondo e aspetta richieste sul tuo computer all'indirizzo http://localhost:11434. Per controllarlo apri quell'indirizzo nel browser: deve comparire la scritta Ollama is running. Se non compare, avvia l'app Ollama (su macOS e Windows) oppure, su Linux, lancia ollama serve in un terminale e lascialo aperto.

2. Scarica il modello#

Ollama da solo è un motore senza carburante: devi scaricare un modello. Questo comando scarica qwen2.5:7b, un modello da circa 7 miliardi di parametri (i numeri interni che il modello ha imparato durante l'addestramento). Pesa 4,7 GB, quindi il download richiede un po' di tempo. Il comando è uguale su tutti i sistemi:

# scarica il modello qwen2.5 nella versione da 7 miliardi di parametri
ollama pull qwen2.5:7b

# scarica il modello qwen2.5 nella versione da 7 miliardi di parametri
ollama pull qwen2.5:7b

Quando ha finito, ollama list (anche questo uguale ovunque) mostra i modelli presenti. Questo è l'output reale sul computer del corso, dove oltre al 7b c'è la versione più piccola qwen2.5:3b e un modello di servizio che userai più avanti:

NAME                       ID              SIZE      MODIFIED
nomic-embed-text:latest    0a109f422b47    274 MB    19 seconds ago
qwen2.5:7b                 845dbda0ea48    4.7 GB    12 minutes ago
qwen2.5:3b                 357c53fb659c    1.9 GB    25 minutes ago

3. Scrivi il .env#

Con Ollama non c'è nessuna chiave: basta il modello, con il prefisso ollama/ seguito dal nome esatto che vedi in ollama list.

# Modello locale servito da Ollama: nessuna chiave necessaria
MODEL=ollama/qwen2.5:7b
CREWAI_DISABLE_TELEMETRY=true

La documentazione di CrewAI, nella sezione su Ollama, dice di installare anche l'aggiunta crewai[litellm] e di indicare l'indirizzo http://localhost:11434. Con CrewAI 1.15.21 abbiamo verificato che non serve nessuna delle due cose: un crew completo gira con MODEL=ollama/qwen2.5:7b e il pacchetto normale, perché CrewAI conosce già l'indirizzo predefinito di Ollama. Se con una versione diversa ricevi errori che nominano litellm, aggiungi litellm tra le parentesi quadre dell'intestazione, come hai fatto sopra per Anthropic.

I limiti dei modelli locali piccoli#

Gratis non vuol dire senza compromessi. Un modello che sta in 5 GB è molto più piccolo di quelli dei provider online, e si vede:

• Lentezza sul processore. Senza una scheda video adatta il modello gira sul processore. Sul computer usato per il corso qwen2.5:7b produce circa 2–4 token al secondo, e un crew breve richiede dai 5 ai 15 minuti. Un modello online di solito fa lo stesso lavoro molto più in fretta.
• Più allucinazioniAllucinazione: Quando un modello scrive con sicurezza una cosa falsa o inventata. Succede perché il modello genera testo plausibile, non verifica fatti. glossario. I modelli piccoli inventano più facilmente fatti, nomi e luoghi, con la stessa sicurezza con cui scrivono cose vere. Nel capitolo 8 vedrai un output reale sbagliato, prodotto da qwen2.5:3b, e impareremo a riconoscerlo.
• Istruzioni seguite peggio. Nella stessa prova il modello da 3 miliardi di parametri ha risposto in spagnolo invece che in italiano. Per questo gli script del corso chiedono esplicitamente «in italiano» nel risultato atteso.

Un buon compromesso: impara e prova con Ollama, poi passa a un modello online quando ti serve un risultato di qualità. Grazie al file .env basta cambiare una riga.

Il rate limit#

I provider online non accettano richieste all'infinito. Ogni account ha un rate limitRate limit: Il limite di richieste al minuto imposto da un provider. Superarlo dà errori temporanei. In CrewAI si rispetta con max_rpm. glossario: un numero massimo di richieste, o di token, al minuto. Se lo superi, il provider risponde con un errore temporaneo invece che con la risposta. Succede più facilmente con gli account nuovi o gratuiti, che hanno limiti più bassi, e con le crew, che mandano molte richieste di fila.

Come si evita: CrewAI permette di fissare un tetto di richieste al minuto con l'impostazione max_rpm, sul singolo agente o su tutta la crew (la vedrai nei capitoli sugli agenti e sulle crew). I limiti precisi del tuo account sono descritti nelle pagine ufficiali di OpenAI, Anthropic e Google Gemini. Con Ollama il problema non esiste: l'unico limite è la velocità del tuo computer.

Il computer è pronto e il modello è scelto: nel prossimo capitolo scrivi e lanci il tuo primo crew.

Corso indipendente, non affiliato a CrewAI Inc. Contenuti verificati su CrewAI 1.15.21 il 15 settembre 2026.