آموزش OpenAI برای استفاده از API معاونان

1. معرفی وظایف رابط برنامه‌نویسی کمکی OpenAI

1.1 تعریف و هدف از رابط برنامه‌نویسی کمکی

رابط برنامه‌نویسی کمکی به توسعه‌دهندگان اجازه می‌دهد تا هوش مصنوعی کمکی را در داخل برنامه‌های خود ایجاد کنند. با تعریف دستورات سفارشی و انتخاب مدل‌ها، کمک‌ها می‌توانند با استفاده از مدل‌ها، ابزارها و دانش به پرسش‌های کاربر پاسخ دهند. در حال حاضر، رابط برنامه‌نویسی کمکی سه نوع ابزار را پشتیبانی می‌کند: تفسیر کد، بازیابی و فراخوانی تابع.

1.2 کاربردهای رابط برنامه‌نویسی کمکی

رابط برنامه‌نویسی کمکی مناسب برای اسناد مختلفی است که نیاز به پشتیبانی هوش مصنوعی تعاملی دارند. به عنوان مثال:

• پشتیبانی مشتری: به طور خودکار به سوالات متداول پاسخ دهید تا بار کاری از خدمات مشتری انسانی کاهش یابد.
• آموزش آنلاین: به سوالات دانش‌آموزان پاسخ دهید و پشتیبانی آموزش سفارشی ارائه دهید.
• تجزیه و تحلیل داده: فایل‌های داده‌ایی که توسط کاربران بارگذاری شده استتحلیل کنید، گزارشات تولید کنید و نمودارها را تجسم کنید.
• پیشنهادات شخصی: پیشنهادات و خدمات شخصی بر اساس تعاملات تاریخی کاربران ارائه دهید.

1.3 مفاهیم اصلی کمک‌ها

اشیاء اصلی رابط برنامه‌نویسی کمک‌ها شامل کمک، موضوع و پیام می‌شوند. اینجا معرفی‌های جزئیاتی از این اشیاء و وظایف آنها وجود دارد:

کمک

اشیاء کمک بر روی مدل‌های OpenAI ساخته شده‌اند و می‌توانند از ابزارهای هوش مصنوعی استفاده کنند. شما می‌توانید دستورالعمل‌های کمک را سفارشی کنید تا شخصیت و عملکرد آنها را تغییر دهید. به عنوان مثال، می‌توانید یک کمک به نام "تحلیل داده" ایجاد کنید که با استفاده از ابزار "تفسیر کد"، داده‌ها را تجزیه و نمودارها تولید می‌کند.

موضوع

اشیاء موضوع نشان‌دهنده نشست گفتگو بین کاربر و کمک هستند. شما می‌توانید برای هر کاربر یک موضوع ایجاد کنید و پیام‌ها را وقتی کاربر با کمک تعامل دارد به آن اضافه کنید. شیء موضوع تاریخچه پیام را به‌طور مؤثر ذخیره می‌کند و پیام‌ها را در صورت نیاز که به حداکثر طول مدل مربوطه برسد کوتاه‌می‌کند.

پیام

اشیاء پیام می‌توانند توسط کاربر یا کمک ایجاد شوند. پیام‌ها می‌توانند متن، تصاویر و سایر فایلها را حاوی باشند. پیام‌ها به عنوان یک لیست در موضوع ذخیره می‌شوند. در استفاده واقعی از رابط برنامه‌نویسی، توسعه‌دهندگان می‌توانند پیام‌های کاربر را به موضوع اضافه کرده و به دلخواه پاسخ کمک را فعال کنند.

اجرا

اشیاء اجرا نمایانگر اجرای درخواست یک کمک است و با توجه به محتوای پیام در موضوع کمک را فراخوانی می‌کند. کمک از پیکربندی خود و پیام‌های موضوع برای اجرای وظایف با فراخوانی مدل‌ها و ابزارها استفاده می‌کند. به عنوان یک بخش از اجرا، کمک پیام‌ها را به موضوع اضافه می‌کند.

۲. فرایند توسعه رابط برنامه‌نویسی کمک‌ها

2.1 ایجاد کمک خود

برای ایجاد یک کمک، شما باید یک درخواست با دستورالعمل‌ها، نام مدل و پیکربندی ابزار به رابط بفرستید. در ادامه یک مثال ساده برای ایجاد یک کمک معلم ریاضی شخصی آورده شده است:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "شما یک معلم ریاضی شخصی هستید. کد نوشته و اجرا کنید تا به سوالات ریاضی پاسخ دهید.",
    "name": "معلم ریاضی",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

پارامترهای رابط:

• instructions - دستورالعمل‌های سیستمی که به کمک می‌گوید چه کاری انجام دهد.
• name - نام کمک.
• tools - تعیین می‌کند که کمک چه ابزارهایی را می‌تواند استفاده کند. هر کمک می‌تواند تا ۱۲۸ ابزار داشته باشد. انواع فعلی ابزارها می‌تواند تفسیر کد، بازیابی یا تابع باشد.
• model - کدام مدل باید کمک استفاده کند؟

بعد از موفقیت‌آمیز ایجاد کمک، شناسه کمک را دریافت خواهید کرد.

2.2 ایجاد موضوع نشست

یک موضوع نشان‌دهنده یک گفتگو است و ما توصیه می‌کنیم که وقتی کاربر یک گفتگو را آغاز می‌کند، یک موضوع نشست ایجاد کنید. شما می‌توانید یک موضوع به صورت زیر ایجاد کنید:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

بعد از ایجاد موضوع، شما یک شناسه موضوع دریافت خواهید کرد.

۲.۳ اضافه کردن پیام‌ها به مبحث

می‌توانید پیام‌ها را به یک مبحث خاص اضافه کنید، که شامل متن و اختیاری فایل‌های قابل آپلود توسط کاربر است. به عنوان مثال:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "من نیاز به حل این معادله `3x + 11 = 14` دارم. می‌توانید به من کمک کنید؟"
    }'

پارامترهای API:

• thread_id - نمایانگر شناسه مبحث گفتگو است، که می‌توانید آن را هنگام ایجاد مبحث دریافت کنید.

بدنه درخواست API یک پیام کاربر است، معمولاً نمایانگر سوال کاربر است، مشابه ساختار پیام مدل گفتگو.

۲.۴ اجرای دستیار برای تولید یک پاسخ

برای دستیار پاسخ به پیام‌های کاربر، باید یک اجرا (Run) ایجاد کنید. این به دستیار اجازه می‌دهد تا مبحث را بخواند و تصمیم بگیرد که آیا از ابزارها استفاده کند (اگر فعال شده است) یا فقط از مدل برای بهترین پاسخ به پرسش استفاده کند.

توجه: تا این نقطه، دستیار به سوال کاربر پاسخ نداده است. فقط زمانی که شما API Run را فراخوانی می‌کنید، دستیار به سوال کاربر پاسخ خواهد داد.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "assistant_id",
    "instructions": "با نام Jane Doe به کاربر پاسخ دهید. کاربر حساب ویژه دارد."
  }'

پارامترهای API:

• thread_id - نمایانگر شناسه مبحث گفتگو است که می‌توانید آن را هنگام ایجاد مبحث دریافت کنید.
• assistant_id - نمایانگر شناسه دستیار است که می‌توانید آن را هنگام ایجاد دستیار دریافت کنید.
• instructions - دستورات دستیار که می‌توانند دستورات تنظیم شده هنگام ایجاد دستیار را نادیده بگیرند.

یک درخواست API موفق، یک شناسه Run را برمی‌گرداند.

۲.۵ بررسی وضعیت اجرای دستیار

پس از شروع یک کار (Run) در دستیار، اجرای وظیفه ناهمگام است. این بدان معنی است که ما باید به طور منظم وضعیت Run را بررسی کنیم تا مشخص شود آیا این اجرا تکمیل شده است یا خیر. برای بررسی وضعیت Run، می‌توانیم از یک درخواست HTTP با استفاده از CURL انجام دهیم. در زیر یک معرفی خاص به این فرآیند آمده است.

مثال درخواست CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

توضیح پارامترهای API:

• https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: این URL درخواست API است، جایی که thread_abc123 شناسه یکتای مبحث (Thread) و run_abc123 شناسه یکتای اجرا است.

مثال بدنه پاسخ API:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

توضیح پارامترهای پاسخ API:

• id: شناسه یکتای اجرا.
• object: نشان دهنده نوع شیء برگشتی است، که در اینجا thread.run است.
• status: وضعیت اجرا، مقادیر ممکن شامل queued، in_progress، completed، requires_action، failed و غیره هستند.
• created_at: زمان‌نشان ایجاد اجرا.

۲.۶ دریافت نتایج پاسخ دستیار

پس از اینکه اجرای دستیار تکمیل شود، می‌توانیم نتایج پاسخ دستیار را با بررسی پیام‌های افزوده شده به مبحث (Thread) بخوانیم. در زیر یک نمایش از چگونگی انجام این درخواست از طریق CURL و یک توضیح دقیق از پارامترهای API آمده است.

نکته: مشابه گفتگویی با یک دستیار، زمانی که دستیار پردازش پرسش کاربر را تمام می‌کند، دستیار یک پیام را به مبحث گفتگو (Thread) اضافه خواهد کرد. بنابراین، فقط کافی است آخرین پیام در مبحث گفتگو (Thread) را جستجو کنیم تا پاسخ دستیار را بدست آوریم.

