BroadRouter
ابدأ الآن

الانتقال إلى واجهة API متوافقة مع OpenAI: قائمة تحقق للترحيل

بقلم فريق BroadNet Inference · قراءة في 5 دقائق · تاريخ النشر · آخر تحديث

للانتقال إلى واجهة API متوافقة مع OpenAI، غيّر ثلاثة إعدادات (base_url وapi_key وmodel)، ثم تحقّق مما يختلف: معرّفات النماذج، واحتساب رموز الاستدلال المنطقي ضمن max_tokens، وطريقة إبلاغ البث عن الاستخدام، والأخطاء التي تُعاد محاولتها، وحدود المعدل، وأمان المفاتيح. العنوان الأساسي (base URL) في BroadNet Inference هو https://inference.broadnet.ai/v1.

يتحدث معظم مزودي نماذج اللغة الكبيرة اليوم صيغة OpenAI API. وهذا يجعل الانتقال يبدو تغييرًا في سطر واحد، وهو كذلك فعلًا إن كان كل ما تريده إجابة أولى. أما لتشغيل حركة الإنتاج، فمرّ على هذه القائمة بندًا بندًا. كل بند فيها مأخوذ من طريقة حقيقية تتعطل بها عمليات الترحيل.

0. ما الذي يستخدمه تطبيقك اليوم؟

قبل أن تغيّر أي شيء، دوّن ما يعتمد عليه تطبيقك. ابحث في الكود عن كل استدعاء للـ SDK وأدرجه في قائمة. وإذا كنت تستدعي Whisper API من OpenAI، فلاحظ أن OpenAI تُدرج whisper-1 على أنه سيتوقف في 26 فبراير 2027؛ ويغطي مقال بدائل Whisper API جانب الصوت.

الميزة أين تبحث ما تختبره بعد الانتقال
إكمالات المحادثة (chat completions) كل chat.completions.create الأوامر نفسها، وقارن الإجابات
البث المتدفق stream=True وصول الأجزاء، وانتهاؤها بـ [DONE]، ووجود بيانات الاستخدام
استدعاء الأدوات tools= تحليل استدعاءات الأدوات وتنفيذها
المخرجات المنظَّمة response_format= مطابقة JSON للمخطط (schema) لديك
الصور أجزاء الصور في الرسائل قبول النموذج لها
تحويل الكلام إلى نص audio.transcriptions صحة النص واللغة
التضمينات والملفات والدفعات نقاط نهاية أخرى تحقّق أولًا من أن المزود يقدّمها أصلًا

الصف الأخير مهم. «متوافقة مع OpenAI» تغطي عادةً إكمالات المحادثة قبل أي شيء آخر. يُدرج كتالوج BroadNet Inference نماذج المحادثة على /v1/chat/completions ونماذج تحويل الكلام إلى نص على /v1/audio/transcriptions؛ فإن كنت تستخدم نقاط نهاية أخرى، فأبقِها لدى مزودك الحالي أو ابحث عن بديل.

1. ما الإعدادات الثلاثة التي تتغير؟

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)

يختلف اسم إعداد العنوان الأساسي (base URL) حسب المكتبة: base_url في Python SDK وفي ChatOpenAI من LangChain، وbaseURL في Node.js SDK. وتقرأ Python SDK أيضًا متغير البيئة OPENAI_BASE_URL، بحسب ملف README الخاص بها. تحقّق من عدم وجود قيمة قديمة في بيئتك، وإلا فقد تذهب الطلبات إلى المزود القديم دون أي خطأ.

احفظ مفاتيح API في متغيرات البيئة أو في مدير أسرار، ولا تضعها في الكود أبدًا. الإعداد لكل SDK: Python، Node.js، LangChain. ولبناء طلب أول واختباره يدويًا، استخدم منشئ طلبات API. ولتطبيق تعديلات العنوان الأساسي والمفتاح والنموذج على كود موجود، الصقه في أداة الانتقال من OpenAI إلى BroadNet، التي تسرد أيضًا ما يجب التحقق منه.

2. ما معرّفات النماذج الجديدة؟

لكل مزود طريقته في تسمية النماذج. على BroadNet Inference:

النموذج المعرّف
DeepSeek V4.1 Flash broadnet/deepseek-v4.1-flash
GLM 5.3 broadnet/glm-5.3
Qwen3.8 27B broadnet/qwen3.8-27b
Gemma 4 VL 26B broadnet/gemma-4-26b-a4b

