vertex ai role error 400 solution aistudio difference fr image 0 图示

Résoudre l’erreur 400 de Vertex AI : 3 types de problèmes de format de corps de requête causés par des différences dans le paramètre role

par

vertex-ai-role-error-400-solution-aistudio-difference-fr 图示

Lors de l'utilisation de l'API Google Gemini, passer de AI Studio à Vertex AI est une étape incontournable pour de nombreux développeurs. Cependant, une différence apparemment mineure sur le paramètre role a causé bien des maux de tête à de nombreux utilisateurs :

[&{Please use a valid role: user, model. (request id: xxx) 400 }]

La cause fondamentale de cette erreur 400 est la suivante : Vertex AI exige que chaque objet du tableau contents inclue impérativement le champ role, alors qu'AI Studio permet de l'omettre lors d'un dialogue simple (monocoup).

Cet article analyse en profondeur les différences de format du corps de requête entre Vertex AI et AI Studio, et propose des solutions complètes pour trois scénarios différents.

Aperçu des différences clés entre Vertex AI et AI Studio

Avant de résoudre l'erreur 400, il est essentiel de comprendre les distinctions fondamentales entre ces deux plateformes.

Positionnement des plateformes

Dimension AI Studio (Google AI) Vertex AI
Utilisateurs cibles Prototypage rapide pour développeurs Déploiement en production (entreprise)
Méthode d'authentification Clé API Compte de service / OAuth
Limites de débit Limites de base, usage commercial restreint Limites de production, usage commercial supporté
Champ role Facultatif en dialogue simple Obligatoire
Format du point de terminaison generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Plateformes disponibles APIYI apiyi.com, API officielle APIYI apiyi.com, Google Cloud

Pourquoi l'erreur role 400 survient-elle ?

En tant que plateforme d'entreprise, Vertex AI applique des validations de format beaucoup plus strictes. Si le champ role manque dans votre corps de requête, Vertex AI renvoie immédiatement :

{
  "error": {
    "code": 400,
    "message": "Please use a valid role: user, model.",
    "status": "INVALID_ARGUMENT"
  }
}

vertex-ai-role-error-400-solution-aistudio-difference-fr 图示

🎯 Conseil technique : Lors de votre migration vers Vertex AI, nous vous recommandons d'effectuer vos tests d'appels via la plateforme APIYI apiyi.com. Elle offre un format d'interface unifié qui gère automatiquement les différences de paramètres entre les plateformes, facilitant ainsi la validation rapide de vos solutions techniques.

Détails du format du corps de requête Vertex AI

Format de requête Vertex AI correct

Le corps de requête de l'API Gemini de Vertex AI doit impérativement respecter la structure suivante :

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Explique-moi ce qu'est un grand modèle de langage"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 2048
  }
}

Valeurs valides pour le paramètre role

Vertex AI n'accepte que deux valeurs pour le champ role :

Valeur de role Signification Cas d'utilisation
user Entrée utilisateur Questions ou instructions envoyées au modèle
model Réponse du modèle Réponses historiques dans une conversation multi-tours

Exemple incorrect vs Exemple correct

❌ Erreur : champ role manquant (style AI Studio)

{
  "contents": [
    {
      "parts": [
        {
          "text": "Hello, how are you?"
        }
      ]
    }
  ]
}

✅ Correct : champ role inclus (style Vertex AI)

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Hello, how are you?"
        }
      ]
    }
  ]
}

Détails du format du corps de requête AI Studio

Mode flexible d'AI Studio

AI Studio (Google AI) est plus souple sur les exigences de format. Dans le cas d'un dialogue à tour unique, vous pouvez omettre le champ role :

{
  "contents": [
    {
      "parts": [
        {
          "text": "What is machine learning?"
        }
      ]
    }
  ]
}

Comparaison du corps de requête entre les deux plateformes

vertex-ai-role-error-400-solution-aistudio-difference-fr 图示

Champ AI Studio Vertex AI
contents Requis Requis
contents[].role Optionnel (un seul tour) Requis
contents[].parts Requis Requis
contents[].parts[].text Requis Requis
systemInstruction Supporté Supporté
generationConfig Optionnel Optionnel

Scénarios de dialogue multi-tours

Dans les dialogues multi-tours, les formats des deux plateformes convergent et nécessitent de spécifier explicitement le role :

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Bonjour, présente-toi s'il te plaît"}]
    },
    {
      "role": "model",
      "parts": [{"text": "Bonjour ! Je suis Gemini, un assistant IA développé par Google..."}]
    },
    {
      "role": "user",
      "parts": [{"text": "Que sais-tu faire ?"}]
    }
  ]
}

