DEV Community

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

Posted on • Originally published at apidog.com

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

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

جرّب Apidog اليوم

في هذا الدليل ستنفّذ استدعاءات فعلية لـ Mistral Medium 3.5: المصادقة، المعلمات المهمة، أمثلة Python وNode، إدخال الصور، استدعاء الأدوات، JSON Mode، البث، معالجة الأخطاء، وتتبع التكلفة باستخدام Apidog. وللمقارنة مع نماذج مشابهة، راجع كيفية استخدام DeepSeek V4 API وكيفية استخدام GPT-5.5 API.

ملخص سريع

  • نقطة النهاية: POST https://api.mistral.ai/v1/chat/completions.
  • المصادقة: Authorization: Bearer <MISTRAL_API_KEY>.
  • معرف النموذج: mistral-medium-3.5.
  • نافذة السياق: 256 ألف رمز.
  • التسعير: 1.5 دولار لكل مليون رمز إدخال، و7.5 دولار لكل مليون رمز إخراج.
  • يدعم الرؤية، استدعاء الوظائف، JSON المهيكل، والبث عبر SSE.
  • الأوزان المفتوحة متوفرة على Hugging Face باسم mistralai/Mistral-Medium-3.5-128B بموجب ترخيص MIT معدل مع استثناء للإيرادات الكبيرة.
  • يمكنك تنزيل Apidog لاختبار الطلبات، تخزين المفتاح كمتغير سري، ومقارنة تكلفة كل تشغيل.

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

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

صورة Mistral Medium 3.5

الأرقام المهمة عمليًا:

  • 77.6% على SWE-Bench Verified: مناسب لمراجعة وتصحيح التعليمات البرمجية.
  • 91.4 على τ³-Telecom: جيد في الحوارات متعددة الأدوار واستخدام الأدوات.
  • سياق 256k: يسمح بتمرير ملفات كثيرة، مستندات طويلة، أو محادثات كبيرة دون تقسيم مبكر.

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

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

قبل أول طلب، جهّز التالي:

  1. حساب على console.mistral.ai مع طريقة دفع أو رصيد متاح.
  2. مفتاح API مخصص للمشروع.
  3. بيئة تشغيل:
    • Python مع حزمة mistralai أو openai.
    • أو Node.js مع @mistralai/mistralai أو openai.
  4. عميل API مثل curl للاختبار الأول، ثم Apidog لتخزين الطلبات، المتغيرات، والنتائج بشكل منظم.

سير عمل Apidog

صدّر المفتاح في الطرفية:

export MISTRAL_API_KEY="..."
Enter fullscreen mode Exit fullscreen mode

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

كل استدعاءات المحادثة تمر عبر:

POST https://api.mistral.ai/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

أبسط طلب باستخدام curl:

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

الاستجابة الناجحة تحتوي عادةً على:

  • choices: مخرجات النموذج.
  • usage.prompt_tokens: رموز الإدخال.
  • usage.completion_tokens: رموز الإخراج.
  • usage.total_tokens: الإجمالي.
  • id: معرف الطلب للتتبع.

مثال على حساب تكلفة الطلب:

cost =
  prompt_tokens * 1.5 / 1_000_000 +
  completion_tokens * 7.5 / 1_000_000
Enter fullscreen mode Exit fullscreen mode

معلمات الطلب المهمة

المعلمة النوع القيم الاستخدام
model string mistral-medium-3.5 مطلوب
messages array رسائل system / user / assistant مطلوب
temperature number 0 إلى 1.5 استخدم 0.3 للكود و0.7 للاستخدام العام
top_p number 0 إلى 1 الافتراضي 1.0
max_tokens integer حسب السياق يحدد الحد الأقصى للمخرجات
stream boolean true / false تفعيل البث
tools array مواصفات أدوات OpenAI استدعاء وظائف
tool_choice string/object auto / any / none / أداة محددة any تعني إجبار استدعاء أداة
response_format object JSON object أو JSON schema مخرجات منظمة
random_seed integer أي عدد صحيح قابلية تكرار أفضل
safe_prompt boolean true / false إضافة مقدمة أمان من ميسترال
presence_penalty number -2 إلى 2 تقليل تكرار المواضيع
frequency_penalty number -2 إلى 2 تقليل تكرار الرموز