مثال درخواست CURL:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

توضیح پارامترهای API:

• https://api.openai.com/v1/threads/thread_abc123/messages: آدرس URL درخواست API است که thread_abc123 شناسه منحصر به فرد موضوع (Thread) است.
• همانطور که هدرهای درخواست برای بررسی وضعیت اجرا را استفاده می کنیم، شامل اطلاعات اعتبارسنجی و اطلاعات نسخه API است.

نمونه‌ی پاسخ نماینده:

در این مثال، کاربر سوال ریاضی از نماینده پرسید و نماینده پس از پردازش پاسخی به موضوع اضافه کرد.

کاربر: می‌خواهم معادله `3x + 11 = 14` را حل کنم. می‌توانید کمکم کنید؟
نماینده: البته، جین دو. برای حل معادله `(3x + 11 = 14)`، باید `(x)` را در یک سوی معادله جدا کنید. اجازه بدهید مقدار `(x)` را برای شما محاسبه کنم.
نماینده: راه حل معادله `(3x + 11 = 14)` `(x = 1)` است.

بعد از به دست آوردن نتایج پاسخ از نماینده، می‌توان آن را به کاربر ارائه داد تا به بهتر فهمیدن و استفاده از خدمات ارائه شده توسط نماینده کمک کند.

3. ابزارها: ابزارهای داخلی ارائه شده توسط OpenAI

3.1 ابزار تفسیر کد

ابزار تفسیر کد به نماینده فرصت می‌دهد تا کد پایتون بنویسد و در یک محیط اجرایی محدود اجرا کند. این ابزار می‌تواند با فرمت‌های مختلف داده و فایل کار کرده و فایل‌ها را با داده و تصاویر گرافیکی تولید کند. تفسیر کد، به نماینده امکان می دهد کد را به صورت انعطاف پذیر اجرا کرده و مسائل کدنویسی و ریاضی پیچیده را حل کند. وقتی کد نوشته شده توسط نماینده نتواند اجرا شود، می‌توان این کد را با تلاش در طول زمان انتها دهیم تا کد با موفقیت اجرا شود.

فعال کردن تفسیر کد

برای فعال کردن تفسیر کد، وقتی نماینده اشیا ساخته می کنید، code_interpreter را در پارامتر tools گذاشته:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "شما یک معلم ریاضی شخصی هستید. وقتی یک سوال ریاضی پرسیده شود، کد بنویسید و اجرا کنید تا به آن پاسخ دهید.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

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

استفاده از تفسیر کد برای پردازش فایلها

تفسیر کد می‌تواند داده‌ها را از فایلها بخواند. این وقتی مفید است که می‌خواهید مقدار زیادی داده را به نماینده بدهید یا اجازه دهید کاربران خود فایلهایی را برای تجزیه و تحلیل بارگذاری کنند. توجه کنید که هنگامی که فایلها برای تفسیر کد بار گذاری می‌شود، برای بازیابی این فایلها فهرست نخواهند شد. برای اطلاعات دقیق در مورد این که چگونه فایلها را برای بازیابی فهرست کنیم، به بخش ابزار بازیابی زیر مراجعه کنید.

فایلهای ارسال شده در سطح نماینده توسط تمام اجراهای مرتبط با این نماینده قابل دسترسی هستند:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "شما یک معلم ریاضی شخصی هستید. وقتی یک سوال ریاضی پرسیده شود، کد بنویسید و اجرا کنید تا به آن پاسخ دهید.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

خواندن تصاویر و فایل‌های تولید شده توسط مفسر کد

مفسر کد همچنین می‌تواند فایل‌ها را در API خروجی دهد، مانند تولید نمودارهای تصویری، فایل‌های CSV و PDF. دو نوع فایل تولید شده وجود دارد: تصاویر و فایل‌های داده (مانند یک فایل CSV با داده‌های تولید شده توسط دستیار).

هنگامی که مفسر کد یک تصویر تولید می‌کند، می‌توانید این فایل را در فیلد file_id پاسخ پیام دستیار پیدا کرده و دانلود کنید:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 ابزار بازیابی

ابزار بازیابی قابلیت‌های دستیار را با اضافه کردن دانش از خارج از مدل (مانند اطلاعات محصولات اختصاصی یا اسناد ارائه شده توسط کاربر) افزایش می‌دهد. هنگامی که فایل بارگذاری شده و به دستیار ارسال می‌شود، OpenAI به طور خودکار شرایط مربوط به اسلایس، ایندکس، ذخیره تعبیه‌های سند شما را پیاده‌سازی کرده و جستجوی بردار برای بازیابی محتوای مرتبط برای پاسخ به سوالات کاربر را انجام می‌دهد.