Solutions complètes pour 3 scénarios

Scénario 1 : Appel de Vertex AI via le SDK Python

Lors de l'utilisation du SDK Python officiel de Google, assurez-vous de transmettre correctement le paramètre role :

from google import genai
from google.genai.types import Content, Part

# 初始化客户端
client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)

# 正确的请求格式 - 必须包含 role
contents = [
    Content(
        role="user",
        parts=[Part(text="什么是 Vertex AI?")]
    )
]

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=contents
)

print(response.text)

Scénario 2 : Appel direct via l'API REST

Utilisation de curl ou d'un client HTTP pour appeler directement l'API REST de Vertex AI :

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "解释量子计算的基本原理"}
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

💡 Démarrage rapide : Nous vous recommandons d'utiliser la plateforme APIYI (apiyi.com) pour créer rapidement vos prototypes. Cette plateforme propose des interfaces API prêtes à l'emploi qui gèrent uniformément les différences de format entre Vertex AI et AI Studio. Sans configuration complexe, l'intégration se fait en seulement 5 minutes.

Scénario 3 : Appel au format compatible OpenAI

Si votre code est basé sur le SDK OpenAI, vous pouvez utiliser le format de compatibilité :

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 使用 APIYI 统一接口
)

# OpenAI 兼容格式自动处理 role
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "user", "content": "什么是神经网络?"}
    ]
)

print(response.choices[0].message.content)

Le cas particulier du mode Vertex AI Express

Qu'est-ce que le mode Vertex AI Express ?

Le mode Vertex AI Express est une option intermédiaire entre AI Studio et le Vertex AI standard :

Caractéristique AI Studio Vertex AI Express Vertex AI Standard
Méthode d'authentification Clé API Clé API Compte de service
Limites de débit Basiques Niveau production Niveau production
Licence commerciale Non Oui Oui
Exigence role Optionnel Requis Requis
Endpoint generativelanguage aiplatform aiplatform

Exigences du champ role en mode Express

Même si le mode Express utilise l'authentification par clé API (identique à AI Studio), il hérite des exigences de format strictes de Vertex AI : le champ role est obligatoire.

# Express Mode 示例 - role 必填
import requests

url = "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent"

headers = {
    "Content-Type": "application/json",
    "X-Goog-Api-Key": "YOUR_API_KEY"
}

data = {
    "contents": [
        {
            "role": "user",  # 必须包含!
            "parts": [{"text": "Hello World"}]
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

Guide de dépannage des erreurs courantes

Erreur 1 : Please use a valid role: user, model

Cause : Le champ role est manquant dans les objets du tableau contents.

Solution :

{
  "contents": [
    {
+     "role": "user",
      "parts": [{"text": "..."}]
    }
  ]
}

Erreur 2 : Invalid role value

Cause : Le champ role utilise une valeur non valide (comme "system" ou "assistant").

Solution : Vertex AI n'accepte que user et model. Il ne reconnaît pas system ou assistant dans le tableau des contenus.

{
  "contents": [
    {
-     "role": "assistant",
+     "role": "model",
      "parts": [{"text": "..."}]
    }
  ]
}

Erreur 3 : Mauvais emplacement des instructions système (System instructions)

Cause : Le prompt système a été placé dans contents au lieu du champ spécifique systemInstruction.

Solution :

{
  "systemInstruction": {
    "parts": [{"text": "Tu es un consultant technique professionnel."}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Aide-moi à comprendre ce qu'est une API."}]
    }
  ]
}

💰 Optimisation des coûts : Pour les projets qui nécessitent des tests fréquents sur le format de l'API, vous pouvez envisager de passer par la plateforme APIYI (apiyi.com). Elle propose des modes de facturation flexibles et des tarifs plus avantageux, ce qui est parfait pour les petites et moyennes équipes ou les développeurs solos en phase de développement et de débogage.

Liste de vérification pour la migration

Lors du passage d'AI Studio à Vertex AI, utilisez cette liste pour vous assurer que le format de vos requêtes est correct :

Éléments à modifier obligatoirement

Élément Format AI Studio Format Vertex AI
Champ role Peut être omis Doit être ajouté "role": "user"
URL du point de terminaison generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Méthode d'authentification x-goog-api-key Authorization: Bearer
Chemin du modèle models/gemini-pro publishers/google/models/gemini-pro

Exemple de migration de code

Avant (AI Studio) :

import google.generativeai as genai

genai.configure(api_key="VOTRE_CLE_API")
model = genai.GenerativeModel('gemini-pro')
response = model.generate_content("Bonjour")

Après (Vertex AI) :

from google import genai
from google.genai.types import Content, Part

client = genai.Client(vertexai=True, project="votre-projet", location="us-central1")

contents = [
    Content(role="user", parts=[Part(text="Bonjour")])  # role obligatoire
]

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=contents
)

Gestion du rôle dans les requêtes multimodales

Requêtes Image + Texte

Lors de l'envoi d'une requête multimodale contenant des images, il est également nécessaire de spécifier le role :

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Décris le contenu de cette image"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        }
      ]
    }
  ]
}