انتبه لاختلافين عند الترحيل من OpenAI:

  • في ميسترال: tool_choice="any" بدل tool_choice="required".
  • في ميسترال: random_seed بدل seed.

استخدام Python SDK الرسمي

ثبّت الحزمة:

pip install mistralai
Enter fullscreen mode Exit fullscreen mode

مثال كامل:

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,
)

content = response.choices[0].message.content
prompt_tokens = response.usage.prompt_tokens
completion_tokens = response.usage.completion_tokens

cost = (
    prompt_tokens * 1.5 / 1_000_000 +
    completion_tokens * 7.5 / 1_000_000
)

print(content)
print("Total tokens:", response.usage.total_tokens)
print("Estimated cost USD:", cost)
Enter fullscreen mode Exit fullscreen mode

استخدام OpenAI SDK مع Mistral

إذا كانت لديك قاعدة كود مبنية على OpenAI SDK، غيّر base_url ومعرف النموذج فقط:

import os
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."}
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

استخدم OpenAI SDK إذا كنت تريد طبقة موحدة بين مزودين. واستخدم mistralai إذا كنت تريد وضوحًا أكبر في ميزات ميسترال الخاصة.

استخدام Node.js

ثبّت SDK الرسمي:

npm install @mistralai/mistralai
Enter fullscreen mode Exit fullscreen mode

مثال:

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);
Enter fullscreen mode Exit fullscreen mode

وباستخدام OpenAI SDK في Node:

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." },
  ],
});

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

البث Streaming

فعّل stream: true عندما تحتاج عرض النتيجة تدريجيًا في واجهة مستخدم أو CLI.

مثال Python:

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)
Enter fullscreen mode Exit fullscreen mode

الشكل قريب من OpenAI SSE، والمحتوى يأتي داخل:

choices[].delta.content
Enter fullscreen mode Exit fullscreen mode

في الاختبارات الجانبية عبر عارض الاستجابات في Apidog، يمكن مقارنة زمن أول رمز، زمن الإكمال، وعدد الرموز لكل تشغيل بين Mistral وDeepSeek وGPT.

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

عرّف الأدوات داخل 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)
print(tool_call.function.arguments)
Enter fullscreen mode Exit fullscreen mode

النمط العملي:

  1. أرسل السؤال مع تعريف الأدوات.
  2. إذا أعاد النموذج tool_calls، نفّذ الدالة محليًا.
  3. أضف نتيجة الدالة كرسالة role: "tool".
  4. أعد استدعاء النموذج ليولّد الإجابة النهائية.

لإجبار النموذج على استخدام أداة، استخدم:

{
  "tool_choice": "any"
}
Enter fullscreen mode Exit fullscreen mode

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

إذا كنت تحتاج مخرجات قابلة للمعالجة مباشرة، استخدم response_format.

مثال JSON Schema:

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,
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

للحالات الأبسط، اطلب JSON صالحًا فقط:

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "user", "content": "Return three API testing tips as JSON."}
    ],
    response_format={"type": "json_object"},
)
Enter fullscreen mode Exit fullscreen mode

حتى مع JSON Mode، احتفظ بالتحقق على جانب العميل إذا كان الناتج سيُستخدم في مسار إنتاجي حساس.

إدخال الصور Vision Input

يدعم Medium 3.5 إرسال نص وصورة في نفس الرسالة.

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",
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

تُحاسب الصور كرموز إدخال. العدد الفعلي يظهر في:

usage.prompt_tokens
Enter fullscreen mode Exit fullscreen mode

