Inférence d'IA en temps réel à grande échelle avec WebSockets et objets durables

En octobre 2024, nous avons parlé du stockage de milliards de journaux de votre application d'IA à l'aide d'AI Gateway et de la manière dont nous avons utilisé la plateforme de développement de Cloudflare pour ce faire.

In October 2024, we covered how to store billions of logs from your AI application using AI Gateway, and how we used Cloudflare’s Developer Platform to do this.

En octobre 2024, nous avons expliqué comment stocker des milliards de journaux de votre application d'IA à l'aide d'AI Gateway, et comment nous avons utilisé la plateforme de développement de Cloudflare pour ce faire.

With AI Gateway already processing over 3 billion logs and experiencing rapid growth, the number of connections to the platform continues to increase steadily. To help developers manage this scale more effectively, we wanted to offer an alternative to implementing HTTP/2 keep-alive to maintain persistent HTTP(S) connections, thereby avoiding the overhead of repeated handshakes and TLS negotiations with each new HTTP connection to AI Gateway. We understand that implementing HTTP/2 can present challenges, particularly when many libraries and tools may not support it by default and most modern programming languages have well-established WebSocket libraries available.

Alors qu'AI Gateway traite déjà plus de 3 milliards de journaux et connaît une croissance rapide, le nombre de connexions à la plateforme continue d'augmenter régulièrement. Pour aider les développeurs à gérer cette échelle plus efficacement, nous souhaitions proposer une alternative à la mise en œuvre de HTTP/2 keep-alive pour maintenir des connexions HTTP(S) persistantes, évitant ainsi la surcharge des poignées de main répétées et des négociations TLS à chaque nouvelle connexion HTTP à AI Gateway. . Nous comprenons que la mise en œuvre de HTTP/2 peut présenter des défis, en particulier lorsque de nombreuses bibliothèques et outils ne le prennent pas en charge par défaut et que la plupart des langages de programmation modernes disposent de bibliothèques WebSocket bien établies.

With this in mind, we used Cloudflare’s Developer Platform and Durable Objects (yes, again!) to build a WebSockets API that establishes a single, persistent connection, enabling continuous communication.

Dans cet esprit, nous avons utilisé la plateforme de développement et les objets durables de Cloudflare (oui, encore une fois !) pour créer une API WebSockets qui établit une connexion unique et persistante, permettant une communication continue.

Through this API, all AI providers supported by AI Gateway can be accessed via WebSocket, allowing you to maintain a single TCP connection between your client or server application and the AI Gateway. The best part? Even if your chosen provider doesn’t support WebSockets, we handle it for you, managing the requests to your preferred AI provider.

Grâce à cette API, tous les fournisseurs d'IA pris en charge par AI Gateway sont accessibles via WebSocket, vous permettant de maintenir une connexion TCP unique entre votre application client ou serveur et AI Gateway. La meilleure partie ? Même si le fournisseur que vous avez choisi ne prend pas en charge les WebSockets, nous nous en occupons pour vous, en gérant les demandes adressées à votre fournisseur d'IA préféré.

By connecting via WebSocket to AI Gateway, we make the requests to the inference service for you using the provider’s supported protocols (HTTPS, WebSocket, etc.), and you can keep the connection open to execute as many inference requests as you would like.

En vous connectant via WebSocket à AI Gateway, nous effectuons les requêtes au service d'inférence pour vous en utilisant les protocoles pris en charge par le fournisseur (HTTPS, WebSocket, etc.), et vous pouvez garder la connexion ouverte pour exécuter autant de requêtes d'inférence que vous le souhaitez.

To make your connection to AI Gateway more secure, we are also introducing authentication for AI Gateway. The new WebSockets API will require authentication. All you need to do is create a Cloudflare API token with the permission “AI Gateway: Run” and send that in the cf-aig-authorization header.

Pour rendre votre connexion à AI Gateway plus sécurisée, nous introduisons également l'authentification pour AI Gateway. La nouvelle API WebSockets nécessitera une authentification. Tout ce que vous avez à faire est de créer un jeton API Cloudflare avec l'autorisation « AI Gateway : Run » et de l'envoyer dans l'en-tête cf-aig-authorization.

In the flow diagram above:

Dans l'organigramme ci-dessus :

1. When Authenticated Gateway is enabled and a valid token is included, requests will pass successfully.

1. Lorsque la passerelle authentifiée est activée et qu'un jeton valide est inclus, les demandes seront transmises avec succès.

2. If Authenticated Gateway is enabled, but a request does not contain the required cf-aig-authorization header with a valid token, the request will fail. This ensures only verified requests pass through the gateway.

2. Si la passerelle authentifiée est activée, mais qu'une demande ne contient pas l'en-tête cf-aig-authorization requis avec un jeton valide, la demande échouera. Cela garantit que seules les demandes vérifiées transitent par la passerelle.

3. When Authenticated Gateway is disabled, the cf-aig-authorization header is bypassed entirely, and any token — whether valid or invalid — is ignored.

3. Lorsque la passerelle authentifiée est désactivée, l'en-tête cf-aig-authorization est entièrement contourné et tout jeton, qu'il soit valide ou non, est ignoré.

How we built it

Comment nous l'avons construit

We recently used Durable Objects (DOs) to scale our logging solution for AI Gateway, so using WebSockets within the same DOs was a natural fit.

