طريقة استخدام GLM-5.3-Flash API مع مدخلات الصور

GLM-5.3-Flash متوافق مع OpenAI، مما يعني أن أسرع طريقة لإجراء مكالمة عمل هي توجيه عميل لديك بالفعل إلى عنوان URL أساسي مختلف وتغيير سلسلة واحدة. الجزء الجديد حقًا هو إدخال الصور: هذا هو أول نموذج GLM-5 يلتقط صورًا في نفس الطلب مع النص الخاص بك، وشكل الحمولة يربك الناس.

يغطي هذا الدليل الحصول على مفتاح، وإجراء مكالمة نصية، وإرسال الصور، والتحكم في جهد التفكير، والتدفق، واستدعاء الأدوات. يستخدم كل مثال معرف النموذج glm-5.3-flash.

إذا كنت ترغب في معرفة المزيد عن هذا النموذج قبل توصيله، فابدأ بـ شرحنا لـ GLM-5.3-Flash. إذا كنت تستخدم بالفعل النموذج الأكبر، فإن دليل API الخاص بـ GLM-5.3 يغطي هذا النموذج، والاختلافات أدناه حقيقية: معرف نموذج مختلف، وبطاقة أسعار مختلفة، ومسار صور لا يمتلكه GLM-5.3 بشكل طبيعي.

احصل على مفتاح API

أنشئ حسابًا على z.ai، وافتح قسم مفاتيح API في لوحة التحكم، وأنشئ مفتاحًا. ضعه في بيئتك بدلاً من شفرة المصدر الخاصة بك:

export ZAI_API_KEY="your-key-here"

عنوان URL الأساسي لواجهة برمجة التطبيقات القياسية هو:

https://api.z.ai/api/paas/v4/

يوجد عنوان URL أساسي منفصل تستخدمه نقاط نهاية خطة الترميز، وهو أمر مهم إذا كنت تقوم بتوصيل Claude Code أو Cline بدلاً من استدعاء API مباشرة. يتم تغطية هذا الإعداد في دليلنا لـ Claude Code و Cline.

أول مكالمة لك

نظرًا لأن نقطة النهاية متوافقة مع OpenAI، فإن حزمة OpenAI SDK الرسمية تعمل بدون تعديل:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ZAI_API_KEY"],
    base_url="https://api.z.ai/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {"role": "user", "content": "Explain what a KV cache is in two sentences."}
    ],
)

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

نفس الشيء باستخدام curl:

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [
      {"role": "user", "content": "Explain what a KV cache is in two sentences."}
    ]
  }'

وفي Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZAI_API_KEY,
  baseURL: "https://api.z.ai/api/paas/v4/",
});

const response = await client.chat.completions.create({
  model: "glm-5.3-flash",
  messages: [
    { role: "user", content: "Explain what a KV cache is in two sentences." },
  ],
});

console.log(response.choices[0].message.content);

لا يوجد هنا شيء خاص بـ GLM باستثناء عنوان URL الأساسي وسلسلة النموذج. هذه هي فائدة واجهة متوافقة مع OpenAI، وهذا هو السبب في أن تبديل النماذج رخيص بما يكفي ليجعل الأمر يستحق مقارنتها بحمل العمل الخاص بك.

إرسال الصور

هذا هو القسم الذي لا يوجد لـ GLM-5.3. يعمل إدخال الصور من خلال كتل المحتوى: فبدلاً من أن يكون content سلسلة نصية عادية، يصبح مصفوفة من الكتل المكتوبة.

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "This screenshot shows a rendering bug. What is wrong with the layout?",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/screenshots/broken-layout.png"
                    },
                },
            ],
        }
    ],
)

تحكم هذه الحمولة ثلاث قواعد:

يقبل حقل URL إما عنوان URL عامًا أو عنوان URL لبيانات base64. إذا كانت صورتك محلية أو خاصة، قم بتشفيرها:

import base64

