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

Mengatasi Kesalahan Vertex AI 400: 3 Masalah Format Body Permintaan yang Disebabkan oleh Perbedaan Parameter role

oleh

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

Saat menggunakan Google Gemini API, beralih dari AI Studio ke Vertex AI adalah langkah yang umum bagi banyak pengembang. Namun, perbedaan parameter role yang tampak sepele seringkali membuat banyak pengembang terjebak:

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

Penyebab utama error 400 ini adalah: Vertex AI mewajibkan setiap objek dalam array contents menyertakan kolom role, sementara AI Studio mengizinkannya untuk dikosongkan pada percakapan satu putaran.

Artikel ini akan mengupas tuntas perbedaan format request body antara Vertex AI dan AI Studio, serta memberikan solusi lengkap untuk 3 skenario berbeda.

Ringkasan Perbedaan Inti antara Vertex AI dan AI Studio

Sebelum memperbaiki error 400, kita perlu memahami perbedaan mendasar antara kedua platform ini.

Perbedaan Pemosisian Platform

Dimensi Perbandingan AI Studio (Google AI) Vertex AI
Target Pengguna Prototipe cepat untuk pengembang Penerapan produksi tingkat perusahaan
Metode Autentikasi API Key Service Account / OAuth
Batas Kecepatan Batas dasar, bukan untuk komersial Batas tingkat produksi, mendukung komersial
Kolom role Opsional untuk satu putaran Wajib diisi
Format Endpoint generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Platform yang Tersedia APIYI apiyi.com, API resmi APIYI apiyi.com, Google Cloud

Mengapa Error role 400 Terjadi

Sebagai platform tingkat perusahaan, Vertex AI memiliki validasi format permintaan yang lebih ketat. Jika kolom role hilang dari request body Anda, Vertex AI akan segera mengembalikan:

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

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

🎯 Saran Teknis: Saat bermigrasi dari AI Studio ke Vertex AI, kami menyarankan untuk melakukan pengujian panggilan antarmuka melalui platform APIYI apiyi.com. Platform ini menyediakan format antarmuka API yang seragam dan secara otomatis menangani perbedaan parameter antar platform, sehingga membantu memvalidasi kelayakan solusi teknis dengan cepat.

Penjelasan Detail Format Request Body Vertex AI

Format Request Vertex AI yang Benar

Request body untuk Gemini API di Vertex AI harus mengikuti struktur berikut:

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

Nilai Valid untuk Parameter role

Vertex AI hanya menerima dua nilai role:

Nilai role Arti Skenario Penggunaan
user Input pengguna Pertanyaan atau instruksi yang dikirim ke model
model Respons model Balasan riwayat dalam percakapan multi-turn

Contoh Salah vs Contoh Benar

❌ Salah: Kurang field role (Gaya AI Studio)

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

✅ Benar: Menyertakan field role (Gaya Vertex AI)

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

Penjelasan Detail Format Request Body AI Studio

Mode Longgar AI Studio

AI Studio (Google AI) memiliki persyaratan format request yang relatif longgar. Dalam skenario percakapan single-turn, field role bisa diabaikan:

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

Perbandingan Request Body Kedua Platform

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

Field AI Studio Vertex AI
contents Wajib Wajib
contents[].role Opsional (single-turn) Wajib
contents[].parts Wajib Wajib
contents[].parts[].text Wajib Wajib
systemInstruction Mendukung Mendukung
generationConfig Opsional Opsional

Skenario Percakapan Multi-turn

Dalam percakapan multi-turn, format kedua platform cenderung sama, keduanya memerlukan spesifikasi role secara jelas:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "你好,请介绍一下自己"}]
    },
    {
      "role": "model",
      "parts": [{"text": "你好!我是 Gemini,由 Google 开发的 AI 助手..."}]
    },
    {
      "role": "user",
      "parts": [{"text": "你能做什么?"}]
    }
  ]
}

Solusi Lengkap untuk 3 Skenario

Skenario 1: Memanggil Vertex AI dengan Python SDK

Saat menggunakan Python SDK resmi dari Google, pastikan kamu menyertakan parameter role dengan benar:

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

# Inisialisasi klien
client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)

# Format permintaan yang benar - harus menyertakan 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)

Skenario 2: Pemanggilan Langsung via REST API

Gunakan curl atau HTTP client untuk memanggil Vertex AI REST API secara langsung:

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

💡 Mulai Cepat: Direkomendasikan menggunakan platform APIYI (apiyi.com) untuk membangun prototipe dengan cepat. Platform ini menyediakan antarmuka API siap pakai yang menangani perbedaan format antara Vertex AI dan AI Studio secara otomatis. Tanpa konfigurasi rumit, integrasi bisa selesai dalam 5 menit.

Skenario 3: Pemanggilan dengan Format Kompatibel OpenAI

Jika kode kamu berbasis OpenAI SDK, kamu bisa menggunakan format yang kompatibel:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Menggunakan antarmuka terpadu APIYI
)

# Format kompatibel OpenAI menangani role secara otomatis
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "user", "content": "什么是神经网络?"}
    ]
)

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

Kasus Khusus: Vertex AI Express Mode

Apa itu Vertex AI Express Mode?

Vertex AI Express Mode adalah opsi penengah antara AI Studio dan Vertex AI standar:

Fitur AI Studio Vertex AI Express Vertex AI Standard
Metode Autentikasi API Key API Key Service Account
Rate Limit Dasar Kelas Produksi Kelas Produksi
Lisensi Komersial Tidak Ya Ya
Persyaratan role Opsional Wajib diisi Wajib diisi
Endpoint generativelanguage aiplatform aiplatform

Persyaratan role pada Express Mode

Meskipun Express Mode menggunakan autentikasi API Key (sama seperti AI Studio), mode ini tetap mewarisi persyaratan format Vertex AI yang ketat: field role wajib diisi.

# Contoh Express Mode - role wajib diisi
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",  # Wajib ada!
            "parts": [{"text": "Hello World"}]
        }
    ]
}

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

Panduan Troubleshooting Kesalahan Umum

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

Penyebab: Objek dalam array contents tidak memiliki kolom role.

Solusi:

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

Kesalahan 2: Invalid role value

Penyebab: Kolom role menggunakan nilai yang tidak valid (seperti "system" atau "assistant").

Solusi: Vertex AI hanya menerima user dan model, serta tidak menerima system atau assistant.

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

Kesalahan 3: Posisi System instructions salah

Penyebab: Menempatkan system prompt di dalam contents, bukan di kolom systemInstruction.

Solusi:

{
  "systemInstruction": {
    "parts": [{"text": "Anda adalah konsultan teknis profesional"}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Bantu saya jelaskan apa itu API"}]
    }
  ]
}

💰 Optimasi Biaya: Untuk proyek yang membutuhkan pengujian format API secara berkala, Anda bisa mempertimbangkan untuk memanggil API melalui platform APIYI apiyi.com. Platform ini menawarkan metode penagihan yang fleksibel dan harga yang lebih terjangkau, sangat cocok bagi tim kecil-menengah maupun developer perorangan dalam melakukan pengembangan dan debugging.

Checklist Migrasi

Saat bermigrasi dari AI Studio ke Vertex AI, gunakan checklist berikut untuk memastikan format permintaan sudah benar:

Item yang Wajib Diubah

Item Pemeriksaan Penulisan AI Studio Penulisan Vertex AI
Kolom role Bisa dikosongkan Wajib ditambahkan "role": "user"
URL Endpoint generativelanguage.googleapis.com {region}-aiplatform.googleapis.com
Metode Autentikasi x-goog-api-key Authorization: Bearer
Path Model models/gemini-pro publishers/google/models/gemini-pro

Contoh Migrasi Kode

