3 طرق لحل فشل استدعاء نموذج لغة كبير للتعرف على الصور في OpenClaw: أخطاء وضع توافق OpenAI الشائعة ودليل تكوين التنسيق الأصلي

غالبًا ما يواجه المطورون أخطاءً عند استخدام وضع التوافق مع OpenAI في OpenClaw لاستدعاء نماذج Gemini من أجل التعرف على الصور، وهو تحدٍ شائع عند إعداد وكلاء الذكاء الاصطناعي متعددي الوسائط. سنقوم في هذا المقال بتحليل السبب الجذري لخطأ Invalid JSON payload، ونقدم 3 حلول مجربة لمساعدتك في إصلاح فشل التعرف على الصور في Gemini عبر OpenClaw بسرعة.

القيمة الجوهرية: بعد قراءة هذا المقال، ستفهم الاختلافات الجوهرية بين وضع التوافق مع OpenAI وواجهة برمجة تطبيقات (API) Gemini الأصلية، وستتقن طرق الإعداد الصحيحة لحل مشكلة فشل التعرف على الصور نهائيًا.

ظاهرة خطأ فشل التعرف على الصور في Gemini عبر OpenClaw

بعد إعداد نموذج Gemini في OpenClaw، عند محاولة التعرف على الصور، تظهر عادةً رسائل الخطأ التالية في سجلات النظام (Logs):

Invalid JSON payload received. Unknown name "patternProperties"
at 'tools[0].function_declarations[3].parameters.properties[4].value':
Cannot find field.

Invalid JSON payload received. Unknown name "const"
at 'tools[0].function_declarations[37].parameters.properties[0].value':
Cannot find field.

السمات الرئيسية لخطأ التعرف على الصور في Gemini عبر OpenClaw

التشخيص السريع لفشل التعرف على الصور في Gemini عبر OpenClaw

من المفاهيم الخاطئة الشائعة الاعتقاد بأن قدرة Gemini على التعرف على الصور بها خلل. في الواقع، عند اختبار واجهة برمجة التطبيقات مباشرة باستخدام العرض التوضيحي الرسمي للرؤية الحاسوبية من Gemini، تعمل ميزة التعرف على الصور بشكل طبيعي تمامًا. تكمن المشكلة في عدم توافق التنسيق عندما يقوم OpenClaw بإعادة توجيه الطلبات عبر وضع التوافق مع OpenAI.

طريقة التحقق بسيطة:

# استدعاء واجهة برمجة تطبيقات Gemini مباشرة لاختبار التعرف على الصور — يعمل بشكل طبيعي
import google.generativeai as genai
import PIL.Image

genai.configure(api_key="YOUR_GEMINI_API_KEY")
model = genai.GenerativeModel("gemini-2.5-flash")

image = PIL.Image.open("test.jpg")
response = model.generate_content(["صِف هذه الصورة", image])
print(response.text)  # ✅ مخرجات وصف الصورة طبيعية

🎯 نصيحة تشخيصية: إذا واجهت مشكلة في التعرف على الصور باستخدام Gemini في OpenClaw، تأكد أولاً من أن مفتاح API والنموذج نفسه يعملان بشكل صحيح بالطريقة المذكورة أعلاه. يمكنك أيضًا الاختبار بسرعة عبر منصة APIYI (apiyi.com)، حيث تتعامل المنصة تلقائيًا مع مشكلات توافق التنسيق.

تحليل السبب الجذري لفشل التعرف على الصور في OpenClaw Gemini

لفهم كيفية اختيار الحل الأمثل، يجب أولاً إدراك السبب الجذري للمشكلة. إن فشل OpenClaw في التعرف على الصور عند استخدام Gemini يعود بشكل أساسي إلى مشكلة في توافق مخطط JSON (JSON Schema).

الاختلافات في مخطط JSON لاستدعاء الأدوات بين OpenAI وGemini

عندما يستخدم OpenClaw وضع التوافق مع OpenAI (openai-completions) لاستدعاء Gemini، تكون دورة الطلب كالتالي:

OpenClaw يبني الطلب (بتنسيق OpenAI)
    ↓
يحتوي على تعريفات الأدوات بتنسيق JSON Schema
    ↓
يتم الإرسال إلى نقطة نهاية Gemini المتوافقة مع OpenAI
    ↓
Gemini يحلل function_declarations
    ↓
❌ يواجه حقول مخطط غير مدعومة ← خطأ 400

قائمة حقول JSON Schema غير المدعومة في Gemini API

هذا هو جوهر المشكلة. دعم Gemini لـ function_declarations في مخطط JSON هو مجموعة فرعية محدودة، والحقول التالية تؤدي مباشرة إلى خطأ 400:

لماذا لا توجد مشكلة عند التبديل إلى GPT-5.4؟

هذا يؤكد صحة تحليل السبب الجذري. عند تبديل النموذج في OpenClaw من Gemini إلى GPT-5.4، يعود التعرف على الصور للعمل بشكل طبيعي؛ لأن واجهة برمجة تطبيقات (API) الخاصة بـ GPT-5.4 تدعم بشكل أصلي مواصفات JSON Schema الكاملة، مما يجعل مخطط تعريف الأدوات الذي ينشئه OpenClaw متوافقاً تماماً.

