BroadRouter
ابدأ الآن

الانتقال من OpenAI API: شرح عملي للشيفرة بـ Python وNode وcURL

بقلم فريق BroadNet Inference · قراءة في 6 دقائق · تاريخ النشر

غيّر العنوان الأساسي (base URL) للعميل ومفتاح API ومعرّف النموذج، وهذا يكفي لاستدعاءات Chat Completions. أما الشيفرة المبنية على Responses API فيجب إعادة كتابتها إلى Chat Completions: يصبح input هو messages، وoutput_text هو choices[0].message.content، وتفقد الأدوات مستوى من التداخل. أبقِ التضمينات على عميل منفصل إن لم يكن لدى المزوّد الجديد تضمينات، ثم شغّل اختبارًا سريعًا قبل نقل الحركة.

نقل تطبيق من OpenAI إلى مزوّد متوافق مع OpenAI تعديل صغير في الشيفرة إن كنت تستخدم Chat Completions، وإعادة كتابة إن كنت تستخدم Responses API. يعرض هذا المقال التعديلات بدقة في Python وNode وcURL، وما يجب فعله مع Responses والأدوات والمخرجات المنظَّمة والتضمينات، واختبارًا سريعًا تشغّله قبل نقل أي حركة. تستخدم الأمثلة BroadNet Inference على https://inference.broadnet.ai/v1؛ والخطوات نفسها تنطبق على أي مزوّد.

هذا هو الرفيق البرمجي لـ قائمة التحقق للانتقال، التي تغطي حدود المعدل والأخطاء وتخطيط التحويل. ولعناوين المزوّدين الآخرين الأساسية، راجع العناوين الأساسية للواجهات المتوافقة مع OpenAI، بعد التحقق منها.

ما الذي يتغيّر في إعداد العميل؟

ثلاث قيم: العنوان الأساسي، ومفتاح API، ومعرّف النموذج.

Python

import os
from openai import OpenAI

# before: client = OpenAI()  # reads OPENAI_API_KEY, calls api.openai.com
client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
r = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",          # was e.g. "gpt-..."
    messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(r.choices[0].message.content)

Node

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://inference.broadnet.ai/v1",
  apiKey: process.env.BROADNET_API_KEY,
});
const r = await client.chat.completions.create({
  model: "broadnet/gemma-4-26b-a4b",
  messages: [{ role: "user", content: "Reply with one short sentence." }],
});
console.log(r.choices[0].message.content);

cURL

curl https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","messages":[{"role":"user","content":"Reply with one short sentence."}]}'

انتبه إلى المسار: العنوان الأساسي ينتهي أصلًا بـ /v1، وتضيف SDK المسار /chat/completions. وتكرار /v1 هو أشيع خطأ في البداية.

هل أستطيع الانتقال دون لمس الشيفرة؟

نعم، لشيفرة Chat Completions. تقرأ Python SDK المتغير OPENAI_BASE_URL حين لا يُمرَّر base_url، والقيمة الافتراضية لـ baseURL في عميل Node هي process.env['OPENAI_BASE_URL']. وكلاهما يقرأ OPENAI_API_KEY. فضبط متغيري بيئة ينقل كل الاستدعاءات.

وهنا الخطر أيضًا. كل الاستدعاءات تنتقل، بما فيها التضمينات، والإشراف على المحتوى (moderation)، ورفع الملفات، وأي شيء آخر قد لا يتوفر لدى المزوّد الجديد. لا تستخدم التبديل عبر البيئة إلا إذا كان تطبيقك يجري استدعاءات محادثة فقط ولا شيء غيرها.

ماذا لو كانت شيفرتي تستخدم Responses API؟

تصف ملفات README لحزم SDK من OpenAI الآن واجهة Responses API بأنها الواجهة الأساسية؛ ويصف ملف README لـ Python واجهة Chat Completions بأنها “the previous standard (supported indefinitely)” (الترجمة: «المعيار السابق (مدعوم إلى أجل غير مسمى)»). وكثير من المزوّدين المتوافقين لا ينفّذون إلا Chat Completions. توثّق BroadNet POST /v1/chat/completions وPOST /v1/audio/transcriptions، لذا تحتاج استدعاءات Responses إلى إعادة كتابة. وهذه هي المطابقة:

