درک محدودیت‌های نرخ و درخواست‌های همزمان
محدودیت‌های نرخ تعیین می‌کنند که کلید API شما می‌تواند در یک بازه زمانی مشخص چند درخواست را پردازش کند تا از بار بیش‌ازحد سرور جلوگیری شود.
Anthropic هم محدودیت درخواست در دقیقه (RPM) و هم محدودیت توکن در دقیقه (TPM) اعمال می‌کند. اگر از سقف RPM عبور کنید، خطای 429 Too Many Requests دریافت می‌کنید. این اتفاق اغلب زمانی رخ می‌دهد که چندین رشته درخواست‌های موازی را از همان کلید ارسال می‌کنند. باید در کد کلاینت خود بازگشت نمایی (exponential backoff) را پیاده‌سازی کنید تا این تلاش‌های مجدد را به صورت روان مدیریت کنید.
درخواست‌های موازی نیز مهم هستند. اگرچه ممکن است محدودیت RPM بالایی داشته باشید، اما حداکثر تعداد اتصالات همزمان برای هر کلید معمولاً محدود است. اگر یک پایپ‌لاین با پهنای باند بالا اجرا می‌کنید، داشبورد خود را برای این معیارها مانیتور کنید. فراتر رفتن از محدودیت‌های همزمانی می‌تواند باعث صف‌بندی درخواست‌ها یا قطع اتصالات شود.
| نوع محدودیت | اثر | وضوح |
|---|---|---|
| RPM | خطای 429 | افزایش بازگشتی پیاده‌سازی کنید |
| TPM | محدودیت نرخ | کاهش اندازه دسته |
| موازی | صف/حذف | کاهش همزمانی |
مدیریت خطاهای پنجره زمینه توکن
خطاهای پنجره زمینه توکن زمانی رخ می‌دهد که ورودی شما از حداکثر طول پشتیبانی شده مدل فراتر رود و باعث شکست سخت شود.
هر مدل دارای یک پنجره زمینه تعریف‌شده است، مانند ۲۰۰,۰۰۰ توکن برای جدیدترین نسخه‌ها. این پنجره شامل هم پرامپت و هم تکمیل است. اگر تعداد توکن‌های ترکیبی شما از این محدودیت تجاوز کند، API بلافاصله خطا برمی‌گرداند. نمی‌توانید پاسخ را صرفاً کوتاه کنید؛ باید اندازه ورودی را مدیریت کنید.
برای جلوگیری از این مشکل، قبل از ارسال درخواست‌ها، تعداد توکن‌ها را تخمین بزنید. از کتابخانه‌هایی که توکن‌ها را به دقت می‌شمارند استفاده کنید. اگر اسناد طولانی پردازش می‌کنید، استراتژی‌های chunking یا خلاصه‌سازی را قبل از ارسال متن کامل در نظر بگیرید. همیشه مستندات مدل را برای طول زمینه خاص آن بررسی کنید.
پیکربندی URL پایه‌ها برای سازگاری
پیکربندی URL پایه صحیح تضمین می‌کند که درخواست‌های شما به سرورهای Anthropic مورد نظر بدون خطاهای مسیریابی برسد.
آدرس پایه استاندارد HTTPS://api.anthropic.com است. با این حال، برخی مناطق یا نقاط پایانی خاص ممکن است از آدرس‌های متفاوتی استفاده کنند. استفاده از آدرس پایه نادرست منجر به زمان‌های انتظار اتصال (timeouts) یا خطاهای 404 می‌شود. همیشه بررسی کنید که URL در پیکربندی کلاینت شما با مستندات رسمی مطابقت دارد.
اگر از یک پوشش سازگار با OpenAI استفاده می‌کنید، مطمئن شوید که URL پایه به پراکسی صحیح اشاره می‌کند. URLهای ناسازگار می‌توانند منجر به رفتارهای غیرمنتظره مانند هدرهای گمشده یا طرح‌های احراز هویت نادرست شوند. متغیرهای محیطی خود را برای تنظیم URL پایه دوباره بررسی کنید.
مدیریت انقضا و چرخش کلید API
انقضای کلید API و چرخش آن، از حساب شما در برابر استفاده‌های غیرمجاز محافظت می‌کند اگر کلیدی لو برود.
برخی ارائه‌دهندگان اجازه می‌دهند که کلیدها پس از یک دوره مشخص منقضی شوند. اگر کلید شما منقضی شود، درخواست‌ها با خطای احراز هویت شکست می‌خورند. کلیدها را به طور منظم بچرخانید تا خطر را به حداقل برسانید. کلیدها را به طور ایمن در متغیرهای محیطی یا مدیریت‌کنندگان رمزنگاری ذخیره کنید، نه در فایل‌های منبع کدنویسی شده.
چرخش باید در دوره‌های ترافیک کم انجام شود. یک کلید جدید تولید کنید، پیکربندی مشتری خود را به‌روزرسانی کنید و عملکرد را قبل از لغو کلید قدیمی تأیید کنید. این تضمین می‌کند که قطعی صفر وجود دارد. تاریخچه تاریخ‌های ایجاد کلید را برای پیش‌بینی انقضا نگه دارید.
اشکال‌زدایی مشکلات پاسخ جریان‌دار
مشکلات پاسخ استریم اغلب ناشی از مدیریت نادرست رویدادهای ارسالی سرور (SSE) یا هدرهای گمشده است.
هنگام Streaming، API داده‌ها را در Chunkها ارسال می‌کند. کلاینت شما باید این Chunkها را به درستی Parse کند. اگر یک Chunk را از دست بدهید یا رویداد نهایی را مدیریت نکنید، برنامه شما ممکن است Hang کند یا متن ناقص نمایش دهد. اطمینان حاصل کنید که کد شما به رویداد Stream گوش می‌دهد و هر Token را هنگام رسیدن پردازش می‌کند.
از جمله اشتباهات رایج نادیده گرفتن stop_reason field or failing to close the stream connection. Always handle errors within the stream to prevent resource leaks. Use libraries that abstract the streaming logic if you are building a custom client.
بهینه‌سازی ساختار پرامپت برای کارایی هزینه
بهینه‌سازی ساختار پرامپت، مصرف توکن را کاهش داده و هزینه‌های شما را کاهش می‌دهد، در حالی که کیفیت خروجی حفظ می‌شود.
هر توکن در پرامپت شما هزینه دارد. فضاهای خالی غیرضروری، دستورالعمل‌های تکراری و مثال‌های بیش‌ازحد را حذف کنید. از زبان مختصر و فرمت‌های ساختاریافته مانند JSON یا XML برای دستورالعمل‌های واضح استفاده کنید. این کار تعداد توکن‌های ورودی را به طور قابل توجهی کاهش می‌دهد.
از دستورات سیستم برای دستورالعمل‌های عمومی و دستورات کاربر برای وظایف خاص استفاده کنید. این جداسازی می‌تواند عملکرد مدل را بهبود بخشد و نیاز به زمینه تکراری را کاهش دهد. استفاده از توکن خود را در داشبورد نظارت کنید تا پیکربندی‌های ناکارآمد را شناسایی کنید. پیکربندی‌های خود را بر اساس داده‌های استفاده تنظیم کنید تا هزینه‌ها بهینه شوند.
اشتباهات رایج در پیاده‌سازی Tool Calling
اشتباهات فراخوانی ابزار اغلب شامل طرح‌های JSON نادرست یا مدیریت نادرست پاسخ‌های ابزار است.
هنگام استفاده از ابزارها، طرحواره JSON را به‌دقت تعریف کنید. عدم تطابق انواع داده یا فیلدهای ضروری باعث می‌شود مدل در تولید فراخوانی‌های ابزار معتبر شکست بخورد. مطمئن شوید که کد کلاینت شما می‌تواند آرگومان‌های فراخوانی ابزار را تجزیه کند و تابع را به‌درستی اجرا کند. نتیجه را در فرمت مورد انتظار برای مدل بازگردانید تا مدل بتواند ادامه دهد.
خطای رایج دیگر عدم مدیریت خطاهای ابزار به‌صورت مناسب است. اگر یک ابزار شکست خورد، یک پیام خطا به مدل برگردانید تا بتواند تلاش مجدد کند یا تنظیمات را تغییر دهد. این امر قابلیت اطمینان کلی برنامه شما را بهبود می‌بخشد. تعاریف ابزار خود را به دقت پیش از استقرار در محیط تولید آزمایش کنید.
بهترین شیوه‌های امنیت برای کلیدهای API
بهترین شیوه‌های امنیت از دسترسی غیرمجاز به منابع API شما جلوگیری کرده و خطر کلاهبرداری صورت‌حساب را کاهش می‌دهد.
هرگز کلید API خود را در مخازن عمومی یا کدهای سمت کلاینت به اشتراک نگذارید. از متغیرهای محیطی یا سرویس‌های مدیریت رمز عبور برای ذخیره کلیدها استفاده کنید. کلیدها را به‌طور منظم تغییر دهید و کلیدهای استفاده‌نشده را لغو کنید. مصرف API خود را برای الگوهای غیرعادی، مانند افزایش ناگهانی مصرف توکن، نظارت کنید.
اگر ارائه‌دهنده شما از آن پشتیبانی می‌کند، IP whitelisting را پیاده‌سازی کنید. این کار لایه امنیتی اضافی‌ای با محدود کردن دسترسی به آدرس‌های IP شناخته‌شده اضافه می‌کند. برای تمام درخواست‌های API از HTTPS استفاده کنید تا داده‌ها در حال انتقال رمزنگاری شوند. به‌طور منظم مجوزهای کلید خود را بررسی کنید تا مطمئن شوید با نیازهای برنامه شما مطابقت دارند.
