Distribuire Llama 3 Sull'edge Con Cloudflare Workers AI

Questo tutorial Cloudflare Workers AI mostra come distribuire ed eseguire modelli di machine learning direttamente sulla rete globale edge di Cloudflare. Con Cloudflare Workers AI , è possibile eseguire modelli linguistici di grandi dimensioni (LLMs), traduzioni di testi, generazioni di immagini e trascrizioni audio vicino ai tuoi utenti, senza dover gestire complessi server GPU. I passaggi seguenti illustrano come configurare Wrangler, scrivere un fetch handler, eseguire un modello Llama e ottimizzare i costi delle API all’edge.

TL;DR

• Eseguire modelli AI in modalità serverless ; Cloudflare Workers AI gestisce l’infrastruttura GPU sottostante e ti addebita solo la potenza di calcolo attiva.
• Configurare le associazioni (bindings) in wrangler.toml ; collega il tuo worker direttamente all’associazione AI senza dover gestire chiavi API.
• Scrivere un fetch handler per ricevere le richieste degli utenti, eseguire il modello e trasmettere risposte JSON in tempo reale (streaming).
• Selezionare modelli ottimizzati dal catalogo di Cloudflare (come Llama 3, Whisper o Stable Diffusion) per bilanciare velocità e precisione.
• Implementare limiti di frequenza per proteggere il tuo endpoint da abusi legati all’alto costo dei token in produzione.

Perché eseguire modelli AI all’edge?

Tradizionalmente, l’integrazione di funzionalità AI richiedeva la chiamata ad API esterne (come OpenAI) o l’hosting di modelli open source su costosi server cloud.

L’uso di API esterne presenta problemi di latenza e privacy dei dati. La gestione dei propri server GPU introduce sfide di manutenzione e una scalabilità complessa. Cloudflare Workers AI risolve questo dilemma. La piattaforma ospita modelli open source su GPU distribuite sulla rete globale di Cloudflare. Il tuo codice viene eseguito come un Worker leggero, eseguendo i modelli vicino ai tuoi utenti con una latenza quasi nulla. Per un’introduzione alla creazione di strutture edge di base, consulta la nostra guida su come creare un’API serverless con Cloudflare Workers .

Prerequisiti

Prima di iniziare, assicurati di avere a disposizione quanto segue:

• Un account Cloudflare con i Workers abilitati. Il piano gratuito include un’allocazione giornaliera per l’inferenza ampiamente sufficiente per seguire questa guida.
• Node.js 18 o più recente installato localmente, in modo da poter eseguire gli strumenti e il server di sviluppo locale.
• Wrangler, la CLI di Workers, installata e autenticata. Installala con npm install -g wrangler, quindi esegui wrangler login per collegarla al tuo account.
• Familiarità di base con JavaScript e il modello di richiesta/risposta fetch su cui si basa ogni Worker.

Se stai partendo da zero, crea un progetto con lo strumento create-cloudflare (C3). Genera un Worker pronto per la distribuzione, un file wrangler.toml e una data di compatibilità (compatibility_date) adatta:

1npm create cloudflare@latest my-edge-ai
2cd my-edge-ai

Scegli il modello Worker “Hello World” quando richiesto. Questo ti fornirà un punto di partenza pulito a cui aggiungere l’associazione AI nel passaggio successivo.

Passaggio 1: Configurazione di wrangler.toml

Per accedere ai modelli AI, devi prima definire l’associazione (binding) AI nel file di configurazione del tuo progetto.

Apri il tuo file wrangler.toml (o wrangler.json) e aggiungi il seguente blocco:

1[ai]
2binding = "AI"

Questa associazione rende disponibile il servizio AI sull’argomento dell’ambiente (env.AI) nel codice del tuo Worker. Non è necessario gestire chiavi API, configurare endpoint o gestire stringhe di connessione. Wrangler gestisce l’autenticazione automaticamente al momento della distribuzione.

Un file wrangler.toml completo per questo progetto si presenta così:

1name = "my-edge-ai"
2main = "src/index.js"
3compatibility_date = "2025-01-01"
4
5[ai]
6binding = "AI"

La data di compatibilità (compatibility_date) è fondamentale: fissa il comportamento del runtime in modo che future modifiche alla piattaforma non alterino silenziosamente l’esecuzione del tuo Worker. Se la ometti, la distribuzione fallirà con un errore di configurazione, uno degli ostacoli iniziali più comuni.

Passaggio 2: Scrittura del codice del Worker

Una volta configurata l’associazione, puoi chiamare il servizio AI dal tuo handler fetch. L’esempio seguente mostra come ricevere un payload JSON contenente un prompt dell’utente e generare un testo di completamento utilizzando Llama 3.

 1export default {
 2  async fetch(request, env) {
 3    if (request.method !== "POST") {
 4      return new Response("Method not allowed", { status: 405 });
 5    }
 6
 7    try {
 8      const { prompt } = await request.json();
 9      if (!prompt) {
10        return Response.json({ error: "Missing prompt" }, { status: 400 });
11      }
12
13      // Call the model using the AI binding
14      const response = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
15        prompt: prompt,
16        max_tokens: 256
17      });
18
19      return Response.json(response);
20    } catch (err) {
21      return Response.json({ error: err.message }, { status: 500 });
22    }
23  }
24};

Questa struttura semplice consente di creare sintetizzatori di testo, strumenti per l’analisi dei sentimenti o generatori di contenuti. Se desideri connettere queste funzionalità al tuo database, puoi connetterti a un database SQL serverless; vedi la configurazione del database Cloudflare D1 per i dettagli.

Utilizzo del formato dei messaggi di chat

Il campo prompt è comodo per completamenti singoli, ma i modelli conversazionali si comportano meglio con un array strutturato di messaggi (messages). Questo consente di impostare un’istruzione di sistema per definire il tono del modello e mantenerla separata dall’input dell’utente:

 1const messages = [
 2  { role: "system", content: "You are a concise technical assistant." },
 3  { role: "user", content: prompt }
 4];
 5
 6const response = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
 7  messages,
 8  max_tokens: 512
 9});
10
11// Text models return the generated text on the `response` property
12return Response.json({ answer: response.response });

Nota che i modelli di generazione del testo racchiudono il loro output in un campo response, pertanto il testo completato si trova in response.response e non a livello principale. Questo dettaglio confonde molti nuovi utenti, che visualizzano l’oggetto grezzo e notano una struttura inattesa.

Scelta del modello corretto

Il catalogo di Cloudflare include decine di modelli e la scelta corretta è un compromesso tra velocità, qualità e costo. I modelli più piccoli rispondono più velocemente e consumano meno risorse; i modelli più grandi ragionano meglio ma costano di più per richiesta. La tabella seguente confronta alcune opzioni popolari per la generazione di testo.

Come regola generale, inizia con un modello 8B come Llama 3 8B Instruct. Gestisce la maggior parte dei carichi di lavoro di sintesi, classificazione e chat a una frazione della latenza e del costo di un modello 70B. Passa a un modello più grande solo quando le tue valutazioni dimostrano che quello più piccolo è realmente insufficiente.

Passaggio 3: Streaming delle risposte per una migliore esperienza utente

Nelle applicazioni di chat, attendere la generazione completa della risposta può tradursi in una scarsa esperienza utente.

È possibile configurare l’associazione AI per trasmettere (stream) la risposta token per token durante la sua generazione. Per fare ciò, passa stream: true nelle opzioni della richiesta. Il Worker restituirà un ReadableStream che potrai inviare direttamente al client browser, creando un’interfaccia di chat fluida e interattiva. Per confrontare questo approccio di runtime all’edge con l’hosting cloud tradizionale, leggi il nostro confronto tra Cloudflare Workers e AWS Lambda .

Ecco un handler di streaming completo. Invece di restituire JSON analizzato, trasmetti direttamente lo stream al client con il corretto content-type in modo che il browser possa consumarlo come Server-Sent Events:

 1export default {
 2  async fetch(request, env) {
 3    const { prompt } = await request.json();
 4
 5    const stream = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
 6      prompt,
 7      max_tokens: 512,
 8      stream: true
 9    });
10
11    return new Response(stream, {
12      headers: { "content-type": "text/event-stream" }
13    });
14  }
15};

La differenza fondamentale rispetto alla versione senza streaming risiede nella risposta stessa: passi il flusso direttamente in new Response() e imposti il content-type su text/event-stream. Se racchiudi lo stream in un Response.json(), non verrà serializzato correttamente e il client riceverà un corpo vuoto.

Testare e distribuire il Worker

Una volta posizionati associazione e handler, esegui il Worker localmente prima di distribuirlo:

1npx wrangler dev

Poiché l’inferenza viene eseguita sulle GPU di Cloudflare e non sulla tua macchina locale, l’associazione AI contatta la rete anche durante lo sviluppo locale. Wrangler gestisce questo per te, ma significa che i test locali richiedono una connessione attiva e una sessione di accesso valida.

Invia una richiesta di test con curl mentre wrangler dev è in esecuzione:

1curl -X POST http://localhost:8787 \
2  -H "Content-Type: application/json" \
3  -d '{"prompt": "Summarise the benefits of edge computing in one sentence."}'

Quando sei soddisfatto dell’output, distribuisci sulla rete globale:

1npx wrangler deploy

Wrangler carica il tuo Worker e restituisce un URL *.workers.dev. Il tuo endpoint è ora attivo in ogni data center di Cloudflare e ogni richiesta viene instradata automaticamente alla posizione più vicina all’utente.

Errori comuni e risoluzione dei problemi

