كيفية استخدام واجهة برمجة تطبيقات DeepSeek V4؟

تم إطلاق DeepSeek V4 مع واجهة برمجة التطبيقات (API) مباشرة في اليوم الأول. معرّفات النموذج هي deepseek-v4-pro و deepseek-v4-flash، ونقطة النهاية متوافقة مع OpenAI، وعنوان URL الأساسي هو https://api.deepseek.com. هذا يعني أن أي عميل تستخدمه بالفعل مع GPT-5.5 أو واجهات برمجة التطبيقات الأخرى المتوافقة مع OpenAI سيعمل مع V4 بمجرد تبديل عنوان URL الأساسي.

يغطي هذا الدليل المصادقة، كل معلمة مهمة، أمثلة Python و Node، الرياضيات في وضع التفكير، استدعاء الأدوات، البث المباشر (streaming)، وسير عمل يعتمد على Apidog يحافظ على وضوح التكلفة أثناء التكرار.

للحصول على نظرة عامة على مستوى المنتج، راجع ما هو DeepSeek V4. للمسار بدون تكلفة، راجع كيفية استخدام DeepSeek V4 مجانًا.

خلاصة القول (TL;DR)

• يتوفر DeepSeek V4 على نقطة النهاية المتوافقة مع OpenAI على https://api.deepseek.com/v1/chat/completions ونقطة النهاية المتوافقة مع Anthropic على https://api.deepseek.com/anthropic.
• معرفات النموذج: deepseek-v4-pro (إجمالي 1.6 تيرابايت، نشط 49 مليار) و deepseek-v4-flash (إجمالي 284 مليار، نشط 13 مليار).
• كلا الإصدارين يدعمان سياق 1 مليون توكن وثلاثة أوضاع للتفكير: non-thinking، thinking، thinking_max.
• استخدم temperature=1.0, top_p=1.0 كما توصي DeepSeek؛ لا تستورد الإعدادات الافتراضية لـ GPT-5.5 أو Claude.
• سيتم إيقاف المعرفات القديمة deepseek-chat و deepseek-reasoner في 24 يوليو 2026؛ قم بالترحيل قبل ذلك.
• قم بتنزيل Apidog لإعادة تشغيل الطلبات، ومقارنة أوضاع التفكير، وإبقاء المفتاح خارج سجل shell الخاص بك.

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

قبل الطلب الأول، جهز أربعة أشياء.

• حساب مطور DeepSeek على platform.deepseek.com مع رصيد لا يقل عن 2 دولار. بدون رصيد، ستُرجع المكالمات 402 Insufficient Balance.
• مفتاح API خاص بالمشروع الذي ستتم الفوترة عليه. مفاتيح النطاق الخاص بالمشروع أكثر أمانًا من مفاتيح الحساب لأي شيء إنتاجي.
• حزمة تطوير برمجيات (SDK) يمكنها الوصول إلى عنوان URL أساسي متوافق مع OpenAI. تعمل كل من Python openai>=1.30.0 و Node openai@4.x دون تعديل.
• عميل API يمكنه إعادة تشغيل الطلبات دون إغراق الطرفية. يعمل curl لمكالمة واحدة؛ بعد ذلك، استخدم Apidog.

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

export DEEPSEEK_API_KEY="sk-..."

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

عنواني URL أساسيين يغطيان شكلين للطلبات.

POST https://api.deepseek.com/v1/chat/completions    # تنسيق OpenAI
POST https://api.deepseek.com/anthropic/v1/messages  # تنسيق Anthropic

اختر المتوافق مع OpenAI ما لم يكن لديك قاعدة كود حالية بتنسيق Anthropic. يستخدم بقية هذا الدليل تنسيق OpenAI.

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

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "اشرح توجيه MoE في جملتين."}
    ]
  }'

تُرجع الاستجابات الناجحة جسم JSON مع مصفوفة choices، وكتلة usage مقسمة إلى توكنات الإدخال والإخراج (و reasoning_tokens إذا كان وضع التفكير قيد التشغيل)، ومعرف id يمكنك استخدامه للتتبع. تُرجع الإخفاقات غلاف OpenAI القياسي مع error.code و error.message.

معلمات الطلب

يرتبط كل حقل بالتكلفة أو السلوك. هذه هي الخريطة لـ deepseek-v4-pro و deepseek-v4-flash.

thinking_mode هو أكبر محرك للتكلفة. يتخطى non-thinking تتبع التفكير بالكامل ويعيد التوكنات بسرعة V3.2 تقريبًا. يُمكّن thinking كتلة تفكير تكلف توكنات إضافية ولكنها تحسن الدقة في الكود والرياضيات. ينتج thinking_max النتائج في جدول DeepSeek الرئيسي؛ كما أنه يستهلك معظم التوكنات وهو الوضع الوحيد الذي يتطلب ميزانية سياق تزيد عن 384 ألف توكن.

عميل بايثون

تعمل حزمة تطوير البرمجيات (SDK) الرسمية لـ openai مع تجاوز عنوان URL الأساسي. كما تعمل كل برامج التغليف الموجودة المتوافقة مع OpenAI، بما في ذلك LangChain و LlamaIndex و DSPy.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("Content:", choice.message.content)
print("Reasoning tokens:", response.usage.reasoning_tokens)
print("Total tokens:", response.usage.total_tokens)

حيلة extra_body هي كيفية تمرير المعلمات الخاصة بـ DeepSeek عبر حزمة تطوير برمجيات OpenAI دون تصحيح المكتبة.

