حل خطأ 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 في المحادثات أحادية الدور.

ستتعمق هذه المقالة في تحليل الاختلافات في تنسيق جسم الطلب بين Vertex AI وAI Studio، وستقدم حلولاً كاملة لثلاثة سيناريوهات مختلفة.

نظرة عامة على الاختلافات الجوهرية بين Vertex AI وAI Studio

قبل حل خطأ 400، نحتاج أولاً إلى فهم الفروق الجوهرية بين المنصتين.

الاختلاف في توجه المنصة

بُعد المقارنة	AI Studio (Google AI)	Vertex AI
المستخدم المستهدف	النمذجة الأولية السريعة للمطورين	النشر الإنتاجي على مستوى المؤسسات
طريقة المصادقة	مفتاح API (API Key)	حساب الخدمة (Service Account) / 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

التنسيق الصحيح لطلب 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?"
        }
      ]
    }
  ]
}

مقارنة بين نص الطلب في كلا المنصتين

الحقل	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

استخدم 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
حد المعدل (Rate Limit)	أساسي	مستوى الإنتاج	مستوى الإنتاج
الترخيص التجاري	لا	نعم	نعم
متطلبات role	اختياري	مطلوب	مطلوب
نقطة النهاية (Endpoint)	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": [
    {
-     "role": "assistant",
+     "role": "model",
      "parts": [{"text": "..."}]
    }
  ]
}

الخطأ 3: موقع تعليمات النظام (System instructions) خاطئ

السبب: وضع الموجه (prompt) الخاص بالنظام داخل contents بدلاً من حقل systemInstruction.

الحل:

{
  "systemInstruction": {
    "parts": [{"text": "أنت مستشار تقني محترف"}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "ساعدني في شرح ما هو الـ API"}]
    }
  ]
}

💰 تحسين التكلفة: بالنسبة للمشاريع التي تتطلب اختبارات متكررة لتنسيقات الـ API، يمكنك التفكير في استدعاء الـ API عبر منصة APIYI (apiyi.com). توفر هذه المنصة طرق فوترة مرنة وأسعاراً أكثر تنافسية، مما يجعلها مناسبة للفرق الصغيرة والمتوسطة والمطورين الأفراد أثناء عمليات التطوير والتصحيح.

قائمة التحقق للانتقال

عند الانتقال من AI Studio إلى Vertex AI، استخدم القائمة التالية لضمان صحة تنسيق الطلب:

العناصر التي يجب تعديلها

بند التحقق	صيغة AI Studio	صيغة Vertex AI
حقل role	يمكن حذفه	يجب إضافة `"role": "user"`
رابط النهاية (Endpoint)	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.generai.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 في الطلبات متعددة الوسائط (Multimodal)

طلبات الصور + النصوص

عند إرسال طلب متعدد الوسائط يتضمن صوراً، من الضروري أيضاً تحديد الـ 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

س1: لماذا يمكن لـ AI Studio الاستغناء عن حقل role بينما لا يمكن ذلك في Vertex AI؟

تم تصميم AI Studio كأداة سريعة للتحقق من النماذج الأولية، لذا فإن متطلبات التنسيق فيه مرنة. أما Vertex AI، كونه منصة إنتاج للمؤسسات، فإنه يتطلب تنسيقًا صارمًا للطلبات لضمان استقرار النظام وقابليته للصيانة. يمكنك الحصول على رصيد اختبار مجاني عبر منصة APIYI (apiyi.com) للتحقق بسرعة من متطلبات التنسيق لمختلف المنصات.

س2: هل يدعم Vertex AI دور النظام (system role)؟

لا يدعم ذلك. يقبل حقل role في Vertex AI قيمتين فقط هما user و model. يجب استخدام حقل systemInstruction المنفصل لتعليمات النظام:

{
  "systemInstruction": {
    "parts": [{"text": "موجه النظام الخاص بك"}]
  },
  "contents": [...]
}

س3: كيف يتم تعيين دور assistant الخاص بتنسيق OpenAI؟

يقابل دور assistant في تنسيق OpenAI دور model في Vertex AI. إذا كنت تستخدم الواجهة الموحدة لمنصة APIYI (apiyi.com)، فسيتم التعامل مع هذا التعيين تلقائيًا.

س4: كيف يمكنني اختبار ما إذا كان تنسيق الطلب صحيحًا بسرعة؟

نوصي باستخدام الطرق التالية للتحقق السريع:

استخدام منصة APIYI للاختبار: توفر ميزة التحقق من تنسيق الطلب وتظهر تنبيهات بالأخطاء.
استخدام Google Cloud Console: يوفر Vertex AI Studio واجهة اختبار مرئية.
اختبار المحاكاة (Mock) المحلي: تحقق من المنطق أولاً باستخدام AI Studio، ثم قم بتعديل التنسيق للانتقال إلى Vertex AI.

س5: هل تنسيق Vertex AI Express Mode هو نفسه التنسيق القياسي؟

نعم، تنسيق جسم الطلب (Request Body) متطابق تمامًا في كليهما، حيث يشترط كلاهما وجود حقل role. الاختلاف الرئيسي يكمن في طريقة المصادقة (مفتاح API مقابل حساب الخدمة Service Account).

الملخص

تتمثل الاختلافات الرئيسية في تنسيق جسم الطلب بين Vertex AI و AI Studio في المتطلبات الإلزامية لحقل role:

المنصة	متطلبات role	القيم الصالحة
AI Studio	اختياري في الجولة الواحدة، إلزامي في الجولات المتعددة	user, model
Vertex AI	إلزامي دائماً	user, model
Vertex AI Express	إلزامي دائماً	user, model

الخطوات الأساسية لحل خطأ 400:

تأكد من أن كل كائن في contents يحتوي على "role": "user" أو "role": "model".
استخدم حقل systemInstruction لتعليمات النظام بدلاً من حقل role.
قم بتحويل دور 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) للحصول على المزيد من الموارد التقنية ودعم المطورين.