Blog

كيفية استخدام واجهة برمجة تطبيقات Mistral Medium 3.5؟

Ashley Innocent

Ashley Innocent

30 أبريل 2026

كيفية استخدام واجهة برمجة تطبيقات Mistral Medium 3.5؟

أصدرت ميسترال الإصدار Medium 3.5 في 29 أبريل 2026. معرف نموذج الـ API هو mistral-medium-3.5، ونقطة النهاية هي https://api.mistral.ai/v1/chat/completions، وشكل الطلب قريب بما يكفي من معيار OpenAI بحيث يتطلب تبديل عناوين URL الأساسية من مزود آخر سطرًا واحدًا من التعليمات البرمجية. الأرقام الرئيسية هي نافذة سياق بحجم 256 ألفًا، ورؤية مدمجة، واستدعاء الوظائف، ودعم 24 لغة، و77.6% على SWE-Bench Verified؛ وهي أرقام تضعها في نفس مستوى GPT-5.5 و DeepSeek V4 لأنواع العمل القائم على الوكلاء والمركز على التعليمات البرمجية التي تقوم معظم الفرق بتجهيزها حاليًا.

يغطي هذا الدليل المصادقة، وكل معلمة مهمة، وأمثلة بايثون ونود، ومدخلات الرؤية، واستدعاء الأدوات، ووضع JSON، والبث، ومعالجة الأخطاء، وسير عمل Apidog الذي يحافظ على تكلفة مرئية أثناء تكرار المطالبات. لأدلة النماذج المماثلة، انظر كيفية استخدام DeepSeek V4 API و كيفية استخدام GPT-5.5 API.

زر

ملخص

ما الذي تغير في Medium 3.5

تم إطلاق Medium 3 في وقت سابق من العام كنموذج نصي فقط بسياق 128 ألفًا. أما Medium 3.5 فهو أمر مختلف تمامًا. إنه أول نموذج مدمج رائد لميسترال: يتميز باتباع التعليمات والاستدلال والترميز في مجموعة واحدة من الأوزان، لذلك لم تعد تختار بين نقطة تحقق للمحادثة ونقطة تحقق للاستدلال. الرؤية مدمجة، ويتضاعف السياق إلى 256 ألفًا، ويتم تضمين استدعاء الوظائف على مستوى النموذج بدلاً من إضافتها عبر واجهة API منفصلة.

صورة Mistral Medium 3.5

ترتكز الترقية على ثلاثة أرقام. نسبة 77.6% في SWE-Bench Verified تضعها في نفس مستوى النماذج الرائدة في تصحيح التعليمات البرمجية. و91.4 في τ³-Telecom تضعها في المقدمة على معظم النماذج العامة في الحوارات التفاعلية متعددة الأدوار. يغطي سياق 256 ألفًا قاعدة تعليمات برمجية متوسطة الحجم بالكامل أو نصًا مسجلًا لعدة ساعات دون اقتطاع. ليست أي من هذه الأرقام أخطاء تقريب تسويقية؛ بل ترتبط مباشرة بقدرة النموذج على إنجاز مهمتك دون الحاجة إلى محاولة ثانية.

تغيير التسعير هو الجزء الذي يجب أخذه في الاعتبار عند وضع الميزانية. كان سعر Medium 3 هو 0.40 دولار لكل مليون رمز إدخال و2.00 دولار لكل مليون رمز إخراج. يقفز Medium 3.5 إلى 1.5 دولار للإدخال و7.5 دولار للإخراج، أي حوالي 4 أضعاف. هذه هي تكلفة نهج نقاط التحقق المدمجة بالإضافة إلى الرؤية بالإضافة إلى السياق الأطول. تعامل مع Medium 3 الأقدم كخيار للإنتاجية العالية، ومع Medium 3.5 كالمستوى "أحتاج هذه الإجابة بشكل صحيح".

المتطلبات الأساسية

قبل أول استدعاء، جهّز أربعة أمور.

سير عمل Apidog

صدر المفتاح مرة واحدة:

export MISTRAL_API_KEY="..."

نقطة النهاية والمصادقة

تكشف منصة ميسترال (La Plateforme) عن كل شيء من خلال عنوان URL أساسي واحد.

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

المصادقة هي رمز حامل (bearer token) في ترويسة Authorization. يبدو الحد الأدنى من الطلب القابل للتنفيذ كما يلي:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {"role": "user", "content": "Explain dense merged checkpoints in two sentences."}
    ]
  }'

يعيد الاستجابة الناجحة هيئة JSON تحتوي على مصفوفة choices، وكتلة usage مقسمة إلى prompt_tokens و completion_tokens و total_tokens، ومعرف id يمكنك استخدامه للتتبع. تعيد حالات الفشل مظروف error مع code و message. يتطابق الشكل مع مظروف OpenAI بشكل وثيق بما يكفي بحيث يعمل أي محلل أخطاء لديك بالفعل دون تعديل.