with open("broken-layout.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

image_block = {
    "type": "image_url",
    "image_url": {"url": f"data:image/png;base64,{encoded}"},
}

صور متعددة تعني كتلًا متعددة. لا يوجد اختصار لمصفوفة عناوين URL. لمقارنة تصميم بتنفيذه، أرسل كتلتين من image_url في نفس مصفوفة المحتوى:

content = [
    {"type": "text", "text": "Does the second image match the design in the first?"},
    {"type": "image_url", "image_url": {"url": design_data_url}},
    {"type": "image_url", "image_url": {"url": built_data_url}},
]

الترتيب يحمل معنى. يقرأ النموذج مصفوفة المحتوى بالتتابع، لذا ضع النص الذي يحدد المهمة قبل الصور التي يشير إليها. "قارن هذين" متبوعًا بصورتين يقرأ بشكل أفضل من صورتين متبوعتين بسؤال.

توثيق Z.ai يسرد أيضًا إدخال الفيديو والملفات باستخدام نفس آلية كتل المحتوى. الفيديو أحدث وأقل استخدامًا بكثير في الواقع من إدخال الصور، لذا تحقق من صحته مقابل الوسائط الخاصة بك قبل بناء ميزة عليه.

للحصول على معالجة أعمق لجانب الرؤية، بما في ذلك سير عمل تحويل لقطة الشاشة إلى كود ووضع الصور بجانب مستند طويل في نفس نافذة الرموز التي يبلغ حجمها مليون رمز، راجع دليل الرؤية الخاص بنا لـ GLM-5.3-Flash.

التحكم في جهد التفكير

يكشف GLM-5.3-Flash عن ثلاثة أوضاع للتفكير من خلال reasoning_effort:

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Refactor this function for clarity."}],
    extra_body={"reasoning_effort": "low"},
)

القيم المقبولة هي low و high و max. القيمة الافتراضية هي max، وهو أمر يستحق المعرفة لأنه الخيار الأكثر تكلفة. إذا كنت تقوم بتصنيف أو استخراج بكميات كبيرة حيث لا تحتاج الإجابة إلى تفكير، فإن تعيين low بشكل صريح سيقلل عدد رموز الإخراج بشكل كبير.

هذا تغيير عن GLM-5.2، الذي كان يكشف فقط عن High و Max. المستوى low جديد، وبالنسبة للأعمال الدفعية الحساسة للتكلفة، فمن المحتمل أنه المعلمة الأكثر فائدة في النموذج.

لاحظ أن reasoning_effort يذهب في extra_body عند استخدام حزمة OpenAI Python SDK، لأنه ليس جزءًا من مخطط OpenAI القياسي. في استدعاء curl الخام، هو مجرد حقل على المستوى الأعلى.

معلمات أخذ العينات الموصى بها

تنشر Z.ai إعدادات افتراضية مختلفة حسب ما تفعله:

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

التدفق

تنطبق دلالات تدفق OpenAI القياسية:

stream = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Write a bash script that rotates logs."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

اضبط التوقعات هنا. يولد GLM-5.3-Flash حوالي 49 رمزًا في الثانية وفقًا لتحليل الذكاء الاصطناعي، وهو أبطأ من شقيقه الأكبر GLM-5.3 الذي يولد حوالي 86 رمزًا. وقت الوصول إلى الرمز الأول جيد عند 1.52 ثانية، لذا تبدأ الاستجابة بسرعة ثم تصل بثبات بدلاً من السرعة. إذا كنت تقوم بالتدفق إلى واجهة مستخدم، فإن هذا الملف الشخصي جيد. إذا كنت تقوم بإنشاء مستندات طويلة في مهمة دفعية، فخصص ميزانية لذلك.

استدعاء الأدوات

