سرفصل‌ها درس 121 از 250 · فراخوانی یک LLM واقعی
فراخوانی یک LLM واقعی

مدیریت خطاهای API

تماس‌های واقعی شبکه‌ای شکست می‌خورند و یک کلاینت تولیدکننده‌ی LLM با واکنشش زنده می‌ماند یا از کار می‌افتد. مفیدترین غریزه این است که شکست‌ها را به دو دسته تقسیم کنید: آن‌هایی که ارزش تلاش مجدد دارند (یک اختلال موقتی که احتمالاً برطرف می‌شود) و آن‌هایی که باید در خود درخواست اصلاح شوند (یک باگ در تماس شما که هیچ میزان تلاش مجددی کمکی نخواهد کرد). کد وضعیت HTTP به شما می‌گوید در کدام دسته قرار دارید.

در کد واقعی، شما استثناءهای تایپ‌شده SDK را می‌گیرید که هر کدام یک ... حمل می‌کنند .status_code (صرفاً برای نمایش -> ما شبکه را فراخوانی نمی‌کنیم):

import anthropic
try:
    resp = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                                  messages=history)
except anthropic.RateLimitError:          # HTTP 429 -> back off and retry
    ...
except anthropic.APIStatusError as e:     # any other 4xx/5xx, has e.status_code
    if should_retry(e.status_code):
        ...   # retry with backoff
    else:
        raise # 400/401/403/404 -> a bug in YOUR request, surface it

دسته‌بندی‌ها، بر اساس کد وضعیت:

  • تکرار -> 408 (انقضای درخواست)، 409 (تداخل)، 429 (محدودیت نرخ)، و هر خطای سرور از 500 به 599، مانند 502, 503 (در دسترس نیست) یا 529 (بارگذاری بیش از حد). این خطاها موقتی هستند: منتظر بمانید، سپس دوباره تلاش کنید. وقتی پاسخ شامل یک retry-after سربرگ، حداقل به همان مدت صبر کنید.
  • درخواست را اصلاح کنید -> 400 (درخواست نادرست)، 401 (کلید API نامعتبر)، 403 (ممنوع)، 404 (مدل یا مسیر اشتباه). دوباره تلاش برای یک فراخوانی معیوب فقط کوتا را هدر می‌دهد.
  • نامشخص -> هر چیز دیگری (از جمله موفقیت مانند 200): فرض نکنید که دوباره تلاش کردن امن است.

شما در حال ساخت دو تابع کوچک هستید. classify_error(status) نام باکت را برمی‌گرداند: "retry", "fix-request"، یا "unknown". should_retry(status) بازگرداندن مقدار بولی -> True دقیقاً زمانی که وضعیت در مجموعهٔ تلاش مجدد باشد، در غیر این صورت False.

این درس تصمیم می‌گیرد که آیا باید دوباره تلاش کرد؛ انتظار بین تلاش‌ها مهارتِ خودِ آن است. ماژول production-patterns عقب‌نشینی نمایی (هر بار تأخیر را دو برابر می‌کند: ۱ ثانیه، ۲ ثانیه، ۴ ثانیه ...) را پوشش می‌دهد، و روی آن jitter اضافه می‌کنید -> مقدار اندکی تصادفی از انتظار اضافی -> تا گروهی از کلاینت‌ها که هم‌زمان رد شده‌اند، همگی در همان ضرب‌آهنگ دوباره تلاش نکنند و دوباره سرور را شلوغ نکنند (گله غرش‌کننده). آن را طوری بسازید که جدول وضعیت چندین پاسخ متفاوت بدهد (429 -> تلاش مجدد، 400 -> fix-request، 200 -> نامشخص)، که به این معنی است که هیچ مقدار ثابتی نمی‌تواند عبور کند.

نوبت شما

نوشتن classify_error(status) بازگشت "retry" برای 408 (درخواست اتمام زمان)، 409 (تضاد)، 429 (محدودیت نرخ) و هر خطای سرور از 500 تا 599 (529 به معنای بارگذاری بیش از حد)، "fix-request" برای {400, 401, 403, 404}، و "unknown" برای هر چیز دیگر. بنویسید should_retry(status) بازگرداندن بولین True دقیقاً وقتی classify_error(status) است "retry"، در غیر این صورت False. (این همان قاعده‌ای است که SDK رسمی Anthropic استفاده می‌کند: این وضعیت‌ها و خطاهای اتصال را به‌طور پیش‌فرض دو بار مجدداً امتحان می‌کند و تا زمانی که یک retry-after سربرگ می‌پرسد. در کد واقعی شما عمدتاً پیکربندی می‌کنید max_retries به‌جای اینکه خودتان آن را بنویسید؛ نوشتن آن یک‌بار به شما نشان می‌دهد که چه کاری انجام می‌دهد.)

مشکلی در این درس دیدید؟ گزارشش کنید · دربارهٔ این درس بپرسید

این تمرین به‌زودی باز می‌شود

درس پیش از آن را تمام کنید تا این یکی باز شود. کل دوره رایگان است، حساب کاربری لازم نیست، و می‌توانید همین الان این درس را بخوانید.