مثال على طلب واجهة برمجة التطبيقات لـ OpenAI

1. الإرساليّة عبر إستخدام CURL

CURL هو أداة سطر الأوامر التي تدعم إرسال واستقبال البيانات باستخدام بروتوكولات متنوعة مثل HTTP و HTTPS. لإرسال طلب إلى واجهة برمجة التطبيقات API التابعة لـ OpenAI باستخدام CURL، تحتاج في البداية إلى الحصول على مفتاح API صالح ثم إضافته إلى رأس الطلب.

إليك مثالاً على أمر CURL يستخدم لإرسال طلب إلى واجهة برمجة التطبيقات API التابعة لـ OpenAI:

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
     "model": "gpt-3.5-turbo",
     "messages": [{"role": "user", "content": "قل هذا اختبار!"}],
     "temperature": 0.7
   }'

عليك استبدال $OPENAI_API_KEY بمفتاحك API. لأسباب أمانية، تجنب عرض مفتاح الـ API الخاص بك في أي بيئة عامة.

1.2 تحليل رؤوس الطلب

في الأمر CURL أعلاه، استخدمنا رأسي طلب حاسمين: Content-Type و Authorization.

• Content-Type: يُعلم الخادم أننا نرسل البيانات في تنسيق JSON. قيمته عادة ما تكون application/json.
• Authorization: هذا هو معرف الاعتماد المستخدم للمصادقة على طلب الـ API، وتكون صيغته دائماً Bearer (مفتاحك API).

ضمان صحة هذين الرأسين هو حاسم لنجاح الطلب.

1.3 بناء جسم الطلب

جسم الطلب هو سلسلة متنسقة بتنسيق JSON تُعلم OpenAI عن نوايانا. في هذا الطلب، نستخدم model لتحديد النموذج الذكاء الاصطناعي الذي نستخدمه، نمرر مصفوفة messages التي تحدد إدخال المستخدم، ونضبط temperature لضبط تباين الاستجابة.

الـ JSON يبدو كما يلي:

{
  "model": "gpt-3.5-turbo",
  "messages": [{"role": "user", "content": "قل هذا اختبار!"}],
  "temperature": 0.7
}

في هذا المثال، نطلب من النموذج توليد استجابة اختبارية بناءً على رسالة الإدخال.

1.4 شرح مفصّل لمعلمات الطلب

ضمن جسم الطلب، هناك عدة معلمات هامة يجب ملاحظتها:

• model: يحدد النموذج الذكاء الاصطناعي الذي ننوي استخدامه. توفر OpenAI عدة نماذج، كل منها له وظائف وتأثيرات مختلفة.
• messages: هذه مصفوفة تحتوي على رسالة واحدة أو أكثر، حيث تتكون كل رسالة من role المحدد لوظيفة الرسالة و content الذي يمثل محتوى الرسالة.
• temperature: يتحكم في اليقين في الاستجابة. قيمة temperature الأقل تولد إجابات أكثر يقيناً، بينما تؤدي القيمة الأعلى إلى المزيد من العشوائية.

2. تحليل الاستجابات من واجهة برمجة التطبيقات API

2.1 فهم الاستجابة

عند إرسال طلب، سيقوم الخادم بإرجاع رمز الحالة HTTP وربما جسم استجابة. عادةً ما سيتلقى الطلب الناجح رمز حالة في السلسلة 200. تحتوي البيانات المُرجعة بتنسيق JSON على نتيجة الطلب، ومثال على الاستجابة يكون كما يلي:

{
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1677858242,
    "model": "gpt-3.5-turbo-1106",
    "usage": {
        "prompt_tokens": 13,
        "completion_tokens": 7,
        "total_tokens": 20
    },
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "\n\nهذا اختبار!"
            },
            "logprobs": null,
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

في هذه الاستجابة، يمكننا رؤية معرف الاكتمال، الطابع الزمني للإنشاء، النموذج المستخدم، استخدام الرموز، والمحتوى الفعلي للرد (في حقل choices).

2.2 الاكتمال ومعالجة الأخطاء

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

2.3 إرسال طلبات API باستخدام Python SDK

فيما يلي مثال على استخدام مكتبة OpenAI Python SDK الرسمية لإجراء مكالمات API.

أولاً، يجب عليك تثبيت مكتبة openai، ويمكن القيام بذلك باستخدام الأمر التالي في سطر الأوامر:

pip install --upgrade openai

بعد ذلك، يمكنك استخدام الكود البرمجي التالي في لغة Python لإجراء طلب API مماثل كما في المثال أعلاه. تذكر أن تستبدل YOUR_OPENAI_API_KEY بمفتاح الخاص بك.

from openai import OpenAI

client = OpenAI(
   api_key="YOUR_OPENAI_API_KEY",
)

completion = client.chat.completions.create(
  model="gpt-3.5-turbo",
  messages=[
    {"role": "system", "content": "أنت مساعد تطوير محترف، ماهر في حل مختلف مشاكل البرمجة."},
    {"role": "user", "content": "اكتب دالة لفرز سريع في Go."}
  ]
)

print(completion.choices[0].message)