Vertex AI 400 에러 해결: role 파라미터 차이로 인한 3가지 요청 본문 형식 문제

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의 요청 본문 형식 차이를 심층 분석하고, 세 가지 시나리오에 따른 완벽한 해결책을 제시해 드릴게요.

Vertex AI와 AI Studio의 핵심 차이점 개요

400 오류를 해결하기 전에, 먼저 두 플랫폼의 본질적인 차이를 이해해야 합니다.

플랫폼 포지셔닝 차이

비교 항목	AI Studio (Google AI)	Vertex AI
대상 사용자	개발자의 빠른 프로토타입 검증	엔터프라이즈급 운영 배포
인증 방식	API Key	서비스 계정 / OAuth
속도 제한	기본 제한, 상업적 이용 불가	운영 수준 제한, 상업적 이용 지원
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"
  }
}

🎯 기술 팁: AI Studio에서 Vertex AI로 마이그레이션할 때, APIYI (apiyi.com) 플랫폼을 통해 인터페이스 호출 테스트를 진행해 보시길 추천해요. 이 플랫폼은 통일된 API 인터페이스 형식을 제공하여 서로 다른 플랫폼 간의 파라미터 차이를 자동으로 처리해 주므로, 기술 솔루션의 타당성을 빠르게 검증할 수 있습니다.

Vertex AI 요청 본문(Request Body) 형식 상세 가이드

올바른 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?"
        }
      ]
    }
  ]
}

두 플랫폼의 요청 본문 비교

필드	AI Studio	Vertex AI
`contents`	필수	필수
`contents[].role`	선택 (단일 대화)	필수
`contents[].parts`	필수	필수
`contents[].parts[].text`	필수	필수
`systemInstruction`	지원	지원
`generationConfig`	선택	선택

멀티턴 대화 시나리오

멀티턴 대화(여러 차례 주고받는 대화)에서는 두 플랫폼의 형식이 거의 동일해져요. 두 플랫폼 모두 role을 명확하게 지정해야 합니다.

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "안녕하세요, 자기소개 좀 해주세요"}]
    },
    {
      "role": "model",
      "parts": [{"text": "안녕하세요! 저는 Google에서 개발한 AI 어시스턴트 Gemini입니다..."}]
    },
    {
      "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
    }
  }'

💡 빠른 시작: 프로토타입을 빠르게 구축하려면 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 Key	API Key	Service Account
속도 제한	기초	프로덕션급	프로덕션급
상업적 라이선스	아니요	예	예
role 요구 사항	선택 사항	필수	필수
엔드포인트	generativelanguage	aiplatform	aiplatform

Express Mode의 role 요구 사항

Express Mode는 (AI Studio와 마찬가지로) API Key 인증을 사용하더라도, 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 위치 오류

원인: 시스템 프롬프트를 systemInstruction 필드가 아닌 contents 내부에 넣었습니다.

해결 방법:

{
  "systemInstruction": {
    "parts": [{"text": "당신은 전문 기술 컨설턴트입니다."}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "API가 무엇인지 설명해 주세요."}]
    }
  ]
}

💰 비용 최적화: API 형식을 빈번하게 테스트해야 하는 프로젝트라면 APIYI(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"
          }
        }
      ]
    }
  ]
}

자주 묻는 질문 FAQ

Q1: 왜 AI Studio에서는 role을 생략할 수 있는데, Vertex AI에서는 안 되나요?

AI Studio는 빠른 프로토타입 검증을 위한 도구로 설계되어 형식이 비교적 유연합니다. 반면 Vertex AI는 기업용 프로덕션 플랫폼으로서 시스템 안정성과 유지보수성을 위해 엄격한 요청 형식을 요구하죠. APIYI(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에 대응합니다. APIYI(apiyi.com)의 통합 인터페이스를 사용하면 이러한 매핑이 자동으로 처리됩니다.

Q4: 요청 형식이 올바른지 빠르게 테스트하려면 어떻게 해야 하나요?

다음 방법들을 추천드려요:

APIYI 플랫폼 사용: 요청 형식 검증 및 구체적인 오류 메시지를 제공합니다.
Google Cloud Console 사용: Vertex AI Studio에서 시각적인 테스트 인터페이스를 활용할 수 있습니다.
로컬 Mock 테스트: 먼저 AI Studio에서 로직을 검증한 뒤, 형식을 수정하여 Vertex AI로 이전하세요.

Q5: Vertex AI 익스프레스 모드(Express Mode)와 표준 모드의 형식이 같나요?

네, 두 모드 모두 요청 본문(Request Body) 형식은 완전히 동일하며 반드시 role 필드를 포함해야 합니다. 주요 차이점은 인증 방식(API 키 vs 서비스 계정)에 있습니다.

요약

Vertex AI와 AI Studio의 요청 본문(Request Body) 형식 차이는 주로 role 필드의 필수 여부에서 나타납니다.

플랫폼	role 요구 사항	유효 값
AI Studio	단일 턴은 선택 사항, 다중 턴은 필수	user, model
Vertex AI	항상 필수	user, model
Vertex AI Express	항상 필수	user, model

400 오류 해결을 위한 핵심 단계:

각 contents 객체에 "role": "user" 또는 "role": "model"이 포함되어 있는지 확인하세요.
시스템 지침은 role 대신 systemInstruction 필드를 사용하세요.
OpenAI 형식의 assistant를 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 기술 팀 | AI 대규모 언어 모델 API 통합 및 최적화 전문
🔗 기술 교류: APIYI(apiyi.com)를 방문하여 더 많은 기술 리소스와 개발 지원을 확인해 보세요.