نکات کلیدی
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- استریم نیازمند مدیریت دقیق رویدادهای SSE است تا از خراب شدن JSON یا از دست رفتن توکنها جلوگیری شود.
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- صورتحساب کریپتو پیشپرداخت به این معنی است که خطاها رایگان هستند، اما شمارش توکنها باید دقیق باشد تا از اتفاقات غیرمنتظره جلوگیری شود.
چرا کلید API شما ممکن است رد شود
کلیدهای API زمانی رد می‌شوند که کلاینت هدرهای نامعتبر ارسال کند یا از محدودیت حجم بدنه درخواست فراتر رود. سرور قبل از پردازش هرگونه منطق، هدر احراز هویت را اعتبارسنجی میکند. اگر هدر موجود نباشد یا حاوی فاصله‌های اضافی باشد، درخواست فوراً شکست می‌خورد.
یکی دیگر از دلایل رایج، ارسال پیکربندی‌ای است که از محدودیت حجم بدنه ۸ مگابایتی تجاوز میکند. پنجره‌های بزرگ زمینه با تعداد زیادی پیام می‌توانند به راحتی از این حد فراتر روند. قبل از ارسال، طول آرایه پیام‌ها و تعداد توکنها را بررسی کنید.
- اطمینان حاصل کنید که هدر Authorization از پیشوند 'Bearer' به درستی استفاده میکند.
- Verify the request body size stays under 8 MB.
- بررسی کنید که کلید API فعال باشد و منقضی نشده باشد.
درک محدودیت‌های پنجره زمینه
پنجره زمینه شامل هم متن ورودی و هم پاسخ تولیدشده می‌شود. API ما از پنجره ۱۰۰,۰۰۰ توکنی پشتیبانی میکند، اما باید هر دو طرف را در نظر بگیرید. اگر ۸۰,۰۰۰ توکن از زمینه ارسال کنید، فقط ۲۰,۰۰۰ توکن برای پاسخ باقی می‌ماند.
اکثر مدل‌ها اگر max_tokens را مشخص نکنید، به طور پیش‌فرض یک محدودیت خروجی کوچک دارند. این می‌تواند باعث بریده شدن ناگهانی پاسخ‌های طولانی شود. max_tokens را فقط در صورتی که می‌خواهید یک سقف تعیین کنید، به طول مورد نظر خود تنظیم کنید. به یاد داشته باشید که این محدودیت به کل درخواست اعمال می‌شود، نه فقط به پرامپت.
مدیریت صحیح وقفه‌های جریان داده
پخش زنده از طریق رویدادهای ارسالی سرور (SSE) به مدیریت خطای مقاوم نیاز دارد. اگر اتصال قطع شود، ممکن است آخرین توکن یا دادههای مصرف را از دست بدهید. همیشه قطعات ورودی را در بافر نگه دارید و پاسخ کامل را در سمت کلاینت بازسازی کنید.
دادههای مصرف توکن معمولاً در آخرین قطعه از جریان ارسال می‌شوند. اگر اتصال را زودتر از موعد قطع کنید، ممکن است تعداد دقیق توکنها را از دست بدهید. این موضوع بر دقت صورت‌حساب‌دهی در سیستم‌های پیشپرداخت تأثیر می‌گذارد. یک مکانیسم تلاش مجدد با بازگشت نمایی را برای مدیریت مشکلات موقت شبکه پیاده‌سازی کنید.
از یک کلاینت استریمینگ اختصاصی استفاده کنید که پردازش SSE را به‌طور خودکار انجام می‌دهد. این کار خطر خطاهای پردازش را کاهش می‌دهد و اطمینان حاصل میکند که تمام داده‌ها دریافت شوند.
خطاهای تجزیه حالت JSON
هنگام استفاده از response_format: {"type": "json_object"}، مدل باید JSON معتبر برگرداند. هرگونه انحراف باعث خطاهای تجزیه در برنامه شما می‌شود. مطمئن شوید که پرامپت شما به صراحت به مدل دستور می‌دهد که فقط JSON خروجی دهد.
گاهی اوقات مدل بلوک‌های کد مارک‌داون را در اطراف JSON قرار می‌دهد که باعث خرابی پارسرهای سخت‌گیر می‌شود. قبل از تجزیه، بسته‌های را حذف کنید. همچنین، ساختار JSON را در سمت کلاینت قبل از استفاده از داده‌ها اعتبارسنجی کنید.
از یک کتابخانه اعتبارسنجی طرحواره برای تشخیص خطاها در مراحل اولیه استفاده کنید. این کار از کرش کردن برنامه زمانی که مدل کلیدها یا انواع دادههای غیرمنتظره‌ای را برمی‌گرداند، جلوگیری میکند.
غافلگیری‌های مربوط به شمارش توکن و صورتحساب
صورتحساب پیشپرداخت فقط برای مصرف واقعی توکنها اعمال می‌شود. خطاها و رد شدنها رایگان هستند که مزیت قابل توجهی نسبت به مدلهای اشتراکی محسوب می‌شود. با این حال، شمارش توکنها می‌تواند پیچیده باشد اگر کل زمینه را در نظر نگیرید.
هر پیام در تاریخچه گفتگو در محدودیت توکن ورودی حساب می‌شود. مکالمات طولانی اعتبار پیشپرداخت شما را سریع‌تر از آنچه تصور میکنید کاهش می‌دهند. برای جلوگیری از تمام شدن اعتبار در میانه جلسه، استفاده خود را به طور منظم پایش کنید.
برای موجودی کم اعتبار، هشدارها را تنظیم کنید. این تضمین میکند که می‌توانید قبل از شکست درخواست‌های خود، اعتبار خود را شارژ کنید. به یاد داشته باشید که اعتبارها هرگز منقضی نمی‌شوند، بنابراین می‌توانید هر زمان که مناسب است، اعتبار خود را شارژ کنید.
پرهیز از ردّهای نرم در پرامپت‌های NSFW
ردّهای نرم زمانی رخ می‌دهند که مدل مکث میکند یا به جای پاسخ مستقیم، پاسخی ناقص ارائه می‌دهد. این موضوع اغلب در موضوعات جنجالی یا بزرگسالانه اتفاق میافتد. حتی در یک مدل بدون سانسور، برخی محرک‌ها می‌توانند باعث تردید شوند.
پارامتر temperature را تنظیم کنید تا تصادفی بودن کاهش یابد. دمای پایین‌تر مدل را قطعی‌تر میکند و احتمال احتیاط در پاسخگویی را کاهش می‌دهد. همچنین، مطمئن شوید که پرامپت شما واضح و مستقیم است. از زبان مبهم که ممکن است مدل را گیج کند، پرهیز کنید.
اگر با ردّهای نرم مکرر مواجه شدید، سعی کنید پرسش را کمی بازنویسی کنید. تغییرات کوچک در بیان اغلب می‌تواند از تردید بگذرد و پاسخ مستقیمی دریافت کند.
نوسانات محدود نرخ و استراتژی‌های بازگشت
API اجازه ۳۰۰ درخواست در دقیقه و ۸ درخواست همزمان به ازای هر کلید را می‌دهد. افزایش ناگهانی ترافیک می‌تواند به سرعت به این محدودیت‌ها برسد. برای مدیریت روان خطاهای محدودیت نرخ، از بازگشت نمایی استفاده کنید.
هنگامی که کد وضعیت 429 را دریافت میکنید، پیش از تلاش مجدد صبر کنید. با یک تأخیر کوتاه شروع کنید و آن را با هر بار تلاش مجدد افزایش دهید. این کار از بار بیش از حد روی سرور در ساعات اوج جلوگیری میکند.
نرخ درخواست‌های خود را پایش کنید و سطح همزمانی را متناسب با آن تنظیم نمایید. اگر درخواست‌های همزمان زیادی ارسال میکنید، در نظر بگیرید که آن‌ها را در طول زمان پخش کنید. این امر باعث می‌شود تا throughput پایدار بدون رسیدن به محدودیت‌ها حفظ شود.
ساختارهای payload فراخوانی تابع
برای فراخوانی تابع، نیاز به یک ساختار پیکربندی خاص است. توابع خود را در پارامتر tools تعریف کنید و tool_choice را مشخص کنید. اگر مدل تشخیص دهد که این پاسخ مناسب است، یک فراخوانی تابع را برمی‌گرداند.
اطمینان حاصل کنید که تعاریف توابع شما دقیق و کامل هستند. پارامترهای گمشده یا انواع نادرست می‌توانند باعث شوند مدل فراخوانی‌های نامعتبر تولید کند. همیشه قبل از اجرای فراخوانی تابع، آرگومان‌های آن را اعتبارسنجی کنید.
از پارامتر tool_choice برای کنترل زمان فراخوانی توابع توسط مدل استفاده کنید. می‌توانید یک فراخوانی تابع را اجباری کنید، به مدل اجازه دهید تصمیم بگیرد، یا فراخوانی تابع را کاملاً غیرفعال کنید. این به شما کنترل دقیقی بر رفتار مدل می‌دهد.
عیب‌یابی خطاهای 400 و 500
خطاهای 400 نشان‌دهنده مشکلات سمت کلاینت، مانند JSON نامعتبر یا پارامترهای جاافتاده هستند. خطاهای 500 مشکلات سمت سرور، مانند خطاهای داخلی یا زمان‌بندی‌های منقضی‌شده را نشان می‌دهند. تشخیص بین این دو به شما کمک میکند تا سریع‌تر اشکال‌زدایی کنید.
برای خطاهای 400، پیام خطای ارائه‌شده در پاسخ را بررسی کنید. این پیام معمولاً مستقیماً به مشکل اشاره دارد. برای خطاهای 500، پس از یک تأخیر کوتاه، درخواست را مجدداً ارسال کنید. در صورت تداوم خطا، با ارائه شناسه درخواست، با پشتیبانی تماس بگیرید.
جزئیات درخواست و پاسخ را برای هر خطا ثبت کنید. این کار به شناسایی الگوها و مشکلات تکراری کمک میکند. از یک سرویس لاگ برای ردیابی خطاها در طول زمان و بهبود یکپارچه‌سازی API خود استفاده کنید.