معلمات الطلب

ترتبط كل حقل إما بالتكلفة أو بالسلوك. إليك الخريطة لـ mistral-medium-3.5.

المعلمة النوع القيم الملاحظات
model سلسلة mistral-medium-3.5 مطلوب.
messages مصفوفة أزواج الدور/المحتوى مطلوب. نفس مخطط OpenAI.
temperature عدد عشري 0 إلى 1.5 توصي ميسترال بـ 0.7 للاستخدام العام، و 0.3 للتعليمات البرمجية.
top_p عدد عشري 0 إلى 1 القيمة الافتراضية 1.0.
max_tokens عدد صحيح 1 إلى حد السياق يحدد طول المخرجات.
stream منطقي صحيح أو خطأ يُمكّن البث عبر SSE.
tools مصفوفة مواصفات أداة OpenAI استدعاء وظيفي أصلي.
tool_choice سلسلة أو كائن auto، any، none، أو أداة محددة يتحكم في استخدام الأداة. ملاحظة: any بدلاً من required.
response_format كائن {"type": "json_object"} أو مخطط JSON مخرجات مهيكلة.
random_seed عدد صحيح أي عدد صحيح لضمان قابلية التكرار. ملاحظة: ليس seed.
safe_prompt منطقي صحيح أو خطأ يضيف مقدمة الأمان الخاصة بـ ميسترال.
presence_penalty عدد عشري -2 إلى 2 يفرض عقوبة على تكرار المواضيع.
frequency_penalty عدد عشري -2 إلى 2 يفرض عقوبة على تكرار الرموز (tokens).

هناك اختلافان بسيطان يربكان الناس عند الانتقال من OpenAI: tool_choice="any" تعني "إجبار على استدعاء أداة" (تستخدم OpenAI required)، ومعلمة التمهيد (seed) هي random_seed (تستخدم OpenAI seed). كل شيء آخر متوافق.

عميل بايثون

تُصدر ميسترال حزمة SDK رسمية لبايثون تطابق API بشكل كامل.

import os
from mistralai import Mistral

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

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

print("Content:", response.choices[0].message.content)
print("Total tokens:", response.usage.total_tokens)
print("Cost estimate (USD):",
      response.usage.prompt_tokens * 1.5 / 1_000_000 +
      response.usage.completion_tokens * 7.5 / 1_000_000)

إذا كان لديك بالفعل قاعدة تعليمات برمجية بتنسيق OpenAI، فإن حزمة OpenAI Python SDK تعمل مع نقطة نهاية ميسترال بتغييرين: عنوان URL الأساسي ومعرف النموذج.

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MISTRAL_API_KEY"],
    base_url="https://api.mistral.ai/v1",
)

response = client.chat.completions.create(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Hello, Mistral."}],
)

مسار حزمة OpenAI SDK هو الطريق الأقل مقاومة للفرق التي تشغل تعليمات برمجية مستقلة عن المزود؛ بينما حزمة mistralai SDK الأصلية هي المسار الذي يكشف عن الميزات الخاصة بـ ميسترال بوضوح، لذا اختر بناءً على ما إذا كنت تخطط لاستخدام الرؤية والمخرجات المهيكلة بشكل مكثف.

عميل Node

نفس الاختيار ثنائي المسار في Node. حزمة SDK الأصلية:

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

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

const response = await client.chat.complete({
  model: "mistral-medium-3.5",
  messages: [
    { role: "user", content: "Explain dense merged checkpoints in plain English." },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log("Usage:", response.usage);

مسار حزمة OpenAI SDK، للتوافق مع التعليمات البرمجية الموجودة:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MISTRAL_API_KEY,
  baseURL: "https://api.mistral.ai/v1",
});

const response = await client.chat.completions.create({
  model: "mistral-medium-3.5",
  messages: [{ role: "user", content: "Hello, Mistral." }],
});

استجابات البث

عيّن stream: true وكرر قطع SSE. يتطابق الشكل مع OpenAI تمامًا، ويتم تضمين تتبع الاستدلال التراكمي في choices[].delta.content بدلاً من فصله إلى حقل جانبي.

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Stream a 300-word essay on merged checkpoints."}],
)

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

بالنسبة لإخراج الطرفية، فإن سرعة بث ميسترال أسرع من DeepSeek V4-Pro على نفس طول المطالبة، وتتساوى تقريبًا مع GPT-5.5، بناءً على التشغيلات جنبًا إلى جنب عبر عارض استجابات Apidog.

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

يأتي Medium 3.5 مزودًا بوظيفة استدعاء الأدوات الأصلية. تصبح الوظائف المعرفة في مصفوفة tools قابلة للاستدعاء، ويختار النموذج متى يتم استدعاؤها.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Return the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Weather in Lagos in Celsius?"}],
    tools=tools,
    tool_choice="auto",
)

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

