كيفية استخدام Mistral Large 4 API؟

أصبح Mistral Large 4 متاحًا على واجهة برمجة تطبيقات Mistral في 6 أكتوبر 2026، قبل ثلاثة أسابيع من إطلاق أوزانه المفتوحة. إذا كنت ترغب في تجربة نموذج "Le Chonk" ذي التريليون معلمة الآن، فإن واجهة برمجة التطبيقات هي الطريقة الوحيدة للوصول إليه، وحاليًا هي أيضًا الطريقة الأرخص: تُدرجه Mistral بسعر 0.68 دولار لكل مليون رمز إدخال و 2.09 دولار لكل مليون رمز إخراج خلال المعاينة العامة، وهو نصف السعر المعلن البالغ 1.36 دولار / 4.18 دولار.

يرشدك هذا الدليل من البداية إلى إجراء أول مكالمة عاملة في حوالي خمس دقائق، ثم يغطي الأجزاء التي قد تربك المستخدمين: أجزاء التفكير (reasoning chunks)، إدخال الصور، استدعاء الدوال (function calling)، مخرجات JSON والتكلفة. يمكن حفظ كل طلب وإعادة تشغيله في Apidog بحيث يمكنك مقارنة Large 4 بأي نموذج تستخدمه اليوم.

هل أنت جديد على النموذج نفسه؟ اقرأ أولاً ميسترال يعود: Le Chonk يتغلب على GPT-6 Astra و Claude في Cyber للحصول على المعايير والنقطة الأساسية وراء العنوان الرئيسي حول الأمن السيبراني.

ماذا تحتاج

الخطوة 1: الحصول على مفتاح API

1. سجّل الدخول إلى Mistral Studio (المعروف سابقًا باسم La Plateforme).
2. افتح API Keys (مفاتيح API) وأنشئ مفتاحًا جديدًا. امنحه اسمًا يشير إلى مكان استخدامه، مثل local-dev أو ci-staging.
3. انسخه مرة واحدة. لن يظهر الاستوديو المفتاح مرة أخرى.
4. صدّره في سطر الأوامر الخاص بك:

export MISTRAL_API_KEY="your-key-here"

احفظ المفتاح بعيدًا عن نظام التحكم بالمصدر. إذا كنت تقوم بتوصيله بأدوات متعددة، فإن دليلنا حول أفضل الممارسات لإدارة مفاتيح API يغطي التدوير وتحديد النطاق.

الخطوة 2: إجراء أول استدعاء لك

أسرع فحص هو باستخدام curl العادي:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {"role": "user", "content": "Give me three edge cases to test on a pagination API."}
    ]
  }'

تُرجع الاستجابة الناجحة choices[0].message.content مع الإجابة، وكتلة usage تحتوي على prompt_tokens، completion_tokens و total_tokens. إذا تلقيت 401، فالمفتاح خاطئ أو لم يتم تصديره. يشير رمز 404 للنموذج عادةً إلى خطأ إملائي في معرف النموذج.

نفس الاستدعاء في Python

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-large-4",
    messages=[
        {"role": "user", "content": "Give me three edge cases to test on a pagination API."}
    ],
)

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

وفي TypeScript

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.chat.complete({
  model: "mistral-large-4",
  messages: [
    { role: "user", content: "Give me three edge cases to test on a pagination API." },
  ],
});

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

الخطوة 3: حفظه في Apidog

تصبح أوامر curl متكررة بمجرد أن تبدأ في مقارنة النماذج. في Apidog:

1. أنشئ طلب HTTP جديدًا: POST https://api.mistral.ai/v1/chat/completions.
2. أضف متغير بيئة MISTRAL_API_KEY وقم بتعيين الرأس Authorization: Bearer {{MISTRAL_API_KEY}}.
3. الصق نص JSON من الخطوة 2 واضغط على إرسال.
4. كرر الطلب، غيّر model إلى النموذج الذي تستخدمه اليوم (على سبيل المثال mistral-medium-3-5)، وقم بتشغيلهما معًا.

لديك الآن طلبان محفوظان بنفس المطالبة. يعرض Apidog نص الاستجابة، الحالة، التوقيت، والحجم لكل منهما، بحيث يمكنك مقارنة جودة الإجابة، زمن الاستجابة (latency)، وعدد الرموز المميزة usage دون الحاجة لكتابة سكربت. أضف تأكيدًا بعد الاستجابة بأن choices[0].message.content ليس فارغًا، وبذلك يكون لديك اختبار دخان (smoke test) يمكنك إعادة تشغيله كلما قامت Mistral بتحديث المعاينة.