Sebelum Migrasi (AI Studio):

import google.generativeai as genai

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

Setelah Migrasi (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 wajib diisi
]

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

Penanganan role pada Permintaan Multimoda

Permintaan Gambar + Teks

Saat mengirimkan permintaan multimoda yang berisi gambar, Anda juga perlu menentukan role:

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

Menggunakan File 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-id 图示

Pertanyaan yang Sering Diajukan (FAQ)

Q1: Mengapa AI Studio bisa mengabaikan role, sedangkan Vertex AI tidak?

AI Studio dirancang sebagai alat validasi prototipe yang cepat, sehingga persyaratan formatnya lebih longgar. Sebaliknya, Vertex AI sebagai platform produksi tingkat perusahaan memerlukan format permintaan yang ketat untuk memastikan stabilitas dan kemudahan pemeliharaan sistem. Melalui platform APIYI (apiyi.com), Anda bisa mendapatkan kuota uji coba gratis untuk memvalidasi persyaratan format di berbagai platform dengan cepat.

Q2: Apakah Vertex AI mendukung system role?

Tidak mendukung. role di Vertex AI hanya menerima dua nilai: user dan model. Untuk instruksi sistem, Anda harus menggunakan field systemInstruction yang terpisah:

{
  "systemInstruction": {
    "parts": [{"text": "petunjuk sistem Anda"}]
  },
  "contents": [...]
}

Q3: Bagaimana cara memetakan assistant dari format OpenAI?

role assistant dalam format OpenAI setara dengan role model di Vertex AI. Jika Anda menggunakan antarmuka terpadu dari APIYI (apiyi.com), pemetaan ini akan ditangani secara otomatis.

Q4: Bagaimana cara cepat untuk mengetes apakah format permintaan sudah benar?

Direkomendasikan menggunakan metode berikut untuk validasi cepat:

  1. Gunakan pengujian platform APIYI: Menyediakan pengecekan format permintaan dan pesan kesalahan.
  2. Gunakan Google Cloud Console: Vertex AI Studio menyediakan antarmuka pengujian visual.
  3. Pengujian Mock lokal: Validasi logika menggunakan AI Studio terlebih dahulu, lalu sesuaikan formatnya saat migrasi ke Vertex AI.

Q5: Apakah format Vertex AI Express Mode dan mode standar sama?

Ya, format body permintaan keduanya benar-benar sama, keduanya mewajibkan adanya field role. Perbedaan utamanya terletak pada metode autentikasi (API Key vs. Service Account).

Kesimpulan

Perbedaan format request body antara Vertex AI dan AI Studio terutama terletak pada persyaratan wajib untuk field role:

Platform Persyaratan role Nilai yang valid
AI Studio Opsional untuk single-turn, wajib untuk multi-turn user, model
Vertex AI Selalu wajib user, model
Vertex AI Express Selalu wajib user, model

Langkah-langkah utama untuk mengatasi error 400:

  1. Pastikan setiap objek contents menyertakan "role": "user" atau "role": "model"
  2. Gunakan field systemInstruction untuk instruksi sistem, bukan role
  3. Petakan format OpenAI assistant menjadi model

Direkomendasikan untuk memvalidasi hasilnya dengan cepat melalui APIYI apiyi.com. Platform ini menangani masalah kompatibilitas berbagai format API secara otomatis, sehingga Anda bisa fokus pada pengembangan logika bisnis.

Bacaan Lanjutan:

  • Dokumentasi Resmi Vertex AI: cloud.google.com/vertex-ai/docs
  • Referensi Gemini API: ai.google.dev/api
  • Panduan Migrasi: cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai

📝 Penulis: Tim Teknis APIYI | Fokus pada integrasi dan optimasi API Model Bahasa Besar AI
🔗 Diskusi Teknis: Kunjungi APIYI apiyi.com untuk mendapatkan lebih banyak sumber daya teknis dan dukungan pengembangan

Tinggalkan komentar