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

Solución de errores 400 de Vertex AI: 3 problemas de formato del cuerpo de la solicitud causados por diferencias en el parámetro role

por

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

Al usar la API de Google Gemini, migrar de AI Studio a Vertex AI es un paso obligatorio para muchos desarrolladores. Sin embargo, una diferencia aparentemente simple en el parámetro role ha hecho tropezar a muchísimos desarrolladores:

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

La causa principal del error 400 es que Vertex AI exige que cada objeto en el array contents incluya el campo role, mientras que AI Studio permite omitirlo en diálogos de una sola ronda.

En este artículo, analizaremos a fondo las diferencias en el formato del cuerpo de la solicitud entre Vertex AI y AI Studio, y ofreceremos soluciones completas para 3 escenarios comunes.

Resumen de diferencias clave entre Vertex AI y AI Studio

Antes de solucionar el error 400, necesitamos entender las diferencias fundamentales entre ambas plataformas.

Diferencias de posicionamiento

Dimensión comparativa AI Studio (Google AI) Vertex AI
Usuario objetivo Prototipado rápido para desarrolladores Despliegue de producción empresarial
Método de autenticación API Key Cuenta de servicio / OAuth
Límites de velocidad Límites básicos, no comercial Límites de nivel de producción, comercial
Campo role Opcional en diálogos de una sola ronda Obligatorio
Formato del endpoint generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Plataformas disponibles APIYI apiyi.com, API oficial APIYI apiyi.com, Google Cloud

¿Por qué ocurre el error role 400?

Como plataforma empresarial, Vertex AI es mucho más estricta con la validación del formato de las solicitudes. Cuando falta el campo role en el cuerpo de tu solicitud, Vertex AI devuelve inmediatamente:

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

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

🎯 Consejo técnico: Al migrar de AI Studio a Vertex AI, te recomendamos realizar pruebas de llamadas a la interfaz a través de la plataforma APIYI apiyi.com. Esta plataforma ofrece un formato de interfaz API unificado que procesa automáticamente las diferencias de parámetros entre distintas plataformas, ayudándote a validar rápidamente la viabilidad de tu solución técnica.

Detalles del formato del cuerpo de la solicitud en Vertex AI

Formato correcto de solicitud para Vertex AI

El cuerpo de la solicitud (request body) de la API de Gemini en Vertex AI debe seguir la siguiente estructura:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Explica qué es un Modelo de Lenguaje Grande"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 2048
  }
}

Valores válidos para el parámetro role

Vertex AI solo acepta dos valores para role:

Valor de role Significado Caso de uso
user Entrada del usuario Preguntas o instrucciones enviadas al modelo
model Respuesta del modelo Respuestas históricas en una conversación multivuelta

Ejemplo incorrecto vs. Ejemplo correcto

❌ Incorrecto: Falta el campo role (estilo AI Studio)

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

✅ Correcto: Incluye el campo role (estilo Vertex AI)

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

Detalles del formato del cuerpo de la solicitud en AI Studio

Modo flexible de AI Studio

AI Studio (Google AI) es relativamente más flexible con los requisitos de formato. En escenarios de una sola ronda de conversación, se puede omitir el campo role:

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

Comparación del cuerpo de la solicitud entre ambas plataformas

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

Campo AI Studio Vertex AI
contents Obligatorio Obligatorio
contents[].role Opcional (ronda única) Obligatorio
contents[].parts Obligatorio Obligatorio
contents[].parts[].text Obligatorio Obligatorio
systemInstruction Soportado Soportado
generationConfig Opcional Opcional

Escenario de conversación multivuelta

En conversaciones multivuelta, los formatos de ambas plataformas tienden a ser consistentes, ya que ambas requieren especificar claramente el role:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Hola, por favor preséntate"}]
    },
    {
      "role": "model",
      "parts": [{"text": "¡Hola! Soy Gemini, un asistente de IA desarrollado por Google..."}]
    },
    {
      "role": "user",
      "parts": [{"text": "¿Qué puedes hacer?"}]
    }
  ]
}

3 soluciones completas para diferentes escenarios

Escenario 1: Llamada a Vertex AI desde el SDK de Python

Al usar el SDK oficial de Google para Python, asegúrate de pasar correctamente el parámetro 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)

Escenario 2: Llamada directa a través de la REST API

Usa curl o un cliente HTTP para llamar directamente a la REST API 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
    }
  }'

💡 Inicio rápido: Te recomendamos usar la plataforma APIYI (apiyi.com) para crear prototipos rápidamente. Esta plataforma ofrece interfaces API listas para usar que gestionan de forma unificada las diferencias de formato entre Vertex AI y AI Studio, sin configuraciones complejas y permitiendo completar la integración en solo 5 minutos.

Escenario 3: Llamada con formato compatible con OpenAI

Si tu código se basa en el SDK de OpenAI, puedes utilizar el formato compatible:

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)

Casos especiales de Vertex AI Express Mode

¿Qué es Vertex AI Express Mode?

Vertex AI Express Mode es una opción intermedia entre AI Studio y el Vertex AI estándar:

Característica AI Studio Vertex AI Express Vertex AI Standard
Método de autenticación API Key API Key Service Account
Límites de velocidad Básico Grado de producción Grado de producción
Licencia comercial No Sí Sí
Requisito de role Opcional Obligatorio Obligatorio
Endpoint generativelanguage aiplatform aiplatform

Requisitos de role en Express Mode