من هناك، قم بتشغيل الوظيفة محليًا، وأضف النتيجة كرسالة role: "tool"، واستدعِ الـ API مرة أخرى لمواصلة الحلقة. النمط مطابق لحلقة استخدام أداة OpenAI. تظهر القدرة العاملة في نتيجة τ³-Telecom؛ عمليًا، يترجم ذلك إلى عدد أقل من القفزات الضائعة في سير العمل متعدد الأدوار حيث يتعين على النموذج أن يقرر بين استدعاء أداة، أو سؤال المستخدم، أو الإجابة مباشرة.

وضع JSON والمخرجات المهيكلة

للحصول على مخرجات تم التحقق من صحتها بواسطة مخطط (schema)، مرر مخطط JSON في response_format.

schema = {
    "type": "json_schema",
    "json_schema": {
        "name": "release_note",
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "date": {"type": "string"},
                "bullets": {"type": "array", "items": {"type": "string"}},
            },
            "required": ["title", "date", "bullets"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply with a single JSON object matching the schema."},
        {"role": "user", "content": "Summarize today's Mistral Medium 3.5 release."},
    ],
    response_format=schema,
)

يفرض الوضع الصارم المخطط (schema) في وقت فك التشفير، لذلك لا تحتاج إلى إضافة خطوة تحليل Pydantic أو Zod على العميل؛ فإما أن تتطابق الاستجابة مع المخطط أو يفشل الاستدعاء مع خطأ مهيكل. للحالات الأقل تعقيدًا حيث تحتاج فقط إلى JSON صالح بأي شكل، اضبط response_format={"type": "json_object"} وقم بالتحقق من صحته على جانب العميل.

إدخال الرؤية

تم تدريب مشفر الرؤية الخاص بـ Medium 3.5 من الصفر للتعامل مع أحجام الصور ونسب العرض إلى الارتفاع المتغيرة؛ لا تحتاج إلى تغيير حجم أي شيء مسبقًا. مرر محتوى الصورة جنبًا إلى جنب مع النص في مصفوفة messages.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What is in this image and what is it doing wrong?"},
            {"type": "image_url", "image_url": "https://example.com/diagram.png"},
        ],
    }],
)

تُحاسب مدخلات الصور كرموز إدخال بنفس معدل 1.5 دولار لكل مليون؛ يختلف العدد الدقيق للرموز لكل صورة حسب الدقة ويتم الإبلاغ عنه في حقل usage.prompt_tokens. لأحمال عمل الصور عالية الحجم، سجل تكلفة الرمز لكل صورة مبكرًا وقرر ما إذا كنت ستقوم بضغط الإطارات أو اقتصاصها أو تخطيها قبل التوسع.

بناء المجموعة في Apidog

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

  1. قم بتنزيل Apidog وأنشئ مشروعًا.
  2. أضف بيئة مع تخزين {{MISTRAL_API_KEY}} كمتغير سري بحيث لا يصل أبدًا إلى الصادرات المشتركة.
  3. احفظ طلب POST إلى {{BASE_URL}}/chat/completions مع ترويسة Authorization: Bearer {{MISTRAL_API_KEY}}.
  4. قم بتعريف المعلمات model و temperature و tool_choice بحيث يمكنك إجراء اختبار A/B بين المتغيرات دون تكرار الطلبات.
  5. استخدم عارض الاستجابات لفحص usage في كل تشغيل. أضف نصًا برمجيًا صغيرًا بعد الاستجابة يضرب prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000 بحيث تظهر تكلفة كل استدعاء بجانب كل نتيجة.

يمكن للفرق التي تدير بالفعل مجموعة DeepSeek V4 API المطابقة في Apidog تكرارها، وتبديل عنوان URL الأساسي إلى https://api.mistral.ai/v1، وتغيير معرف النموذج إلى mistral-medium-3.5، وتشغيل مطالبات مباشرة عبر كلا المزودين في دقائق. ينطبق نفس النمط على المقارنة مع GPT-5.5.

معالجة الأخطاء

يتبع غلاف الخطأ اتفاقيات OpenAI عن كثب. الرموز التي ستصادفها أولاً:

الرمز المعنى الإصلاح
400 طلب سيء تحقق من مخطط JSON، خاصة messages و tools.
401 مفتاح غير صالح أعد الإنشاء على console.mistral.ai.
402 الدفع مطلوب قم بتعبئة الرصيد أو أضف بطاقة.
403 النموذج غير مسموح به تحقق من نطاق مفتاح المشروع وتدقيق معرف النموذج.
422 معلمة خارج النطاق max_tokens يتجاوز السياق، أو tool_choice مشوه.
429 تجاوز الحد الأقصى للمعدل تراجع، ثم أعد المحاولة مع تباين أسي (exponential jitter).
500 خطأ في الخادم أعد المحاولة مرة واحدة. إذا تكرر، تحقق من صفحة الحالة.
503 حمل زائد ارجع إلى Mistral Medium 3 أو انتظر 30 ثانية.

