Basta con gli errori! Configura facilmente l'URL di base e l'API di Cloudflare per la compatibilità con OpenAI.

Cloudflare AI Perché l'URL di base restituisce sempre un errore 404?

Questo articolo ti insegna in pochi secondi come ottenere e configurare rapidamente un URL di base OpenAI compatibile con Cloudflare. Include modelli perfetti per le API REST ufficiali, il formato AI Gateway e client di terze parti (Dify/One-API), aiutandoti ad avviare API AI gratuite con un solo clic!

La settimana scorsa, un amico che lavora come sviluppatore indipendente mi ha contattato all'improvviso e mi ha mandato uno screenshot che mostrava una schermata piena di errori 401. Mi ha detto: "Fratello, ho provato a fare il debug dell'API AI di Cloudflare tutto il giorno, ma proprio non funziona."

Ho dato un'occhiata al suo codice. L'URL di base era impostato su /ai/v1, ma il corpo della richiesta era formattato come l'API REST ufficiale, quindi i due non corrispondevano affatto.

Ha detto che voleva semplicemente usare l'SDK di OpenAI per eseguire il debug di un modello su Workers AI, c'è qualche problema?

Questo è un grosso problema.

I servizi di intelligenza artificiale di Cloudflare utilizzano tre URL di base completamente diversi a seconda dello scenario. Ognuno ha un formato e degli scenari di applicazione specifici. Sebbene esista una documentazione, è frammentata in diverse pagine, il che rende difficile capire a quale fare riferimento al primo tentativo. L'utilizzo dell'URL errato comporterà un errore 401 o 400, impedendo l'accesso al servizio.

Quando mi sono imbattuto per la prima volta in questo problema, ho provato diverse volte prima di riuscire a risolverlo. Sono rimasto senza parole di fronte allo schermo pieno di messaggi di errore.

Oggi vi illustrerò chiaramente queste tre strade, così che dopo aver letto questo non commetterete più errori.

URL di base dell'interfaccia compatibile con OpenAI

Iniziamo con quello più comunemente usato.

Se stai utilizzando l'SDK OpenAI o strumenti che supportano formati OpenAI personalizzati come LangChain, Dify, NextChat o One-API, allora questo è l'approccio corretto.

https://api.cloudflare.com/client/v4/accounts/{你的account_id}/ai/v1

Questa è una funzionalità che Cloudflare ha specificamente progettato per essere compatibile con il formato dell'interfaccia OpenAI. Aggiungi `/chat/completions` dopo l'endpoint del dialogo completo. Sostituisci l'URL di base OpenAI originale con questo e sostituisci la chiave API con il tuo token Cloudflare; a quel punto dovrebbe funzionare correttamente. Ho provato modelli come `@cf/deepseek-ai/deepseek-r1-distill-qwen-32b` e `@cf/meta/llama-3.1-8b-instruct` e funzionano tutti senza problemi.

Tuttavia, va notato che questo supporta solo modelli di dialogo basati su testo.

API REST nativa ufficiale di Cloudflare

Se devi utilizzare Stable Diffusion per la creazione di grafici, Whisper per la trascrizione audio o qualsiasi altro modello non testuale, scegli la seconda opzione, ovvero l'API REST nativa ufficiale di Cloudflare.

https://api.cloudflare.com/client/v4/accounts/{你的account_id}/ai/run

Il nome del modello può essere scritto nel percorso, ad esempio /ai/run/@cf/bytedance/stable-diffusion-xl-lightning, oppure può essere inserito nel campo `model` del corpo della richiesta. Preferisco inserirlo nel campo; il percorso è più breve e pulito. Anche io all'inizio ero confuso su questo dettaglio. Alcuni modelli accettano entrambi i metodi, mentre altri ne accettano solo uno. Presta attenzione a questo aspetto quando consulti la documentazione.

URL di base del gateway AI

Esiste una terza via: AI Gateway.

Questo scenario è leggermente diverso. Se hai configurato un AI Gateway nel backend di Cloudflare per fungere da proxy per le API di terze parti, ad esempio inoltrando le richieste OpenAI attraverso il gateway di Cloudflare per la memorizzazione nella cache, il monitoraggio e la limitazione della frequenza, l'URL di base sarebbe...

https://gateway.ai.cloudflare.com/v1/{你的account_id}/{你的gateway_id}/openai

Aggiungendo `/chat/completions` dopo l'endpoint di completamento, si garantisce che tutto il traffico passi attraverso il gateway di Cloudflare e il pannello dei log mostra la latenza e il risultato di ogni richiesta. Questa funzionalità è incredibilmente utile man mano che il team cresce con più progetti, eliminando la necessità di cercare singolarmente i dati provenienti dai backend di diversi fornitori.

Come scegliere: Tre serie di URL spiegate in una frase.

Bene, questo copre i tre percorsi. In sintesi, c'è un solo principio.

Il percorso che intraprenderete dipenderà dagli strumenti che utilizzerete.

Per utilizzare l'SDK OpenAI per richiamare un modello di dialogo, vai a `/ai/v1`. Per richiamare un modello di immagine/audio, vai a `/ai/run`. Per la gestione unificata tramite un gateway, vai a `/gateway/`. Il metodo di autenticazione è lo stesso: inserisci `Authorization: Bearer` seguito dal tuo token API nell'intestazione. Crea il token nel backend di Cloudflare e ricorda di selezionare l'autorizzazione `Workers AI: Edit`.

Dove trovare l'account_id? Accedi al pannello di amministrazione di Cloudflare, scorri verso il basso fino alla sezione API nella barra laterale destra oppure controlla la barra degli indirizzi del tuo browser; quella stringa alfanumerica di 32 caratteri è proprio quella.

Onestamente, dopo aver aiutato il mio amico a completare la procedura quel giorno, mi ha detto una cosa che credo sia assolutamente giusta: non è che non sapessi come fare, è che la documentazione non me l'aveva spiegato chiaramente.

Molte configurazioni tecniche sono così. Non che siano particolarmente difficili, ma ci sono troppi punti di accesso, il che rende facile perdersi al primo tentativo. Se hai riscontrato vari errori inspiegabili durante la configurazione di Cloudflare AI, molto probabilmente è dovuto a un URL di base errato o a un formato non corretto. Tieni a portata di mano questi tre set di URL; la prossima volta potrai trovare facilmente quello corretto.

Prego.

Quindi, visto che sei arrivato a leggere fin qui, se hai trovato utile questo articolo, metti mi piace e condividilo. Se vuoi ricevere gli aggiornamenti in anteprima, puoi anche seguirmi! ⭐

Grazie per aver letto il mio articolo. Alla prossima.