شناسه فنی و FQN مدل
در پایان این راهنما، میدانید چه زمانی باید از شناسه فنی مدل مجازی استفاده کنید، FQN مدل چه ساختاری دارد، و مقدار درست فیلد model را هنگام فراخوانی API از کجا بردارید.
اگر فقط میخواهید یک درخواست نمونه بفرستید، اولین درخواست به درگاه مسیر کوتاهتری است. اگر میخواهید شناسه پایدار برای محصول بسازید، مدل مجازی را هم بخوانید.
سه نوع شناسهای که شبیه هماند
در گدارAI چند شناسه نزدیک به هم میبینید. این شناسهها جای هم استفاده نمیشوند:
| نوع شناسه | نمونه | کاربرد اصلی |
|---|---|---|
| شناسه فنی مدل مجازی | support-chat | مقدار پایدار و کوتاه برای مصرف مدل مجازی در فیلد model |
| FQN مدل | openai:openai-daring-lotus:gpt-4o-mini | اشاره دقیق به یک مدل فعال در یک حساب ارائهدهنده مشخص |
| شناسه کامل مدل در کاتالوگ | openai/gpt-4o | جستوجو، مقایسه و پیوند عمیق در کاتالوگ مدلها |
شناسه کامل کاتالوگ برای انتخاب و بررسی مدل مفید است، اما همیشه همان مقداری نیست که باید در درخواست درگاه بفرستید. برای درخواستهای واقعی، مقدار model را از مدلهای مجاز فضای کاری، صفحه حساب ارائهدهنده، مدل مجازی، یا میز تست آمادهشده در پنل بردارید.
شناسه فنی چیست؟
شناسه فنی نامی است که برای ارجاع پایدار به یک موجودیت استفاده میشود. در مدل مجازی، شناسه فنی همان مقداری است که اپلیکیشن شما میتواند در فیلد model بفرستد.
برای نمونه، اگر مدل مجازی با شناسه فنی support-chat ساخته باشید، درخواست شما میتواند این شکل را داشته باشد:
{
"model": "support-chat",
"messages": [
{ "role": "user", "content": "وضعیت سفارش من را بررسی کن." }
]
}
در این حالت، اپلیکیشن فقط support-chat را میشناسد. گدارAI پشت این شناسه، مقصد واقعی، حساب ارائهدهنده، تلاش دوباره، مسیر جایگزین و دسترسیها را مدیریت میکند.
فرمت شناسه فنی
برای شناسه فنی مدل مجازی از حروف انگلیسی، عدد، خط تیره و آندرلاین استفاده کنید:
support-chat
invoice_assistant
content-review-v2
از فاصله، نویسه فارسی، دونقطه، اسلش و نشانههای تزئینی استفاده نکنید:
پشتیبانی
support chat
openai:gpt-4o
support/chat
شناسه فنی را بر اساس کاربرد محصول انتخاب کنید، نه نام مدل پشت آن. اگر امروز support-chat به gpt-4o-mini وصل است و بعداً مقصد را تغییر میدهید، بهتر است کد محصول همچنان support-chat را بفرستد.
کاربردهای شناسه فنی
شناسه فنی زمانی مفید است که میخواهید قرارداد مصرف مدل در کد محصول پایدار بماند:
- اپلیکیشن بهجای نام مدل واقعی، یک نام محصولی و قابل فهم میفرستد.
- تیم زیرساخت میتواند مقصد مدل را بدون تغییر کد محصول عوض کند.
- دسترسی، محدودیت نرخ درخواست، بودجه و گاردریلها را میتوان روی همان شناسه پایدار مدیریت کرد.
- گزارش رخداد و رد درخواستها با نامی خوانا و قابل پیگیری ثبت میشوند.
- برای حذف یا تغییرهای حساس، کاربر میتواند همان شناسه فنی را برای تأیید تایپ کند.
FQN مدل چه ساختاری دارد؟
FQN مدل شناسه کامل یک مدل فعال در حساب ارائهدهنده است. این شناسه از سه بخش ساخته میشود:
provider:account_name:model_id
| بخش | معنی | نمونه |
|---|---|---|
provider | شناسه فنی ارائهدهنده | openai |
account_name | نام حساب ارائهدهنده در فضای کاری | openai-daring-lotus |
model_id | شناسه مدل در همان ارائهدهنده | gpt-4o-mini |
نمونه کامل:
openai:openai-daring-lotus:gpt-4o-mini
اگر شناسه مدل در داده کاتالوگ با پیشوند همان ارائهدهنده آمده باشد، گدارAI آن را هنگام ساخت FQN نرمال میکند. برای نمونه، openai/gpt-4o-mini در حساب OpenAI به این مقدار تبدیل میشود:
openai:openai-daring-lotus:gpt-4o-mini
نه به این مقدار:
openai:openai-daring-lotus:openai/gpt-4o-mini
FQN مدل در فراخوانی API
وقتی میخواهید یک مدل مشخص از یک حساب ارائهدهنده مشخص را مستقیم صدا بزنید، FQN مدل را در فیلد model بفرستید:
{
"model": "openai:openai-daring-lotus:gpt-4o-mini",
"messages": [
{ "role": "user", "content": "سلام، یک پاسخ کوتاه بده." }
]
}
در فراخوانیهای سازگار با OpenAI، محل استفاده از FQN همان محل استفاده از شناسه مدل است. فقط مقدار model عوض میشود؛ نشانی پایه و توکن همچنان متعلق به گدارAI هستند:
POST /v1/chat/completions
Authorization: Bearer YOUR_GODARAI_TOKEN
برای جداسازی دقیق حسابها، FQN مدل باید دقیقاً با یک مدل فعال و مجاز در همان فضای کاری تطبیق داشته باشد. اگر حساب یا مدل پیدا نشود، درخواست نباید به یک مقصد عمومی یا حساب دیگر منحرف شود.
شناسه فنی یا FQN؛ کدام را بفرستم؟
| نیاز شما | مقدار پیشنهادی برای model |
|---|---|
| تست مستقیم یک مدل فعال در یک حساب مشخص | FQN مدل مثل openai:openai-daring-lotus:gpt-4o-mini |
| پایدار نگه داشتن کد محصول در برابر تغییر مقصد | شناسه فنی مدل مجازی مثل support-chat |
| مسیریابی، وزندهی، تلاش دوباره یا مسیر جایگزین | شناسه فنی مدل مجازی |
| مقایسه مدلها در کاتالوگ یا لینک دادن به صفحه مدل | شناسه کامل کاتالوگ مثل openai/gpt-4o |
برای محیط عملیاتی، معمولاً مدل مجازی انتخاب قابل نگهداریتری است. FQN برای تست، اتصال مستقیم، عیبیابی و سناریوهایی مناسب است که عمداً میخواهید یک حساب و مدل مشخص را هدف بگیرید.
بررسی مقدار درست
پیش از ارسال درخواست، این موارد را بررسی کنید:
- مقدار
modelرا کپی کردهاید و دستی از روی حدس ننوشتهاید. - توکن شما به همان مدل یا مدل مجازی دسترسی دارد.
- نقطه پایانی با نوع مدل سازگار است؛ برای نمونه، مدل امبدینگ را با
Chat Completionsصدا نمیزنید. - اگر از FQN استفاده میکنید، هر سه بخش
provider،account_nameوmodel_idوجود دارند. - اگر از مدل مجازی استفاده میکنید، شناسه فنی فعال است و مقصدهای آن مجازند.
رفع خطاهای رایج
خطای مربوط به model میگیرم
نشانه: درخواست با خطای مدل نامعتبر، مدل پیدا نشد یا دسترسی رد شد برمیگردد.
راهحل: مقدار model را از صفحه مدلهای مجاز، حساب ارائهدهنده یا مدل مجازی دوباره کپی کنید. سپس بررسی کنید توکن شما به همان مدل دسترسی دارد.
شناسه کاتالوگ را در API فرستادهام
نشانه: مقداری مثل openai/gpt-4o را در model گذاشتهاید، اما درخواست به مدل موردنظر نمیرسد.
راهحل: اگر میخواهید از حساب ارائهدهنده مشخص استفاده کنید، FQN مدل را بفرستید. اگر میخواهید یک شناسه پایدار محصولی داشته باشید، مدل مجازی بسازید و شناسه فنی آن را بفرستید.
بعد از تغییر شناسه فنی، درخواستها خطا میگیرند
شناسه فنی بخشی از قرارداد مصرف محصول شماست. اگر آن را تغییر دهید، همه سرویسهایی که مقدار قبلی را میفرستند باید بهروزرسانی شوند. در محیط عملیاتی، تغییر مقصد پشت مدل مجازی معمولاً از تغییر خود شناسه کمریسکتر است.
گام بعدی
- برای ساخت شناسه پایدار، مدل مجازی را بخوانید.
- برای ارسال درخواست با مقدار
model، اولین درخواست به درگاه را دنبال کنید. - برای تشخیص خطای دسترسی، احراز هویت در گدارAI را ببینید.
پرسشهای پرتکرار
آیا FQN همان شناسه مدل در کاتالوگ است؟
خیر. شناسه کاتالوگ معمولاً با قالب provider/model نمایش داده میشود. FQN مدل برای فراخوانی مستقیم از مسیر یک حساب ارائهدهنده مشخص، قالب provider:account_name:model_id دارد.
آیا میتوانم در کد محصول همیشه FQN بفرستم؟
بله، اگر عمداً میخواهید همان حساب و مدل مشخص هدف قرار بگیرد. اما اگر میخواهید بعداً مدل، حساب، وزندهی یا مسیر جایگزین را بدون تغییر کد عوض کنید، مدل مجازی و شناسه فنی آن انتخاب بهتری است.
آیا شناسه فنی باید نام مدل واقعی را داشته باشد؟
خیر. بهتر است شناسه فنی کاربرد محصول را نشان دهد؛ مثل support-chat یا invoice-assistant. نام مدل واقعی میتواند پشت مدل مجازی تغییر کند.