Ecco alcuni dei problemi più frequenti che si verificano quando le organizzazioni distribuiscono per la prima volta l’inferenza all’edge. Conoscere in anticipo la soluzione consente di risparmiare ore di debug.

• Cannot read properties of undefined (reading 'run') – l’associazione env.AI non è definita. Questo significa quasi sempre che il blocco [ai] manca nel file wrangler.toml, o che hai modificato il file senza riavviare wrangler dev (o senza ridistribuire). Verifica che il nome dell’associazione corrisponda esattamente.
• No such model o errore 400 su run – l’identificatore del modello è errato. I nomi dei modelli fanno distinzione tra maiuscole e minuscole e devono includere il percorso completo, ad esempio @cf/meta/llama-3-8b-instruct. Copiali dal catalogo dei modelli anziché digitarli a memoria.
• Risposte in streaming vuote o malformate – hai restituito lo stream tramite Response.json() anziché con new Response(stream, ...). I flussi devono essere trasmessi direttamente, non serializzati.
• Errori di capacità o errori 429 sotto carico – il modello è temporaneamente sovraccarico o hai raggiunto un limite dell’account. Aggiungi un breve meccanismo di tentativo (retry) con temporizzazione e considera un modello più piccolo per gestire i picchi di traffico.
• Risposte troncate – la risposta si interrompe a metà frase perché max_tokens è impostato su un valore troppo basso. Aumenta il limite, tenendo presente che valori più elevati aumentano sia la latenza che il costo.

Se una richiesta fallisce senza messaggi di errore, controlla i log in tempo reale con npx wrangler tail mentre invii una richiesta di test. Visualizza gli errori di runtime e gli output di console.log del Worker distribuito.

Ottimizzazione dei costi di produzione e della sicurezza

Sebbene Workers AI sia molto economico, l’esecuzione di inferenze di modelli in produzione richiede controlli accurati.

• Implementare limiti di frequenza (Rate Limiting): Limita la frequenza con cui un client può chiamare il tuo endpoint. I costi di calcolo GPU aumentano proporzionalmente all’uso.
• Sanificare i prompt: Valuta gli input per prevenire attacchi di prompt injection e assicurarti che gli output del modello rimangano in linea con l’immagine aziendale.
• Limitare le dimensioni del contesto: Mantieni brevi le cronologie dei prompt. L’invio di enormi volumi di contesto a ogni chiamata aumenta i costi di elaborazione dei token.

Per un’analisi dettagliata della gestione del contesto, consulta la nostra guida su come creare un chatbot con l’API OpenAI .

Punti chiave da considerare

• Cloudflare Workers AI fornisce accesso serverless a modelli open source senza manutenzione di server GPU.
• Configura l’accesso aggiungendo il blocco di associazione [ai] nel tuo file wrangler.toml.
• Scrivi fetch handler per eseguire la generazione di testo, traduzioni o immagini direttamente all’edge.
• Abilita lo streaming di token con stream: true per ottimizzare l’esperienza su dispositivi mobili e nelle app di chat.
• Implementa limiti di frequenza e sanificazione dei prompt per proteggere i tuoi endpoint edge in produzione.

Costruisci le tue applicazioni AI all’edge

La creazione di integrazioni AI affidabili richiede una profonda conoscenza dell’architettura serverless. Mecanik è specializzato nei servizi di integrazione AI e nelle configurazioni di API personalizzate tramite il nostro servizio di integrazione delle API OpenAI . Sviluppiamo strumenti nativi dell’edge in grado di scalare in modo trasparente, ottimizzando i costi e l’esperienza dell’utente. Contatta i nostri esperti oggi stesso per discutere del tuo progetto.

Domande frequenti (FAQ)

Che cos’è Cloudflare Workers AI? Si tratta di una piattaforma serverless che consente di eseguire modelli di machine learning (generazione di testo, traduzione, speech-to-text, generazione di immagini) sulla rete globale di GPU di Cloudflare.

Ho bisogno di una chiave API per utilizzare Workers AI? No. Una volta dichiarata l’associazione AI nel file wrangler.toml, Cloudflare gestisce le credenziali internamente, rendendo il servizio accessibile tramite env.AI.

Quali modelli sono disponibili su Cloudflare Workers AI? La piattaforma ospita popolari modelli open source, tra cui Meta Llama, Mistral, OpenAI Whisper e Stable Diffusion, che vengono regolarmente aggiornati nel catalogo dei modelli.

Posso trasmettere in streaming risposte di testo da Workers AI? Sì. Impostando stream: true nei parametri della chiamata env.AI.run, il Worker restituisce un ReadableStream standard per inviare il testo al browser in tempo reale.

Come funziona la fatturazione per Workers AI? La fatturazione si basa sul numero di token elaborati (per i modelli di testo) o sulla durata del tempo di calcolo (per altri modelli), offrendo un modello a consumo molto conveniente.