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

解決 Vertex AI 400 錯誤:role 參數差異導致的 3 種請求體格式問題

作者:

vertex-ai-role-error-400-solution-aistudio-difference-zh-hant 图示

在使用 Google Gemini API 時，從 AI Studio 遷移到 Vertex AI 是許多開發者的必經之路。然而，一個看似簡單的 role 參數差異，卻讓無數開發者栽了跟頭:

[&{Please use a valid role: user， model. （request id: xxx） 400 }]

這個 400 錯誤的根本原因是:Vertex AI 強制要求 contents 數組中的每個對象必須包含 role 字段，而 AI Studio 在單輪對話中可以省略。

本文將深入剖析 Vertex AI 和 AI Studio 的請求體格式差異，提供 3 種場景的完整解決方案。

Vertex AI 和 AI Studio 的核心差異概覽

在解決 400 錯誤之前，我們需要先理解兩個平臺的本質區別。

平臺定位差異

對比維度 AI Studio （Google AI） Vertex AI
目標用戶 開發者快速原型驗證 企業級生產部署
認證方式 API Key Service Account / OAuth
速率限制 基礎限制，不可商用 生產級限制，支持商用
role 字段 單輪對話可省略 強制必填
端點格式 generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
可用平臺 API易 apiyi.com， 官方 API API易 apiyi.com， Google Cloud

爲什麼會出現 role 400 錯誤

Vertex AI 作爲企業級平臺，對請求格式的校驗更爲嚴格。當你的請求體中缺少 role 字段時，Vertex AI 會立即返回:

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

vertex-ai-role-error-400-solution-aistudio-difference-zh-hant 图示

🎯 技術建議: 在從 AI Studio 遷移到 Vertex AI 時，我們建議通過 API易 apiyi.com 平臺進行接口調用測試。該平臺提供統一的 API 接口格式，自動處理不同平臺的參數差異，有助於快速驗證技術方案的可行性。

Vertex AI 請求體格式詳解

正確的 Vertex AI 請求格式

Vertex AI 的 Gemini API 請求體必須遵循以下結構:

{
  "contents": [
    {
      "role": "user"，
      "parts": [
        {
          "text": "解釋一下什麼是大語言模型"
        }
      ]
    }
  ]，
  "generationConfig": {
    "temperature": 0.7，
    "maxOutputTokens": 2048
  }
}

role 參數的有效值

Vertex AI 只接受兩個 role 值:

role 值 含義 使用場景
user 用戶輸入 發送給模型的問題或指令
model 模型響應 多輪對話中的歷史回覆

錯誤示例 vs 正確示例

❌ 錯誤:缺少 role 字段 （AI Studio 風格）

{
  "contents": [
    {
      "parts": [
        {
          "text": "Hello， how are you？"
        }
      ]
    }
  ]
}

✅ 正確:包含 role 字段 （Vertex AI 風格）

{
  "contents": [
    {
      "role": "user"，
      "parts": [
        {
          "text": "Hello， how are you？"
        }
      ]
    }
  ]
}

AI Studio 請求體格式詳解

AI Studio 的寬鬆模式

AI Studio （Google AI） 對請求格式的要求相對寬鬆，在單輪對話場景下可以省略 role 字段:

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

兩個平臺的請求體對比

vertex-ai-role-error-400-solution-aistudio-difference-zh-hant 图示

字段 AI Studio Vertex AI
contents 必填 必填
contents[].role 可選 （單輪） 必填
contents[].parts 必填 必填
contents[].parts[].text 必填 必填
systemInstruction 支持 支持
generationConfig 可選 可選

多輪對話場景

在多輪對話中，兩個平臺的格式趨於一致，都需要明確指定 role:

{
  "contents": [
    {
      "role": "user"，
      "parts": [{"text": "你好，請介紹一下自己"}]
    }，
    {
      "role": "model"，
      "parts": [{"text": "你好！我是 Gemini，由 Google 開發的 AI 助手..."}]
    }，
    {
      "role": "user"，
      "parts": [{"text": "你能做什麼？"}]
    }
  ]
}

3 種場景的完整解決方案

場景 1:Python SDK 調用 Vertex AI

使用 Google 官方 Python SDK 時，確保正確傳遞 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）

場景 2:REST API 直接調用

使用 curl 或 HTTP 客戶端直接調用 Vertex AI REST API:

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

💡 快速開始: 推薦使用 API易 apiyi.com 平臺快速搭建原型。該平臺提供開箱即用的 API 接口，統一處理 Vertex AI 和 AI Studio 的格式差異，無需複雜配置，5 分鐘即可完成集成。

場景 3:OpenAI 兼容格式調用

如果你的代碼基於 OpenAI SDK，可以使用兼容格式:

import openai

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"  # 使用 API易 統一接口
）

# OpenAI 兼容格式自動處理 role
response = client.chat.completions.create（
    model="gemini-2.0-flash"，
    messages=[
        {"role": "user"， "content": "什麼是神經網絡？"}
    ]
）

print（response.choices[0].message.content）

Vertex AI Express Mode 的特殊情況

什麼是 Vertex AI Express Mode

Vertex AI Express Mode 是一個介於 AI Studio 和標準 Vertex AI 之間的選項:

特性 AI Studio Vertex AI Express Vertex AI Standard
認證方式 API Key API Key Service Account
速率限制 基礎 生產級 生產級
商用許可 否 是 是
role 要求 可選 必填 必填
端點 generativelanguage aiplatform aiplatform

