بازشدن وبسایت یک ارائهدهنده سرویس هوش مصنوعی، به معنی قابل استفاده بودن API آن نیست.
ممکن است صفحه اصلی سرویس بدون مشکل باز شود، اما ثبتنام کامل نشود، امکان ساخت API Key وجود نداشته باشد، مدل موردنظر برای حساب فعال نباشد یا درخواستهای API به دلیل محدودیت حساب و موقعیت جغرافیایی رد شوند.
از طرف دیگر، عبارت «رایگان» همیشه یک معنی مشخص ندارد. بعضی سرویسها سهمیه رایگان دورهای ارائه میکنند، بعضی فقط اعتبار آزمایشی دارند و بعضی پس از چند درخواست اولیه نیازمند فعالسازی پرداخت هستند.
بنابراین انتخاب یک API مدل زبانی باید بر اساس آزمایش واقعی انجام شود، نه فقط نام Provider، کیفیت مدل یا بازشدن وبسایت آن.
در این مقاله یک مسیر عملی برای ارزیابی APIهای مدل زبانی، از تعریف نیاز پروژه تا اجرای اولین درخواست واقعی، بررسی میشود.
قبل از مقایسه Providerها، باید بدانیم دقیقاً چه چیزی از مدل میخواهیم.
یک API ممکن است برای تولید متن عمومی مناسب باشد، اما در پاسخگویی فارسی، تولید کد، تحلیل اسناد یا خروجی ساختاریافته عملکرد مناسبی نداشته باشد.
بهتر است پیش از انتخاب سرویس، این موارد را مشخص کنیم:
هدف اصلی پروژه چیست؟
ورودی فقط متن است یا تصویر و صوت هم وجود دارد؟
پاسخها باید به زبان فارسی باشند؟
طول تقریبی ورودی و خروجی چقدر است؟
سرعت پاسخگویی چقدر اهمیت دارد؟
آیا Streaming لازم است؟
آیا Tool Calling یا Function Calling نیاز داریم؟
آیا خروجی باید JSON معتبر باشد؟
تعداد کاربران یا درخواستهای روزانه چقدر است؟
پروژه آزمایشی است یا قرار است در محیط واقعی استفاده شود؟
برای مثال، نیازهای یک ربات پرسشوپاسخ ساده با سامانهای که اسناد طولانی را تحلیل میکند متفاوت است.
در پروژه اول ممکن است یک مدل سبک با Context محدود کافی باشد، اما پروژه دوم به Context Window بزرگتر، پایداری بیشتر و محدودیت توکن مناسب نیاز دارد.
بنابراین سؤال اصلی این نیست که «بهترین مدل چیست؟» بلکه باید پرسید:
کدام مدل و کدام API با نیازهای مشخص این پروژه سازگارتر است؟
در بیشتر راهنماهای عمومی فرض میشود کاربر میتواند بدون مانع حساب بسازد، شماره تلفن خود را تأیید کند، کارت بانکی وارد کند و API Key دریافت کند.
اما در عمل ممکن است کاربران ایرانی در یکی از مراحل زیر با محدودیت روبهرو شوند:
بازنشدن صفحه ثبتنام؛
پذیرفتهنشدن شماره تلفن؛
نبودن ایران در فهرست کشورها؛
نیاز به کارت بانکی بینالمللی؛
غیرفعالبودن پنل API؛
امکاننداشتن ساخت API Key؛
فعالنبودن بعضی مدلها برای حساب؛
دریافت خطای منطقهای هنگام اجرای API؛
مسدودشدن درخواست بر اساس IP؛
محدودیت استفاده تجاری یا سازمانی.
به همین دلیل، بازشدن دامنه اصلی یک سرویس فقط نشان میدهد وبسایت آن در دسترس است. این موضوع ثابت نمیکند که ثبتنام، ساخت کلید و اجرای درخواست نیز امکانپذیر است.
گاهی سه بخش زیر رفتار متفاوتی دارند:
وبسایت اصلی Provider پنل مدیریت و ساخت API Key دامنه API
ممکن است سایت اصلی باز شود، اما پنل توسعهدهندگان یا Endpoint اصلی API در دسترس نباشد.
یکی از خطاهای رایج در انتخاب API، یکسان در نظر گرفتن انواع دسترسی رایگان است.
هر سرویسی که چند درخواست رایگان ارائه میکند، لزوماً دارای پلن رایگان دائمی نیست.
Free Tier معمولاً یک سهمیه رایگان تکرارشونده است. این سهمیه ممکن است روزانه یا ماهانه تمدید شود.
برای مثال:
۲۰ درخواست در دقیقه ۱۰۰۰ درخواست در روز ۲۰۰ هزار توکن در ماه
در این حالت، پس از آغاز دوره جدید، سهمیه دوباره در اختیار حساب قرار میگیرد.
بااینحال، باید بررسی شود که Free Tier:
دائمی است یا ممکن است متوقف شود؛
برای استفاده تجاری مجاز است یا خیر؛
به کارت بانکی نیاز دارد یا خیر؛
برای همه مدلها فعال است یا فقط چند مدل محدود؛
در محیط واقعی قابل استفاده است یا فقط برای آزمایش.
Trial یک دوره آزمایشی محدود است.
محدودیت آن ممکن است بر اساس زمان یا مصرف باشد:
۱۴ روز استفاده رایگان ۱۰۰ درخواست آزمایشی یک میلیون توکن اولیه
پس از پایان Trial، سهمیه معمولاً تمدید نمیشود و برای ادامه استفاده باید پلن پولی فعال شود.
Trial برای بررسی کیفیت و سازگاری مدل مناسب است، اما بهتر است یک پروژه بلندمدت به آن وابسته نشود.
Credit اعتبار اولیهای است که Provider به حساب اختصاص میدهد.
برای مثال:
۵ دلار اعتبار اولیه اعتبار مصرف یک میلیون توکن اعتبار با تاریخ انقضای ۳۰ روزه
پس از پایان این اعتبار، درخواستها ممکن است متوقف شوند یا نیاز به روش پرداخت داشته باشند.
بهجای اینکه فقط بپرسیم «آیا این API رایگان است؟»، بهتر است موارد زیر را بررسی کنیم:
دسترسی رایگان دائمی است یا موقت؟
سهمیه چه زمانی تمدید میشود؟
آیا اعتبار تاریخ انقضا دارد؟
آیا ثبت کارت بانکی لازم است؟
سقف درخواست در دقیقه چقدر است؟
سقف درخواست روزانه چقدر است؟
محدودیت توکن ورودی و خروجی چقدر است؟
استفاده تجاری مجاز است؟
پس از پایان سهمیه چه اتفاقی میافتد؟
آیا هزینه بهصورت خودکار ایجاد میشود؟
سهمیه برای هر حساب محاسبه میشود یا هر مدل؟
ارزیابی واقعی یک API باید در چند مرحله انجام شود.
ابتدا بررسی کنید که بخشهای زیر در دسترس هستند:
صفحه ثبتنام؛
مستندات API؛
پنل توسعهدهندگان؛
صفحه ساخت API Key؛
صفحه مدلها؛
صفحه قیمتگذاری؛
توضیحات Rate Limit؛
قوانین استفاده؛
سیاست حفظ حریم خصوصی.
اگر اطلاعات مربوط به محدودیت درخواست، دادههای کاربران یا شرایط استفاده مشخص نیست، بهتر است پیش از استفاده در پروژه واقعی احتیاط کنیم.
ثبتنام زمانی کامل است که بتوانیم وارد Dashboard شویم و به بخش توسعهدهندگان دسترسی داشته باشیم.
در این مرحله باید مشخص شود:
ثبتنام با ایمیل انجام میشود یا شماره تلفن؟
آیا ایمیل تأیید دریافت میشود؟
آیا احراز هویت لازم است؟
آیا انتخاب کشور اجباری است؟
آیا کارت بانکی درخواست میشود؟
آیا ورود با حساب Google یا GitHub امکانپذیر است؟
تا زمانی که یک API Key واقعی ساخته نشده است، نمیتوان نتیجه گرفت که سرویس قابل استفاده است.
پس از ساخت کلید این موارد را بررسی کنید:
کلید بلافاصله فعال است؟
تاریخ انقضا دارد؟
امکان حذف یا غیرفعالکردن آن وجود دارد؟
امکان ساخت چند کلید وجود دارد؟
Scope یا سطح دسترسی کلید قابل تنظیم است؟
آیا کلید فقط یکبار نمایش داده میشود؟
آیا میتوان محدودیت مصرف تعریف کرد؟
مدلهایی که در وبسایت معرفی میشوند ممکن است همگی برای حساب رایگان فعال نباشند.
نام دقیق مدل را از Dashboard یا مستندات رسمی بردارید. تغییر کوچک در شناسه مدل میتواند باعث خطا شود.
برای مثال:
provider/model-name provider/model-name:free provider/model-name-v2
این سه شناسه ممکن است به مدلها یا پلنهای متفاوتی اشاره کنند.
استفاده از Playground بهتنهایی کافی نیست.
بهتر است یک درخواست واقعی از محیط پروژه، ترمینال یا یک اسکریپت ساده ارسال شود.
در این تست باید مشخص شود:
API Key معتبر است؟
مدل فعال است؟
دامنه API در دسترس است؟
پاسخ واقعی دریافت میشود؟
زبان فارسی درست پردازش میشود؟
محدودیت منطقهای وجود دارد؟
زمان پاسخگویی قابل قبول است؟
موفقیت یک درخواست، پایداری سرویس را ثابت نمیکند.
چند درخواست را در زمانهای مختلف اجرا و این موارد را ثبت کنید:
متوسط زمان پاسخ؛
درصد درخواستهای ناموفق؛
خطاهای 429؛
خطاهای 500 و 503؛
محدودیت درخواست همزمان؛
رفتار Streaming؛
ثبات کیفیت پاسخ فارسی؛
تغییر احتمالی نام مدل.
بسیاری از Providerها اعلام میکنند که API آنها با ساختار OpenAI سازگار است.
در حالت معمول، این یعنی میتوان از یک SDK مشابه استفاده کرد و فقط سه مقدار را تغییر داد:
API Key Base URL Model Name
نمونه کلی:
from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.provider.example/v1", ) response = client.chat.completions.create( model="provider-model-name", messages=[ { "role": "user", "content": "سلام، یک توضیح کوتاه درباره API بده." } ], ) print(response.choices[0].message.content)
اما عبارت OpenAI-compatible لزوماً به معنی سازگاری کامل نیست.
ممکن است یک Provider فقط درخواست متنی ساده را پشتیبانی کند، اما بعضی قابلیتهای دیگر را نداشته باشد.
Chat Completions؛
Streaming؛
System Prompt؛
Structured Output؛
JSON Mode؛
Tool Calling؛
Function Calling؛
Embedding؛
ورودی تصویر؛
ورودی صوت؛
شمارش توکن؛
دریافت Usage؛
مدیریت Stop Sequence؛
پارامترهای Temperature و Top P.
ممکن است پروژه شما به همه این قابلیتها نیاز نداشته باشد.
بنابراین سازگاری API باید بر اساس نیاز پروژه بررسی شود، نه صرفاً ادعای Provider.
برای ارسال یک درخواست آزمایشی میتوان از Python استفاده کرد.
ابتدا کتابخانههای موردنیاز را نصب کنید:
pip install openai python-dotenv
.envLLM_API_KEY=your-api-key LLM_BASE_URL=https://api.provider.example/v1 LLM_MODEL=provider-model-name
فایل .env را در Git ذخیره نکنید.
در فایل .gitignore این موارد را قرار دهید:
.env *.log __pycache__/
import os import sys from dotenv import load_dotenv from openai import ( APIConnectionError, APIStatusError, AuthenticationError, OpenAI, RateLimitError, ) load_dotenv() api_key = os.getenv("LLM_API_KEY") base_url = os.getenv("LLM_BASE_URL") model = os.getenv("LLM_MODEL") required_variables = { "LLM_API_KEY": api_key, "LLM_BASE_URL": base_url, "LLM_MODEL": model, } missing_variables = [ name for name, value in required_variables.items() if not value ] if missing_variables: print( "متغیرهای زیر تنظیم نشدهاند: " + ", ".join(missing_variables), file=sys.stderr, ) sys.exit(1) client = OpenAI( api_key=api_key, base_url=base_url, timeout=30, max_retries=2, ) try: response = client.chat.completions.create( model=model, messages=[ { "role": "system", "content": "پاسخ را کوتاه و به زبان فارسی بنویس.", }, { "role": "user", "content": "مدل زبانی بزرگ چیست؟", }, ], temperature=0.2, max_tokens=200, ) print(response.choices[0].message.content) except AuthenticationError: print( "احراز هویت ناموفق بود. API Key و Base URL را بررسی کنید.", file=sys.stderr, ) except RateLimitError: print( "محدودیت درخواست یا سهمیه حساب فعال شده است.", file=sys.stderr, ) except APIConnectionError: print( "اتصال به API برقرار نشد. شبکه، دامنه API و Timeout را بررسی کنید.", file=sys.stderr, ) except APIStatusError as error: print( f"Provider خطای HTTP {error.status_code} برگرداند.", file=sys.stderr, ) except Exception as error: print( f"خطای پیشبینینشده: {type(error).__name__}", file=sys.stderr, )
این نمونه میتواند مشخص کند:
متغیرهای محیطی تنظیم شدهاند یا خیر؛
API Key معتبر است یا خیر؛
Base URL درست است یا خیر؛
مدل برای حساب فعال است یا خیر؛
درخواست با محدودیت Rate Limit مواجه شده است یا خیر؛
اتصال شبکه برقرار میشود یا خیر؛
Provider چه کد خطایی برمیگرداند.
API Key نباید مستقیماً داخل کد نوشته شود.
نمونه نامناسب:
api_key = "sk-example-secret-key"
قرارگرفتن کلید در کد میتواند باعث افشای آن در Repository، Log، تصویر آموزشی یا فایل اشتراکی شود.
برای پروژههای کوچک میتوان از Environment Variable یا فایل .env استفاده کرد.
برای پروژههای بزرگتر بهتر است کلید در ابزارهای مدیریت Secret نگهداری شود.
ساختار مناسب معمولاً به این شکل است:
مرورگر یا اپلیکیشن کاربر ↓ Backend برنامه ↓ API مدل زبانی
API Key نباید در کد JavaScript مرورگر یا اپلیکیشن قابل استخراج قرار بگیرد.
اگر احتمال میدهید کلید افشا شده است:
کلید را فوراً غیرفعال کنید؛
کلید جدید بسازید؛
میزان مصرف حساب را بررسی کنید؛
درخواستهای مشکوک را بررسی کنید؛
کلید را از کد و فایلهای Log حذف کنید؛
تاریخچه Git را نیز پاکسازی کنید؛
در صورت امکان سقف مصرف تعریف کنید.
حذف کلید از آخرین نسخه فایل کافی نیست، زیرا ممکن است همچنان در Commitهای قدیمی وجود داشته باشد.
Providerها معمولاً محدودیتهای خود را با چند شاخص بیان میکنند.
تعداد درخواست مجاز در هر دقیقه:
Requests Per Minute
تعداد درخواست مجاز در هر روز:
Requests Per Day
تعداد توکن مجاز در هر دقیقه:
Tokens Per Minute
تعداد توکن مجاز در هر روز:
Tokens Per Day
ممکن است یک سرویس RPM بالایی داشته باشد، اما TPM آن پایین باشد. در این حالت میتوان درخواستهای متعدد ارسال کرد، ولی مجموع متن ورودی و خروجی محدود خواهد بود.
همچنین باید بررسی شود که محدودیتها:
برای هر حساب هستند؛
برای هر API Key هستند؛
برای هر مدل جداگانه محاسبه میشوند؛
میان همه مدلها مشترک هستند؛
بر اساس IP اعمال میشوند.
هنگام تست Provider بهتر است کدهای خطا را ثبت کنیم.
درخواست نامعتبر است.
دلایل احتمالی:
نام مدل اشتباه؛
پارامتر پشتیبانینشده؛
ساختار نادرست پیامها؛
طول بیش از حد Context؛
مقدار نامعتبر max_tokens.
احراز هویت ناموفق است.
دلایل احتمالی:
API Key اشتباه؛
کلید غیرفعال؛
Base URL نادرست؛
فرمت اشتباه Header.
حساب یا منطقه اجازه دسترسی ندارد.
دلایل احتمالی:
مدل برای حساب فعال نیست؛
محدودیت جغرافیایی؛
محدودیت سطح دسترسی؛
ممنوعیت استفاده از قابلیت خاص.
Endpoint یا مدل پیدا نشده است.
دلایل احتمالی:
Base URL اشتباه؛
نام مدل تغییر کرده؛
نسخه Endpoint درست نیست؛
قابلیت موردنظر پشتیبانی نمیشود.
محدودیت درخواست یا سهمیه فعال شده است.
در این وضعیت بهتر است:
تعداد درخواستها کاهش یابد؛
Retry با فاصله انجام شود؛
از Exponential Backoff استفاده شود؛
سهمیه حساب بررسی شود.
این خطاها معمولاً به مشکل موقت سمت Provider مربوط هستند.
در این موارد میتوان درخواست را با فاصله محدود تکرار کرد یا از Provider جایگزین استفاده کرد.
حتی اگر یک API امروز بهخوبی کار کند، ممکن است در آینده یکی از این تغییرات رخ دهد:
مدل رایگان حذف شود؛
سهمیه کاهش یابد؛
نام مدل تغییر کند؛
سرویس موقتاً قطع شود؛
محدودیت حساب تغییر کند؛
شرایط استفاده اصلاح شود؛
سرعت پاسخ کاهش یابد.
بهتر است منطق برنامه مستقیماً به یک Provider وابسته نباشد.
برای مثال، یک تابع عمومی در پروژه تعریف کنید:
def generate_text(prompt: str) -> str: ...
سپس درون آن، ارتباط با Provider اصلی مدیریت شود.
ساختار کلی:
Provider اصلی ↓ در صورت خطای موقت Provider جایگزین اول ↓ Provider جایگزین دوم
Fallback بیشتر برای خطاهای موقت مناسب است:
Timeout؛
خطای 429؛
خطای 500؛
خطای 503؛
قطع موقت سرویس.
اما خطاهایی مانند API Key اشتباه یا درخواست نامعتبر، معمولاً با تغییر Provider حل نمیشوند.
[ ] کاربرد پروژه مشخص است [ ] زبان مورد نیاز مشخص است [ ] نوع ورودی مشخص است [ ] Context مورد نیاز مشخص است [ ] حداکثر طول خروجی مشخص است [ ] Streaming در صورت نیاز تست شده است [ ] Tool Calling در صورت نیاز تست شده است [ ] کیفیت پاسخ فارسی بررسی شده است
[ ] صفحه ثبتنام باز میشود [ ] ثبتنام کامل میشود [ ] حساب تأیید میشود [ ] پنل توسعهدهندگان در دسترس است [ ] API Key ساخته میشود [ ] مدل موردنظر فعال است [ ] درخواست واقعی اجرا میشود
[ ] نوع دسترسی رایگان مشخص است [ ] تفاوت Free Tier و Trial بررسی شده است [ ] تاریخ انقضای Credit مشخص است [ ] RPM مشخص است [ ] RPD مشخص است [ ] TPM مشخص است [ ] محدودیت Context بررسی شده است [ ] محدودیت درخواست همزمان مشخص است
[ ] API Key داخل کد قرار نگرفته است [ ] فایل .env وارد Git نمیشود [ ] کلید در Frontend استفاده نشده است [ ] امکان لغو کلید وجود دارد [ ] اطلاعات حساس قبل از ارسال حذف میشوند [ ] سیاست نگهداری داده مطالعه شده است [ ] وضعیت استفاده از دادهها برای آموزش مشخص است
[ ] Timeout تعریف شده است [ ] Retry محدود وجود دارد [ ] خطای 429 مدیریت میشود [ ] خطاهای 500 و 503 مدیریت میشوند [ ] Log امن ثبت میشود [ ] Provider جایگزین در نظر گرفته شده است
شرایط سرویسهای API ممکن است در مدت کوتاهی تغییر کند. به همین دلیل، تجربه کاربران زمانی مفید است که دقیق و تاریخدار باشد.
یک گزارش مناسب بهتر است شامل این اطلاعات باشد:
تاریخ آزمایش: نام Provider: روش ثبتنام: نیاز به شماره تلفن: نیاز به کارت بانکی: امکان ساخت API Key: نام مدل: نوع سهمیه: نتیجه درخواست: کد خطای احتمالی: توضیحات تکمیلی:
عبارتهایی مانند «برای من کار کرد» یا «این سرویس بسته است» بدون تاریخ، مدل و نوع خطا برای تصمیمگیری کافی نیستند.
انتخاب API مدل زبانی برای کاربران ایرانی فقط به کیفیت مدل مربوط نمیشود.
ممکن است یک مدل کیفیت بالایی داشته باشد، اما امکان ثبتنام، ساخت API Key یا اجرای درخواست آن برای کاربر فراهم نباشد. از طرف دیگر، یک سرویس ممکن است رایگان معرفی شود، اما دسترسی آن فقط یک Trial کوتاه یا Credit محدود باشد.
برای انتخاب مطمئنتر باید این مراحل را جداگانه بررسی کنیم:
تعریف نیاز پروژه ↓ بررسی نوع سهمیه رایگان ↓ تکمیل ثبتنام ↓ ساخت API Key ↓ بررسی مدلهای فعال ↓ اجرای درخواست واقعی ↓ بررسی Rate Limit و خطاها ↓ مدیریت امن کلید ↓ درنظرگرفتن Provider جایگزین
هیچ Providerی نباید فقط بر اساس نام، تبلیغات، فهرست مدلها یا تجربه قدیمی دیگران وارد معماری یک پروژه شود.
ملاک نهایی باید نتیجه یک آزمایش واقعی، قابل تکرار و تاریخدار باشد.
نوشته: علیرضا صفایی