فعال‌سازی بازیابی

برای فعال‌سازی بازیابی در پارامتر tools دستیار، retrieval را منتقل کنید:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "شما یک چت‌بات پشتیبانی مشتری هستید. از پایگاه دانش خود برای پاسخ به پرسش‌های مشتریان به صورت مؤثر استفاده کنید.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

بارگذاری فایل‌ها برای بازیابی

مشابه مفسر کد، فایل‌ها می‌توانند در سطح دستیار یا سطح پیام‌های فردی بارگذاری شوند.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "شما یک چت‌بات پشتیبانی مشتری هستید. از پایگاه دانش خود برای پاسخ به پرسش‌های مشتریان به صورت مؤثر استفاده کنید.",
    "name": "Math Tutor",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 ابزار فراخوانی تابع

مشابه API تکمیل‌های چت، API‌های دستیاران فراخوانی توابع را پشتیبانی می‌کنند. فراخوانی تابع امکان می‌دهد که توابع را به دستیار توصیف کرده و به طور هوشمندانه تابع مورد نیاز را به همراه پارامترهای آن برگرداند. هنگام اجرای یک فراخوانی تابع، API‌های دستیاران اجرا را متوقف می‌کند و شما می‌توانید نتیجه فراخوانی تابع را ارائه دهید تا اجرای ادامه یابد.

تعریف توابع

هنگام ایجاد یک دستیار، می‌توانید یک مجموعه از توابع برای دستیار تعریف کنید تا از آنها استفاده کند. این توابع باید به صورت صریح مشخص شوند هنگام ایجاد شی دستیار. هر تابع باید یک نام منحصر به فرد، توضیح و مشخصات پارامتر داشته باشد.

کد زیر نشان می‌دهد چگونه می‌توان دو تابع با استفاده از دستور curl در هنگام ایجاد یک دستیار تعریف کرد:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "شما یک ربات پیش‌بینی آب و هوا هستید. از توابع ارائه شده برای پاسخ دادن به سوالات استفاده کنید.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "دریافت وضعیت آب و هوا برای یک مکان خاص",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "شهر و استان، مثلا، سان فرانسیسکو، کالیفرنیا"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "دریافت نام مستعار برای یک شهر",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "شهر و استان، مثلا، سان فرانسیسکو، کالیفرنیا"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

خواندن توابع فراخوانی شده توسط دستیار

وقتی کاربر یک پیام را به دستیار ارسال می‌کند و محتوای پیام باعث فراخوانی یک تابع می‌شود، شما نیاز دارید تا اطلاعات این فراخوانی تابع را بخوانید. در این فرآیند، دستیار یک اجرای وضعیت requires_action تولید می‌کند. در این نقطه، می‌توانید شیء Run را به دست آورید تا اطلاعات دقیق در مورد فراخوانی تابع را به دست آورید.

در ادامه یک مثال از به دست آوردن شیء Run و نمایش چگونگی به دست آوردن اطلاعات فراخوانی توابع آمده است:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"سان فرانسیسکو\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"لس‌آنجلس\"}"
          }
        }
      ]
    }
  },
  ...
}

پارامتر tool_calls شامل اطلاعات فراخوانی تابع است و شما فقط نیاز دارید تا تابع مربوطه را در برنامه محلی خود فراخوانی کنید.

ارسال خروجی‌های تابع

پس از اجرای فراخوانی تابع به صورت محلی و به دست آوردن نتایج، نیاز دارید تا این نتایج را به دستیار Assistants ارسال کنید تا دستیار بتواند ادامه پردازش درخواست کاربر را انجام دهد. هنگام ارسال خروجی‌های تابع، باید اطمینان حاصل کنید که خروجی‌ها با فراخوانی‌های تابع اصلی مرتبط شده‌اند.

در زیر، یک کد نمونه از چگونگی ارسال نتایج خروجی تابع آمده است:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"سلسیوس\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"ال ای\"}"
      }
    ]
  }'

توضیحات پارامتر:

• thread_abc123 نشان‌دهنده شناسه موضوع مکالمه است
• run_123 نشان‌دهنده شناسه شیء Run است
• tool_call_id نشان‌دهنده شناسه یک فراخوانی تابع خاص است که از پارامتر قبلی tool_calls به دست می‌آید.

بعد از ارسال موفق همه خروجی‌های تابع، وضعیت شیء Run دوباره به‌روزرسانی می‌شود، و دستیار ادامه پردازش را انجام داده و پاسخ نهایی را به کاربر باز می‌گرداند.