ضع معرّف النموذج في الإعدادات لا في الكود، حتى يصبح التغيير لاحقًا مجرد نشر لا إعادة كتابة. حدود كل نموذج وأسعاره في صفحته: DeepSeek V4.1 Flash، وGLM 5.3، وQwen3.8 27B، وGemma 4 VL 26B.

3. لماذا تعود الإجابات فارغة بعد الانتقال؟

هذه أكثر المفاجآت شيوعًا. تستدل نماذج DeepSeek V4.1 Flash وGLM 5.3 وQwen3.8 27B منطقيًا قبل أن تجيب، وتُحتسب رموز الاستدلال المنطقي ضمن max_tokens. فالحد 256 الذي كان يكفي مع نموذج لا يستدل قد يُستهلك كله في التفكير، فتعود الإجابة فارغة. اترك 1,000 رمز أو أكثر، أو اضبط reasoning_effort على low للمهام البسيطة. الشرح الكامل.

4. هل ما زال البث يُبلغ عن الاستخدام؟

يعتمد البث المتدفق على Server-Sent Events وينتهي بـ data: [DONE]. ولا يصل استخدام الرموز في الجزء الأخير إلا إذا طلبته:

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash", messages=messages,
    stream=True, stream_options={"include_usage": True},
)

من دونه ستقرأ لوحة متابعة التكلفة صفرًا. وإذا انتهى البث قبل [DONE]، فاعتبره غير مكتمل. دليل البث المتدفق.

5. ما الأخطاء التي يجب إعادة محاولتها؟

الحالة المعنى الإجراء
401 مفتاح خاطئ أو ملغى، أو نفاد حصة الدفع حسب الاستخدام أصلح، ولا تُعد المحاولة
402 الرصيد أو الميزانية اشحن الرصيد، ولا تُعد المحاولة
403 رفض بسبب سياسة النموذج أو المسار أو عنوان IP أصلح عدم التطابق
413 الطلب كبير جدًا صغّره، ولا تُعد المحاولة
429 حد المعدل أو التزامن أو الإنفاق انتظر ثم أعد المحاولة
5xx خطأ من جهة الخادم أعد المحاولة مع انتظار متزايد له حد أقصى

تعيد Python SDK الرسمية محاولة بعض الأخطاء تلقائيًا: يقول ملف README إن أخطاء الاتصال واستجابات 408 و409 و429 و5xx تُعاد محاولتها مرتين افتراضيًا مع انتظار أسي متزايد قصير. اضبط max_retries صراحةً حتى يكون السلوك قرارًا منك لا قيمة افتراضية. وسجّل معرّف الطلب من كل استجابة حتى يتمكن الدعم من تتبّع أي مشكلة. كل الرموز.

6. ما حدود المعدل الجديدة؟

اعرف الحدود الجديدة قبل أن تصل الحركة. يسمح مفتاح الدفع حسب الاستخدام في BroadNet بـ 30 طلبًا في الدقيقة و4 طلبات قيد التنفيذ في آن واحد. وتشغّل الخطط غير المحدودة طلبًا واحدًا في كل مرة لكل جلسة. اضبط حجم مجموعة العمّال (workers) بما يتناسب مع ذلك، وإلا رأيت أخطاء 429 من اليوم الأول؛ وتتولى حاسبة حدود المعدل هذا الحساب. تحديد الحجم للوكلاء المتوازين.

7. هل ستظل أوامرك تتسع؟

راجع نوافذ السياق: 1,048,576 رمزًا في DeepSeek V4.1 Flash وGLM 5.3، و262,144 في Qwen3.8 27B، و32,768 في Gemma 4 VL 26B. الأمر الذي كان يتسع في نموذجك القديم قد لا يتسع في نافذة أصغر؛ تحقّق بـ حاسبة نافذة السياق. وضع المحتوى الثابت في أول الأمر لتستفيد من سعر الإدخال المخزّن مؤقتًا.

8. وماذا عن المفاتيح والاحتفاظ بالبيانات؟

اقصر مفاتيح الإنتاج على عناوين IP لخوادمك عبر قائمة عناوين IP المسموحة. واسأل المزود الجديد عمّا يحتفظ به؛ راجع قائمة تحقق عدم الاحتفاظ بالبيانات (ZDR).

9. كيف تنفّذ التحويل بأمان؟

  1. أرسل نسخة من طلبات يوم حقيقي إلى المزودين كليهما.
  2. قارن الإجابات على عيّنة، إضافة إلى زمن الاستجابة والأخطاء والتكلفة لكل طلب.
  3. انقل 10% من الحركة، وراقب يومًا كاملًا، ثم انقل الباقي.
  4. أبقِ المزود القديم مُعدًّا كخيار احتياطي لمدة أسبوع.

إذا كنت تدير خدمات كثيرة، فوكيل (proxy) مثل LiteLLM يتيح لك تبديل المزود في مكان واحد بدلًا من كل تطبيق.

ما الأخطاء الشائعة في الترحيل؟

  • نسيان /v1 في العنوان الأساسي. تُرجع الطلبات 404. استخدم العنوان كاملًا.
  • أسماء نماذج قديمة في الإعدادات. المزود الجديد لا يعرفها.
  • ترك حقول خاصة بالمزود في الطلبات. الحقول التي لم يكن يفهمها إلا المزود القديم قد تُرفض أو تُتجاهل. احذفها من العملاء العامّين.
  • اختبار أمر واحد فقط. نفّذ الجرد من الخطوة 0 ميزةً ميزة.
  • التحويل يوم الجمعة. اترك وقتًا لمراقبة يوم كامل من الحركة الحقيقية.

أين تقع BroadNet Inference؟

BroadNet Inference بديل مباشر للتطبيقات التي تستخدم إكمالات المحادثة وتحويل الكلام إلى نص عبر حزم OpenAI SDK: غيّر ثلاثة إعدادات ومرّ على القائمة أعلاه. لا يُدرج كتالوجها سوى نماذج المحادثة وتحويل الكلام إلى نص، فإن كنت تعتمد على نقاط نهاية أخرى، مثل التضمينات أو تخزين الملفات، فأبقِها لدى مزود آخر. تبدأ الحسابات الجديدة برصيد قدره $5. ومن نماذج المحادثة لا يعمل عليه إلا Gemma 4 VL 26B (ويغطي أيضًا نموذجَي Transcribe)، لذا يحتاج الاختبار الموازي (shadow test) على DeepSeek أو GLM أو Qwen إلى شحن الرصيد.

أسئلة شائعة

هل أحتاج إلى SDK مختلفة؟

لا. تقبل حزم OpenAI SDK الرسمية لـ Python وNode.js عنوانًا أساسيًا (base URL) مخصصًا، وكذلك أطر العمل المبنية عليها مثل ChatOpenAI في LangChain.

كيف أغيّر العنوان الأساسي (base URL) في OpenAI SDK؟

مرّر base_url إلى العميل في Python أو baseURL في Node.js، أو اضبط متغير البيئة OPENAI_BASE_URL. في BroadNet Inference القيمة هي https://inference.broadnet.ai/v1، ويوضع المفتاح في api_key.

لماذا تصلني إجابة فارغة بعد الانتقال؟

نماذج الاستدلال المنطقي مثل DeepSeek V4.1 Flash وGLM 5.3 وQwen3.8 27B تفكّر قبل أن تجيب، ويُحتسب التفكير ضمن max_tokens. ارفع max_tokens إلى 1,000 أو أكثر، أو اضبط reasoning_effort على low.

لماذا يظهر خطأ 404 أو «النموذج غير موجود» بعد الانتقال؟

غالبًا لأن معرّف النموذج ما زال باسم المزود القديم، أو لأن العنوان الأساسي ينقصه المسار /v1. استخدم معرّف النموذج الدقيق لدى المزود الجديد والعنوان الأساسي كاملًا.

ما الأخطاء التي يجب إعادة محاولتها؟

أعد محاولة 429 و5xx مع انتظار أسي متزايد له حد أقصى. أصلح 401 و402 و413 قبل إعادة المحاولة. ويسرد دليل الأخطاء في هذا الموقع كل الرموز.

هل «متوافقة مع OpenAI» تعني «مطابقة لها»؟

لا. شكل الطلب والاستجابة متطابق، لكن معرّفات النماذج والمعاملات المدعومة والحدود وحقول الاستخدام وتفاصيل الأخطاء قد تختلف. اختبر كل ميزة يستخدمها تطبيقك.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity