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

Vertex AI 400-Fehler beheben: 3 Arten von Problemen im Request-Body-Format aufgrund von Unterschieden im role-Parameter

von

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

Bei der Verwendung der Google Gemini API ist der Wechsel von AI Studio zu Vertex AI für viele Entwickler ein notwendiger Schritt. Doch ein scheinbar einfacher Unterschied beim Parameter role lässt unzählige Entwickler stolpern:

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

Der Hauptgrund für diesen 400-Fehler ist: Vertex AI setzt zwingend voraus, dass jedes Objekt im contents-Array ein role-Feld enthält, während AI Studio dieses bei Einzelrunden-Dialogen optional behandelt.

In diesem Artikel analysieren wir die Unterschiede im Format des Request-Bodys zwischen Vertex AI und AI Studio und bieten Lösungen für drei gängige Szenarien.

Kernunterschiede zwischen Vertex AI und AI Studio im Überblick

Bevor wir den 400-Fehler beheben, müssen wir die grundlegenden Unterschiede zwischen den beiden Plattformen verstehen.

Plattform-Positionierung

Vergleichsdimension AI Studio (Google AI) Vertex AI
Zielgruppe Schnelle Prototypenerstellung für Entwickler Enterprise-Bereitstellung
Authentifizierung API-Key Service Account / OAuth
Ratenbegrenzung Basis-Limits, nicht für kommerzielle Nutzung Enterprise-Limits, kommerzieller Support
role-Feld Bei Einzelrunden optional Zwingend erforderlich
Endpunkt-Format generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Verfügbarkeit APIYI apiyi.com, Offizielle API APIYI apiyi.com, Google Cloud

Warum der role 400-Fehler auftritt

Vertex AI führt als Enterprise-Plattform eine strengere Validierung der Anfrageformate durch. Wenn das role-Feld in Ihrem Request-Body fehlt, gibt Vertex AI sofort folgende Fehlermeldung zurück:

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

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

🎯 Technischer Tipp: Wenn Sie von AI Studio zu Vertex AI migrieren, empfehlen wir, Tests über die Plattform APIYI (apiyi.com) durchzuführen. Diese Plattform bietet ein einheitliches API-Format und gleicht Parameterunterschiede automatisch aus, was die Validierung technischer Lösungen erheblich beschleunigt.

Vertex AI Request Body Format im Detail

Das korrekte Vertex AI Anfrageformat

Der Request Body für die Gemini API von Vertex AI muss zwingend der folgenden Struktur entsprechen:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Erkläre mir kurz, was ein großes Sprachmodell ist."
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 2048
  }
}

Gültige Werte für den Parameter role

Vertex AI akzeptiert nur zwei Werte für role:

role Wert Bedeutung Einsatzszenario
user Benutzereingabe Fragen oder Anweisungen, die an das Modell gesendet werden
model Modellantwort Historische Antworten in einer Multi-Turn-Konversation

Falsches Beispiel vs. Richtiges Beispiel

❌ FALSCH: Fehlendes role-Feld (AI Studio Stil)

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

✅ RICHTIG: Inklusive role-Feld (Vertex AI Stil)

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

AI Studio Request Body Format im Detail

Der flexible Modus von AI Studio

AI Studio (Google AI) ist bei den Anforderungen an das Anfrageformat etwas lockerer. In Single-Turn-Szenarien (einzelne Anfrage) kann das Feld role weggelassen werden:

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

Vergleich der Request Bodies beider Plattformen

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

Feld AI Studio Vertex AI
contents Erforderlich Erforderlich
contents[].role Optional (Single-Turn) Erforderlich
contents[].parts Erforderlich Erforderlich
contents[].parts[].text Erforderlich Erforderlich
systemInstruction Unterstützt Unterstützt
generationConfig Optional Optional

Szenario für Multi-Turn-Konversationen

In Multi-Turn-Konversationen (Dialogen) gleichen sich die Formate beider Plattformen an. In diesem Fall muss die role explizit angegeben werden:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Hallo, bitte stell dich kurz vor."}]
    },
    {
      "role": "model",
      "parts": [{"text": "Hallo! Ich bin Gemini, ein von Google entwickeltes KI-Modell..."}]
    },
    {
      "role": "user",
      "parts": [{"text": "Was sind deine Hauptfunktionen?"}]
    }
  ]
}

