مثال درخواست API OpenAI

1. ساخت درخواست‌های API

1.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": "Say this is a test!"}],
     "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": "Say this is a test!"}],
  "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\nThis is a test!"
            },
            "logprobs": null,
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

در این پاسخ، ما می‌توانیم شناسه تکمیل، زمان‌بندی ایجاد، مدل استفاده شده، استفاده از توکن و محتوای واقعی پاسخ (در فیلد choices) را ببینیم.

2.2 کاملیت و پردازش خطا

فیلد finish_reason نشان می‌دهد که چرا API دیگر محتوای بیشتری را خروجی نداد. دلایل معمول شامل stop، length و idle هستند. اگر خطایی رخ دهد، مانند تجاوز از حدود توکن یا استفاده از کلید API نادرست، شما پیام خطا مربوطه و کد وضعیت دریافت خواهید کرد. مهم است که این خطاها را به درستی پردازش کنید تا پیوستگی تجربه کاربر و پایداری برنامه خود را به معنی کنید. برای پردازش خطا، می‌توانید بر اساس کد وضعیت و پیام خطا برگشتی، بهترین استراتژی پردازش خطا را تعیین کنید، مانند تلاش مجدد برای ارسال درخواست یا ارائه بازخورد به کاربر برای توضیح دلیل خطا.

۲.۳ ارسال درخواست‌های API با استفاده از Python SDK

در زیر مثالی از استفاده از Python SDK رسمی OpenAI برای انجام فراخوانی‌های API آمده است.

اولین قدم، نصب کتابخانه openai است که می‌توان آن را با استفاده از pip نصب کرد:

pip install --upgrade openai

سپس می‌توانید از کد Python زیر برای انجام یک درخواست مشابه به مثال بالا استفاده کنید. حتما به یاد داشته باشید که YOUR_OPENAI_API_KEY را با کلید API خود جایگزین کنید.

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": "یک تابع برای مرتب‌سازی سریع (quicksort) در Go بنویسید."}
  ]
)

print(completion.choices[0].message)