SMT pour l'inférence de l'IA

La transformation SMT (Single Method Transform) d'inférence d'IA vous permet d'obtenir des inférences sur les messages Pub/Sub à partir de modèles Gemini Enterprise Agent Platform. Vous pouvez utiliser vos propres modèles personnalisés déployés sur des points de terminaison Agent Platform, ou utiliser l'un des modèles Google et partenaires disponibles via Agent Platform. Les inférences du modèle sont ajoutées à chaque message, ce qui les rend disponibles pour le traitement en aval, ainsi que les données du message d'origine.

Voici quelques cas d'utilisation de l'inférence IA SMT :

  • Enrichissement en temps réel : ajoutez du contexte, des classifications, des prédictions, des sentiments ou des embeddings aux données d'événement lorsqu'elles transitent par Pub/Sub.

  • Pipelines d'IA simplifiés : éliminez le besoin de services intermédiaires pour obtenir des inférences à partir de modèles d'IA. Pub/Sub gère l'appel du modèle d'IA et l'enrichissement du message avec l'inférence.

  • Latence réduite pour les pipelines d'IA : supprimez les sauts de réseau supplémentaires dans votre architecture pour réduire la latence de bout en bout.

  • Contrôle de flux amélioré : pour éviter de surcharger les points de terminaison du modèle, Pub/Sub optimise le taux de requêtes envoyées au modèle d'IA. Pour en savoir plus, consultez la section Flux de messages de ce document.

Le SMT d'inférence d'IA est compatible avec les types de modèles suivants :

  • Modèles auto-déployés. Modèles ouverts, partenaires et personnalisés déployés sur un point de terminaison Agent Platform public partagé ou dédié.

  • Modèles MaaS (Model-as-a-Service). Modèles proposés en tant que service via Model Garden, tels que Gemini et Claude, qui ne nécessitent pas de gérer le déploiement. Pour obtenir la liste des modèles MaaS compatibles avec AI Inference SMT, consultez Modèles MaaS compatibles.

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour créer un sujet ou un abonnement avec des SMT, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Pub/Sub (roles/pubsub.editor) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour créer un sujet ou un abonnement avec des SMT. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer un sujet ou un abonnement avec des SMT :

  • Créer un thème : pubsub.topics.create sur le projet
  • Créer un abonnement : pubsub.subscriptions.create sur le projet

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Autorisations de compte de service

Le SMT d'inférence d'IA utilise un compte de service IAM pour appeler le point de terminaison Agent Platform. Par défaut, il utilise le compte Agent de service Cloud Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com). Vous pouvez également fournir votre propre compte de service.

Le compte de service doit disposer des autorisations suivantes sur le projet Google Cloudqui contient le point de terminaison Agent Platform :

  • aiplatform.endpoints.get
  • aiplatform.endpoints.predict

Pour accorder ces autorisations, attribuez le rôle Utilisateur Agent Platform au compte de service (que vous utilisiez le compte de service Agent de service Cloud Pub/Sub ou un compte de service personnalisé).

Traitement des messages

Cette section décrit comment la solution AI Inference SMT traite les messages Pub/Sub.

Entrée

Les données du message Pub/Sub doivent être une requête à envoyer au modèle d'IA, sous forme de chaîne JSON. Vous pouvez également spécifier des paramètres de modèle supplémentaires à envoyer avec chaque requête. La SMT fusionne ces paramètres avec les données du message et envoie le JSON fusionné au point de terminaison du modèle.

Par exemple, si vous avez :

  • Données du message d'entrée : {"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
  • Paramètres SMT : {"temperature": 0.2}

La charge utile résultante envoyée au modèle est la suivante :

{
  "messages": [
    {
      "role": "user",
      "content": "Explain photosynthesis"
    }
  ],
  "temperature": 0.2
}

Si un paramètre spécifié dans la configuration SMT porte le même nom qu'un champ des données du message, la valeur des données du message est prioritaire.