Express Mode 的 role 要求

即使 Express Mode 使用 API Key 認證（與 AI Studio 相同），它仍然繼承了 Vertex AI 的嚴格格式要求，role 字段必填。

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

常見錯誤排查指南

錯誤 1:Please use a valid role: user， model

原因: contents 數組中的對象缺少 role 字段

解決方案:

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

錯誤 2:Invalid role value

原因: role 字段使用了無效值（如 "system"、"assistant"）

解決方案: Vertex AI 只接受 user 和 model，不接受 system 或 assistant

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

錯誤 3:System instructions 位置錯誤

原因: 將 system prompt 放在 contents 中而非 systemInstruction 字段

解決方案:

{
  "systemInstruction": {
    "parts": [{"text": "你是一個專業的技術顧問"}]
  }，
  "contents": [
    {
      "role": "user"，
      "parts": [{"text": "幫我解釋一下 API 是什麼"}]
    }
  ]
}

💰 成本優化: 對於需要頻繁測試 API 格式的項目，可以考慮通過 API易 apiyi.com 平臺調用 API。該平臺提供靈活的計費方式和更優惠的價格，適合中小團隊和個人開發者進行開發調試。

遷移檢查清單

從 AI Studio 遷移到 Vertex AI 時，使用以下清單確保請求格式正確:

必須修改的項目

檢查項 AI Studio 寫法 Vertex AI 寫法
role 字段 可省略 必須添加 "role": "user"
端點 URL generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
認證方式 x-goog-api-key Authorization: Bearer
模型路徑 models/gemini-pro publishers/google/models/gemini-pro

代碼遷移示例

遷移前 （AI Studio）:

import google.generativeai as genai

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

遷移後 （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 必填
]

response = client.models.generate_content（
    model="gemini-2.0-flash"，
    contents=contents
）

多模態請求的 role 處理

圖片 + 文本請求

發送包含圖片的多模態請求時，同樣需要指定 role:

{
  "contents": [
    {
      "role": "user"，
      "parts": [
        {"text": "描述這張圖片的內容"}，
        {
          "inlineData": {
            "mimeType": "image/jpeg"，
            "data": "BASE64_ENCODED_IMAGE"
          }
        }
      ]
    }
  ]
}

使用 Cloud Storage 文件

{
  "contents": [
    {
      "role": "user"，
      "parts": [
        {"text": "分析這個視頻的主要內容"}，
        {
          "fileData": {
            "mimeType": "video/mp4"，
            "fileUri": "gs://your-bucket/video.mp4"
          }
        }
      ]
    }
  ]
}

vertex-ai-role-error-400-solution-aistudio-difference-zh-hant 图示

常見問題解答 FAQ

Q1: 爲什麼 AI Studio 可以省略 role，Vertex AI 不行？

AI Studio 設計爲快速原型驗證工具，對格式要求較爲寬鬆。而 Vertex AI 作爲企業級生產平臺，需要嚴格的請求格式以確保系統穩定性和可維護性。通過 API易 apiyi.com 平臺可以獲取免費測試額度，快速驗證不同平臺的格式要求。

Q2: Vertex AI 支持 system role 嗎？

不支持。Vertex AI 的 role 只接受 user 和 model 兩個值。系統指令需要使用單獨的 systemInstruction 字段:

{
  "systemInstruction": {
    "parts": [{"text": "你的系統提示詞"}]
  }，
  "contents": [...]
}

Q3: OpenAI 格式的 assistant 如何映射？

在 OpenAI 格式中的 assistant role 對應 Vertex AI 的 model role。如果你使用 API易 apiyi.com 的統一接口，這種映射會自動處理。

Q4: 如何快速測試請求格式是否正確？

推薦使用以下方法快速驗證:

  1. 使用 API易平臺測試: 提供請求格式校驗和錯誤提示
  2. 使用 Google Cloud Console: Vertex AI Studio 提供可視化測試界面
  3. 本地 Mock 測試: 先用 AI Studio 驗證邏輯，再修改格式遷移到 Vertex AI

Q5: Vertex AI Express Mode 和標準模式的格式一樣嗎？

是的，兩者的請求體格式完全相同，都要求必須包含 role 字段。主要區別在於認證方式（API Key vs Service Account）。

總結

Vertex AI 和 AI Studio 的請求體格式差異主要體現在 role 字段的強制性要求上:

平臺 role 要求 有效值
AI Studio 單輪可選，多輪必填 user， model
Vertex AI 始終必填 user， model
Vertex AI Express 始終必填 user， model

解決 400 錯誤的核心步驟:

  1. 確保每個 contents 對象都包含 "role": "user" 或 "role": "model"
  2. 系統指令使用 systemInstruction 字段而非 role
  3. 將 OpenAI 格式的 assistant 映射爲 model

推薦通過 API易 apiyi.com 快速驗證效果，該平臺自動處理不同 API 格式的兼容性問題，讓你專注於業務邏輯開發。

延伸閱讀:

  • Vertex AI 官方文檔: cloud.google.com/vertex-ai/docs
  • Gemini API 參考: ai.google.dev/api
  • 遷移指南: cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai

📝 作者: APIYI 技術團隊 | 專注 AI 大模型 API 集成與優化
🔗 技術交流: 訪問 API易 apiyi.com 獲取更多技術資源和開發支持

發佈留言