Déployer Llama 3 en Périphérie Avec Cloudflare Workers AI

Ce tutoriel Cloudflare Workers AI vous montre comment déployer et exécuter des modèles de machine learning directement sur le réseau edge mondial de Cloudflare. Avec Cloudflare Workers AI , vous pouvez exécuter des modèles de langage (LLMs), de la traduction de texte, de la génération d’images et de la transcription audio au plus près de vos utilisateurs, sans avoir à gérer des serveurs GPU complexes. Les étapes ci-dessous décrivent comment configurer Wrangler, écrire un handler de fetch, exécuter un modèle Llama et optimiser les coûts de vos API à l’edge.

TL;DR

• Exécuter des modèles d’IA en serverless ; Cloudflare Workers AI gère l’infrastructure GPU sous-jacente et ne vous facture que la puissance de calcul active.
• Configurer les liaisons (bindings) dans wrangler.toml ; associez votre worker directement à la liaison AI sans avoir à gérer des clés d’API.
• Écrire un handler de fetch pour recevoir les requêtes des utilisateurs, exécuter le modèle et renvoyer des réponses JSON sous forme de flux (stream).
• Sélectionner des modèles optimisés parmi le catalogue de Cloudflare (comme Llama 3, Whisper ou Stable Diffusion) pour équilibrer vitesse et précision.
• Mettre en place des limites de débit pour protéger votre point de terminaison (endpoint) contre les abus de coûts de tokens en production.

Pourquoi exécuter des modèles d’IA à l’edge ?

Traditionnellement, l’intégration de fonctionnalités d’IA nécessitait d’appeler des API externes (comme OpenAI) ou d’héberger des modèles open source sur de coûteux serveurs cloud.

L’appel d’API externes pose des problèmes de latence et de confidentialité des données. Gérer vos propres serveurs GPU introduit des défis de maintenance et passe difficilement à l’échelle. Cloudflare Workers AI résout ce dilemme. La plateforme héberge des modèles open source sur des GPU déployés sur le réseau mondial de Cloudflare. Votre code s’exécute sous la forme d’un Worker léger, exécutant les modèles au plus près de vos utilisateurs avec une latence quasi nulle. Pour une introduction à la création de structures edge de base, consultez notre guide sur la création d’une API serverless avec Cloudflare Workers .

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

• Un compte Cloudflare avec les Workers activés. Le plan gratuit comprend une allocation d’inférence quotidienne amplement suffisante pour suivre ce guide.
• Node.js 18 ou plus récent installé localement pour exécuter les outils et le serveur de développement local.
• Wrangler, le CLI des Workers, installé et authentifié. Installez-le avec npm install -g wrangler, puis lancez wrangler login pour l’associer à votre compte.
• Une familiarité de base avec JavaScript et le modèle de requête/réponse fetch sur lequel repose chaque Worker.

Si vous partez d’une page blanche, générez un projet avec l’outil create-cloudflare (C3). Il génère un Worker prêt à être déployé, un fichier wrangler.toml et une date de compatibilité (compatibility_date) cohérente :

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

Choisissez le modèle de Worker “Hello World” lorsque vous y êtes invité. Cela vous donne un point de départ propre auquel vous pourrez ajouter le binding AI à l’étape suivante.

Étape 1 : Configurer wrangler.toml

Pour accéder aux modèles d’IA, vous devez d’abord définir la liaison (binding) AI dans le fichier de configuration de votre projet.

Ouvrez votre fichier wrangler.toml (ou wrangler.json) et ajoutez le bloc suivant :

1[ai]
2binding = "AI"

Cette liaison rend le service d’IA disponible sur l’argument d’environnement (env.AI) dans le code de votre Worker. Vous n’avez pas besoin de gérer de clés d’API, de configurer de points de terminaison ou de manipuler des chaînes de connexion. Wrangler gère automatiquement l’authentification lors du déploiement.

Un fichier wrangler.toml complet pour ce projet ressemble à ceci :

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

La date de compatibilité (compatibility_date) est importante : elle fixe le comportement de la plateforme à une date donnée pour éviter que de futures modifications n’altèrent silencieusement le fonctionnement de votre Worker. Si vous l’omettez, le déploiement échouera avec une erreur de configuration, ce qui est l’une des erreurs les plus fréquentes lors d’un premier lancement.

Étape 2 : Écrire le code du Worker