Le tableau suivant indique l'API appelée par le SMT pour obtenir l'inférence, en fonction du type de modèle.

Déploiement du modèle Type de modèle API
Déployé automatiquement Tous rawPredict
Model-as-a-Service (MaaS)

Modèle de fondation Gemini

Exemple : gemini-3.0-pro

 Chat Completions API

Autres modèles Gemini

Exemple : gemini-embeddings

 rawPredict
Anthropic, Mistral AI ou AI21 rawPredict
Tous les autres modèles MaaS Chat Completions API

Pour mettre en forme correctement les données de message et les paramètres du modèle, consultez la documentation de votre modèle. Par exemple, pour les modèles de base Gemini, consultez Exemples de l'API Chat Completions.

Si votre application de publication ne peut pas formater les messages dans la structure JSON spécifique requise par le modèle (comme le format de l'API Chat Completions), vous pouvez enchaîner une SMT UDF JavaScript avant la SMT d'inférence d'IA pour prétraiter et formater la charge utile de la requête. Pour obtenir un exemple, consultez Prétraiter des charges utiles avec une fonction JavaScript définie par l'utilisateur.

Sortie

Si l'appel du point de terminaison du modèle aboutit, la SMT enrichit le message Pub/Sub d'origine avec la réponse du modèle. Le message enrichi est une chaîne JSON semblable à la suivante, où ORIGINAL_MESSAGE correspond aux données du message d'origine et INFERENCE_RESULT à la réponse du modèle :

{
  "original_message": { ORIGINAL_MESSAGE },
  "model_output": { INFERENCE_RESULT }
}

Flux de messages

SMT de sujet : lorsque vous définissez un SMT AI Inference sur un sujet, Pub/Sub gère les messages entrants comme suit :

  1. Une application d'éditeur envoie un message à un sujet Pub/Sub.

  2. Le message est envoyé au point de terminaison du modèle configuré pour l'inférence. Le message enrichi, contenant les données d'origine et l'inférence du modèle, est écrit dans la mémoire de stockage interne de Pub/Sub.

  3. Pub/Sub transmet le message enrichi à tous les abonnements associés.

SMT d'abonnement : lorsque vous définissez un SMT d'inférence d'IA sur un abonnement, Pub/Sub gère les messages entrants comme suit :

  1. Une application d'éditeur envoie un message à un sujet Pub/Sub.

  2. Pub/Sub distribue le message à l'abonnement.

  3. Le message est envoyé au point de terminaison du modèle configuré pour l'inférence.

  4. L'abonnement envoie le message enrichi à l'application d'abonné.

  5. Pub/Sub optimise le taux de requêtes envoyées au modèle d'IA pour maximiser le débit, en fonction de la latence et du quota de votre déploiement. Remarque : Cette fonctionnalité n'est pas disponible lorsque vous utilisez l'API de pull unaire.

Vous pouvez chaîner une SMT AI Inference avec une ou plusieurs SMT UDF JavaScript. Utilisez ce modèle pour prétraiter un message afin qu'il corresponde au format d'entrée attendu par votre modèle, ou pour post-traiter la sortie du modèle avant qu'elle ne soit envoyée aux abonnés.

Bonne pratique : Nous vous recommandons vivement d'utiliser des SMT d'abonnement plutôt que des SMT de sujet pour l'inférence d'IA. Si le point de terminaison du modèle d'IA est limité, que la latence augmente ou qu'il devient indisponible, l'impact potentiel sur votre pipeline est plus important avec un SMT thématique :

  • Avec un SMT de sujet, la requête de publication échoue, ce qui a un impact direct sur la disponibilité de votre application de publication.

  • Avec un SMT d'abonnement, Pub/Sub relance la distribution, y compris l'exécution du SMT, conformément à la stratégie de nouvelle tentative de l'abonnement. Vous pouvez également configurer une file d'attente de lettres mortes pour gérer les échecs persistants sans affecter la disponibilité de l'ingestion.

Créer un SMT AI Inference

Les SMT peuvent être configurées sur des sujets ou des abonnements Pub/Sub.

  • Les SMT de sujet sont exécutées avant que Pub/Sub ne stocke le message, et les résultats sont disponibles pour tous les abonnés.

  • Les SMT d'abonnement sont exécutés avant la distribution du message, et les résultats ne sont disponibles que pour cet abonnement.

Console

  1. Dans la console Google Cloud , accédez à la page Sujets de Pub/Sub.

    Accéder aux sujets

  2. Créez un sujet ou un abonnement.

    • Pour créer un sujet, cliquez sur Créer un sujet. La page Créer un sujet s'ouvre.

    • Pour créer un abonnement :

      1. Cliquez sur le nom du sujet auquel vous souhaitez vous abonner.

      2. Cliquez sur Créer un abonnement. La page Ajouter un abonnement au sujet s'ouvre.

  3. Sous Transformations, cliquez sur Ajouter une transformation.

  4. Pour Type de transformation, sélectionnez Inférence de l'IA.

  5. Dans le champ Point de terminaison, saisissez le nom complet de la ressource de votre point de terminaison de modèle :

    • Modèle auto-déployé : projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Modèle Model Garden : projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  6. Facultatif. Sélectionnez un compte de service à utiliser lors de l'appel du point de terminaison Agent Platform. Pour en savoir plus, consultez Autorisations des comptes de service.

  7. Facultatif. Dans le champ Paramètres, saisissez les paramètres du modèle sous forme d'objet JSON. Le SMT fusionne ces paramètres avec chaque message avant d'appeler le modèle. Exemple :

    {
  "temperature": 0.5,
  "max_tokens": 1000
}

  8. Pour créer le sujet ou l'abonnement, cliquez sur Créer.

gcloud

Créer un fichier de définition

Créez un fichier YAML ou JSON qui définit l'IA d'inférence.

YAML 

- aiInference:
    endpoint: "ENDPOINT_RESOURCE"
    unstructuredInference: {
        parameters:
          MODEL_PARAMETERS
    }
    service_account_email: SERVICE_ACCOUNT

JSON 

{
  "aiInference": {
    "endpoint": "ENDPOINT_RESOURCE",
    "unstructuredInference": {
        "parameters": {
          MODEL_PARAMETERS
        }
    }
    "service_account_email": SERVICE_ACCOUNT
  }
}

Remplacez les éléments suivants :

  • ENDPOINT_RESOURCE : nom complet de la ressource du point de terminaison du modèle. Utilisez le format suivant :

    • Modèle auto-déployé : projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Modèle Model Garden : projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  • MODEL_PARAMETERS : facultatif. Paramètres du modèle, spécifiés sous forme d'objet JSON. La SMT fusionne ces paramètres avec chaque message avant d'appeler le modèle. Exemple :

    {
  "temperature": 0.5,
  "max_tokens": 1000
}

  • SERVICE_ACCOUNT : facultatif. Adresse e-mail du compte de service à utiliser lors de l'appel du point de terminaison. Pour en savoir plus, consultez Autorisations des comptes de service.

Créer un sujet ou un abonnement

Pour créer un sujet, exécutez la commande gcloud pubsub topics create.

gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Remplacez les éléments suivants :

  • TOPIC_ID : ID ou nom du sujet que vous souhaitez créer.
  • TRANSFORMS_FILE : chemin d'accès au fichier de définition.

Pour créer un abonnement, exécutez la commande gcloud pubsub subscriptions create.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=projects/PROJECT_ID/topics/TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Remplacez les éléments suivants :

  • SUBSCRIPTION_ID : ID ou nom de l'abonnement à créer.

  • PROJECT_ID : ID du projet contenant le sujet.

  • TOPIC_ID : ID du thème auquel s'abonner.

  • TRANSFORMS_FILE : chemin d'accès au fichier de définition.

Validation et test

Vous pouvez éventuellement valider et tester la SMT configurée avant de créer le sujet ou l'abonnement. Pour en savoir plus, consultez les documents suivants :

Exemples

Utiliser AI Inference SMT

L'exemple suivant montre comment créer un abonnement avec un SMT d'inférence d'IA, puis l'utiliser pour envoyer une requête à Gemini.

gcloud

  1. À l'aide d'un éditeur de texte, créez un fichier nommé ai-smt.yaml et collez-y le texte suivant :

    - aiInference:
    endpoint: projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-3.8-flash
    unstructuredInference: {
        parameters: {
            "max_tokens": 25000
        }
    }

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud.
    • LOCATION : emplacement du point de terminaison à appeler. Exemple : us-central1.

  2. Créez un sujet Pub/Sub.

    gcloud pubsub topics create TOPIC_ID

    Remplacez TOPIC_ID par le nom du sujet à créer. Exemple : topic-1.

  3. Créez un abonnement doté d'une SMT d'inférence d'IA.

    gcloud pubsub subscriptions create TOPIC_ID-sub \
  --ack-deadline=600 \
  --topic TOPIC_ID \
  --message-transforms-file ai-smt.yaml

  4. Publier un message dans le sujet Le message contient une requête formatée pour l'API Chat Completions.

    gcloud pubsub topics publish TOPIC_ID --message=$'{
  "model":"google/gemini-3.8-flash","messages":[{
    "role": "user",
    "content": "Explain how AI works in a few words"
    }]
  }'

  5. Recevez un message de l'abonnement.

    gcloud pubsub subscriptions pull TOPIC_ID-sub

    Si l'appel à Agent Platform aboutit, le message est enrichi avec le résultat du prompt.

