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

Resolvendo o erro 400 do Vertex AI: 3 tipos de problemas de formato do corpo da requisição causados por diferenças no parâmetro role

por

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

Ao usar a API do Google Gemini, migrar do AI Studio para o Vertex AI é um caminho comum para muitos desenvolvedores. No entanto, uma diferença aparentemente simples no parâmetro role faz com que muitos desenvolvedores se atrapalhem:

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

A causa raiz deste erro 400 é: O Vertex AI exige obrigatoriamente que cada objeto no array contents contenha o campo role, enquanto o AI Studio permite omiti-lo em conversas de turno único.

Neste artigo, vamos analisar detalhadamente as diferenças no formato do corpo da requisição entre o Vertex AI e o AI Studio, oferecendo soluções completas para três cenários diferentes.

Visão Geral das Diferenças entre Vertex AI e AI Studio

Antes de resolver o erro 400, precisamos entender a diferença fundamental entre as duas plataformas.

Diferenças de Posicionamento das Plataformas

Dimensão de Comparação AI Studio (Google AI) Vertex AI
Público-alvo Prototipagem rápida para desenvolvedores Implantação de produção empresarial
Método de Autenticação Chave de API (API Key) Service Account / OAuth
Limites de Taxa Limites básicos, não comercial Limites de produção, uso comercial
Campo role Opcional em turno único Obrigatório
Formato do Endpoint generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Plataformas Disponíveis APIYI apiyi.com, API oficial APIYI apiyi.com, Google Cloud

Por que o erro role 400 ocorre?

Como o Vertex AI é uma plataforma de nível corporativo, a validação do formato das requisições é muito mais rigorosa. Quando o campo role está ausente no corpo da sua requisição, o Vertex AI retorna imediatamente:

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

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

🎯 Sugestão Técnica: Ao migrar do AI Studio para o Vertex AI, recomendamos realizar testes de chamada de interface através da plataforma APIYI (apiyi.com). Essa plataforma oferece um formato de interface de API unificado e trata automaticamente as diferenças de parâmetros entre as plataformas, ajudando a validar rapidamente a viabilidade da sua solução técnica.

Detalhes do Formato do Corpo da Requisição no Vertex AI

Formato Correto de Requisição no Vertex AI

O corpo da requisição da API Gemini no Vertex AI deve seguir a seguinte estrutura:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Explique o que é um Grande Modelo de Linguagem"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 2048
  }
}

Valores Válidos para o Parâmetro role

O Vertex AI aceita apenas dois valores para role:

Valor de role Significado Cenário de Uso
user Entrada do usuário Perguntas ou comandos enviados ao modelo
model Resposta do modelo Respostas históricas em conversas de vários turnos

Exemplo Incorreto vs. Exemplo Correto

❌ Erro: Falta o campo role (estilo AI Studio)

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

✅ Correto: Contém o campo role (estilo Vertex AI)

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

Detalhes do Formato do Corpo da Requisição no AI Studio

Modo Flexível do AI Studio

O AI Studio (Google AI) possui requisitos de formato mais flexíveis; em cenários de conversa de turno único, o campo role pode ser omitido:

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

Comparação do Corpo da Requisição entre as Duas Plataformas

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

Campo AI Studio Vertex AI
contents Obrigatório Obrigatório
contents[].role Opcional (Turno único) Obrigatório
contents[].parts Obrigatório Obrigatório
contents[].parts[].text Obrigatório Obrigatório
systemInstruction Suportado Suportado
generationConfig Opcional Opcional

Cenário de Conversa de Vários Turnos

Em conversas de vários turnos, os formatos de ambas as plataformas tendem a ser consistentes, exigindo a especificação explícita do role:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Olá, por favor, apresente-se"}]
    },
    {
      "role": "model",
      "parts": [{"text": "Olá! Eu sou o Gemini, um assistente de IA desenvolvido pelo Google..."}]
    },
    {
      "role": "user",
      "parts": [{"text": "O que você pode fazer?"}]
    }
  ]
}

Soluções completas para 3 cenários

Cenário 1: Chamada do Vertex AI via Python SDK

Ao usar o SDK oficial do Google para Python, certifique-se de passar corretamente o parâmetro role:

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

# Inicializa o cliente
client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)

# Formato de requisição correto - deve incluir o role
contents = [
    Content(
        role="user",
        parts=[Part(text="O que é o Vertex AI?")]
    )
]

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

print(response.text)

Cenário 2: Chamada direta via REST API

Use curl ou um cliente HTTP para chamar diretamente a REST API do 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": "Explique os princípios básicos da computação quântica"}
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

💡 Início rápido: Recomendo usar a plataforma APIYI (apiyi.com) para criar protótipos rapidamente. A plataforma oferece interfaces de API prontas para uso, que tratam de forma unificada as diferenças de formato entre o Vertex AI e o AI Studio, permitindo concluir a integração em 5 minutos sem configurações complexas.

Cenário 3: Chamada via formato compatível com OpenAI

Se o seu código for baseado no SDK da OpenAI, você pode usar o formato de compatibilidade:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Uso da interface unificada da APIYI
)

# O formato compatível com OpenAI processa o role automaticamente
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "user", "content": "O que é uma rede neural?"}
    ]
)

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

Situações especiais do Vertex AI Express Mode

O que é o Vertex AI Express Mode

O Vertex AI Express Mode é uma opção intermediária entre o AI Studio e o Vertex AI padrão:

Recurso AI Studio Vertex AI Express Vertex AI Standard
Método de autenticação API Key API Key Service Account
Limite de taxa Básico Nível de produção Nível de produção
Licença comercial Não Sim Sim
Requisito de role Opcional Obrigatório Obrigatório
Endpoint generativelanguage aiplatform aiplatform