تستخدم الأدوات مخطط OpenAI القياسي:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_deployment_status",
            "description": "Returns the current status of a named deployment.",
            "parameters": {
                "type": "object",
                "properties": {
                    "service": {
                        "type": "string",
                        "description": "The service name, for example 'checkout-api'.",
                    }
                },
                "required": ["service"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Is checkout-api healthy?"}],
    tools=tools,
)

call = response.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

تعتمد المعايير الوكيلية التي نشرتها Z.ai عند الإطلاق بشكل كبير على استخدام الأدوات، مع AutomationBench عند 48.8 مقابل 26.2 لـ GLM-5.2. هذه أرقام الموردين، ولكن الاتجاه يتوافق مع ضبط النموذج لحلقات استدعاء الأدوات بدلاً من الدردشة أحادية الدور.

إذا كنت تقوم بإنشاء تعريفات الأدوات من واجهة برمجة تطبيقات تمتلكها بالفعل، فإن منشورنا حول تحويل مواصفات OpenAPI إلى أدوات وكيل يغطي كيفية القيام بذلك دون كتابة المخططات يدويًا.

معالجة الأخطاء الجديرة بالكتابة

ثلاثة أنماط للفشل تمثل معظم مشكلات الإنتاج على نقطة النهاية هذه.

حدود المعدل (Rate limits). أعد المحاولة مع التراجع الأسي والتذبذب. تنتج فترة إعادة محاولة ثابتة عبر العديد من العمال عمليات إعادة محاولة متزامنة، وهي الطريقة الكلاسيكية لتحويل حد مؤقت إلى حد مستمر.

import time, random
from openai import RateLimitError

def call_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            if attempt == 4:
                raise
            time.sleep((2 ** attempt) + random.random())

تجاوز سياق (Context overflow). نافذة بحجم مليون رمز كبيرة بما يكفي ليتوقف الناس عن العد، ثم يتجاوزها مستند طويل بالإضافة إلى عدد قليل من الصور عالية الدقة. تستهلك الصور السياق، ويصل الخطأ في وقت الطلب بدلاً من عند تجميع المطالبة. تتبع ميزانية الرموز الخاصة بك عند الإدخال.

إخراج مقتطع (Truncated output). إذا توقفت الاستجابة في منتصف الجملة، تحقق من finish_reason في الاختيار. تعني قيمة length أنك وصلت إلى حد الإخراج، وليس أن النموذج استسلم. نظرًا لأن رقم الإخراج الأقصى نفسه متنازع عليه بين المصادر، فإن هذا يستحق التحقق منه صراحة بدلاً من الافتراض.

قراءة استخدام الرموز

تحمل كل استجابة كائن usage، وهو المصدر الموثوق الوحيد لتكلفة المكالمة الفعلية:

print(response.usage.prompt_tokens, response.usage.completion_tokens)

راقب عدد الإكمال على وجه الخصوص. مع ضبط reasoning_effort على القيمة الافتراضية max، يتم احتساب رموز التفكير كإخراج، لذا يمكن أن تحمل إجابة مرئية قصيرة عددًا كبيرًا من الإكمال خلفها. مقارنة هذا العدد عبر مستويات الجهد على مطالباتك الخاصة هي أسرع طريقة لتحديد الإعداد الذي تحتاجه بالفعل.

ماذا يكلف

سعر القائمة هو 0.15 دولار لكل مليون رمز إدخال، 0.50 دولار لكل مليون رمز إخراج، و 0.03 دولار لكل مليون رمز إدخال مخزن مؤقتًا. يسري خصم إطلاق بنسبة 50% حتى 9 سبتمبر 2026، مما يخفض هذه الأسعار إلى 0.075 دولار، 0.25 دولار، و 0.015 دولار.

تختلف الأسعار بين الموزعين. OpenRouter، Cloudflare Workers AI، Vercel AI Gateway، DeepInfra، وغيرهم، جميعهم يقدمون النموذج بأسعارهم الخاصة. تحليلنا للأسعار يشرح حساب التكلفة وما يتغير عند انتهاء الخصم. تحقق من أي رقم مقابل المزود الذي تستخدمه بالفعل قبل أن تضع ميزانية عليه.

اختبار التكامل

هناك أمران في واجهة برمجة التطبيقات هذه مزعجان للتحقق منهما يدويًا. الحمولة متعددة الوسائط مطولة، لذا فإن كتلة صورة base64 في أمر curl غير سارة للكتابة وأسوأ لإعادة التشغيل. وتعد تبديلات النموذج بالضبط نوع التغيير الذي يغير شكل الاستجابة بصمت.

يتعامل Apidog مع كليهما. احفظ استدعاء النص، واستدعاء الصورة، واستدعاء الأدوات كمجموعة، وأرفق تأكيدات بحقول الاستجابة التي يقرأها تطبيقك بالفعل، وخزن مفتاح API كمتغير بيئة بدلاً من لصقه في سطر الأوامر. عندما ينتهي خصم الإطلاق وتقرر ما إذا كنت ستبقى على Flash أو تنتقل إلى GLM-5.3، يمكنك تبديل معرف النموذج في مكان واحد وإعادة تشغيل المجموعة ضد كليهما.

هذا يحول ترحيل النموذج إلى فرق يمكنك النظر إليه بدلاً من شيء تأمل أن يعمل.

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

ما هو معرف النموذج بالضبط؟ glm-5.3-flash على واجهة برمجة تطبيقات Z.ai. على OpenRouter هو z-ai/glm-5.3-flash.

هل تعمل حزمة OpenAI SDK حقًا بدون تغييرات؟ نعم، لإكمال الدردشة والتدفق واستدعاء الأدوات. تحتاج المعلمات غير القياسية مثل reasoning_effort إلى extra_body في حزمة Python SDK.

كم عدد الصور التي يمكنني إرسالها في طلب واحد؟ متعددة، كل منها ككتلة image_url خاصة بها. تأتي الحدود العملية من ميزانية السياق الخاصة بك بدلاً من عدد ثابت.

لماذا استجاباتي مطولة وبطيئة جدًا؟ reasoning_effort افتراضيًا max. اضبطه على low للأعمال التي لا تحتاج إلى تفكير.

ما هو الحد الأقصى لطول الإخراج؟ تختلف المصادر: OpenRouter يسرد 131,072 رمزًا وتشير بطاقة Hugging Face إلى 163,840. تحقق من المزود الخاص بك قبل الاعتماد على عمليات توليد طويلة جدًا.