Deixa de rebre errors! Configura fàcilment l'URL base i l'API de Cloudflare per a la compatibilitat amb OpenAI.

Per què la meva URL base d' IA de Cloudflare sempre retorna un error 404?

Aquest article t'ensenya en segons com obtenir i configurar ràpidament una URL base d'OpenAI compatible amb Cloudflare. Inclou plantilles perfectes per a l'API REST oficial, el format AI Gateway i clients de tercers (Dify/One-API), cosa que t'ajuda a posar en funcionament API d'IA gratuïtes amb un sol clic!

La setmana passada, un amic que fa desenvolupament independent es va posar en contacte amb mi de sobte i em va enviar una captura de pantalla que mostrava una pantalla plena d'errors 401. Em va dir: "Germà, he estat intentant depurar l'API d'IA de Cloudflare tot el dia, però no funciona".

Vaig fer una ullada al seu codi. L'URL base estava configurada com a /ai/v1, però el cos de la sol·licitud estava formatat com a l'API REST oficial, de manera que les dues no coincidien en absolut.

Va dir que només volia utilitzar l'SDK d'OpenAI per depurar un model a Workers AI, hi ha algun problema?

Això és un gran problema.

Els serveis d'IA de Cloudflare utilitzen tres URL base completament diferents segons l'escenari. Cadascun té el seu propi format i escenaris aplicables. Tot i que hi ha documentació, està dispersa per diferents pàgines, cosa que dificulta saber a quina consultar en el primer intent. L'ús d'una URL incorrecta provocarà un error 401 o 400, que us impedirà accedir al servei.

Quan vaig tenir aquest problema per primera vegada, ho vaig intentar diverses vegades abans de resoldre'l. Em vaig quedar sense paraules mirant la pantalla plena de missatges d'error.

Avui us dibuixaré clarament aquests tres camins, perquè no cometeu més errors després de llegir això.

URL base de la interfície compatible amb OpenAI

Comencem amb el més utilitzat.

Si feu servir l'SDK d'OpenAI o eines que admeten formats personalitzats d'OpenAI com ara LangChain, Dify, NextChat o One-API, aquest és l'enfocament correcte.

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

Això és una cosa que Cloudflare ha dissenyat específicament per alinear-se amb el format d'interfície OpenAI. Afegeix `/chat/completions` després del punt final del diàleg complet. Substitueix l'URL base original d'OpenAI per aquesta i substitueix la clau API pel teu token de Cloudflare, i hauria d'executar-se directament. He provat models com `@cf/deepseek-ai/deepseek-r1-distill-qwen-32b` i `@cf/meta/llama-3.1-8b-instruct`, i tots funcionen bé.

Tanmateix, cal tenir en compte que això només admet models de diàleg basats en text.

API REST nativa oficial de Cloudflare

Si necessiteu utilitzar Stable Diffusion per a la creació de gràfics, Whisper per a la transcripció d'àudio o qualsevol model que no sigui textual, trieu la segona ruta, que és l'API REST nativa oficial de Cloudflare.

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

El nom del model es pot escriure a la ruta, com ara /ai/run/@cf/bytedance/stable-diffusion-xl-lightning, o es pot col·locar al camp `model` del cos de la sol·licitud. Prefereixo posar-lo al camp; la ruta és més curta i neta. Al principi també em va confondre aquest detall. Alguns models accepten els dos mètodes, mentre que d'altres només n'accepten un. Presteu atenció a això quan consulteu la documentació.

URL base de la passarel·la d'IA

Hi ha una tercera via: AI Gateway.

Aquest escenari és lleugerament diferent. Si heu configurat una passarel·la d'IA al backend de Cloudflare per intermediar API de tercers, com ara reenviar sol·licituds d'OpenAI a través de la passarel·la de Cloudflare per a l'emmagatzematge en memòria cau, la supervisió i la limitació de velocitat, l'URL base seria...

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

Afegir `/chat/completions` després del punt final complet garanteix que tot el trànsit passi per la passarel·la de Cloudflare, i el panell de registre mostra la latència i el resultat de cada sol·licitud. Aquesta funció és increïblement útil a mesura que l'equip creix amb més projectes, eliminant la necessitat de cercar dades dels backends de diversos proveïdors un per un.

Com triar: Tres conjunts d'URL explicats en una frase.

D'acord, això cobreix els tres camins. En resum, només hi ha un principi.

El camí que tries depèn de les eines que fas servir.

Per utilitzar l'SDK d'OpenAI per cridar un model de diàleg, aneu a `/ai/v1`. Per cridar un model d'imatge/àudio, aneu a `/ai/run`. Per a una gestió unificada a través d'una passarel·la, aneu a `/gateway/`. El mètode d'autenticació és el mateix: poseu `Authorization: Bearer` seguit del vostre token d'API a la capçalera. Creeu el token al backend de Cloudflare i recordeu de comprovar el permís `Workers AI: Edit`.

On puc trobar l'identificador account_id? Inicieu la sessió al tauler d'administració de Cloudflare, desplaceu-vos cap avall fins a la secció API de la barra lateral dreta o consulteu la barra d'adreces del navegador; aquesta cadena alfanumèrica de 32 caràcters és la que trobareu.

Sincerament, després d'ajudar el meu amic a fer-ho aquell dia, em va dir una cosa que crec que té força raó: no era que no sabés com, sinó que la documentació no m'ho havia explicat clarament.

Moltes configuracions tècniques són així. No és que siguin particularment difícils, però hi ha massa punts d'entrada, cosa que fa que sigui fàcil perdre's al primer intent. Si heu trobat diversos errors inexplicables en configurar Cloudflare AI, el més probable és que sigui degut a una URL base incorrecta o a un format incorrecte. Tingueu a mà aquests tres conjunts d'URL; podreu trobar fàcilment la correcta la propera vegada.

De benvingut.

Així doncs, ja que heu llegit fins aquí, si us ha semblat útil, feu-li un "m'agrada" i compartiu-ho. Si voleu rebre actualitzacions primer, també em podeu seguir! ⭐

Gràcies per llegir el meu article. Fins la propera.