Prétraiter les charges utiles avec une UDF JavaScript

Si votre application d'éditeur émet du texte brut, des journaux ou des charges utiles d'événements plutôt que le format JSON structuré requis par les modèles d'IA (comme le format Chat Completions compatible avec OpenAI), vous pouvez chaîner une UDF JavaScript SMT avant le SMT d'inférence d'IA. La fonction définie par l'utilisateur agit comme une couche de traduction, en transformant le message brut au format attendu par le modèle.

L'exemple d'UDF JavaScript suivant montre comment prétraiter un message contenant un prompt textuel en une requête API Chat Completions compatible avec Gemini 3.8 Flash :

/**
 * Pre-processes a message containing a text prompt into a
 * Chat Completions API request compatible with Gemini 3.8 Flash.
 */
function prepareGeminiRequest(message, metadata) {
  // Assuming the incoming message data is a raw text prompt
  const promptText = message.data;

  const chatRequest = {
    "model": "google/gemini-3.8-flash",
    "messages": [
      {
        "role": "user",
        "content": promptText
      }
    ]
  };

  // Replace the message data with the stringified JSON request
  message.data = JSON.stringify(chatRequest);
  return message;
}

Vous pouvez également enchaîner une UDF JavaScript de post-traitement après la SMT d'inférence d'IA pour extraire des champs spécifiques de la réponse du modèle avant de la transmettre aux abonnés.

