لا يمثل ربط DeepSeek API بحد ذاته تعقيدًا كبيرًا، لكن ثلاث نقاط هي التي تسبب التعطل عادةً: إلى أي منصة ينتمي المفتاح، وهل كُتب Base URL كاملًا، وهل اسم الطراز هو الإصدار الحالي. كثير من حالات «لا يعمل الاستدعاء» ليست مشكلة في قدرة الطراز، بل في عدم تطابق بيانات الاعتماد والعنوان.
تبدأ المقالة من التسجيل والشحن وإنشاء المفتاح، ثم تنفذ أول استدعاء عبر curl وPython بالترتيب، وتشرح بعد ذلك الإخراج المتدفق ووضع thinking وmax_tokens والأخطاء الشائعة. بتطبيقها مرة واحدة يمكن تشغيل مسار الربط أساسًا.
ملاحظة: DeepSeek علامة تجارية مملوكة لمالكها، ولا توجد بين هذه المقالة وDeepSeek الرسمية أي تبعية. قد تتغير أسماء الطرازات والمعاملات والحدود مع الإصدارات، وتعتمد المقالة على الشكل الشائع في وثائق أكتوبر 2026، ويُعتمد في النهاية على الوثائق الرسمية وأسعار الطرازات داخل الموقع.
أولًا: ميّز أربعة أشياء قبل الربط
غالبية أعطال الربط ليست في قدرة الطراز، بل في عدم تطابق العناصر الأربعة التالية:
| العنصر | الوظيفة | أكثر موضع يخطئ فيه الناس |
|---|---|---|
| الحساب | يحدد الرصيد والفاتورة وانتماء المفتاح | استخدام مفتاح من منصة A مع عنوان منصة B |
| مفتاح API | إثبات الهوية | نسخ المفتاح مع مسافة أو سطر جديد أو علامة اقتباس |
| Base URL | إلى أي مدخل يُرسل الطلب | نسيان /v1، أو خلط العنوان الرسمي وعنوان البوابة |
| اسم الطراز | حقل model في الطلب |
الاعتماد على اسم قديم من مقالة سابقة |
القاعدة بسيطة: المفتاح وBase URL يجب أن يكونا زوجًا متطابقًا. المفتاح الرسمي يُستخدم مع المدخل الرسمي فقط، ومفتاح البوابة مع مدخل البوابة فقط، والخلط يعيد عادةً 401 مباشرة.
ثانيًا: التسجيل والشحن وإنشاء المفتاح
باتخاذ منصة المطورين الرسمية مثالًا، يكون الترتيب كالتالي:
- افتح منصة DeepSeek للمطورين، وسجّل حسابًا ثم ادخل.
- أكمل التحقق المطلوب في الصفحة، ثم انتقل إلى صفحة الشحن.
- اشحن مبلغًا صغيرًا أولًا، وتأكد من وصوله قبل تشغيل المهام الدفعية.
- انتقل إلى صفحة API Keys، وأنشئ مفتاحًا جديدًا باسم يوضح الغرض، مثل
deepseek-testوdeepseek-prod. - انسخ المفتاح واحفظه فورًا في مدير كلمات المرور أو متغير بيئة على الخادم؛ فالصفحة لا تعرض القيمة الكاملة بعد الإغلاق عادةً.
- أنشئ مفتاحًا للاختبار وآخر للإنتاج، واضبط تنبيهات الميزانية أو الاستخدام.
إذا كنت تستخدم بوابة ZSQH AI، فالإجراء مشابه: أنشئ حسابًا في صفحة التسجيل، ثم مفتاحًا في لوحة التحكم، واشحن الرصيد، ثم اتبع أسلوب التوافق مع OpenAI الموضح لاحقًا. لا تشارك المفتاح نفسه بين الجانبين، وإلا صعب تحديد ما إذا كانت المشكلة في الرصيد أم الحد أم الإعداد.
ثالثًا: Base URL واسم الطراز: تأكد قبل كتابة الشيفرة
الوثائق الرسمية الحالية تعطي مدخل التوافق مع OpenAI بالعنوان https://api.deepseek.com، ومسار إكمال المحادثة /chat/completions. بعض الشروحات القديمة تكتب https://api.deepseek.com/v1، ويُعتمد في صلاحيته على تعليمات الوثائق الحالية؛ وعند الشك، شغّل المثال الرسمي أولًا.
| العنصر | الاتصال الرسمي المباشر | بوابة ZSQH AI |
|---|---|---|
| Base URL | https://api.deepseek.com |
https://ai.zhongshangqihang.com/v1 |
| مسار المحادثة | /chat/completions |
/v1/chat/completions |
| مصدر المفتاح | منصة المطورين الرسمية | لوحة تحكم البوابة |
| اسم الطراز | حسب الوثائق الرسمية | حسب أسعار الطرازات |
| مناسب لـ | من يستخدم DeepSeek وحده ووصوله ودفعه سلسان | من يحتاج مدخلًا موحدًا أو عدة طرازات أو فاتورة محلية |
حتى أكتوبر 2026، تذكر الوثائق الرسمية اسمي الطراز deepseek-flash وdeepseek-v4-pro؛ أما deepseek-chat وdeepseek-reasoner في المقالات القديمة فقد لا تكون متاحة. لا تكتب اسم الطراز من الذاكرة، بل راجعه في الوثائق أو صفحة الأسعار قبل الاستدعاء.
رابعًا: أول curl: شغّل أصغر طلب
أوقف thinking أولًا لتقليل المتغيرات. مثال المدخل الرسمي:
export DEEPSEEK_API_KEY="sk-مفتاحك"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"messages": [{"role": "user", "content": "أجب بكلمة OK فقط"}],
"thinking": {"type": "disabled"},
"max_tokens": 32
}'
إذا عاد 200 وكان choices[0].message.content يحتوي نصًا، فالعناصر الثلاثة صحيحة: المفتاح وBase URL واسم الطراز. عند استخدام البوابة، استبدل العنوان بـhttps://ai.zhongshangqihang.com/v1/chat/completions واستخدم مفتاح البوابة.
تنبيه: thinking معامل امتداد خاص بـDeepSeek، وليس كل خدمة متوافقة مع OpenAI تدعمه. إذا لم تدعمه البوابة، فاحذف الحقل أو استخدم المعامل المقابل وفق وثائقها.
خامسًا: أول استدعاء بـPython: استخدم OpenAI SDK
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com", # مع البوابة استخدم https://ai.zhongshangqihang.com/v1
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "أنت مساعد تقني، وأجب بإيجاز."},
{"role": "user", "content": "اشرح ما هي قاعدة بيانات المتجهات في ثلاث جمل."},
],
max_tokens=512,
extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)
print(resp.usage)
لا يعرف OpenAI SDK حقل thinking، لذا يُمرر عبر extra_body. بعد نجاح الاستدعاء، افحص usage: كم رمزًا للإدخال وكم للإخراج، وهل تُعاد إصابة التخزين المؤقت، وهل يُحتسب محتوى الاستدلال منفصلًا. هذه البيانات أدلّ من «الإحساس بالسرعة» في ضبط التكلفة والمهل لاحقًا.
سادسًا: الإخراج المتدفق وreasoning_content
يكون thinking مفعّلًا افتراضيًا بدرجة high. عند تفعيله يظهر reasoning_content في الاستجابة على المستوى نفسه للنص النهائي content؛ وفي الاستجابة المتدفقة يُعاد في delta.reasoning_content كتلًا متتابعة.
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "اكتب مثال Python لقراءة ملف CSV"}],
stream=True,
max_tokens=4096,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
reasoning, answer = [], []
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
reasoning.append(delta.reasoning_content)
if delta.content:
answer.append(delta.content)
print("مسار التفكير:", "".join(reasoning))
print("الإجابة النهائية:", "".join(answer))
في المحادثات متعددة الأدوار، إذا تضمن الطلب tools، فيجب إعادة reasoning_content من الدور السابق كاملًا، وإلا فقد يعود 400؛ وعند عدم استخدام tools يمكن حذفه وسيتجاهله الخادم. أما للمستخدم النهائي فيُستحسن عرض محتوى التفكير مطويًا لا مفتوحًا افتراضيًا.
سابعًا: كيف تضبط max_tokens وtemperature وthinking
| المهمة | thinking | نقطة البداية المقترحة | ملاحظة |
|---|---|---|---|
| اختبار الاتصال | مغلق | max_tokens 32–128 | يكفي رد قصير |
| التصنيف والاستخراج | مغلق | 256–1024 | إخراج منظم وتقليل كلفة التفكير |
| خدمة العملاء والكتابة | مفتوح | 1024–4096 | يمكن ضبط effort حسب النتيجة |
| الشيفرة والاستدلال المعقد | مفتوح | 4096 فأكثر | امنح عملية التفكير ميزانية كافية |
تذكر الوثائق الحالية أن طول السياق مليون رمز، وأن نطاق max_tokens من 1 إلى 384K؛ وعند عدم الضبط يكون الافتراضي 8K في غير thinking و64K في thinking، و128K عندما تكون reasoning_effort بقيمة max. هذه الأرقام قابلة للتعديل، ويُعتمد على الوثائق الرسمية.
في وضع thinking لا يؤثر temperature وpresence_penalty وfrequency_penalty؛ تعديلها لا يسبب خطأ لكنه لا يغير النتيجة. ولا يجوز خفض max_tokens كثيرًا: فمحتوى التفكير يستهلك ميزانية الإخراج، وقد تُقطع الإجابة قبل كتابة النص إذا كانت الميزانية صغيرة.
ثامنًا: كيف تشخّص 401 و402 و429 والمهل
| العرض | السبب الشائع | المعالجة |
|---|---|---|
| 401 | مفتاح خاطئ، غياب Bearer، مفتاح وعنوان من منصتين مختلفتين | أعد نسخ المفتاح، وافحص الترويسة، وتأكد من تطابق المدخل |
| 402 | رصيد الحساب غير كافٍ | اشحن ثم أعد المحاولة، وافحص الرصيد قبل تعديل الشيفرة |
| 429 | طلبات سريعة أو تجاوز التزامن أو QPS | خفّض التزامن، واستخدم تراجعًا أسيًا، وافصل المفاتيح حسب المشروع |
| 400/422 | معامل أو اسم طراز أو سياق غير صالح | اقرأ رسالة الخطأ، وتحقق من اسم الطراز وmax_tokens |
| مهلة | الشبكة أو إخراج طويل أو زمن thinking | اضبط مهلة الاتصال والقراءة منفصلتين، وحدّ الإخراج |
| 500/503 | خطأ أو حمل زائد في المنبع | انتظر قليلًا ثم أعد المحاولة بتراجع |
يُحسب سقف التزامن في 429 على مستوى الحساب لا موزعًا بالتساوي على المفاتيح. المفاتيح المتعددة تحت الحساب نفسه تتشارك الحصة، لذا «إنشاء مفاتيح أكثر» لا يتجاوز حد التزامن. تذكر الوثائق أيضًا أن الاتصال يُقطع إذا لم يبدأ الاستدلال خلال 10 دقائق؛ ويجب أن يتعرف العميل على هذه الحالة ويعيد المحاولة.
تاسعًا: أمان المفتاح: خمسة أمور قبل الإطلاق
- احفظ المفتاح في متغير بيئة على الخادم أو خدمة إدارة أسرار فقط، لا في الواجهة أو المستودع أو السجلات.
- استخدم مفتاحًا لكل من الاختبار والتجهيز والإنتاج، لتسهيل التشخيص والإيقاف السريع.
- اضبط تنبيه الرصيد أو سقف الإنفاق، وأوقف الخسارة عند الاستدعاء غير الطبيعي.
- سجّل بادئة المفتاح أو بصمته فقط، لا القيمة الكاملة.
- دوّر المفتاح فورًا عند تغير الموظفين أو الاشتباه في تسربه، وراجع سجلات الاستخدام الأخيرة.
عاشرًا: الانتقال من الرسمي إلى البوابة: تغييران فقط
عند الترحيل، غيّر base_url وapi_key أولًا، وأعد تأكيد أسماء الطرازات من صفحة أسعار البوابة، واترك جسم الطلب كما هو قدر الإمكان. قارن الإخراج والزمن وusage على مجموعة المطالبات الحقيقية نفسها، وراقب من 3 إلى 7 أيام قبل تحويل الإنتاج. احتفظ بالاتصال الرسمي كقناة بديلة للتراجع السريع.
إذا كنت تحتاج مدخلًا موحدًا أو فاتورة متعددة الطرازات، فأنشئ مفتاح اختبار في بوابة ZSQH AI؛ والأسعار والطرازات المتاحة في أسعار الطرازات.
قراءات ذات صلة:
- أسعار DeepSeek API والفوترة: الإدخال والإخراج والتخزين المؤقت
- DeepSeek API في الصين: خيارات الوصول والشبكة
- دليل ربط Kimi API: Base URL وأسماء الطرازات وأول استدعاء
الأسئلة الشائعة
هل يجب إضافة /v1 إلى Base URL؟
يُعتمد على المثال الحالي في الوثائق الرسمية. المدخل الرسمي المتوافق مع OpenAI مكتوب https://api.deepseek.com، ومسار المحادثة /chat/completions؛ أما البوابة فتستخدم عادةً بادئة /v1. لا تخمّن من شرح قديم، بل جرّب العنوان الكامل بـcurl أولًا.
هل 401 يعني مفتاحًا خاطئًا أم رصيدًا غير كافٍ؟
401 فشل مصادقة؛ افحص صحة المفتاح ووجود Bearer وتطابق المفتاح والعنوان مع المنصة نفسها. نقص الرصيد يعيد عادةً 402، ولا تخلط بينهما.
هل أفعّل thinking عند أول استدعاء؟
يُستحسن إغلاقه أولًا، وتأكيد المسار بأقصر طلب. بعد التأكد من المفتاح والعنوان واسم الطراز، فعّله حسب المهمة وابدأ بدرجة reasoning_effort منخفضة.
ما القيمة المناسبة لـmax_tokens؟
أعطِ قيمة كافية للمهمة أولًا، ثم اضبطها بعد النجاح. ابدأ بمئات للتصنيف والاستخراج، وبآلاف للنصوص الطويلة والشيفرة؛ وفي وضع thinking اترك ميزانية للتفكير، فالقيمة الصغيرة جدًا تقطع النص.
هل يمكن استخدام مفتاح رسمي مع عنوان بوابة؟
لا. المفتاح الرسمي يقابل المدخل الرسمي فقط، ومفتاح البوابة يقابل مدخل البوابة فقط، والخلط يعيد 401 عادةً. عند تغيير المدخل، غيّر المفتاح والعنوان معًا.
