DEV Community

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

Posted on • Originally published at apidog.com

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

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

جرّب Apidog اليوم

هذا الدليل عملي: يغطي خطوات المصادقة، أهم المعلمات، أمثلة بايثون و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 لإعادة تشغيل الطلبات، مقارنة أوضاع التفكير، وإدارة المفاتيح بشكل آمن.

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

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

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

صدّر المفتاح في بيئتك:

export DEEPSEEK_API_KEY="sk-..."
Enter fullscreen mode Exit fullscreen mode

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

النقاط الأساسية:

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

اختر تنسيق OpenAI إلا إذا كان لديك قاعدة كود مبنية على Anthropic. المصادقة عبر Bearer في رأس 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 في جملتين."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

الرد الناجح يحتوي على مصفوفة choices، وكتلة usage، وid للتتبع. الأخطاء تظهر في غلاف OpenAI القياسي.

معلمات الطلب

كل معلمة تؤثر على التكلفة/السلوك:

المعلمة النوع القيم ملاحظات
model سلسلة نصية (string) deepseek-v4-pro, deepseek-v4-flash مطلوب.
messages مصفوفة (array) أزواج الدور/المحتوى (role/content) مطلوب. نفس مخطط OpenAI.
thinking_mode سلسلة نصية (string) non-thinking, thinking, thinking_max الافتراضي هو non-thinking.
temperature رقم عشري (float) من 0 إلى 2 توصي DeepSeek بـ 1.0.
top_p رقم عشري (float) من 0 إلى 1 توصي DeepSeek بـ 1.0.
max_tokens عدد صحيح (int) من 1 إلى 131,072 يحدد سقف طول الإخراج.
stream قيمة منطقية (bool) صحيح أو خطأ (true or false) يمكّن تدفق SSE.
tools مصفوفة (array) مواصفات أداة OpenAI لاستدعاء الدالة.
tool_choice سلسلة نصية (string) أو كائن (object) auto, required, none, أو أداة محددة يتحكم في استخدام الأداة.
response_format كائن (object) {"type": "json_object"} إخراج وضع JSON.
seed عدد صحيح (int) أي عدد صحيح للتكرارية.
presence_penalty رقم عشري (float) من -2 إلى 2 يعاقب على المواضيع المتكررة.
frequency_penalty رقم عشري (float) من -2 إلى 2 يعاقب على التوكنات المتكررة.
  • thinking_mode هو أهم محرك تكلفة.
    • non-thinking: أسرع وأقل تكلفة.
    • thinking: يحسن الدقة في الكود/الرياضيات مقابل توكنات إضافية.
    • thinking_max: أعلى دقة/تكلفة، يتطلب ميزانية توكن كبيرة.

عميل بايثون

استخدم حزمة openai الرسمية مع تجاوز عنوان URL:

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

مرر معلمات DeepSeek الخاصة عبر extra_body.

عميل 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);
Enter fullscreen mode Exit fullscreen mode

لا حاجة لـ extra_body؛ مرر thinking_mode مباشرة.

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

اضبط stream: true وكرر عبر كتل SSE:

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

عند تفعيل وضع التفكير، يتم بث آثار التفكير عبر delta.reasoning_content.

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

يدعم V4 استدعاء الأدوات على نمط OpenAI:

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

نفّذ الدالة، أضف نتيجتها كرسالة 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"},
)
Enter fullscreen mode Exit fullscreen mode

الوضع يفرض صيغة 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 متغيرة للمقارنات.
  5. استخدم عارض الاستجابات لمراقبة usage.reasoning_tokens وتحديد استهلاك وضع التفكير.

إذا كنت تدير بالفعل مجموعة GPT-5.5 API في Apidog، استنسخ المجموعة وعدّل عنوان URL ومعرف النموذج للمقارنة المباشرة.

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

الأخطاء تتبع نمط OpenAI. الشائعة منها:

الكود المعنى الإصلاح
400 طلب غير صحيح تحقق من مخطط JSON، خاصةً messages و tools.
401 مفتاح غير صالح أعد إنشاء المفتاح على platform.deepseek.com.
402 رصيد غير كافٍ اشحن الحساب.
403 النموذج غير مسموح به تحقق من نطاق المفتاح وتهجئة معرف النموذج.
422 معلمة خارج النطاق max_tokens أو thinking_mode ربما غير متطابقين.
429 تجاوز حد المعدل انتظر ثم أعد المحاولة مع تذبذب أسي.
500 خطأ في الخادم أعد المحاولة مرة واحدة؛ إذا تكرر، تحقق من صفحة الحالة.
503 محمل بشكل زائد ارجع إلى V4-Flash أو أعد المحاولة في 30 ثانية.

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

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

لضبط الإنفاق:

  1. الوضع الافتراضي: V4-Flash. استخدم V4-Pro فقط عند الحاجة لجودة أعلى مثبتة.
  2. اجعل thinking_max خلف علامة. استخدمه فقط عند أولوية الدقة القصوى.
  3. حدد max_tokens. معظم الردود < 2000 توكن. السياق الواسع للإدخال فقط.
  4. سجّل usage. راقب توكنات التفكير لأي تصاعد غير متوقع.

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

معرفات deepseek-chat وdeepseek-reasoner تنتهي في 24 يوليو 2026. استبدل معرف النموذج في كل استدعاء:

-  model="deepseek-chat"
+  model="deepseek-v4-pro"
Enter fullscreen mode Exit fullscreen mode

قم بمقارنات A/B في Apidog قبل الإنتاج.

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

هل DeepSeek V4 API جاهز للإنتاج؟

نعم، تم إطلاقها في 23 أبريل 2026 وتستند إلى بنية مجرّبة من الإصدارات السابقة.

هل يدعم V4 تنسيق رسائل Anthropic؟

نعم، استخدم نقطة النهاية https://api.deepseek.com/anthropic/v1/messages مع حمولة بتنسيق Anthropic.

ما هي نافذة السياق؟

مليون توكن في كل من V4-Pro وV4-Flash. وضع thinking_max يحتاج 384 ألف توكن على الأقل.

كيف أحسب توكنات الإدخال قبل الإرسال؟

استخدم tokenizer OpenAI، أو اعتمد على usage في الاستجابة.

هل يمكنني ضبط النموذج عبر API؟

ليس حاليًا؛ التخصيص متاح فقط عبر نقاط تحقق مستضافة على Hugging Face.

هل هناك طبقة مجانية؟

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

Top comments (0)