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

Исправление ошибки Vertex AI 400: 3 проблемы с форматом тела запроса из-за различий в параметре role

от

При использовании 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 позволяет опускать его при одиночных запросах (single-turn).

В этой статье мы подробно разберем различия в формате тела запроса между Vertex AI и AI Studio и предложим готовые решения для разных сценариев.

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

Обзор ключевых различий между Vertex AI и AI Studio

Прежде чем исправлять ошибку 400, давайте разберемся в фундаментальных отличиях двух платформ.

Различия в позиционировании платформ

Параметр сравнения AI Studio (Google AI) Vertex AI
Целевая аудитория Быстрое прототипирование для разработчиков Корпоративное промышленное развертывание
Способ аутентификации API Key Service Account / OAuth
Лимиты (Rate limits) Базовые, не для коммерции Промышленные, поддержка коммерции
Поле role Можно опустить в одном ходе Обязательно к заполнению
Формат эндпоинта generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Доступные платформы APIYI (apiyi.com), официальный API APIYI (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-ru 图示

🎯 Совет эксперта: При переходе с AI Studio на Vertex AI мы рекомендуем использовать платформу APIYI (apiyi.com) для тестирования вызовов. Эта платформа предоставляет унифицированный интерфейс API и автоматически обрабатывает различия в параметрах между разными площадками, что помогает быстро проверить работоспособность вашего технического решения.

Подробный разбор формата тела запроса Vertex AI

Корректный формат запроса Vertex AI

Тело запроса к Gemini API в Vertex AI должно строго соответствовать следующей структуре:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "解释一下什么是大语言模型"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 2048
  }
}

Допустимые значения параметра role

Vertex AI принимает только два значения для поля role:

Значение role Значение Сценарий использования
user Ввод пользователя Вопросы или инструкции, отправляемые модели
model Ответ модели История ответов в многораундовом диалоге

Примеры: как неправильно и как правильно

❌ Ошибка: отсутствует поле 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-ru 图示

Поле 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: Вызов Vertex AI через Python SDK

При использовании официального Python SDK от Google убедитесь, что вы правильно передаете параметр 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

Прямой вызов Vertex AI REST API с помощью curl или любого HTTP-клиента:

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

💡 Быстрый старт: Для быстрой сборки прототипов рекомендуем платформу APIYI (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"  # Используем унифицированный интерфейс APIYI
)

# Формат, совместимый с 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-ключ API-ключ Сервисный аккаунт
Лимиты (Rate limits) Базовые Промышленный уровень Промышленный уровень
Коммерческая лицензия Нет Да Да
Требования к role Необязательно Обязательно Обязательно
Эндпоинт generativelanguage aiplatform aiplatform

Требования к параметру role в Express Mode

Хотя Express Mode использует аутентификацию по API-ключу (как и 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.

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

Ошибка 3: Неверное расположение System instructions

Причина: системный промпт размещен в contents вместо поля systemInstruction.

Решение:

{
  "systemInstruction": {
    "parts": [{"text": "Ты — профессиональный технический консультант"}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Объясни мне, что такое API"}]
    }
  ]
}

💰 Оптимизация затрат: Для проектов, требующих частого тестирования форматов API, можно рассмотреть вызов через платформу APIYI (apiyi.com). Она предлагает гибкую тарификацию и более выгодные цены, что отлично подходит для небольших команд и индивидуальных разработчиков в процессе отладки.

Чек-лист для миграции

При переходе с 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-ru 图示

Часто задаваемые вопросы (FAQ)

Q1: Почему в AI Studio можно пропустить role, а в Vertex AI — нет?

AI Studio задумывался как инструмент для быстрого прототипирования, поэтому требования к формату там довольно гибкие. Vertex AI, напротив, является корпоративной платформой, где важна строгая структура запросов для обеспечения стабильности и удобства поддержки системы. На платформе APIYI (apiyi.com) можно получить бесплатные тестовые кредиты, чтобы быстро проверить требования к форматам на разных площадках.

Q2: Поддерживает ли Vertex AI роль system?

Нет, не поддерживает. В Vertex AI поле role принимает только два значения: user и model. Для системных указаний нужно использовать отдельное поле systemInstruction:

{
  "systemInstruction": {
    "parts": [{"text": "Ваш системный промпт"}]
  },
  "contents": [...]
}

Q3: Как маппится роль assistant из формата OpenAI?

Роль assistant в формате OpenAI соответствует роли model в Vertex AI. Если вы используете унифицированный интерфейс APIYI (apiyi.com), этот маппинг выполняется автоматически.

Q4: Как быстро проверить правильность формата запроса?

Рекомендуем следующие способы проверки:

  1. Тестирование через платформу APIYI: система проверит формат запроса и подскажет, если есть ошибки.
  2. Google Cloud Console: в Vertex AI Studio есть визуальный интерфейс для тестов.
  3. Локальное Mock-тестирование: сначала отладьте логику в AI Studio, а затем адаптируйте формат для миграции в Vertex AI.

Q5: Одинаков ли формат запросов для Vertex AI Express Mode и стандартного режима?

Да, структура тела запроса (request body) в обоих случаях идентична и требует обязательного указания поля role. Основная разница заключается в способе аутентификации (API Key против 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 вместо роли для системных промптов.
  3. Маппите assistant из формата OpenAI в model.

Чтобы не тратить время на ручную настройку, рекомендуем использовать APIYI (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 | Специализируемся на интеграции и оптимизации больших языковых моделей
🔗 Техническая поддержка: Посетите APIYI (apiyi.com) для получения ресурсов и помощи в разработке

Оставьте комментарий