واجهة برمجة تطبيقات OpenAI للمطوّرين: استخدم نقطة نهاية متوافقة

النسخة المختصرة

تفترض معظم الأدلة حول واجهة برمجة التطبيقات (API) الخاصة بـ OpenAI للمطورين وجود مورد واحد وفاتورة واحدة. لكن تنسيق السلك هو ببساطة JSON عبر HTTPS، ويمكن للعديد من أكواد العملاء والأطر والأدوات التحدث مع أي خادم يطبقه. يستضيف هذا الموقع أحد هذه الخوادم. تحتفظ بإطار عمل SDK الخاص بك، وتغيّر عنوان URL الأساسي، وتستبدل المفتاح بمفتاح من هذا الموقع، وتضبط النموذج على uncensored.

هذه هي عملية الترحيل الكاملة لتطبيق نموذجي. إليك قائمة التحقق، ويملأ باقي الصفحة كل خطوة.

1. أنشئ حسابًا واحصل على رصيد التجربة من صفحة مفتاح API.
2. عيّن عنوان URL الأساسي إلى https://api.openaigatewayapi.com/v1.
3. أرسل المفتاح بصيغة Authorization: Bearer <key>. تقوم مكتبات SDK بذلك تلقائيًا عند تمرير api_key.
4. استخدم uncensored كمعرّف النموذج في كل الطلبات.
5. عالج أخطاء HTTP 429 بإعادة المحاولة بعد فترة قصيرة، كما هو موضح قرب النهاية.

توجد نقطتا نهاية: POST /v1/chat/completions و GET /v1/models. الخدمة مخصصة للنصوص فقط. لا يوجد توليد صور أو صوت، ولا تضمين (embeddings) ولا ضبط دقيق (fine-tuning)، لذا إذا كانت تطبيقك يستدعي هذه الميزات، فستحتاج إلى مزود خدمة مختلف.

فحص الاتصال باستخدام curl

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

Copyexport API_KEY="paste-your-key-here"

curl https://api.openaigatewayapi.com/v1/models \
  -H "Authorization: Bearer $API_KEY" | grep -o uncensored

يُطبع أمر grep معرّف النموذج uncensored إذا كان موجودًا في القائمة؛ احذف grep لرؤية قائمة JSON الكاملة. إذا حصلت على خطأ 401، فالمفتاح غير صحيح أو يفتقد بادئة Bearer. الآن أرسل طلبًا حقيقيًا:

Copycurl https://api.openaigatewayapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ],
    "temperature": 0.4
  }'

يحتوي الاستجابة على كائنات choices و usage المعتادة. كما يتضمن رؤوسًا تستحق التسجيل: X-Request-Id لأسئلة الدعم، و X-Balance-USD لرصيدك المتبقي، والرأسين X-RateLimit-Limit-* اللذين يعرضان حدود الطلبات والتزامن.

بايثون مع الحزمة الرسمية openai

في بايثون، لا تعدّل سوى مُنشئ العميل. كل ما يليه هو الكود الذي لديك بالفعل.

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short, accurate release notes."},
        {"role": "user", "content": "Summarise: added retry logic, fixed timeout bug."},
    ],
    temperature=0.5,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

اقرأ المفتاح من متغير بيئة في الكود الفعلي. العينة تثبته (hardcodes) فقط لتبسيط المقتطف. max_tokens اختياري هنا؛ إذا تركته، فقد يستخدم التمام أي جزء متبقي من نافذة الـ 100,000 رمز (الموجّه والتمام معًا). تعيينه هو طريقة رخيصة لحدّ التكلفة في حالة التوليد غير المنضبط.

البث المتدفق

يستخدم البث المتدفق أحداث الحافة الخادمية (Server-Sent Events) وعلم stream=True الذي تعرفه. تصل أرقام الاستخدام في نهاية البث، لذا قد تحتوي الشريحة الأخيرة على قائمة choices فارغة.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five edge cases for a date parser."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        print("\ntokens:", chunk.usage.total_tokens)

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

مثال Node.js

تأخذ مكتبة Node الإعدادين نفسهما تحت أسماء مختلفة.

Copyimport OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "user", content: "Write a regex that matches ISO 8601 dates, and explain it." },
  ],
  temperature: 0.3,
});

console.log(completion.choices[0].message.content);

إذا كنت تستخدم إطار عمل يحتوي على تكامل خاص مع OpenAI، ابحث عن حقل بعنوان URL الأساسي، أو API base، أو نقطة النهاية في إعداداته. لصق عنوان URL نفسه هناك هو عادةً كل ما يلزم. واجهات الدردشة الأمامية، وأطر عمل الوكلاء، وإضافات المحررات تتبع هذا النمط بشكل أساسي. تُمرَّر معاملات العينة مثل temperature، و top_p، و stop، و seed، و عقوبات التكرار والوجود إلى النموذج.

استدعاء الدوال ووضع JSON

يحدد ميزتان ما إذا كان النموذج يناسب تطبيقًا حقيقيًا: استدعاء دوالك وإرجاع بيانات يمكنك تحليلها. كلا الميزتين مدعومتان.

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

تعرّف على الأدوات باستخدام tools، وقد تجبر الاختيار باستخدام tool_choice، وترسل النتائج كرسائل باستخدام role: "tool". تقدم الاستجابات المتدفقة tool_calls على أجزاء، كما هو الحال مع التنسيق القياسي.

Copyimport json
from openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up the status of an order by its ID.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = {"order_id": args["order_id"], "status": "shipped"}  # your real lookup here
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

تحقق من صحة الحجج دائمًا قبل اتخاذ إجراء. ينتج النموذج JSON الذي يطابق مخططك في معظم الأوقات، وليس كل الأوقات، لذا تعامل مع call.function.arguments كما تتعامل مع أي إدخال غير موثوق.

وضع JSON

لأعمال الاستخراج والتصنيف، اطلب كائن JSON واذكر ذلك في الموجّه. ذكر JSON في التعليمات يعطي نتائج أفضل من الاعتماد على العلم وحده.

Copyfrom openai import OpenAI
import json

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"sentiment\": string, \"topics\": [string]}."},
        {"role": "user", "content": "The docs are clear but the rate limits caught me off guard."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data)

الحدود والأخطاء وإعادة المحاولة

يسمح المفتاح الكامل بـ 8 طلبات نشطة و300 طلب في الدقيقة. يسمح مفتاح التجربة بـ 2 طلب نشط و60 طلب في الدقيقة. الحد الأقصى لحجم جسم الطلب هو 8 MB. تجاوز حد يؤدي إلى خطأ HTTP 429، ويخبرك رمز الخطأ أي حد تم تجاوزه.

رمز الخطأ	المعنى	الإجراء المطلوب
rate_limited	طلبات كثيرة جداً في الدقيقة	أبطئ المنتج أو وزّع العمل على الدقيقة
concurrency	عدد كبير من الطلبات في آن واحد	خفض عدد عمالك إلى 8 أو أقل، أو 2 في مفتاح التجربة
429 مع Retry-After: 5	حمل زائد مؤقت	انتظر الثواني المحددة وحاول مرة أخرى

تعيد مكتبات SDK محاولة بعض الأخطاء بالفعل. أضف معالجة خاصة بك لخطأ 429 حتى لا يتسبب الانفجار في تعطل مهمة الدفع:

Copyimport time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
    max_retries=0,
)

def ask(prompt, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = float(e.response.headers.get("retry-after", 2 ** i))
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

الطلبات الفاشلة أو المرفوضة لا تُحسب تكلفتها، لذا لا تضاعف فاتورتك عند تكرار المحاولة. استخدام مفتاح مزامنة (semaphore) بحجم مساوٍ لحدّ التوازي هو الطريقة الأنظف للبقاء ضمن الحدّ الأقصى في الكود غير المتزامن.

نقل تطبيق موجود

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

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.openaigatewayapi.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def complete(messages, **kw):
    return client.chat.completions.create(model=MODEL, messages=messages, **kw)

ثم اعمل على روتين الترحيل القصير التالي:

1. شغّل مجموعة الموجّهات الحالية ضد نقطة النهاية الجديدة واقرأ المخرجات بنفسك. تكتشف الفحوصات الآلية أخطاء التنسيق، وليس النبرة.
2. تحقق من أن أي كود يقوم بتحليل JSON لا يزال يعمل مع ضبط response_format، واحتفظ بآلية احتياطية تقوم بإزالة النصوص الزائدة حول الكائن.
3. قيس عدد الرموز الحقيقي من usage، لأن النموذج المختلف يقوم بتجزئة النص بشكل مختلف وقد تكون تقديراتك القديمة غير دقيقة.
4. اضبط مجموعة العاملين على 8 أو أقل حتى لا يكون حدّ التوازي هو أول ما يفشل تحت الحمل.
5. انشر على حصة صغيرة من الحركة، راقب معدل 429 وسجلات الأخطاء، ثم وسّع النطاق.

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

ما يجب معرفته قبل التبديل

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

خطط حول ثلاثة فروق عملية عن منصة متعددة النماذج الكبيرة:

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

الموجّهات لا تُستخدم للتدريب. لمزيد من تفاصيل المعاملات، راجع مستندات API. إذا كنت تقدر الإنفاق، فإن صفحة التسعير تذكر أسعار الرموز: $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، تُحسب من رصيد مسبق الدفع بدون اشتراك. الشحنات تتراوح من $20 إلى $500 ولا ينتهي الرصيد. إذا كنت تزن طبقة وكيل أمام عدة خدمات بدلاً من ذلك، فإن صفحة بوابات LLM تغطي متى يكون هذا الجزء الإضافي مجديًا.

المزيد من الأدلة

• شرح واجهة برمجة تطبيقات بوابة OpenAI بلغة بسيطة
• أسعار واجهة برمجة تطبيقات بوابة OpenAI: أمثلة على التكلفة الحقيقية
• بوابة LLM: تحليل التكلفة مقابل التعقيد