Yusuf Khalidd

Posted on Oct 6 Originally published at apidog.com

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

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

جرّب Apidog اليوم

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

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

ماذا تحتاج

العنصر	القيمة
عنوان URL الأساسي	`https://api.mistral.ai/v1`
المصادقة	`Authorization: Bearer $MISTRAL_API_KEY`
معرف النموذج	`mistral-large-4`، أو الاسم البديل `mistral-large-4-0`
نقطة النهاية الرئيسية	`POST /v1/chat/completions`
نافذة السياق	1M tokens
أنواع الإدخال	نص، صور
حزمة Python	`pip install mistralai`
حزمة TypeScript	`npm install @mistralai/mistralai`

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

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

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: رموز الإدخال.
usage.completion_tokens: رموز الإخراج.
usage.total_tokens: إجمالي الرموز.

أخطاء البداية الأكثر شيوعًا:

401: المفتاح خاطئ أو لم يتم تصديره.
404: تحقق من كتابة معرف النموذج بدقة: mistral-large-4.

نفس الطلب في 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:

أنشئ طلب HTTP جديدًا:

   POST https://api.mistral.ai/v1/chat/completions

أضف متغير بيئة باسم MISTRAL_API_KEY.
أضف الرأس:

   Authorization: Bearer {{MISTRAL_API_KEY}}

الصق جسم JSON من الخطوة السابقة.
أرسل الطلب واحفظه.
انسخ الطلب وغيّر قيمة model إلى النموذج الذي تستخدمه حاليًا، مثل mistral-medium-3-5.
شغّل الطلبين بالمطالبة نفسها.

بهذا تحصل على مقارنة عملية لنص الاستجابة والحالة والوقت والحجم واستهلاك usage دون بناء سكربت مقارنة منفصل.

أضف اختبارًا بعد الاستجابة للتأكد من أن choices[0].message.content ليس فارغًا. سيصبح هذا اختبار دخان يمكنك تشغيله عند تحديث Mistral للمعاينة.

الخطوة 4: التحكم في التفكير

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

القيمة	السلوك	مناسب لـ
`"none"`	أقل قدر من التفكير، ولا تظهر كتلة تفكير في الاستجابة	الدردشة، الاستخراج، التصنيف، والطلبات الحساسة لزمن الاستجابة
`"high"`	كتلة تفكير كاملة قبل الإجابة النهائية	تصحيح الأخطاء، التخطيط متعدد الخطوات، الرياضيات، ومراجعة الكود

مثال على طلب يتطلب تحليلًا أعمق:

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

تعامل مع أجزاء التفكير دون كسر المحلل

عند استخدام reasoning_effort: "high"، لن تكون message.content سلسلة نصية دائمًا. تصبح قائمة من الأجزاء:

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

لذلك لا تفترض أن response.choices[0].message.content نص قابل للطباعة مباشرة. استخرج أجزاء النص صراحةً:

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(chunk.text for chunk in content if chunk.type == "text")

print(answer)

تُحاسب رموز التفكير كرموز إخراج، لذا استخدم "none" افتراضيًا وانتقل إلى "high" فقط عندما يستفيد الطلب فعلًا من التفكير الإضافي.

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

Large 4 نموذج متعدد الأنماط ويحتوي على مشفّر رؤية ذي 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"
          }
        ]
      }
    ]
  }'

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

{
  "type": "image_url",
  "image_url": "data:image/png;base64,<encoded>"
}

تفيد Mistral بأن Large 4 يحقق 42% في معيار Dense 200 لتحديد المواقع البصرية، مقابل 41% لـ GPT-6 Astra. لذلك تعد لقطات لوحات المراقبة والرسوم البيانية وحالات واجهة المستخدم مدخلات مناسبة للتحليل البصري.

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

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

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)
print(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)

مخطط الأداة هو JSON Schema عادي. إذا كانت API لديك تملك مواصفات OpenAPI، يمكنك نقل مخطط الطلب الخاص بكل عملية إلى parameters. يساعدك تصميم المواصفات في Apidog على إبقاء تعريفات الأدوات وواجهة API الفعلية متزامنة.

الخطوة 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 Schema للاستجابة. بهذه الطريقة يفشل الطلب بشكل واضح إذا تغيّر الشكل، بدل تمرير بيانات غير متوقعة إلى خدمة تابعة.

التكلفة

الاستخدام	سعر المعاينة	السعر المعلن
الإدخال، لكل مليون رمز	$0.68	$1.36
الإدخال المخزن مؤقتًا، لكل مليون رمز	$0.07	$0.14
الإخراج، لكل مليون رمز	$2.09	$4.18

مثال: وكيل ينفذ 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 موعد انتهاء سعر المعاينة، لذا ضع ميزانيتك وفق السعر المعلن.

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

الخطأ	السبب المحتمل	الإصلاح
`401 Unauthorized`	مفتاح مفقود أو خاطئ	تحقق من `echo $MISTRAL_API_KEY` ومن بادئة `Bearer`
`404` أو نموذج غير صالح	خطأ إملائي في معرف النموذج	استخدم `mistral-large-4` بدقة
`422 Unprocessable Entity`	جسم طلب غير صالح، وغالبًا مخطط `tools` غير صحيح	تحقق من JSON Schema في `parameters` لكل أداة
`429 Too Many Requests`	تجاوز حد المعدل لمساحة العمل	طبّق التراجع وإعادة المحاولة، أو ارفع الحدود في Studio
الإجابة تطبع كقائمة	`reasoning_effort: "high"` يعيد أجزاء محتوى	استخرج جزء `text` كما في الخطوة 4

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

هل Mistral Large 4 متوافق مع OpenAI؟

شكل الطلب قريب جدًا: model وmessages وtools وtool_choice وresponse_format تعمل كما تتوقع. استخدم حزم Mistral SDK أو HTTP مباشرًا. تختلف مخرجات التفكير لأنها تستخدم صيغة أجزاء خاصة بـ Mistral.

متى يمكن تشغيله محليًا؟

تقول Mistral إن الأوزان ستصل بحلول نهاية أكتوبر 2026. مع 1.05 تريليون معلمة إجمالية، يحتاج النموذج إلى أجهزة خادم متعددة وحدات معالجة الرسوميات. إلى ذلك الحين، راجع دليل تشغيل Mistral 3 محليًا للأدوات المناسبة للنماذج الأصغر.

هل المعاينة مستقرة بما يكفي للإنتاج؟

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

هل يمكن استخدام Large 4 مع كود Mistral الحالي؟

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

خلاصة

يمكنك الحصول على أول استدعاء ناجح خلال خمس دقائق. بعد ذلك، نفّذ مطالباتك الحقيقية على Large 4 ونموذجك الحالي جنبًا إلى جنب.

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

DEV Community