Modèles MaaS compatibles

Le tableau suivant répertorie les modèles MaaS (Model-as-a-Service) que Google a testés avec le SMT d'inférence d'IA et qui sont connus pour être compatibles. Cette liste est susceptible d'être modifiée, car des modèles peuvent devenir obsolètes ou de nouveaux modèles MaaS peuvent être ajoutés.

ModèleAPI appelée
google/gemini-3.8-flash API Chat Completions
google/gemini-3.7-flash API Chat Completions
google/gemini-3.6-flash API Chat Completions
google/gemini-3.5-flash API Chat Completions
google/gemini-3.5-flash-lite API Chat Completions
google/gemini-3.1-flash-lite API Chat Completions
google/gemini-3.1-pro-preview API Chat Completions
google/gemini-3-flash-preview API Chat Completions
google/gemini-3.1-flash-image API Chat Completions
google/gemini-3-pro-image API Chat Completions
google/gemini-2.5-flash-image API Chat Completions
google/gemini-2.5-pro API Chat Completions
google/gemini-2.5-flash-lite API Chat Completions
google/gemini-2.5-flash API Chat Completions
google/gemini-2.0-flash-lite-001 API Chat Completions
google/gemini-2.0-flash-001 API Chat Completions
meta/llama-4-maverick-17b-128e-instruct-maas API Chat Completions
meta/llama-4-scout-17b-16e-instruct-maas API Chat Completions
meta/llama-3.3-70b-instruct-maas API Chat Completions
deepseek-ai/deepseek-r1-0528-maas API Chat Completions
deepseek-ai/deepseek-v3.1-maas API Chat Completions
qwen/qwen3-235b-a22b-instruct-2507-maas API Chat Completions
qwen/qwen3-coder-480b-a35b-instruct-maas API Chat Completions
openai/gpt-oss-20b-maas API Chat Completions
openai/gpt-oss-120b-maas API Chat Completions
google/text-multilingual-embedding-002 rawPredict
google/text-embedding-005 rawPredict
google/text-embedding-large-exp-03-07 rawPredict
google/gemini-embedding-001 rawPredict
google/multimodalembedding rawPredict
anthropic/claude-sonnet-4-6 rawPredict
anthropic/claude-sonnet-4-5 rawPredict
anthropic/claude-sonnet-4 rawPredict
anthropic/claude-opus-4-6 rawPredict
anthropic/claude-opus-4-5 rawPredict
anthropic/claude-opus-4-1 rawPredict
anthropic/claude-opus-4 rawPredict
anthropic/claude-haiku-4-5 rawPredict
mistralai/mistral-ocr-2505 rawPredict
mistralai/mistral-small-2503 rawPredict
mistralai/mistral-medium-3 rawPredict
mistralai/codestral-2 rawPredict