Responses API Chat Completions
client.responses.create(...) client.chat.completions.create(...)
instructions="..." الرسالة الأولى {"role": "system", "content": "..."}
input="..." أو قائمة عناصر messages=[...]
response.output_text response.choices[0].message.content
max_output_tokens max_tokens (في وثائق BroadNet) أو max_completion_tokens
text={"format": {...}} response_format={...}
previous_response_id، والمحادثات أعد إرسال سجل الرسائل كاملًا بنفسك
الأداة {"type": "function", "name": ...} الأداة {"type": "function", "function": {"name": ...}}
عنصر الإخراج function_call، والرد بـ function_call_output وcall_id message.tool_calls، والرد بالدور tool وtool_call_id
الأدوات المدمجة (البحث على الويب، البحث في الملفات) غير متاحة؛ شغّل أداتك الخاصة

قبل التعديل وبعده لاستدعاء بسيط:

# Before: Responses API
r = client.responses.create(model="gpt-...", instructions="Be brief.", input="What is RAG?")
text = r.output_text

# After: Chat Completions
r = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",
    messages=[{"role": "system", "content": "Be brief."},
              {"role": "user", "content": "What is RAG?"}],
)
text = r.choices[0].message.content

أكبر تغيير بنيوي هو الحالة (state). تستطيع Responses الاحتفاظ بحالة المحادثة على جانب OpenAI عبر previous_response_id. أما Chat Completions فلا حالة لها على الخادم، لذا تحفظ شيفرتك قائمة الرسائل وترسلها كاملة في كل دور. احسب حساب ذلك: السجل كله رموز إدخال في كل استدعاء.

كيف تتغيّر استدعاءات الأدوات؟

في Chat Completions، يضع تعريف الأداة الدالة تحت المفتاح function، ويعود الرد في رسالة من نوع tool:

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_order",
        "description": "Look up an order by ID.",
        "parameters": {"type": "object",
                       "properties": {"order_id": {"type": "string"}},
                       "required": ["order_id"]},
    },
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
msg = r.choices[0].message
if msg.tool_calls:
    messages.append(msg)                                   # keep the assistant turn
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)         # a JSON string: parse and validate it
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(lookup_order(args["order_id"]))})
    r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)

النموذج أهم من البنية. تُدرج وثائق BroadNet الأدوات لنموذجي GLM 5.3 وQwen3.8 27B فقط. لا توجّه حلقة أدوات إلى نموذج لا تُدرج وثائقه الأدوات، وتحقّق من الوسائط قبل أن تشغّل أي شيء. ويتضمن مقال استدعاء الأدوات مع النماذج المفتوحة حلقة تحقّق كاملة.

وماذا عن المخرجات المنظَّمة؟

ترسل client.chat.completions.parse(..., response_format=MyPydanticModel) في Python وzodResponseFormat في Node كلتاهما response_format مع مخطط JSON. ولا تعملان إلا إذا قبل المزوّد هذه البنية على ذلك النموذج. تُدرج BroadNet المخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B لكنها لا تسمّي معامل الطلب. نفّذ الاختبار ذا الخطوات الأربع في وضع JSON أم json_schema مرة لكل نموذج، واستمر في التحقق من النتيجة بعد تحليلها مهما وعد المزوّد.

ماذا يحدث للتضمينات؟

إذا غيّرت العنوان الأساسي على عميل مشترك ولم يكن لدى المزوّد نقطة نهاية للتضمينات، فسيفشل كل استدعاء client.embeddings.create. لا تبيع BroadNet التضمينات. احتفظ بعميلين:

chat = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
embed = OpenAI(api_key=os.environ["OPENAI_API_KEY"])   # or any embeddings provider

vec = embed.embeddings.create(model="text-embedding-3-small", input=query).data[0].embedding
answer = chat.chat.completions.create(model="broadnet/glm-5.3", messages=build_prompt(query, search(vec)))

لا تخلط أبدًا متجهات من نموذجَي تضمين مختلفين في فهرس واحد. وإذا غيّرت مزوّد التضمينات أيضًا، فأعد تضمين المجموعة كاملة. وتحسب حاسبة تكلفة التضمينات تكلفة ذلك.

وينطبق الأمر نفسه على كل ما ليس محادثة: توليد الصور، وتحويل النص إلى كلام، والإشراف على المحتوى، وBatch API، وتخزين الملفات. لا تقدّم BroadNet أيًّا منها. أما تحويل الكلام إلى نص فينتقل: يعمل client.audio.transcriptions.create مع /v1/audio/transcriptions بصيغتي WAV أو MP3 وحقل language (دليل تحويل الكلام العربي إلى نص).

كيف تتغيّر شيفرة البث المتدفق؟