قم بتضمين الاستدعاءات في مساعد إعادة المحاولة الذي يتعامل مع الأخطاء 429 و 5xx مع التراجع الأسي. لا تعد محاولة الأخطاء 4xx تلقائيًا؛ فهذه أخطاء منطقية وليست أعطالًا عابرة. يجعل عارض استجابات Apidog من السهل اكتشاف حمولة tools المشوهة لأن الحقل المسبب للمشكلة يتم تمييزه في جسم الطلب بجانب الخطأ.

أنماط التحكم في التكلفة

القفزة السعرية بمقدار 4 أضعاف من Medium 3 إلى Medium 3.5 تعاقب التوجيه غير الفعال. خمسة أنماط تحافظ على فاتورة متوقعة.

  1. الافتراضي هو Medium 3، ثم الترقية إلى Medium 3.5. قم بتشغيل تمريرة أولى رخيصة على Medium 3 ووجه المطالبات الصعبة إلى 3.5 فقط عندما تعيد التمريرة الرخيصة ثقة منخفضة أو تفشل في المدقق.
  2. تحديد سقف max_tokens. معظم الإجابات تتناسب مع 2000 رمز إخراج. نافذة السياق بحجم 256 ألفًا هي للكم الهائل من المدخلات، وليس للكم الهائل من المخرجات؛ فالمخرجات هي الجانب المكلف بسعر 7.5 دولار لكل مليون.
  3. حافظ على إيجاز المطالبات النظامية. يتم احتساب كل رمز في المطالبة النظامية في كل استدعاء؛ تقليص مقدمة بحجم 2000 رمز إلى 500 رمز يقلل فاتورة الإدخال بنسبة 75% على نقطة نهاية عالية الحجم.
  4. سجل usage في كل استدعاء. أرسل prompt_tokens و completion_tokens وتقدير التكلفة بالدولار لكل استدعاء إلى مكدس المراقبة الخاص بك. يلتقط تنبيه عند ارتفاع مفاجئ في رموز الإخراج المطالبات التي انحرفت إلى منطقة تسلسل الأفكار.
  5. استخدم الرؤية بشكل انتقائي. تتراكم رموز الصور بسرعة. اقتصاص المنطقة ذات الصلة قبل الإرسال، وتقليل الحجم إلى أدنى دقة لا تزال تجيب على السؤال.

مقارنة Medium 3.5 بمستويات ميسترال الأخرى

تشكيلة ميسترال اعتبارًا من أواخر أبريل 2026:

النموذج السياق الإدخال $/مليون الإخراج $/مليون الرؤية الأفضل لـ
mistral-small 32 ألفًا 0.10 دولارًا 0.30 دولارًا لا التصنيف عالي الحجم، الدردشة الخفيفة
mistral-medium-3 128 ألفًا 0.40 دولارًا 2.00 دولارًا لا الإنتاجية الكبيرة، الدردشة الأطول
mistral-medium-3.5 256 ألفًا 1.5 دولارًا 7.5 دولارًا نعم الاستدلال، التعليمات البرمجية، الرؤية، الوكلاء
mistral-large 128 ألفًا 2.00 دولارًا 6.00 دولارًا محدود الاستدلال النصي من الفئة الرائدة

يُعد Medium 3.5 المستوى الوحيد الذي يجمع بين السياق الطويل والرؤية وقدرات الاستدلال المدمجة. يقدم المستوى الكبير منحنى تكلفة مختلفًا (مخرجات أرخص، مدخلات أغلى) ويتفوق على 3.5 في بعض معايير النصوص فقط؛ اختر حسب عبء العمل، وليس حسب اسم المستوى.

الترحيل من مزود آخر

الترحيل هو في الغالب تغيير لعنوان URL الأساسي.

من OpenAI:

- base_url="https://api.openai.com/v1"
- model="gpt-5.5"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

من DeepSeek:

- base_url="https://api.deepseek.com/v1"
- model="deepseek-v4-pro"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

نقطتان يجب الانتباه إليهما:

قم بتشغيل الفروقات عبر مجموعة الاختبارات الحالية لديك قبل تحويل حركة المرور الإنتاجية. والأفضل من ذلك، قم بعكس حركة المرور إلى ميسترال في وضع الظل ليوم واحد، وسجل كلا الاستجابتين، وقارن بينهما في Apidog قبل الترقية.

حالات الاستخدام الواقعية

بعض الأنماط حيث يثبت Medium 3.5 جدواه بالفعل:

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

زر

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل