چطور OpenAI API را در اپ خود یکپارچه کنیم

برای یکپارچه‌سازی OpenAI API، یک کلید API در یک پروژه OpenAI بسازید، آن را به‌عنوان یک راز سمت سرور با نام OPENAI_API_KEY ذخیره کنید و API را از یک مسیر روی سرور خودتان با SDK رسمی OpenAI صدا بزنید، نه از کد مرورگر. از سپتامبر ۲۰۲۶، راهنمای شروع سریع OpenAI، Responses API را نقطه شروع پروژه‌های جدید معرفی می‌کند. قبل از انتشار، یک سقف هزینه تعیین کنید، طول پاسخ را محدود کنید، تعداد دفعات فراخوانی هر کاربر را محدود کنید و خطاهای محدودیت نرخ را با تلاش مجدد مدیریت کنید.

این راهنما راه‌اندازی، جریان درخواست، پرامپت برای یک ساخت‌دهنده هوش مصنوعی و اشتباه‌هایی که کلید را لو می‌دهند یا هزینه را بالا می‌برند را پوشش می‌دهد. جزئیات OpenAI بر اساس مستندات رسمی آن تا سپتامبر ۲۰۲۶ است. برای مفاهیم کلی (توکن‌ها، پنجره متن، قیمت‌گذاری) ابتدا چطور از API های LLM استفاده کنیم را بخوانید.

با آن چه می‌توانید بسازید

• یک دستیار گفت‌وگو داخل اپتان (چطور یک اپ چت‌بات هوش مصنوعی بسازیم)
• دکمه‌های «خلاصه کن»، «بازنویسی کن» یا «پیش‌نویس پاسخ بنویس»
• استخراج داده ساخت‌یافته از متن آزاد: تبدیل یک ایمیل به سفارش، برچسب‌گذاری تیکت‌های پشتیبانی
• جست‌وجو و پاسخ به سؤال بر اساس محتوای خودتان
• قابلیت‌های رسانه‌ای مثل ساخت تصویر، گفتار و موارد دیگر، بسته به مدل‌های موجود

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

راه‌اندازی حساب OpenAI

1. یک حساب و یک پروژه در پلتفرم OpenAI بسازید. بهترین شیوه‌های تولید OpenAI پروژه‌های جدا برای staging و production را توصیه می‌کنند تا هر کدام کلیدها و محدودیت‌های خودشان را داشته باشند.
2. یک کلید API پروژه بسازید. OpenAI توصیه می‌کند تاریخ انقضا تعیین کنید و کلیدها را به‌طور منظم عوض کنید.
3. هشدار هزینه و سقف سخت هزینه را در صفحه محدودیت‌ها تنظیم کنید. راهنمای OpenAI می‌گوید هشدارها وقتی مصرف از مبلغی بگذرد خبرتان می‌کنند و سقف سخت، یک سقف ماهانه را اعمال می‌کند.
4. صورتحساب اضافه کنید. مستندات محدودیت نرخ OpenAI سطوح مصرف را توضیح می‌دهد: با گذشت زمان و افزایش مصرف، محدودیت‌های شما خودکار بالا می‌روند.

جریان درخواست

مرورگر  ->  مسیر سرور شما  ->  OpenAI API
        <-  پاسخ (استریم‌شده) <-

1. کاربر روی دکمه کلیک می‌کند یا پیام می‌فرستد.
2. مرورگر مسیر خودتان را صدا می‌زند، برای مثال POST /api/summarise.
3. سرور شما بررسی می‌کند کاربر وارد شده و مجاز به استفاده از قابلیت است.
4. سرور درخواست را می‌سازد: دستورها، ورودی کاربر و هر داده‌ای از پایگاه داده که کار لازم دارد.
5. با کلید از متغیر محیطی، OpenAI را صدا می‌زند. SDKهای OpenAI، OPENAI_API_KEY را خودکار می‌خوانند.
6. پاسخ را استریم یا برمی‌گرداند و مصرف توکن را ثبت می‌کند.

SDK رسمی OpenAI با نام openai هم برای JavaScript/TypeScript (از npm) و هم برای Python (از pip) موجود است.

انتخاب مدل

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

گزینه‌ها و مصالحه‌ها

پرامپت‌هایی برای ساخت‌دهنده هوش مصنوعی

اولین قابلیت:

یک دکمه «خلاصه کن» روی صفحه تیکت اضافه کن. این دکمه مسیر سرور POST /api/summarise را صدا می‌زند که بررسی می‌کند کاربر وارد شده، تیکت را بارگذاری می‌کند و OpenAI Responses API را با SDK رسمی openai و راز OPENAI_API_KEY صدا می‌زند. نام مدل را از راز OPENAI_MODEL بخوان. دستورها: «در ۳ بولت خلاصه کن، سپس یک پاسخ کوتاه پیشنهاد بده. شماره سفارش ابداع نکن.» طول خروجی را محدود کن، پاسخ را استریم کن و کلید را هرگز به مرورگر نفرست.

محافظ‌ها:

هر کاربر را به ۳۰ درخواست هوش مصنوعی در ساعت محدود کن که در پایگاه داده ذخیره شود. توکن‌های ورودی و خروجی هر درخواست را همراه با شناسه کاربر و نام قابلیت ثبت کن. اگر OpenAI خطای ۴۲۹ داد، هدر Retry-After را رعایت کن و با تأخیر نمایی و jitter تا ۳ بار دوباره تلاش کن؛ بعد از آن پیام «هوش مصنوعی الان شلوغ است، یک دقیقه دیگر دوباره امتحان کنید» را نشان بده. برای هر خطای دیگر پیام دوستانه نشان بده و بقیه صفحه را کار کنده نگه دار.

مدیریت خطاها و محدودیت‌ها

OpenAI محدودیت نرخ را به چند روش اندازه می‌گیرد، از جمله درخواست در دقیقه و توکن در دقیقه، و هر کدام زودتر تمام شود شما به آن می‌خورید. وقتی از یکی بگذرید، API یک ۴۲۹ با هدر Retry-After برمی‌گرداند. مستندات OpenAI می‌گوید این مقدار را حداقل زمان انتظار بدانید و یک تأخیر تصادفی کوچک اضافه کنید تا همه کلاینت‌ها با هم دوباره تلاش نکنند.

برای این موارد هم برنامه داشته باشید:

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

اشتباه‌های رایج

• کلید در فرانت‌اند یا در مخزن کد. کد مرورگر عمومی است و کلید لو رفته ظرف چند دقیقه می‌تواند سوءاستفاده شود. چطور کلیدهای API را امن نگه داریم را ببینید.
• نبود سقف هزینه. یک حلقه یا کاربر سوءاستفاده‌گر می‌تواند صورتحساب بزرگی بسازد.
• نبود محدودیت برای هر کاربر. محدودیت ارائه‌دهنده از کیف پول شما محافظت می‌کند، نه از سایر کاربرانتان.
• اعتماد به پرامپت برای امنیت. کاربران می‌توانند بنویسند «دستورهای قبلی را نادیده بگیر». دسترسی‌ها باید در کد سرور باشند.
• فرستادن بیشتر از نیاز. کل سندها و تاریخچه‌های طولانی هزینه را ضرب می‌کنند. فقط آنچه کار لازم دارد را بفرستید.
• ثابت کردن نام مدل در کد. مدل‌ها به‌روز و بازنشسته می‌شوند؛ آن را یک تنظیم کنید.
• فرستادن داده شخصی بدون فکر. شرایط استفاده از داده OpenAI را بخوانید و فقط داده‌ای را بفرستید که قابلیت لازم دارد.

چک‌لیست

• پروژه‌های جدا در OpenAI (یا کلیدهای جدا) برای آزمایش و تولید
• کلید به‌عنوان راز سمت سرور ذخیره شده، نه در کد مرورگر یا مخزن
• هشدار هزینه و سقف سخت تنظیم شده
• همه فراخوانی‌ها از سرور شما عبور می‌کنند و دسترسی کاربر را بررسی می‌کنند
• طول خروجی محدود است؛ نام مدل قابل تنظیم است
• محدودیت نرخ برای هر کاربر در اپ
• مدیریت خطای ۴۲۹ با Retry-After، عقب‌نشینی و jitter
• حالت خطای دوستانه؛ صفحه بدون هوش مصنوعی کار می‌کند
• مصرف توکن برای هر قابلیت ثبت می‌شود
• با ورودی‌های طولانی، خالی و خصمانه آزمایش شده

استفاده از OpenAI API در Mythex

قابلیت‌های هوش مصنوعی در اپ‌هایی که با Mythex می‌سازید از کلید OpenAI خودتان استفاده می‌کنند و هزینه‌اش به حساب OpenAI شما می‌رود، نه به اعتبار ساخت Mythex. OPENAI_API_KEY را از طریق /secrets، تنظیمات پروژه یا کارت راز که عامل وقتی به کلید نیاز دارد نشان می‌دهد، به‌عنوان راز پروژه اضافه کنید و سپس قابلیت را با پرامپتی مثل نمونه‌های بالا توضیح دهید. بعد از تغییر راز روی یک اپ منتشرشده، دوباره منتشر کنید تا راز جدید اعمال شود. دستور افزودن قابلیت‌های هوش مصنوعی با کلیدهای API خودتان یک پرامپت شروع دارد و راز در گفت‌وگو کارت راز را توضیح می‌دهد. اگر بین ارائه‌دهنده‌ها مقایسه می‌کنید، چطور Claude API را یکپارچه کنیم را ببینید.

پرسش‌ها