لخفض التكلفة في أحمال الصور الكبيرة:

  • اقتص المنطقة المهمة فقط.
  • قلّل الدقة إلى الحد الكافي للإجابة.
  • لا ترسل إطارات فيديو متشابهة دون تصفية.
  • سجّل تكلفة كل صورة في مرحلة الاختبار قبل التوسع.

بناء مجموعة اختبار في Apidog

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

  1. نزّل Apidog وأنشئ مشروعًا.
  2. أضف بيئة باسم Mistral.
  3. خزّن المفتاح كمتغير سري: 
   MISTRAL_API_KEY=...
Enter fullscreen mode Exit fullscreen mode
  1. أضف متغيرًا للعنوان الأساسي: 
   BASE_URL=https://api.mistral.ai/v1
Enter fullscreen mode Exit fullscreen mode
  1. أنشئ طلب: 
   POST {{BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode
  1. أضف الترويسات: 
   Authorization: Bearer {{MISTRAL_API_KEY}}
   Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. استخدم جسم طلب قابل للتعديل: 
   {
     "model": "mistral-medium-3.5",
     "temperature": 0.3,
     "max_tokens": 2048,
     "messages": [
       {
         "role": "user",
         "content": "Review this function and suggest improvements."
       }
     ]
   }
Enter fullscreen mode Exit fullscreen mode

بعد كل تشغيل، افحص usage واحسب التكلفة:

const usage = response.json().usage;

const cost =
  usage.prompt_tokens * 1.5 / 1_000_000 +
  usage.completion_tokens * 7.5 / 1_000_000;

console.log("Estimated cost USD:", cost);
Enter fullscreen mode Exit fullscreen mode

إذا كانت لديك مجموعة DeepSeek V4 API في Apidog، انسخها وغيّر:

- https://api.deepseek.com/v1
- deepseek-v4-pro
+ https://api.mistral.ai/v1
+ mistral-medium-3.5
Enter fullscreen mode Exit fullscreen mode

وينطبق النمط نفسه على المقارنة مع GPT-5.5.

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

أكثر الأخطاء التي ستراها في البداية:

الرمز المعنى الإصلاح
400 طلب غير صالح تحقق من JSON، خصوصًا messages وtools
401 مفتاح غير صالح أنشئ مفتاحًا جديدًا من console.mistral.ai
402 الدفع مطلوب أضف رصيدًا أو بطاقة
403 النموذج غير مسموح تحقق من نطاق مفتاح المشروع ومعرف النموذج
422 معلمة خارج النطاق راجع max_tokens أو tool_choice
429 تجاوز حد المعدل استخدم exponential backoff مع jitter
500 خطأ خادم أعد المحاولة مرة واحدة
503 حمل زائد انتظر أو استخدم نموذجًا بديلًا مؤقتًا

مثال retry بسيط في Python:

import time
import random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except Exception as exc:
            status = getattr(exc, "status_code", None)

            if status not in [429, 500, 502, 503, 504]:
                raise

            if attempt == retries - 1:
                raise

            sleep_seconds = (2 ** attempt) + random.random()
            time.sleep(sleep_seconds)
Enter fullscreen mode Exit fullscreen mode

لا تعِد محاولة أخطاء 4xx تلقائيًا باستثناء حالات محددة مثل 429. غالبًا هي أخطاء في الطلب نفسه وليست أعطالًا عابرة.

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

بما أن تكلفة Medium 3.5 أعلى من Medium 3، استخدمه بوعي:

  1. ابدأ بنموذج أرخص ثم صعّد عند الحاجة

    استخدم Medium 3 للمهام البسيطة، وMedium 3.5 عندما يفشل المدقق أو تنخفض الثقة.

  2. ضع حدًا واضحًا لـ max_tokens

    الإخراج أغلى من الإدخال. لا تتركه مفتوحًا دون سبب.

  3. اختصر رسالة النظام

    كل رمز في system يُدفع في كل استدعاء.

  4. سجّل usage دائمًا

    أرسل prompt_tokens وcompletion_tokens وتكلفة الطلب إلى نظام المراقبة.

  5. استخدم الرؤية فقط عند الحاجة

    لا ترسل صورًا كاملة إذا كان السؤال يتعلق بجزء صغير منها.

  6. اختبر المطالبات قبل الإنتاج

    قارن عدة صيغ في Apidog واختر الأقل تكلفة مع نفس الجودة.

مقارنة 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 هو الخيار الأنسب عندما تحتاج اجتماع السياق الطويل والرؤية واستدعاء الأدوات في نموذج واحد. اختر حسب عبء العمل لا حسب اسم المستوى.

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

من OpenAI:

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

من DeepSeek:

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

عدّل أيضًا:

- tool_choice="required"
+ tool_choice="any"
Enter fullscreen mode Exit fullscreen mode 
- seed=123
+ random_seed=123
Enter fullscreen mode Exit fullscreen mode

قبل تحويل حركة الإنتاج:

  1. شغّل مجموعة الاختبارات الحالية.
  2. قارن جودة الإجابات.
  3. قارن عدد الرموز والتكلفة.
  4. جرّب shadow traffic ليوم واحد إن كان النظام حساسًا.

حالات استخدام مناسبة

  • مساعد مراجعة كود

    سياق 256 ألفًا ونتيجة SWE-Bench Verified تجعله مناسبًا لتحليل Pull Requests كبيرة.

  • أسئلة وأجوبة على مستندات طويلة

    يمكنك تمرير عقود، سياسات، أو RFPs طويلة دون تقسيم مبكر.

  • استخراج بيانات من صور ومستندات

    مفيد للإيصالات، لقطات الشاشة، الجداول، والرسوم البيانية.

  • وكلاء يستخدمون أدوات

    استدعاء الوظائف الأصلي يقلل دورات التصحيح اليدوي لمدخلات الأدوات.

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

ما هو معرف النموذج؟

استخدم mistral-medium-3.5 في API المستضاف. على Hugging Face، نقطة التحقق باسم mistralai/Mistral-Medium-3.5-128B.

هل هو متوافق مع OpenAI؟

قريب جدًا. تعمل حزم OpenAI Python وNode عادةً مع تغيير base_url. الاختلافان العمليان هما tool_choice="any" وrandom_seed.

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

نعم، الأوزان مفتوحة بموجب ترخيص MIT معدل مع استثناء للإيرادات الكبيرة. لكن نموذج 128B يحتاج ذاكرة GPU كبيرة. توجد إصدارات GGUF كمية مثل unsloth/Mistral-Medium-3.5-128B-GGUF. أنماط التشغيل مشابهة لما في كيفية تشغيل DeepSeek V4 محليًا.

هل يدعم البث مع استدعاءات الأدوات؟

نعم. يمكن أن تصل أجزاء استدعاء الأداة تدريجيًا عبر delta.tool_calls ثم تُجمّع في JSON كامل عند نهاية البث.

كيف أحسب الرموز قبل الإرسال؟

استخدم أداة الترميز في حزمة mistral-common للحصول على عد قريب من usage.prompt_tokens.

هل يجب أن أستخدم سياق 256 ألفًا دائمًا؟

لا. السياق الطويل مكلف خطيًا. استخدمه فقط عندما تحتاجه فعلًا. كثير من أحمال الإنتاج تكفيها نافذة أقل من 32 ألفًا.

هل توجد طبقة مجانية؟

لا تعلن ميسترال عن طبقة مجانية دائمة، لكن الحسابات الجديدة قد تحصل على رصيد تجريبي. لتجربة مجانية مستمرة مع نماذج من فئة مشابهة، راجع كيفية استخدام DeepSeek V4 API مجانًا.

Top comments (0)