Une fois la liaison configurée, vous pouvez appeler le service d’IA depuis votre handler fetch. L’exemple ci-dessous montre comment recevoir une charge utile JSON contenant un prompt utilisateur et générer une complétion de texte à l’aide de 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};

Cette structure simple vous permet de créer des outils de résumé de texte, d’analyse de sentiments ou des générateurs de contenu. Si vous souhaitez connecter ces fonctionnalités à votre base de données, vous pouvez effectuer une liaison vers une base de données SQL serverless ; consultez notre guide de configuration de base de données Cloudflare D1 pour plus de détails.

Utiliser le format de messages de chat

Le champ prompt est pratique pour les complétions simples, mais les modèles conversationnels fonctionnent mieux avec un tableau structuré de messages (messages). Cela vous permet de définir une consigne système pour orienter le ton du modèle et de la dissocier des entrées de l’utilisateur :

 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 });

Notez que les modèles de génération de texte encapsulent leur sortie dans un champ response, le texte complété se trouve donc au niveau de response.response et non à la racine. Ce détail surprend souvent les nouveaux utilisateurs qui affichent l’objet brut et constatent une structure inattendue.

Choisir le bon modèle

Le catalogue de Cloudflare comprend des dizaines de modèles. Choisir le bon est une affaire de compromis entre vitesse, qualité et coût. Les modèles plus petits répondent plus rapidement et consomment moins de ressources ; les modèles plus grands raisonnent mieux mais coûtent plus cher par requête. Le tableau ci-dessous compare quelques options populaires pour la génération de texte.

En règle générale, commencez par un modèle 8B tel que Llama 3 8B Instruct. Il gère la majorité des flux de travail de résumé, de classification et de chat pour une fraction de la latence et du coût d’un modèle 70B. Ne passez à un modèle supérieur que si vos évaluations montrent que le modèle plus petit est réellement insuffisant.

Étape 3 : Streamer les réponses pour une meilleure expérience utilisateur

Pour les applications de chat, attendre que la réponse complète soit générée peut nuire à l’expérience de l’utilisateur.

Vous pouvez configurer la liaison AI pour diffuser (streamer) la réponse token par token au fur et à mesure de sa génération. Pour cela, passez stream: true dans les options de votre requête. Le Worker renverra un ReadableStream que vous pourrez transmettre directement au client web, créant ainsi une interface de chat fluide et interactive. Pour comparer cette approche d’exécution à l’edge avec l’hébergement cloud classique, consultez notre comparatif entre Cloudflare Workers et AWS Lambda .

Voici un handler de streaming complet. Au lieu de renvoyer du JSON analysé, vous transmettez directement le flux au client avec le bon content-type afin que le navigateur puisse le consommer comme des 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 différence clé par rapport à la version sans streaming réside dans la réponse elle-même : vous passez le flux directement à new Response() et définissez le content-type sur text/event-stream. Si vous encapsulez le flux dans un Response.json(), il ne se sérialisera pas correctement et le client recevra un corps vide.

Tester et déployer votre Worker

Une fois la liaison et le handler en place, testez le Worker localement avant de l’envoyer en production :

1npx wrangler dev

Puisque l’inférence s’exécute sur les GPU de Cloudflare et non sur votre machine, la liaison AI sollicite le réseau même en développement local. Wrangler gère cela pour vous, mais cela signifie que les tests locaux nécessitent une connexion active et une session d’authentification valide.

Envoyez une requête de test avec curl pendant que wrangler dev est en cours d’exécution :

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

Une fois satisfait du résultat, déployez-le sur le réseau mondial :

1npx wrangler deploy

Wrangler téléverse votre Worker et renvoie une URL en *.workers.dev. Votre point de terminaison est désormais actif dans chaque centre de données Cloudflare, et chaque requête est automatiquement acheminée vers l’emplacement le plus proche de l’utilisateur.

Pièges courants et dépannage

Voici quelques-uns des problèmes les plus fréquents rencontrés par les équipes lors de leurs premiers déploiements d’inférence à l’edge. Connaître la solution à l’avance permet d’éviter de longues sessions de débogage.