عميل Node

نفس الهيكل في Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Explain the Muon optimizer in plain English." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

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

تقبل حزمة تطوير برمجيات Node الحقول غير المعروفة بصمت، لذلك يتم تمرير thinking_mode على المستوى الأعلى بدون extra_body.

تدفق الاستجابات (Streaming responses)

اضبط stream: true وكرر كتل SSE. يتطابق الشكل مع OpenAI تمامًا.

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Stream a 300-word essay on MoE."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

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

تتدفق آثار التفكير بشكل منفصل عند تشغيل وضع التفكير؛ يحملها حقل delta.reasoning_content ويمكنك عرضها في واجهة المستخدم أو إسقاطها.

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

يدعم V4 مخطط استدعاء الأدوات القياسي لـ OpenAI. تصبح الوظائف المعرفة في مصفوفة 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.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Weather in Lagos in Celsius?"}],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

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

من هناك، استدعِ الدالة، ألحق النتيجة كرسالة role: "tool"، واستدعِ واجهة برمجة التطبيقات مرة أخرى لمواصلة الحلقة. النمط مطابق لحلقات استخدام أدوات OpenAI و Anthropic.

وضع JSON

للحصول على إخراج منظم، اطلب JSON صراحةً واضبط تنسيق الاستجابة.

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Reply with a single JSON object."},
        {"role": "user", "content": "Summarize this release note as {title, date, bullets}: ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

يفرض وضع JSON تنسيق JSON صالحًا ولكنه لا يفرض مخططًا محددًا. للتحقق من المخطط، قم بإقرانه بـ Pydantic أو Zod من جانب العميل.

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

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

1. قم بتنزيل Apidog وأنشئ مشروعًا.
2. أضف بيئة مع {{DEEPSEEK_API_KEY}} مخزنة كمتغير سري.
3. احفظ طلب POST إلى {{BASE_URL}}/chat/completions مع رأس Authorization: Bearer {{DEEPSEEK_API_KEY}}.
4. قم بتعيين معلمات لـ model و thinking_mode بحيث يمكنك إجراء مقارنات A/B بين الإصدارات دون تكرار الطلبات.
5. استخدم عارض الاستجابات لفحص usage.reasoning_tokens في كل تشغيل. هذه هي أوضح إشارة فردية لما إذا كنت تدفع مقابل وضع التفكير الذي لا تحتاجه.

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

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

الغلاف يتبع OpenAI تمامًا. تلك التي ستواجهها أولاً:

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

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

أربعة أنماط تحافظ على الإنفاق متوقعًا.

1. الوضع الافتراضي هو V4-Flash. انتقل إلى V4-Pro فقط للمطالبات التي قمت فيها بقياس ارتفاع في الجودة.
2. اجعل thinking_max خلف علامة (flag). إنه الوضع الأكثر تكلفة بفارق كبير؛ وجه إليه فقط عندما تكون الدقة أهم من زمن الاستجابة.
3. حدد max_tokens. معظم الإجابات تتناسب مع 2,000 توكن إخراج. السياق البالغ 1 مليون توكن هو للإدخال، وليس للإخراج.
4. سجل usage في كل مكالمة. أرسل عدد توكنات الإدخال والإخراج والتفكير إلى مكدس المراقبة الخاص بك؛ سينبهك تنبيه عند ارتفاع مفاجئ في توكنات التفكير إلى المطالبات التي انحرفت.

الترحيل من نماذج DeepSeek الأقدم

سيتم إيقاف معرفات deepseek-chat و deepseek-reasoner الأقدم في 24 يوليو 2026. يستغرق الترحيل سطرًا واحدًا من التغيير لكل موقع استدعاء؛ تظل أشكال الطلب والاستجابة دون تغيير.

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

قبل قلب الإنتاج، قم بإجراء مقارنات A/B جنبًا إلى جنب في Apidog. عادةً ما يكافئ تحسن جودة الاستجابة هذا التغيير؛ على أي حال، يفرض الموعد النهائي للإيقاف ذلك.

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

هل DeepSeek V4 API جاهز للإنتاج؟ نعم. تم إطلاق واجهة برمجة التطبيقات في 23 أبريل 2026 جنبًا إلى جنب مع الأوزان. عملت DeepSeek V3 و V3.2 على نفس البنية التحتية على نطاق واسع لأكثر من عام، لذا فإن واجهة برمجة التطبيقات ناضجة.

هل يدعم V4 تنسيق رسائل Anthropic؟ نعم. أشر إلى https://api.deepseek.com/anthropic/v1/messages وأرسل حمولة تنسيق Anthropic. كلا التنسيقين يصلان إلى نفس النموذج الأساسي.

ما هو نافذة السياق؟ مليون توكن في كل من V4-Pro و V4-Flash. لاحظ أن وضع Think Max يوصي بحد أدنى لنافذة عمل تبلغ 384 ألف توكن.

كيف أحسب توكنات الإدخال قبل الإرسال؟ استخدم tokenizer OpenAI القياسي للتقديرات؛ تنشر DeepSeek الأعداد الدقيقة في كتلة usage في كل استجابة. لميزانية الإنتاج، ثق بالعدد من جانب الاستجابة.

هل يمكنني ضبط النموذج (fine-tune) عبر API؟ ليس عند الإطلاق. حاليًا، يتم تشغيل الضبط الدقيق من خلال نقاط التحقق (Base checkpoints) المستضافة ذاتيًا على Hugging Face.

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