الخطوة 4: تشغيل وإيقاف التفكير

Large 4 هو نموذج هجين: نفس النموذج يتعامل مع الإجابات السريعة والتفكير خطوة بخطوة. يمكنك التحكم في ذلك بمعلمة واحدة، reasoning_effort:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {"role": "user", "content": "Our API returns 200 with an empty body under load. List likely causes in order of probability."}
    ],
    "reasoning_effort": "high"
  }'

هذا هو الجزء الذي يكسر المحللات (parsers). مع reasoning_effort: "high"، لم يعد message.content سلسلة نصية (string). بل يصبح قائمة من الأجزاء (chunks):

• جزء thinking يحمل أثر التفكير، و
• جزء text يحمل الإجابة النهائية.

لذلك، سيطبع response.choices[0].message.content قائمة، وليس إجابتك. استخرج جزء النص (text chunk) بشكل صريح:

response = client.chat.complete(
    model="mistral-large-4",
    messages=[{"role": "user", "content": "Why would a 200 response have an empty body?"}],
    reasoning_effort="high",
)

content = response.choices[0].message.content
if isinstance(content, str):
    answer = content
else:
    answer = "".join(c.text for c in content if c.type == "text")

print(answer)

تُحاسب رموز التفكير (thinking tokens) كرموز إخراج، لذا فإن "high" يكلف أكثر لكل طلب. استخدم "none" كافتراضي وقم بالتبديل إلى "high" فقط في الاستدعاءات التي تتطلب ذلك.

الخطوة 5: إرسال صورة

Large 4 هو نموذج متعدد الأنماط (multimodal) بطبيعته، مع مشفّر رؤية (vision encoder) ذي 1.6 مليار معلمة. مرر الصور كأجزاء محتوى بجانب نصك:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "This is a screenshot of our API error dashboard. Which endpoint is failing most and what is the error code?"},
          {"type": "image_url", "image_url": "https://example.com/dashboard.png"}
        ]
      }
    ]
  }'

بالنسبة للملفات المحلية، أرسل عنوان URL لبيانات base64 بدلاً من ذلك: "image_url": "data:image/png;base64,<encoded>". تفيد Mistral أن Large 4 يحقق 42% في معيار Dense 200 لتحديد المواقع البصرية (visual-grounding benchmark)، متقدمًا قليلاً على GPT-6 Astra بنسبة 41%، لذا فإن لقطات الشاشة للوحات التحكم والرسوم البيانية وحالات واجهة المستخدم مناسبة بشكل معقول.

الخطوة 6: استدعاء الدوال

يصبح استدعاء الدوال (Function calling) مفيدًا حيث تتجلى معايير أداء الوكيل (agent benchmarks) لنموذج Large 4 (59.9% في AutomationBench). تقوم أنت بوصف الأدوات، ويقرر النموذج متى يتم استدعاؤها، ويقوم كودك بتشغيل الاستدعاء.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Look up the status of an order by its ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string", "description": "The order ID, e.g. ORD-1042"}
                },
                "required": ["order_id"],
            },
        },
    }
]

messages = [{"role": "user", "content": "Where is order ORD-1042?"}]

response = client.chat.complete(
    model="mistral-large-4",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

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

قم بتشغيل الدالة بنفسك، ثم أعد إرسال النتيجة مع tool_call_id المطابق:

import json

result = {"order_id": "ORD-1042", "status": "shipped", "eta": "2026-10-09"}

messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "name": "get_order_status",
    "content": json.dumps(result),
    "tool_call_id": tool_call.id,
})

final = client.chat.complete(model="mistral-large-4", messages=messages, tools=tools)
print(final.choices[0].message.content)

مخطط الأداة (tool schema) هو مخطط JSON Schema عادي. إذا كانت واجهة برمجة التطبيقات (API) الخاصة بك تحتوي بالفعل على مواصفات OpenAPI، يمكنك نقل مخطط الطلب لكل عملية مباشرة إلى parameters. يساعد تصميم المواصفات في Apidog أولاً على الحفاظ على تعريفات الأدوات وواجهة برمجة التطبيقات الحقيقية متزامنة.