Vollständige Lösungen für 3 Szenarien

Szenario 1: Python SDK Aufruf von Vertex AI

Bei der Verwendung des offiziellen Python SDK von Google müssen Sie sicherstellen, dass der Parameter role korrekt übergeben wird:

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)

Szenario 2: Direkter Aufruf über die REST API

Direkter Aufruf der Vertex AI REST API mit curl oder einem HTTP-Client:

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
    }
  }'

💡 Schnellstart: Wir empfehlen die Plattform APIYI (apiyi.com) für den schnellen Prototypenbau. Diese Plattform bietet sofort einsatzbereite API-Schnittstellen, die Formatunterschiede zwischen Vertex AI und AI Studio einheitlich behandeln. Keine komplexe Konfiguration erforderlich, die Integration ist in 5 Minuten abgeschlossen.

Szenario 3: Aufruf im OpenAI-kompatiblen Format

Falls Ihr Code auf dem OpenAI SDK basiert, können Sie ein kompatibles Format verwenden:

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)

Sonderfall: Vertex AI Express Mode

Was ist der Vertex AI Express Mode?

Der Vertex AI Express Mode ist eine Option, die zwischen AI Studio und dem Standard-Vertex AI liegt:

Eigenschaft AI Studio Vertex AI Express Vertex AI Standard
Authentifizierung API Key API Key Service Account
Rate Limits Basis Produktionsniveau Produktionsniveau
Kommerzielle Lizenz Nein Ja Ja
role-Anforderung Optional Erforderlich Erforderlich
Endpunkt generativelanguage aiplatform aiplatform

role-Anforderung im Express Mode

Obwohl der Express Mode die API-Key-Authentifizierung verwendet (genau wie AI Studio), übernimmt er die strengen Formatanforderungen von Vertex AI: Das Feld role ist obligatorisch.

# 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)

Leitfaden zur Fehlerbehebung

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

Ursache: Das Objekt im Array contents enthält kein role-Feld.

Lösung:

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

Fehler 2: Invalid role value

Ursache: Das Feld role verwendet einen ungültigen Wert (z. B. „system“ oder „assistant“).

Lösung: Vertex AI akzeptiert nur user und model. Es akzeptiert kein system oder assistant.

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

Fehler 3: Falsche Position der Systemanweisungen

Ursache: Die System-Eingabeaufforderung wurde in contents anstatt im Feld systemInstruction platziert.

Lösung:

{
  "systemInstruction": {
    "parts": [{"text": "Du bist ein professioneller technischer Berater."}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Erkläre mir bitte, was eine API ist."}]
    }
  ]
}

💰 Kostenoptimierung: Für Projekte, die häufige Tests von API-Formaten erfordern, kann der Aufruf der API über die Plattform APIYI (apiyi.com) in Betracht gezogen werden. Diese Plattform bietet flexible Abrechnungsmodelle und günstigere Preise, was ideal für kleine und mittlere Teams sowie Einzelentwickler während der Entwicklung und beim Debugging ist.

Checkliste für die Migration

Verwenden Sie bei der Migration von AI Studio zu Vertex AI die folgende Checkliste, um sicherzustellen, dass das Anfrageformat korrekt ist:

Erforderliche Änderungen

Prüfpunkt AI Studio Schreibweise Vertex AI Schreibweise
Feld role Kann weggelassen werden Muss hinzugefügt werden "role": "user"
Endpunkt-URL generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Authentifizierung x-goog-api-key Authorization: Bearer
Modellpfad models/gemini-pro publishers/google/models/gemini-pro

Beispiel für die Codemigration

Vor der Migration (AI Studio):

import google.generativeai as genai

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

Nach der Migration (Vertex AI):

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

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

contents = [
    Content(role="user", parts=[Part(text="Hello")])  # role ist erforderlich
]

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

Role-Handling bei multimodalen Anfragen

Bild- + Textanfragen