Limites

  • Vous ne pouvez ajouter qu'un seul SMT d'inférence d'IA à un sujet ou à un abonnement.

  • Les points de terminaison privés ne sont pas acceptés. Les modèles déployés automatiquement doivent être hébergés sur des points de terminaison Agent Platform publics.

  • Le point de terminaison global n'est compatible qu'avec les modèles de fondation Gemini. Pour les autres modèles, vous devez utiliser un point de terminaison régional.

  • Pub/Sub ne valide pas les données des messages d'entrée. Il vous incombe de vous assurer que le format des données est correct.

  • La transformation envoie une requête d'inférence par message Pub/Sub. Le traitement par lot côté client n'est pas effectué.

  • Les inférences par lots asynchrones ne sont pas acceptées.

  • L'inférence ne doit pas prendre plus de 60 secondes. Si ce délai dépasse 60 secondes, la tentative de distribution expire et Pub/Sub réessaie, jusqu'à ce que la durée de conservation des messages et les paramètres de la stratégie de nouvelle tentative configurés soient atteints. Si la tentative expire, le message est transféré vers la file d'attente de lettres mortes, le cas échéant.

Modèles non compatibles

Le SMT d'inférence d'IA n'est pas compatible avec les modèles MaaS suivants. De nombreux modèles de ce type sont disponibles en version auto-déployée que vous pouvez utiliser à la place.

  • deepseek-ai/deepseek-ocr-maas
  • deepseek-ai/deepseek-v3.2-maas
  • google/gemini-embedding-2-preview
  • google/lyria-002
  • google/lyria-3-clip-preview
  • google/lyria-3-pro-preview
  • google/veo-3.1-fast-generate-001
  • google/veo-3.1-generate-001
  • intfloat/multilingual-e5-large-instruct-maas
  • intfloat/multilingual-e5-small-instruct-maas
  • minimaxai/minimax-m2-maas
  • moonshotai/kimi-k2-thinking-maas
  • qwen/qwen3-next-80b-a3b-instruct-maas
  • qwen/qwen3-next-80b-a3b-thinking-maas
  • zai-org/glm-4.7-maas
  • zai-org/glm-5-maas