الخطوة 7: استلام JSON

عندما تحتاج إلى مخرجات قابلة للقراءة آليًا، اضبط response_format:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {"role": "user", "content": "Extract method, path and status code from: GET /v1/users/42 returned 404. Reply in JSON."}
    ],
    "response_format": {"type": "json_object"}
  }'

اذكر JSON في المطالبة وكذلك في response_format. بالنسبة للأشكال الصارمة، يدعم Mistral أيضًا {"type": "json_schema", "json_schema": {...}} مع مخطط كامل. في Apidog، أضف تأكيد مخطط JSON (JSON Schema assertion) على الاستجابة بحيث يفشل أي شكل غير متوقع بشكل واضح بدلاً من تعطيل خدمة تابعة.

التكلفة

مثال عملي: وكيل يُجري 10,000 استدعاء يوميًا، كل منها يحتوي على 3,000 رمز إدخال (غالبًا موجه نظام وأدوات مخزنة مؤقتًا) و 500 رمز إخراج.

• الإدخال: 30 مليون رمز. إذا كان 2,500 من كل 3,000 رمز مخزنًا مؤقتًا، فهذا يعني 25 مليون رمز مخزن مؤقتًا بسعر 0.07 دولار و 5 ملايين رمز جديد بسعر 0.68 دولار، أي حوالي 5.15 دولار/يوميًا.
• الإخراج: 5 ملايين رمز بسعر 2.09 دولار، أي حوالي 10.45 دولار/يوميًا.
• المجموع: حوالي 15.60 دولار/يوميًا بسعر المعاينة، أو حوالي 31 دولارًا بالسعر المعلن.

نفس عبء العمل على GPT-6 Astra (10 دولارات / 50 دولارًا لكل مليون، قبل خصومات التخزين المؤقت) سيكلف عدة مئات من الدولارات يوميًا. لم تحدد Mistral متى تنتهي أسعار المعاينة، لذا قم بوضع الميزانية بناءً على السعر المعلن.

الأخطاء الشائعة

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

هل Mistral Large 4 متوافق مع OpenAI؟ شكل الطلب قريب جدًا: model، messages، tools، tool_choice و response_format كلها تعمل بالطريقة التي تتوقعها. استخدم حزم تطوير Mistral (SDKs) أو HTTP العادي لتكون في أمان. مخرجات التفكير تستخدم صيغة أجزاء (chunk format) خاصة بـ Mistral.

متى يمكنني تشغيله محليًا؟ تقول Mistral أن الأوزان ستُشحن بحلول نهاية أكتوبر 2026. بوجود 1.05 تريليون معلمة إجمالية، فإنه يحتاج إلى أجهزة خادم متعددة وحدات معالجة الرسوميات (multi-GPU). يغطي دليلنا تشغيل Mistral 3 محليًا الأدوات اللازمة للنماذج الأصغر في هذه الأثناء.

هل المعاينة مستقرة بما يكفي للإنتاج؟ ليس بعد. النموذج مصنف كمعاينة عامة وقد يتغير قبل إطلاق الأوزان. قم بتثبيت اختباراتك (Pin your tests)، وأعد تشغيلها عندما تقوم Mistral بتحديث النموذج، واحتفظ بنموذج احتياطي مُعد.

هل يمكنني استخدام Large 4 مع كود Mistral الحالي الخاص بي؟ نعم. نفس عنوان URL الأساسي، نفس المصادقة، نفس حزمة تطوير البرامج (SDK). قم بتغيير سلسلة model إلى mistral-large-4. إذا كنت تنتقل من Medium 3.5، فراجع دليل واجهة برمجة تطبيقات Mistral Medium 3.5 الخاص بنا للأجزاء التي تنتقل.

خلاصة

في خمس دقائق تحصل على استدعاء يعمل. من الأفضل قضاء الساعة التالية في تشغيل مطالبك الحقيقية مقابل Large 4 ونموذجك الحالي جنبًا إلى جنب. احفظ كلا الطلبين في Apidog، أضف تأكيدات على الحالة وشكل الاستجابة، وستعرف في غضون يوم ما إذا كان Le Chonk يستحق مكانًا في نظامك، بينما لا يزال سعر المعاينة بنصف السعر.