Utilisation de fichiers Cloud Storage

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Analyse le contenu principal de cette vidéo"},
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://your-bucket/video.mp4"
          }
        }
      ]
    }
  ]
}

vertex-ai-role-error-400-solution-aistudio-difference-fr 图示

FAQ – Foire Aux Questions

Q1 : Pourquoi AI Studio permet-il d'omettre le rôle alors que Vertex AI ne le permet pas ?

AI Studio est conçu comme un outil de prototypage rapide, ses exigences en matière de format sont donc plus souples. En revanche, Vertex AI, en tant que plateforme de production d'entreprise, impose un format de requête strict pour garantir la stabilité et la maintenabilité du système. Vous pouvez obtenir des crédits de test gratuits sur la plateforme APIYI (apiyi.com) pour vérifier rapidement les exigences de format des différentes plateformes.

Q2 : Vertex AI prend-il en charge le rôle system ?

Non. Le champ role de Vertex AI n'accepte que deux valeurs : user et model. Les instructions système doivent être spécifiées dans un champ distinct nommé systemInstruction :

{
  "systemInstruction": {
    "parts": [{"text": "Votre invite système"}]
  },
  "contents": [...]
}

Q3 : Comment mapper le rôle assistant du format OpenAI ?

Dans le format OpenAI, le rôle assistant correspond au rôle model dans Vertex AI. Si vous utilisez l'interface unifiée d'APIYI (apiyi.com), ce mapping est géré automatiquement.

Q4 : Comment tester rapidement si le format de ma requête est correct ?

Voici les méthodes recommandées pour une vérification rapide :

  1. Utiliser la plateforme APIYI : elle propose une validation du format des requêtes et des messages d'erreur.
  2. Utiliser la console Google Cloud : Vertex AI Studio offre une interface de test visuelle.
  3. Tests Mock locaux : validez d'abord la logique avec AI Studio, puis modifiez le format pour la migration vers Vertex AI.

Q5 : Le format est-il le même pour le mode Express de Vertex AI et le mode standard ?

Oui, le format du corps de la requête est strictement identique pour les deux, et les deux exigent la présence du champ role. La différence principale réside dans la méthode d'authentification (Clé API vs Compte de service).

Résumé

Les différences de format du corps de requête entre Vertex AI et AI Studio concernent principalement le caractère obligatoire du champ role :

Plateforme Exigences du champ role Valeurs valides
AI Studio Optionnel pour un tour simple, obligatoire pour le multi-tour user, model
Vertex AI Toujours obligatoire user, model
Vertex AI Express Toujours obligatoire user, model

Étapes clés pour résoudre l'erreur 400 :

  1. Assurez-vous que chaque objet contents inclut "role": "user" ou "role": "model".
  2. Utilisez le champ systemInstruction pour les instructions système au lieu du champ role.
  3. Mappez le rôle assistant du format OpenAI vers model.

Nous vous recommandons de tester rapidement via APIYI (apiyi.com). Cette plateforme gère automatiquement les problèmes de compatibilité entre les différents formats d'API, vous permettant de vous concentrer pleinement sur le développement de votre logique métier.

Lecture complémentaire :

  • Documentation officielle Vertex AI : cloud.google.com/vertex-ai/docs
  • Référence de l'API Gemini : ai.google.dev/api
  • Guide de migration : cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai

📝 Auteur : Équipe technique APIYI | Spécialiste de l'intégration et de l'optimisation des API de grands modèles de langage
🔗 Échanges techniques : Visitez APIYI (apiyi.com) pour obtenir plus de ressources techniques et un support au développement.

Laisser un commentaire