📌 إدراك جوهري: المشكلة ليست في قدرة Gemini على التعرف على الصور، بل في عدم توافق مخطط الأدوات الذي يرسله وضع التوافق مع OpenAI في OpenClaw مع متطلبات تنسيق Gemini API.

الحل الأول: التبديل إلى التنسيق الأصلي لـ Gemini (موصى به)

الحل الأكثر فاعلية هو تغيير نوع واجهة برمجة التطبيقات (API) لـ Gemini في OpenClaw من openai-completions إلى التنسيق الأصلي google-generative-ai.

خطوات الإعداد

قبل التعديل (وضع التوافق مع OpenAI — يواجه مشاكل):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
  "api": "openai-completions",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

بعد التعديل (التنسيق الأصلي لـ Gemini — موصى به):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
  "api": "google-generative-ai",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

التغييرات الجوهرية في إعدادات التنسيق الأصلي

التبديل السريع باستخدام OpenClaw CLI

# الطريقة الأولى: إعادة تهيئة إعدادات Gemini
openclaw onboard --auth-choice gemini-api-key

# الطريقة الثانية: تعديل ملف الإعدادات يدوياً
# موقع ملف الإعدادات: ~/.openclaw/config.json
# قم بتغيير حقل api من "openai-completions" إلى "google-generative-ai"

{
  "providers": {
    "google": {
      "apiKey": "YOUR_GEMINI_API_KEY",
      "models": {
        "gemini-2.5-flash": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": false
        },
        "gemini-2.5-pro": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": true,
          "thinkingBudget": 8192
        }
      }
    }
  }
}

🚀 بداية سريعة: إذا كنت لا ترغب في التعامل يدوياً مع مشاكل توافق الإعدادات، نوصي باستخدام الواجهة الموحدة لمنصة APIYI (apiyi.com). تقوم المنصة تلقائياً بتحويل طلبات تنسيق OpenAI إلى التنسيق الأصلي لـ Gemini، مما يغنيك عن القلق بشأن اختلافات المخطط (Schema).

الحل الثاني: المعالجة التلقائية للتوافق عبر خدمة وكيل API

إذا كنت ترغب في الاستمرار باستخدام وضع التوافق مع OpenAI في OpenClaw لاستدعاء نماذج متعددة (بما في ذلك Gemini)، يمكنك حل مشاكل التوافق عبر استخدام خدمة وكيل API.

آلية عمل خدمة الوكيل

OpenClaw (طلب بتنسيق OpenAI)
    ↓
خدمة وكيل API (مثل APIYI)
    ↓ تنظيف تلقائي لحقول JSON Schema غير المتوافقة
    ↓ تحويل تلقائي لتنسيق الطلب
Gemini API (التنسيق الأصلي)
    ↓
✅ استلام نتائج التعرف على الصور بشكل طبيعي

مثال على الإعداد

# استدعاء التعرف على الصور في Gemini عبر خدمة وكيل APIYI
import openai
import base64

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # الواجهة الموحدة لـ APIYI
)

# قراءة الصورة وترميزها
with open("test.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "صف محتوى هذه الصورة"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)

مقارنة بين خدمة الوكيل والاتصال المباشر

إعداد وكيل APIYI في OpenClaw:

{
  "provider": "apiyi",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://api.apiyi.com/v1",
  "api": "openai-completions",
  "apiKey": "YOUR_APIYI_KEY"
}

💡 نصيحة للاختيار: إذا كنت تستخدم نماذج متعددة في OpenClaw (مثل GPT-5.4، Claude، Gemini، إلخ)، فإن الإدارة الموحدة لاستدعاءات API عبر APIYI (apiyi.com) تعد خياراً أكثر كفاءة، حيث تجنبك عناء ضبط تنسيقات API مختلفة لكل نموذج على حدة.

الحل الثالث: التنظيف اليدوي للحقول غير المتوافقة في JSON Schema

إذا كنت بحاجة إلى حل مشكلات التوافق على مستوى الكود، يمكنك تنظيف حقول JSON Schema التي لا يدعمها Gemini يدوياً قبل إرسال الطلب.

دالة تنظيف JSON Schema

def clean_schema_for_gemini(schema: dict) -> dict:
    """تنظيف حقول JSON Schema التي لا يدعمها Gemini"""
    unsupported_keys = {
        "patternProperties",
        "const",
        "additionalProperties",
        "$schema",
        "exclusiveMaximum",
        "exclusiveMinimum",
        "propertyNames",
    }

    if isinstance(schema, dict):
        return {
            k: clean_schema_for_gemini(v)
            for k, v in schema.items()
            if k not in unsupported_keys
        }
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

import openai
import json

def clean_schema_for_gemini(schema):
    """تنظيف متكرر لحقول JSON Schema التي لا يدعمها Gemini"""
    unsupported_keys = {
        "patternProperties", "const", "additionalProperties",
        "$schema", "exclusiveMaximum", "exclusiveMinimum",
        "propertyNames", "if", "then", "else",
        "allOf", "anyOf", "oneOf", "not",
    }

    if isinstance(schema, dict):
        cleaned = {}
        for k, v in schema.items():
            if k not in unsupported_keys:
                cleaned[k] = clean_schema_for_gemini(v)
        return cleaned
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

def clean_tools_for_gemini(tools):
    """تنظيف جميع المخططات (Schema) في قائمة الأدوات"""
    cleaned_tools = []
    for tool in tools:
        tool_copy = json.loads(json.dumps(tool))
        if "function" in tool_copy:
            params = tool_copy["function"].get("parameters", {})
            tool_copy["function"]["parameters"] = clean_schema_for_gemini(params)
        cleaned_tools.append(tool_copy)
    return cleaned_tools

# مثال على الاستخدام
tools = [
    {
        "type": "function",
        "function": {
            "name": "analyze_image",
            "description": "تحليل محتوى الصورة",
            "parameters": {
                "type": "object",
                "properties": {
                    "image_url": {"type": "string"},
                    "detail": {"type": "string", "const": "high"}  # غير مدعوم من Gemini
                },
                "patternProperties": {"^x-": {"type": "string"}},  # غير مدعوم من Gemini
                "additionalProperties": False  # غير مدعوم من Gemini
            }
        }
    }
]

# الاستدعاء بعد التنظيف
cleaned_tools = clean_tools_for_gemini(tools)

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Hello"}],
    tools=cleaned_tools
)