تبث Responses API أحداثًا محددة النوع، مثل response.output_text.delta وresponse.completed. أما Chat Completions فتبث أجزاءً (chunks)، والنص في choices[0].delta.content. ولا تُرسَل بيانات الاستخدام ما لم تطلبها، وحينها تصل في جزء أخير قائمة choices فيه فارغة.

// Before (Responses): for await (const e of stream) if (e.type === "response.output_text.delta") out(e.delta);
const stream = await client.chat.completions.create({
  model: "broadnet/gemma-4-26b-a4b",
  messages: [{ role: "user", content: "Count from one to three." }],
  stream: true,
  stream_options: { include_usage: true },
});
for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) console.log("\ntokens:", chunk.usage.total_tokens);   // last chunk
}

عادتان تحفظان شيفرة البث المتدفق بعد الانتقال. احمِ الوصول إلى choices[0]، لأن جزء بيانات الاستخدام لا يحتوي على choices. وتعامل مع البث الذي ينتهي قبل السطر الأخير data: [DONE] على أنه غير مكتمل؛ إذ تقول وثائق BroadNet أن تسجّل X-Request-ID وتقرر هل إرسال طلب جديد آمن. ويتضمن دليل البث المتدفق لإكمال المحادثات النمط الكامل بـ Python.

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

تبقى أصناف الأخطاء في SDK كما هي: AuthenticationError للخطأ 401، وRateLimitError للخطأ 429، وAPIStatusError للبقية. ما يتغيّر هو معنى كل حالة لدى المزوّد الجديد. في BroadNet، قد يعني 401 استنفاد حصة الدفع حسب الاستخدام، لا مجرد مفتاح خاطئ، ويعني 402 عدم كفاية الرصيد لعملية شراء. ولا يزول أيٌّ منهما بإعادة المحاولة. وقد يأتي 429 من حد المعدل، أو التزامن، أو معدل الرموز، أو الإنفاق. أعد محاولة 429 و5xx مع انتظار متزايد، وأصلح كل ما عداهما. ويتضمن دليل الأخطاء وإعادة المحاولة الجدول الكامل.

تعيد SDK محاولة أخطاء الاتصال و408 و409 و429 و5xx مرتين افتراضيًا. وإذا أضفت حلقة إعادة محاولة خاصة بك، فاضبط max_retries=0 على العميل حتى لا تتراكب الاثنتان.

ما المعاملات التي يختلف سلوكها؟

المعامل ما الذي تتحقق منه
max_tokens / max_completion_tokens تصنّف OpenAI max_tokens متقادمًا؛ ووثائق BroadNet تستخدمه. وفي نماذج الاستدلال المنطقي يشمل التفكير، لذا تعيد القيم الصغيرة إجابات فارغة (السبب)
reasoning_effort توثّق BroadNet القيمة low؛ واختبر القيم الأخرى قبل الاعتماد عليها
stream_options: {"include_usage": true} موثّق لدى BroadNet؛ وتصل بيانات الاستخدام في الجزء الأخير
n، logprobs، seed، logit_bias غير موجودة في وثائق BroadNet؛ اختبرها أو احذفها
store، metadata ميزات تخزين خاصة بـ OpenAI؛ احذفها
أجزاء المحتوى image_url فقط في النماذج المدرجة بدعم الصور: DeepSeek V4.1 Flash وQwen3.8 27B وGemma 4 VL 26B

كيف تختبر الانتقال؟

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

import os, openai
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
FAST, REASONING = "broadnet/gemma-4-26b-a4b", "broadnet/qwen3.8-27b"
msg = [{"role": "user", "content": "Reply with the word ok."}]

# 1. Plain chat returns text and usage
r = client.chat.completions.create(model=FAST, messages=msg)
assert r.choices[0].message.content and r.usage.prompt_tokens > 0

# 2. Streaming reports usage in the last chunk
chunks = list(client.chat.completions.create(model=FAST, messages=msg, stream=True,
                                             stream_options={"include_usage": True}))
assert chunks[-1].usage is not None

# 3. A reasoning model needs room: a tiny budget can come back empty
r = client.chat.completions.create(model=REASONING, messages=msg, max_tokens=2000)
assert r.choices[0].finish_reason == "stop" and r.choices[0].message.content

# 4. A bad key raises AuthenticationError (401), which you should not retry
bad = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key="invalid", max_retries=0)
try:
    bad.chat.completions.create(model=FAST, messages=msg)
    raise AssertionError("expected 401")
except openai.AuthenticationError:
    pass
print("smoke test passed")

ثم قارن الجودة، لا البنية فقط. أعد تشغيل عيّنة من الأوامر الحقيقية على المزوّدَين وقيّم الإجابات؛ ويوضح مقال قيّم نموذج LLM قبل الانتقال إليه الطريقة. وتساعدك أداة الانتقال من OpenAI إلى BroadNet على إعادة كتابة مقطع من الشيفرة، وتسرد الميزات التي يستخدمها.

ما الذي يتعطل أكثر من غيره؟

  • عنوان أساسي عام ينقل أيضًا استدعاءات التضمينات والملفات.
  • أدوات مساعدة خاصة بـ Responses مثل output_text تُركت في شيفرة باتت تستدعي Chat Completions.
  • معرّفات النماذج. أسماء gpt-... غير موجودة لدى غير OpenAI. وفي BroadNet تبدو مثل broadnet/glm-5.3.
  • ردود فارغة من نماذج الاستدلال المنطقي مع قيمة صغيرة لـ max_tokens.
  • حدود المعدل. يسمح مفتاح الدفع حسب الاستخدام في BroadNet بـ 30 طلبًا في الدقيقة و4 قيد التنفيذ. والمهام الضخمة تحتاج إلى طابور (معالجة الخطأ 429).

أين تقع BroadNet Inference من هذا؟

تناسب BroadNet Inference التطبيقات التي يقتصر استخدامها لـ OpenAI على المحادثة والتفريغ الصوتي: المساعدات، والاستخراج، والتلخيص، والترجمة، والكلام العربي. وتناسب أيضًا التطبيقات التي تريد خطط DeepSeek V4.1 Flash بسعر ثابت لوكلائها. وهي الوجهة الخاطئة إن كنت تعتمد على حالة Responses API على الخادم، أو الأدوات المدمجة، أو التضمينات، أو توليد الصور، أو تحويل النص إلى كلام، أو الصوت في الوقت الفعلي، أو Batch API. انقل تلك إلى مزوّدين يقدّمونها، أو أبقِها على OpenAI وانقل استدعاءات المحادثة فقط. يعمل Gemma 4 VL 26B ونموذجا التفريغ الصوتي كلاهما على الرصيد المبدئي البالغ $5؛ أما GLM 5.3 وQwen3.8 27B وDeepSeek V4.1 Flash فتتطلب شحن الرصيد أولًا.

أسئلة شائعة

هل أحتاج إلى SDK مختلفة لاستخدام واجهة API متوافقة مع OpenAI؟

لا. احتفظ بحزمة openai الرسمية ومرّر base_url مختلفًا (في Python) أو baseURL (في Node)، مع مفتاح المزوّد الجديد. وتبقى كائنات الطلب والاستجابة كما هي لنقاط النهاية التي يدعمها المزوّد.

هل تدعم الواجهات المتوافقة مع OpenAI واجهة Responses API؟

بعضها يدعمها؛ وكثير منها يدعم Chat Completions فقط. راجع قائمة نقاط النهاية لدى المزوّد. توثّق BroadNet Inference نقطتي /v1/chat/completions و/v1/audio/transcriptions، لذا يجب إعادة كتابة شيفرة Responses إلى Chat Completions.

ماذا يحدث للتضمينات عند الانتقال؟

تتعطل إن لم يكن لدى المزوّد الجديد نقطة نهاية للتضمينات وكنت قد غيّرت العنوان الأساسي على مستوى التطبيق كله. لا تبيع BroadNet التضمينات، لذا أبقِ عميلًا للتضمينات موجّهًا إلى مزوّد التضمينات لديك. ولا تخلط أبدًا متجهات من نموذجَي تضمين مختلفين في فهرس واحد.

هل أرسل max_tokens أم max_completion_tokens؟

تصنّف OpenAI المعامل max_tokens متقادمًا لصالح max_completion_tokens. لكن كثيرًا من المزوّدين المتوافقين يوثّقون max_tokens بدلًا منه، ووثائق BroadNet تستخدم max_tokens. أرسل ما يوثّقه المزوّد، وتأكد في اختبارك السريع أن الحد يُطبَّق فعلًا.

هل تظل أدوات المخرجات المنظَّمة المساعدة في OpenAI تعمل؟

فقط إن كان المزوّد يقبل response_format مع json_schema على النموذج الذي تستخدمه. تُدرج BroadNet المخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B لكنها لا تسمّي معامل الطلب، فاختبره، واستمر في التحقق من النتيجة بعد تحليلها.

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