Beim Senden von multimodalen Anfragen, die Bilder enthalten, muss ebenfalls die role angegeben werden:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Beschreibe den Inhalt dieses Bildes"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        }
      ]
    }
  ]
}

Verwendung von Cloud Storage-Dateien

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Analysiere den Hauptinhalt dieses Videos"},
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://your-bucket/video.mp4"
          }
        }
      ]
    }
  ]
}

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

Häufig gestellte Fragen (FAQ)

Q1: Warum kann in AI Studio die role weggelassen werden, in Vertex AI jedoch nicht?

AI Studio ist als Tool für die schnelle Prototypenerstellung konzipiert und hat lockerere Formatanforderungen. Vertex AI hingegen ist eine Plattform auf Enterprise-Niveau, die strikte Anfrageformate benötigt, um Systemstabilität und Wartbarkeit zu gewährleisten. Über die Plattform APIYI (apiyi.com) können Sie kostenloses Testguthaben erhalten, um die Formatanforderungen der verschiedenen Plattformen schnell zu validieren.

Q2: Unterstützt Vertex AI die system role?

Nein. Die role in Vertex AI akzeptiert nur die Werte user und model. Systemanweisungen müssen über das separate Feld systemInstruction verwendet werden:

{
  "systemInstruction": {
    "parts": [{"text": "Deine System-Eingabeaufforderung"}]
  },
  "contents": [...]
}

Q3: Wie wird der assistant aus dem OpenAI-Format zugeordnet?

Die assistant-Rolle im OpenAI-Format entspricht der model-Rolle in Vertex AI. Wenn Sie die einheitliche Schnittstelle von APIYI (apiyi.com) nutzen, wird diese Zuordnung automatisch vorgenommen.

Q4: Wie kann ich schnell testen, ob das Anfrageformat korrekt ist?

Wir empfehlen die folgenden Methoden zur schnellen Validierung:

  1. Test über die APIYI-Plattform: Bietet Validierung des Anfrageformats und Fehlermeldungen.
  2. Verwendung der Google Cloud Console: Das Vertex AI Studio bietet eine visuelle Testoberfläche.
  3. Lokaler Mock-Test: Validieren Sie die Logik zuerst mit AI Studio und passen Sie dann das Format für die Migration zu Vertex AI an.

Q5: Ist das Format im Vertex AI Express Mode dasselbe wie im Standardmodus?

Ja, das Format des Request Bodys ist bei beiden völlig identisch; beide erfordern zwingend das Feld role. Der Hauptunterschied liegt in der Authentifizierungsmethode (API Key vs. Service Account).

Zusammenfassung

Die Unterschiede im Format des Request-Bodys zwischen Vertex AI und AI Studio zeigen sich hauptsächlich in den obligatorischen Anforderungen an das role-Feld:

Plattform role-Anforderung Gültige Werte
AI Studio Optional bei Einzel-Turn, erforderlich bei Multi-Turn user, model
Vertex AI Immer erforderlich user, model
Vertex AI Express Immer erforderlich user, model

Zentrale Schritte zur Behebung von 400-Fehlern:

  1. Stellen Sie sicher, dass jedes contents-Objekt "role": "user" oder "role": "model" enthält.
  2. Verwenden Sie für System-Anweisungen das Feld systemInstruction anstelle von role.
  3. Mapen Sie das OpenAI-Format assistant auf model.

Wir empfehlen die schnelle Validierung über APIYI (apiyi.com). Die Plattform verarbeitet Kompatibilitätsprobleme zwischen verschiedenen API-Formaten automatisch, sodass Sie sich ganz auf die Entwicklung Ihrer Geschäftslogik konzentrieren können.

Weiterführende Informationen:

  • Offizielle Vertex AI Dokumentation: cloud.google.com/vertex-ai/docs
  • Gemini API Referenz: ai.google.dev/api
  • Migrationsleitfaden: cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai

📝 Autor: APIYI Technik-Team | Spezialisiert auf die Integration und Optimierung von APIs für Große Sprachmodelle
🔗 Technischer Austausch: Besuchen Sie APIYI unter apiyi.com für weitere technische Ressourcen und Unterstützung bei der Entwicklung.

Schreibe einen Kommentar