Nous avons récemment utilisé des objets durables (DO) pour faire évoluer notre solution de journalisation pour AI Gateway. L'utilisation de WebSockets au sein des mêmes DO était donc une solution naturelle.

When a new WebSocket connection is received by our Cloudflare Workers, we implement authentication in two ways to support the diverse capabilities of WebSocket clients. The primary method involves validating a Cloudflare API token through the cf-aig-authorization header, ensuring the token is valid for the connecting account and gateway.

Lorsqu'une nouvelle connexion WebSocket est reçue par nos Cloudflare Workers, nous mettons en œuvre l'authentification de deux manières pour prendre en charge les diverses capacités des clients WebSocket. La méthode principale consiste à valider un jeton API Cloudflare via l'en-tête cf-aig-authorization, garantissant que le jeton est valide pour le compte et la passerelle de connexion.

However, due to limitations in browser WebSocket implementations, we also support authentication via the “sec-websocket-protocol” header. Browser WebSocket clients don't allow for custom headers in their standard API, complicating the addition of authentication tokens in requests. While we don’t recommend that you store API keys in a browser, we decided to add this method to add more flexibility to all WebSocket clients.

Cependant, en raison des limitations des implémentations WebSocket du navigateur, nous prenons également en charge l'authentification via l'en-tête « sec-websocket-protocol ». Les clients WebSocket du navigateur n'autorisent pas les en-têtes personnalisés dans leur API standard, ce qui complique l'ajout de jetons d'authentification dans les requêtes. Bien que nous ne vous recommandons pas de stocker les clés API dans un navigateur, nous avons décidé d'ajouter cette méthode pour ajouter plus de flexibilité à tous les clients WebSocket.

After this initial verification step, we upgrade the connection to the Durable Object, meaning that it will now handle all the messages for the connection. Before the new connection is fully accepted, we generate a random UUID, so this connection is identifiable among all the messages received by the Durable Object. During an open connection, any AI Gateway settings passed via headers — such as cf-aig-skip-cache (which bypasses caching when set to true) — are stored and applied to all requests in the session. However, these headers can still be overridden on a per-request basis, just like with the Universal Endpoint today.

Après cette étape de vérification initiale, nous mettons à niveau la connexion vers l'objet Durable, ce qui signifie qu'il gérera désormais tous les messages de la connexion. Avant que la nouvelle connexion ne soit pleinement acceptée, nous générons un UUID aléatoire, afin que cette connexion soit identifiable parmi tous les messages reçus par l'Objet Durable. Lors d'une connexion ouverte, tous les paramètres AI Gateway transmis via les en-têtes, tels que cf-aig-skip-cache (qui contourne la mise en cache lorsqu'il est défini sur true), sont stockés et appliqués à toutes les requêtes de la session. Cependant, ces en-têtes peuvent toujours être remplacés pour chaque requête, tout comme avec Universal Endpoint aujourd'hui.

How it works

Comment ça marche

Once the connection is established, the Durable Object begins listening for incoming messages. From this point on, users can send messages in the AI Gateway universal format via WebSocket, simplifying the transition of your application from an existing HTTP setup to WebSockets-based communication.

Une fois la connexion établie, l'objet Durable commence à écouter les messages entrants. À partir de ce moment, les utilisateurs peuvent envoyer des messages au format universel AI Gateway via WebSocket, simplifiant ainsi la transition de votre application d'une configuration HTTP existante vers une communication basée sur WebSockets.

When a new message reaches the Durable Object, it’s processed using the same code that powers the HTTP Universal Endpoint, enabling seamless code reuse across Workers and Durable Objects — one of the key benefits of building on Cloudflare.

Lorsqu'un nouveau message atteint l'objet Durable, il est traité à l'aide du même code qui alimente le point de terminaison universel HTTP, ce qui permet une réutilisation transparente du code entre les Workers et les objets durables — l'un des principaux avantages de l'utilisation de Cloudflare.

For non-streaming requests, the response is wrapped in a JSON envelope, allowing us to include additional information beyond the AI inference itself, such as the AI Gateway log ID for that request.

Pour les demandes sans streaming, la réponse est enveloppée dans une enveloppe JSON, ce qui nous permet d'inclure des informations supplémentaires au-delà de l'inférence AI elle-même, telles que l'ID du journal AI Gateway pour cette demande.

Here’s an example response for the request above:

Voici un exemple de réponse à la demande ci-dessus :

For streaming requests, AI Gateway sends an initial message with request metadata telling the developer the stream is starting.

Pour les demandes de streaming, AI Gateway envoie un message initial contenant des métadonnées de demande indiquant au développeur que le flux démarre.

After this initial message, all streaming chunks are relayed in real-time to the WebSocket connection as they arrive from the inference provider. Note that only the eventId field is included in the metadata for these streaming chunks (more info on what this new field is below).

Après ce message initial, tous les morceaux de streaming sont relayés en temps réel vers la connexion WebSocket dès qu'ils arrivent du fournisseur d'inférence. Notez que seul le champ eventId est inclus dans les métadonnées de ces morceaux de streaming (plus d'informations sur ce qu'est ce nouveau champ ci-dessous).

This approach serves two purposes:

Cette approche répond à deux objectifs :