• Cannot read properties of undefined (reading 'run') – la liaison env.AI est indéfinie. Cela signifie presque toujours que le bloc [ai] est manquant dans wrangler.toml, ou que vous avez modifié le fichier sans redémarrer wrangler dev (ou sans redéployer). Vérifiez que le nom de la liaison correspond exactement.
• No such model ou erreur 400 lors du run – l’identifiant du modèle est incorrect. Les noms de modèles sont sensibles à la casse et doivent inclure le chemin complet, par exemple @cf/meta/llama-3-8b-instruct. Copiez-les depuis le catalogue de modèles plutôt que de les saisir de mémoire.
• Réponses en streaming vides ou corrompues – vous avez renvoyé le flux via Response.json() au lieu de new Response(stream, ...). Les flux doivent être transmis directement, pas sérialisés.
• Erreurs de capacité ou d’accès limités (code 429) sous forte charge – le modèle est temporairement saturé ou vous avez atteint une limite de compte. Ajoutez un mécanisme de relance court avec temporisation, et envisagez un modèle plus petit pour faire face aux pics de trafic.
• Réponses tronquées – la réponse s’arrête au milieu d’une phrase car la valeur de max_tokens est trop basse. Augmentez la limite, mais gardez à l’esprit que des valeurs plus élevées augmentent à la fois la latence et le coût.

Si une requête échoue sans message d’erreur, surveillez les journaux d’exécution en temps réel avec npx wrangler tail tout en envoyant une requête de test. Cela affiche les erreurs d’exécution et les sorties de console.log du Worker déployé.

Optimiser les coûts de production et la sécurité

Bien que Workers AI soit très économique, l’exécution d’inférences de modèles en production nécessite la mise en place de contrôles rigoureux.

• Implémenter une limite de débit (Rate Limiting) : Limitez la fréquence à laquelle un client peut appeler votre point de terminaison. Les coûts de calcul GPU évoluent proportionnellement à l’utilisation.
• Assainir les prompts : Validez les entrées pour prévenir les attaques par injection de prompts et vous assurer que les sorties du modèle restent conformes à votre charte.
• Limiter la taille du contexte : Gardez des historiques de prompts courts. L’envoi de volumes massifs de contexte à chaque appel augmente les coûts de traitement des tokens.

Pour une analyse détaillée de la gestion du contexte, consultez notre guide sur la création d’un chatbot avec l’API OpenAI .

Points clés à retenir

• Cloudflare Workers AI permet un accès serverless à des modèles open source sans maintenance de serveurs GPU.
• Configurez l’accès en ajoutant le bloc de liaison [ai] dans votre fichier wrangler.toml.
• Écrivez des handlers de fetch pour exécuter la génération de texte, de traduction ou d’images directement à l’edge.
• Activez le streaming de tokens avec stream: true pour optimiser l’expérience sur mobile et dans les applications de chat.
• Mettez en place des limites de débit et un assainissement des prompts pour protéger vos points de terminaison edge en production.

Bâtissez vos applications d’IA à l’edge

Concevoir des intégrations d’IA fiables requiert une expertise pointue en architecture serverless. Mecanik est spécialisé dans les services d’intégration d’IA et les configurations d’API personnalisées via notre service d’intégration d’API OpenAI . Nous construisons des outils natifs de l’edge capables de passer à l’échelle de façon transparente tout en optimisant les coûts et l’expérience utilisateur. Contactez nos experts pour évaluer votre projet.

Foire aux questions (FAQ)

Qu’est-ce que Cloudflare Workers AI ? Il s’agit d’une plateforme serverless qui vous permet d’exécuter des modèles de machine learning (génération de texte, traduction, transcription audio, génération d’images) sur le réseau mondial de GPU de Cloudflare.

Ai-je besoin d’une clé d’API pour utiliser Workers AI ? Non. Une fois que vous déclarez la liaison AI dans votre fichier wrangler.toml, Cloudflare gère l’authentification et les identifiants en interne, rendant le service accessible via env.AI.

Quels modèles sont disponibles sur Cloudflare Workers AI ? La plateforme héberge des modèles open source populaires, y compris Meta Llama, Mistral, OpenAI Whisper et Stable Diffusion, qui sont régulièrement mis à jour dans son catalogue.

Puis-je streamer des réponses textuelles depuis Workers AI ? Oui. En définissant stream: true dans les paramètres de votre appel env.AI.run, le Worker renvoie un ReadableStream standard permettant de diffuser le texte vers le navigateur.

Comment fonctionne la facturation de Workers AI ? La facturation repose sur le nombre de tokens traités (pour les modèles textuels) ou sur la durée d’utilisation de calcul (pour les autres modèles), offrant un modèle à l’usage très économique.