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 des modèles Gemini Enterprise Agent Platform. Vous pouvez utiliser vos propres modèles personnalisés déployés sur les 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 avec les données du message d'origine.

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

  • 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 la fréquence des requêtes envoyées au modèle d'IA. Pour en savoir plus, consultez Flux de messages dans ce document.

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

  • Modèles autodé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 Model-as-a-Service (MaaS). Modèles proposés en tant que service via le 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 le SMT AI Inference, 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 sujet : 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 de la plate-forme d'agent. 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 a besoin 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 IAM suivant au compte de service :

Traitement des messages

Cette section décrit comment le SMT d'inférence d'IA 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. Le SMT fusionne ces paramètres avec les données du message et envoie le fichier JSON fusionné au point de terminaison du modèle.

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.

Sortie

Si l'appel au 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 d'inférence d'IA 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, qui contient les données d'origine et l'inférence du modèle, est écrit dans le stockage interne de Pub/Sub.

  3. Pub/Sub distribue 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 envoie 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 la fréquence des 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 compatible avec l'API de récupération unaire.

Vous pouvez chaîner un SMT AI Inference avec un 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.

Créer un SMT AI Inference

Les SMT peuvent être configurés 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 IA.

  5. Dans le champ Point de terminaison, saisissez le nom complet de la ressource du point de terminaison de votre 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 de la plate-forme d'agent. Pour en savoir plus, consultez Autorisations de compte 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 thème 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 la forme d'un objet JSON. Le 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 d'un compte de service à utiliser lors de l'appel du point de terminaison. Pour en savoir plus, consultez Autorisations de compte 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 de la rubrique 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 thème.

  • TOPIC_ID : ID du sujet auquel s'abonner.

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

Valider et tester

Vous pouvez également valider et tester le SMT configuré avant de créer le thème ou l'abonnement. Pour en savoir plus, consultez les documents suivants :

Exemple : Utiliser le SMT AI Inference

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-2.5-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 comportant un 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 invite mise en forme pour l'API Chat Completions.

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

  5. Recevoir un message de l'abonnement

    gcloud pubsub subscriptions pull TOPIC_ID-sub

    Si l'appel à la plate-forme d'agents réussit, le message est enrichi avec le résultat de l'invite.

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-2.0-flash-001 API Chat Completions
google/gemini-2.0-flash-lite-001 API Chat Completions
google/gemini-2.5-flash API Chat Completions
google/gemini-2.5-flash-lite API Chat Completions
google/gemini-2.5-pro API Chat Completions
google/gemini-2.5-flash-image API Chat Completions
google/gemini-3-pro-preview API Chat Completions
google/gemini-3-pro-image-preview API Chat Completions
google/gemini-3-flash-preview API Chat Completions
google/gemini-3.1-pro-preview API Chat Completions
google/gemini-3.1-flash-image-preview API Chat Completions
google/gemini-3.1-flash-lite-preview API Chat Completions
meta/llama-3.3-70b-instruct-maas 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
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 rawPredict
anthropic/claude-sonnet-4-5 rawPredict
anthropic/claude-sonnet-4-6 rawPredict
anthropic/claude-opus-4 rawPredict
anthropic/claude-opus-4-1 rawPredict
anthropic/claude-opus-4-5 rawPredict
anthropic/claude-opus-4-6 rawPredict
anthropic/claude-haiku-4-5 rawPredict
mistralai/mistral-small-2503 rawPredict
mistralai/mistral-medium-3 rawPredict
mistralai/mistral-ocr-2505 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 mondial 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. Vous êtes responsable de la vérification du format des données.

  • 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 elle dépasse 60 secondes, la tentative d'envoi expire et Pub/Sub effectue une nouvelle tentative, jusqu'à la durée de rétention des messages et les paramètres de la stratégie de nouvelle tentative configurés. Si la tentative expire, le message est transféré vers le sujet des lettres mortes, si un sujet est configuré.

Modèles non compatibles

Le SMT d'inférence d'IA n'est pas compatible avec les modèles MaaS suivants. Pour la plupart de ces modèles, des versions auto-déployées sont disponibles et peuvent être utilisées à 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 un SMT d'inférence d'IA est défini 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 transformations de message unique des abonnements 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 à l'exportation, la région du point de terminaison doit être celle 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 la redirige automatiquement vers la région du point de terminaison.

  • Si vous extrayez des messages d'un abonnement avec une SMT AI Inference et que la demande d'extraction est envoyée à 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 par extraction. Cette contrainte s'applique à la fois à l'extraction de flux et à l'extraction unaire.

  • Lorsqu'un abonnement push dispose d'un SMT d'inférence d'IA, il envoie les messages depuis la région du point de terminaison. En cas de non-respect d'une contrainte régionale, Pub/Sub cesse d'envoyer 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 aux thèmes. Si l'inférence échoue lors de la publication du message, l'ensemble 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, celui-ci peut être transféré vers une file d'attente de lettres mortes. Nous vous recommandons de configurer un 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, comme 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 ce taux ne peut pas dépasser le quota du modèle.

  • La taille du message transformé final, 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