Aunque Express Mode utiliza autenticación por API Key (igual que AI Studio), sigue heredando los estrictos requisitos de formato de Vertex AI: el campo role es obligatorio.

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

Guía de resolución de problemas comunes

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

Causa: Los objetos dentro del array contents no tienen el campo role.

Solución:

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

Error 2: Invalid role value

Causa: Se ha utilizado un valor no válido en el campo role (como "system" o "assistant").

Solución: Vertex AI solo acepta user y model; no admite system ni assistant dentro de contents.

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

Error 3: Posición incorrecta de System instructions

Causa: Colocar la indicación de sistema (system prompt) dentro de contents en lugar de usar el campo systemInstruction.

Solución:

{
  "systemInstruction": {
    "parts": [{"text": "Eres un consultor técnico profesional"}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Ayúdame a explicar qué es una API"}]
    }
  ]
}

💰 Optimización de costos: Para proyectos que requieren pruebas frecuentes del formato de la API, puedes considerar llamar a la API a través de la plataforma APIYI (apiyi.com). Esta plataforma ofrece métodos de facturación flexibles y precios más competitivos, ideales para equipos pequeños, medianos y desarrolladores individuales durante la fase de desarrollo y depuración.

Lista de verificación para la migración

Al migrar de AI Studio a Vertex AI, utiliza la siguiente lista para asegurarte de que el formato de tus solicitudes sea el correcto:

Elementos que deben modificarse

Ítem de verificación Formato en AI Studio Formato en Vertex AI
Campo role Puede omitirse Debe añadirse "role": "user"
URL del endpoint generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Método de autenticación x-goog-api-key Authorization: Bearer
Ruta del modelo models/gemini-pro publishers/google/models/gemini-pro

Ejemplo de migración de código

Antes de la migración (AI Studio):

import google.generativeai as genai

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

Después de la migración (Vertex AI):

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

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

contents = [
    Content(role="user", parts=[Part(text="Hola")])  # role es obligatorio
]

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

Manejo del role en solicitudes multimodales

Solicitudes de imagen + texto

Al enviar una solicitud multimodal que incluya imágenes, también es necesario especificar el role:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "描述这张图片的内容"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        }
      ]
    }
  ]
}

Uso de archivos de 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-es 图示

Preguntas frecuentes (FAQ)

Q1: ¿Por qué AI Studio puede omitir el role y Vertex AI no?

AI Studio está diseñado como una herramienta de prototipado rápido, por lo que sus requisitos de formato son más flexibles. En cambio, Vertex AI, al ser una plataforma de producción de nivel empresarial, exige un formato de solicitud estricto para garantizar la estabilidad y mantenibilidad del sistema. A través de la plataforma APIYI (apiyi.com) puedes obtener créditos de prueba gratuitos para verificar rápidamente los requisitos de formato en diferentes plataformas.

Q2: ¿Soporta Vertex AI el role de "system"?

No. El role en Vertex AI solo acepta los valores user y model. Las instrucciones del sistema deben enviarse a través del campo independiente systemInstruction:

{
  "systemInstruction": {
    "parts": [{"text": "Tu indicación del sistema"}]
  },
  "contents": [...]
}

Q3: ¿Cómo se mapea el role "assistant" del formato de OpenAI?

El role assistant del formato OpenAI corresponde al role model en Vertex AI. Si utilizas la interfaz unificada de APIYI (apiyi.com), este mapeo se realiza automáticamente.

Q4: ¿Cómo puedo probar rápidamente si el formato de mi solicitud es correcto?

Te recomendamos los siguientes métodos para una validación rápida:

  1. Usar la plataforma APIYI: Ofrece validación de formato y mensajes de error detallados.
  2. Usar Google Cloud Console: El Vertex AI Studio proporciona una interfaz de prueba visual.
  3. Pruebas Mock locales: Valida primero la lógica en AI Studio y luego ajusta el formato para migrar a Vertex AI.

Q5: ¿Es el formato de Vertex AI Express Mode igual al del modo estándar?

Sí, el formato del cuerpo de la solicitud es exactamente el mismo; ambos requieren incluir el campo role. La diferencia principal radica en el método de autenticación (API Key frente a Service Account).

Resumen

Las diferencias en el formato del cuerpo de la solicitud entre Vertex AI y AI Studio se centran principalmente en la obligatoriedad del campo role:

Plataforma Requisitos de role Valores válidos
AI Studio Opcional en una sola ronda, obligatorio en varias rondas user, model
Vertex AI Siempre obligatorio user, model
Vertex AI Express Siempre obligatorio user, model

Pasos clave para solucionar el error 400:

  1. Asegúrate de que cada objeto contents incluya "role": "user" o "role": "model".
  2. Usa el campo systemInstruction para las instrucciones del sistema en lugar de role.
  3. Mapea el rol assistant del formato de OpenAI a model.

Te recomendamos usar APIYI (apiyi.com) para validar los resultados rápidamente. Esta plataforma gestiona automáticamente los problemas de compatibilidad entre diferentes formatos de API, permitiéndote concentrarte en el desarrollo de la lógica de tu negocio.

Lectura adicional:

  • Documentación oficial de Vertex AI: cloud.google.com/vertex-ai/docs
  • Referencia de la API de Gemini: ai.google.dev/api
  • Guía de migración: cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai

📝 Autor: Equipo técnico de APIYI | Especialistas en integración y optimización de APIs para Modelos de Lenguaje Grande
🔗 Intercambio técnico: Visita APIYI (apiyi.com) para obtener más recursos técnicos y soporte de desarrollo.

Deja un comentario