Requisitos de role no Express Mode

Mesmo que o Express Mode utilize autenticação por API Key (igual ao AI Studio), ele ainda herda os requisitos rigorosos de formato do Vertex AI, portanto, o campo role é obrigatório.

# Exemplo do Express Mode - role obrigatório
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",  # Deve ser incluído!
            "parts": [{"text": "Hello World"}]
        }
    ]
}

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

Guia de Solução de Problemas Comuns

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

Causa: O objeto no array contents não possui o campo role.

Solução:

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

Erro 2: Invalid role value

Causa: O campo role utilizou um valor inválido (como "system" ou "assistant").

Solução: O Vertex AI aceita apenas user e model, não aceita system ou assistant.

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

Erro 3: Posição incorreta do System instructions

Causa: Colocar o comando de sistema (system prompt) dentro de contents em vez do campo systemInstruction.

Solução:

{
  "systemInstruction": {
    "parts": [{"text": "Você é um consultor técnico especializado"}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Ajude-me a explicar o que é uma API"}]
    }
  ]
}

💰 Otimização de Custos: Para projetos que exigem testes frequentes de formatos de API, considere chamar a API através da plataforma APIYI (apiyi.com). A plataforma oferece métodos de cobrança flexíveis e preços mais vantajosos, sendo ideal para pequenas e médias equipes e desenvolvedores individuais realizarem depuração de desenvolvimento.

Checklist de Migração

Ao migrar do AI Studio para o Vertex AI, use o seguinte checklist para garantir que o formato da requisição esteja correto:

Itens Obrigatórios de Modificação

Item de Verificação Formato AI Studio Formato Vertex AI
Campo role Pode ser omitido Deve ser adicionado "role": "user"
URL do Endpoint generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Método de Autenticação x-goog-api-key Authorization: Bearer
Caminho do Modelo models/gemini-pro publishers/google/models/gemini-pro

Exemplo de Migração de Código

Antes da Migração (AI Studio):

import google.generativeai as genai

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

Após a Migração (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 é obrigatório
]

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

Tratamento da role em requisições multimodais

Requisições de Imagem + Texto

Ao enviar requisições multimodais que contêm imagens, você também precisa especificar a role:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Descreva o conteúdo desta imagem"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        }
      ]
    }
  ]
}

Usando arquivos do Cloud Storage

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Analise o conteúdo principal deste vídeo"},
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://seu-bucket/video.mp4"
          }
        }
      ]
    }
  ]
}

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

Perguntas Frequentes (FAQ)

Q1: Por que o AI Studio permite omitir a role, mas o Vertex AI não?

O AI Studio foi projetado como uma ferramenta de prototipagem rápida, por isso tem requisitos de formato mais flexíveis. Já o Vertex AI é uma plataforma de produção de nível empresarial e exige um formato de requisição rigoroso para garantir a estabilidade e a manutenção do sistema. Através da plataforma APIYI (apiyi.com), você pode obter créditos de teste gratuitos e validar rapidamente os requisitos de formato de diferentes plataformas.

Q2: O Vertex AI suporta a role system?

Não diretamente no campo role. A role no Vertex AI aceita apenas os valores user e model. Para instruções do sistema, você deve usar o campo específico systemInstruction:

{
  "systemInstruction": {
    "parts": [{"text": "Seu comando de sistema"}]
  },
  "contents": [...]
}

Q3: Como mapear o assistant do formato OpenAI?

No formato da OpenAI, a role assistant corresponde à role model no Vertex AI. Se você estiver utilizando a interface unificada da APIYI (apiyi.com), esse mapeamento é tratado automaticamente para você.

Q4: Como posso testar rapidamente se o formato da minha requisição está correto?

Recomendamos os seguintes métodos para validação rápida:

  1. Usar a plataforma APIYI: Oferece validação de formato de requisição e dicas de erro em tempo real.
  2. Usar o Google Cloud Console: O Vertex AI Studio fornece uma interface de teste visual intuitiva.
  3. Testes de Mock locais: Valide a lógica primeiro no AI Studio e, em seguida, ajuste o formato ao migrar para o Vertex AI.

Q5: O formato do Vertex AI Express Mode é o mesmo do modo padrão?

Sim, o formato do corpo da requisição é idêntico para ambos; ambos exigem obrigatoriamente o campo role. A principal diferença reside no método de autenticação (API Key vs. Service Account).

Conclusão

As diferenças no formato do corpo da requisição (request body) entre o Vertex AI e o AI Studio residem principalmente na obrigatoriedade do campo role:

Plataforma Requisito de role Valores válidos
AI Studio Opcional para turno único, obrigatório para múltiplos turnos user, model
Vertex AI Sempre obrigatório user, model
Vertex AI Express Sempre obrigatório user, model

Passos essenciais para corrigir o erro 400:

  1. Garanta que cada objeto contents inclua "role": "user" ou "role": "model"
  2. Utilize o campo systemInstruction para instruções do sistema, em vez de usar o role
  3. Mapeie o assistant do formato OpenAI para model

Recomendamos utilizar o APIYI (apiyi.com) para validar rapidamente os resultados. A plataforma gerencia automaticamente a compatibilidade entre diferentes formatos de API, permitindo que você foque totalmente no desenvolvimento da sua lógica de negócio.

Leitura complementar:

  • Documentação oficial do Vertex AI: cloud.google.com/vertex-ai/docs
  • Referência da Gemini API: ai.google.dev/api
  • Guia de migração: cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai

📝 Autor: Equipe Técnica APIYI | Especialistas em integração e otimização de APIs de Modelos de Linguagem Grande
🔗 Comunidade Técnica: Visite o APIYI (apiyi.com) para obter mais recursos técnicos e suporte ao desenvolvedor

Deixe um comentário