⚠️ ملاحظة: يتطلب حل التنظيف اليدوي للمخطط (Schema) معالجة تعريفات المعلمات لكل أداة، مما يرفع تكلفة الصيانة. إذا كان عدد الأدوات كبيراً أو يتغير باستمرار، يُفضل استخدام الحل الأول (التنسيق الأصلي) أو الحل الثاني (خدمة وكيل API).

مقارنة الحلول الثلاثة وتوصيات الاختيار

شجرة اتخاذ القرار للاختيار

• استخدام Gemini فقط في OpenClaw ← الحل الأول (التنسيق الأصلي)، الأكثر استقراراً.
• استخدام نماذج متعددة في OpenClaw ← الحل الثاني (وكيل APIYI)، الأكثر راحة.
• بناء تطبيق ذكاء اصطناعي خاص يتطلب تحكماً دقيقاً ← الحل الثالث (التنظيف اليدوي)، الأكثر مرونة.
• غير متأكد من اختيارك ← جرب الحل الثاني أولاً، وتحقق من النتائج بسرعة عبر APIYI apiyi.com.

الأسئلة الشائعة

الخلاصة

السبب الجذري لفشل التعرف على الصور في Gemini عبر OpenClaw هو عدم توافق حقول JSON Schema في وضع التوافق مع OpenAI، وليس خللاً في القدرات البصرية لنموذج Gemini نفسه. هناك 3 حلول متاحة لكل منها سيناريوهات استخدامها:

• التنسيق الأصلي (google-generative-ai): هو الأكثر شمولاً، ويُنصح به في سيناريوهات استخدام Gemini بشكل منفرد.
• خدمة وكيل API: هي الأكثر راحة، ويُنصح بها في سيناريوهات استخدام نماذج متعددة مختلطة.
• التنظيف اليدوي للمخطط (Schema): هو الأكثر مرونة، ويُنصح به للأنظمة المبنية ذاتياً.

نوصي باستخدام منصة APIYI (apiyi.com) للتحقق السريع من نتائج التعرف على الصور في Gemini، حيث تدعم المنصة الاستدعاء الموحد لنماذج Gemini و GPT و Claude وغيرها من النماذج الرئيسية، مع معالجة الاختلافات في تنسيقات واجهة برمجة التطبيقات لكل نموذج تلقائياً.

المراجع

1. وثائق Gemini الرسمية – فهم الصور: شرح لقدرات الرؤية الحاسوبية في Gemini

   • الرابط: ai.google.dev/gemini-api/docs/image-understanding

2. وثائق Gemini الرسمية – التوافق مع OpenAI: تعليمات استدعاء Gemini باستخدام حزمة تطوير البرمجيات (SDK) الخاصة بـ OpenAI

   • الرابط: ai.google.dev/gemini-api/docs/openai

3. مشكلة OpenClaw على GitHub رقم #21172: خطأ 400 في Gemini API بسبب patternProperties

   • الرابط: github.com/openclaw/openclaw/issues/21172

4. مشكلة OpenClaw على GitHub رقم #14456: خطأ 400 في وضع التوافق مع OpenAI لنموذج Gemini 2.5 Flash

   • الرابط: github.com/openclaw/openclaw/issues/14456

5. وثائق إعداد نموذج OpenClaw: دليل إعداد مزود النموذج

   • الرابط: docs.openclaw.ai/concepts/model-providers

📝 كاتب المقال: فريق APIYI — متخصصون في دمج واجهات برمجة تطبيقات نماذج اللغة الكبيرة وتحليل تقنياتها
🔗 المزيد من الدروس: تفضل بزيارة APIYI عبر apiyi.com للحصول على المزيد من أدلة استدعاء النماذج وأرصدة تجريبية مجانية