Contraintes régionales

Les contraintes suivantes s'appliquent aux SMT d'inférence d'IA en fonction de la région du point de terminaison de la plate-forme d'agent.

  • Si une transformation SMT d'inférence d'IA est définie sur un sujet, la région du point de terminaison doit se trouver dans les régions autorisées par la règle de stockage des messages du sujet.

    Cette contrainte s'applique également aux SMT d'abonnement si la contrainte de règle d'administration Appliquer des régions de transit pour les messages Pub/Sub est en vigueur.

  • Si un SMT d'inférence d'IA est défini sur un abonnement d'exportation, la région du point de terminaison doit se trouver dans la région de la ressource associée :

  • Si une requête de publication est envoyée à une région autre que celle du point de terminaison, Pub/Sub redirige automatiquement la requête vers la région du point de terminaison.

  • Si vous extrayez des données d'un abonnement avec un SMT AI Inference et que la demande d'extraction est effectuée dans une région autre que celle du point de terminaison, Pub/Sub la refuse. Nous vous recommandons d'utiliser un point de terminaison de localisation pour les abonnements pull. Cette contrainte s'applique à la fois à l'extraction en flux continu et à l'extraction unaire.

  • Lorsqu'un abonnement push dispose d'un SMT d'inférence d'IA, l'abonnement transmet les messages depuis la région du point de terminaison. En cas de non-respect d'une contrainte régionale, Pub/Sub cesse de transmettre les messages de cet abonnement.

Dépannage

Cette section fournit des conseils de dépannage pour le SMT d'inférence d'IA.

  • Erreurs SMT liées au sujet. Si l'inférence échoue lors de la publication du message, l'intégralité de la requête de publication échoue. Les informations sur l'erreur sont renvoyées au client éditeur.

  • Erreurs SMTP liées aux abonnements Si l'inférence échoue lors de la distribution du message (par exemple, en raison d'une indisponibilité prolongée du modèle, d'un épuisement prolongé du quota ou d'erreurs d'argument non valide), le message d'origine non modifié est transféré vers la file d'attente de lettres mortes configurée. Cela permet de s'assurer qu'aucune donnée n'est perdue. Le message transféré inclut un attribut CloudPubSubDeadLetterSourceSMTErrorMessage contenant les détails de l'échec SMT. Nous vous recommandons de configurer une file d'attente de lettres mortes lorsque vous utilisez des SMT sur un abonnement.

  • Erreurs d'inférence du modèle : Si l'inférence échoue et renvoie une erreur, vérifiez les points suivants :

    • Vérifiez que le point de terminaison configuré est correct.

    • Vérifiez que les données du message Pub/Sub contiennent une requête d'inférence valide pour votre modèle.

    • Vérifiez que tous les paramètres du modèle sont valides.

    L'inférence peut échouer pour d'autres raisons, telles que des problèmes de connectivité.

  • Erreurs d'autorisation ou de point de terminaison. Si le compte de service configuré perd l'autorisation d'accéder au point de terminaison ou si le point de terminaison est supprimé, le SMT échoue.

Quotas et limites

  • En plus des quotas et limites de Pub/Sub, la solution AI Inference SMT est soumise aux quotas et aux limites de débit du point de terminaison de la plate-forme d'agent. Le contrôle de flux intégré de Pub/Sub ajuste automatiquement le taux de demandes pour éviter de surcharger le point de terminaison, mais le taux ne peut pas dépasser le quota du modèle.

  • La taille finale du message transformé, y compris le message d'origine et le résultat de l'inférence, doit être inférieure à la limite de taille des messages Pub/Sub. Si le message transformé dépasse la limite, la transformation échoue.

Étapes suivantes