طراحی پیام‌های خطای API برای عوامل هوش مصنوعی چگونه است؟

طراحی پیام‌های خطای API برای عوامل هوش مصنوعی (Designing API Error Messages for AI Agents)

دنیای APIها پر از پیچیدگی و موانع است. برخورد با خطاها در استفاده معمولی از APIها امری عادی است و نحوه مدیریت و انتقال این خطاها به کاربر نهایی، اغلب معیاری برای تمایز یک محصول خوب از یک محصول متوسط است. ارتباط مؤثر خطاها اهمیت بسیار زیادی دارد و می‌تواند عامل بزرگی در قابلیت استفاده و قابل فهم بودن برای ماشین‌ها باشد. این موضوع وقتی عوامل هوش مصنوعی به عنوان مصرف‌کننده API وارد می‌شوند، پیچیده‌تر می‌شود. یک پیام خطای عجیب ممکن است، با تلاش توسط انسان تفسیر شود.

اما وقتی این پیام خطا با زمینه بسیار کم به یک مدل زبانی بزرگ (LLM) داده شود، چه اتفاقی می‌افتد؟

توسعه‌دهندگان انسانی می‌توانند لاگ‌ها را بخوانند، مستندات را بررسی کنند و حدس بزنند که خطا به چه معناست. اما عوامل هوش مصنوعی کاملاً به معانی صریح و نشانه‌های واضح وابسته هستند تا درباره گام‌های بعدی استدلال کنند و بدون این‌ها، رفتارشان غیرقابل پیش‌بینی می‌شود. امروز قصد داریم درباره طراحی پیام‌های خطای API برای مصرف‌کنندگان هوش مصنوعی صحبت کنیم. به این می‌پردازیم که چرا این یک مشکل است و چگونه می‌توانید با استفاده از بهترین راهنمایی‌های موجود، پیام‌های خطای API بهتری بسازید.

کدهای وضعیت حالت مکالمه‌ای نیستند

شاید بزرگ‌ترین دلیل این مشکل این باشد که کدهای وضعیت HTTP کوتاه و مستقیم هستند. این کدها ایده‌ای از وضعیت زیرین به ما می‌دهند و ممکن است کمی زمینه هم همراه داشته باشند، اما در نهایت، در بیان آنچه می‌توانند و چگونگی کمک به کاربر نهایی، بسیار محدود هستند. کدهای وضعیت استاندارد را در نظر بگیرید. کد ۴۰۴ به ما می‌گوید چیزی پیدا نشد. کد ۵۰۰ می‌گوید چیزی اشتباه شده است. در حالی که می‌توانیم اینجا و آنجا کمی زمینه اضافه کنیم، کد وضعیت به طور طبیعی محدود است. برای یک عامل هوش مصنوعی که سعی دارد مشکلی را حل کند — تصمیم بگیرد که دوباره امتحان کند، ارتقا دهد یا ورودی‌ها را تغییر دهد و تجزیه کند — کدهای وضعیت تقریباً هیچ بینش عملی ارائه نمی‌دهند. بدتر از آن، اغلب این بینش و زمینه را پشت دیواری محکم از «خطای ۵۰۰» پنهان می‌کنند. تصور کنید یک عامل هوش مصنوعی با یک API تجارت الکترونیک کار می‌کند. یک ۴۰۰ Bad Request با زمینه بسیار کم دریافت می‌کند. از دیدگاه هوش مصنوعی، این اساساً بی‌فایده است.

آیا ورودی نادرست بود؟ آیا فیلد ضروری گم شده است؟ آیا درخواست یک قانون تجاری را نقض کرده است؟

بدون زمینه عمیق‌تر، عامل نمی‌تواند بداند که دوباره امتحان کند، ورودی‌ها را تغییر دهد یا تاکتیک کاملاً جدیدی را امتحان کند. در حالی که انسان‌ها می‌توانند از تجربه مادام‌العمر خود برای تفسیر آنچه ممکن است رخ داده باشد استفاده کنند، ماشین‌ها بسیار هدفمندتر و کمتر قادر به چنین رویکردی هستند. این مشکل است.

برخی راه‌حل‌ها چیست؟

راه‌حل ۱: غنی‌سازی خطاها با زمینه غنی

عوامل هوش مصنوعی با ساختار شکوفا می‌شوند و یکی از راه‌حل‌های این مشکل، ارائه کدهای خطای غنی‌شده با بارهای زمینه قابل خواندن برای ماشین است. الگوی خوبی در اینجا پیروی از RFC 7807 IETF برای جزئیات مشکل در APIهای HTTP است. این رویکرد یک فرمت استاندارد برای پیام خطا تعریف می‌کند. برای مثال، در مثال ۴۰۰ Bad Request ما، ممکن است چیزی شبیه به این تولید کنیم:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/invalid-price",
  "title": "Invalid price format",
  "status": 400,
  "detail": "The 'price' field must be a positive number",
  "instance": "/orders/abc123"
}

این زمینه چند قطعه کلیدی اطلاعات ارائه می‌دهد. ابتدا، سیستم را از وقوع خطای نوع ۴۰۰ آگاه می‌کند. سپس، نوع مستقیم را مشخص می‌کند: قیمت نامعتبر، همراه با یک شناسه URI که اطلاعات زمینه‌ای بیشتری ارائه می‌دهد. فیلد عنوان به هوش مصنوعی اطلاع می‌دهد که مشکل مربوط به فرمت قیمت نامعتبر است و فیلد جزئیات مشخص می‌کند که مشکل واقعی در ناهنجاری چیست. در نهایت، کد وضعیت به وضوح به عنوان بخشی از شیء JSON مشخص شده و یک نمونه برای نشان دادن محل وقوع خطا ارائه می‌شود. این مقدار زیادی زمینه بیشتر ارائه می‌دهد و برای یک عامل هوش مصنوعی، جایی برای شروع حل مسئله فراهم می‌کند. بدون هیچ یک از این زمینه‌ها، باید حدس بزنیم چگونه آن را برطرف کنیم. با این اطلاعات خطا در دست، عامل هوش مصنوعی می‌تواند مستقیماً مشکل را برطرف کند و رفع آن را مستقیماً در پرامپت تأیید کند.

راه‌حل ۲: تعریف مسیر بازیابی

انسان‌ها می‌توانند گام‌های بعدی را حدس بزنند. می‌توانند با استفاده از تجربه و داده‌های مشاهده‌شده، مسیر عملی را استنباط کنند. عوامل هوش مصنوعی هنوز به این سطح نرسیده‌اند و به همین دلیل، به دستورالعمل‌های بسیار صریح‌تری نیاز دارند. اگر یک خطای ساختاریافته به یک عامل هوش مصنوعی بدهید و سپس آن را برای فهمیدن اینکه با آن خطا چه کند رها کنید، ممکن است نتیجه خوبی بگیرید، اما ممکن است گام‌های بعدی کاملاً خیالی و مخرب برای کل جریان دریافت کنید. بنابراین، در نظر بگیرید که یک مسیر بازیابی صریح برای عوامل هوش مصنوعی ارائه دهید.

در مثال بالا، یک هوش مصنوعی برای رفع مشکل چه باید بکند؟

به عنوان توسعه‌دهنده، به آن خطا نگاه می‌کنیم و بلافاصله می‌دانیم که رفع آن، رسیدگی به دلیل منفی بودن قیمت است و شاید نوعی اقدام اصلاحی انجام دهیم. برای یک سیستم هوش مصنوعی، این ممکن است به سادگی بازگشت متن برای امتحان یک عدد مثبت باشد. اما در مورد چیزی پیچیده‌تر چطور؟ تصور کنید سیستمی داریم که محدودیت نرخ دارد و عامل هوش مصنوعی ما به دلیل عبور از محدودیت نرخ تعریف‌شده توسط سیستم، متوقف شده است. می‌خواهیم به سیستم اطلاع دهیم چرا متوقف شده است، اما همچنین راه‌هایی ارائه دهیم تا وضعیت فعلی خود را درک کند. خوشبختانه، می‌توانیم از هایپرمدیا برای اتصال این سیستم‌ها برای عامل هوش مصنوعی استفاده کنیم. در زیر یک پیاده‌سازی HATEOAS در JSON با برخی لینک‌ها که زمینه ارائه می‌دهند، همراه با روش‌هایی برای رسیدگی به مسئله اصلی آمده است.

{
  "type": "https://example.com/probs/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have exceeded your rate limit of 100 requests per minute",
  "retry_after": 30,
  "links": [
    {
      "rel": "self",
      "href": "/orders"
    },
    {
      "rel": "retry",
      "href": "/orders",
      "title": "Retry after delay"
    },
    {
      "rel": "status",
      "href": "/rate-limit-status",
      "title": "Check current rate limit usage"
    }
  ]
}

در این مثال، همچنان گزارش خطای اصلی خود را داریم، اما اکنون برخی لینک‌ها برای دنبال کردن توسط عامل داریم. اولی صفحه سفارش است که عامل می‌تواند زمینه سفارش خود را در سیستم درک کند. بعدی، یک تابع دوباره امتحان برای سیستم برای پخش مجدد سفارش و امتحان دوباره ارائه می‌دهد. در نهایت، یک سرویس وضعیت ارائه می‌دهیم تا سیستم بتواند وضعیت محدودیت نرخ خود را بررسی کند و از بررسی‌ها در حالی که هنوز محدود است، جلوگیری کند. این ساده به نظر می‌رسد، اما این پیوندهای هایپرمدیا به هوش مصنوعی زمینه بسیار بیشتری و همچنین ابزارهایی برای حل مشکلات و استدلال درباره بهترین پیاده‌سازی چنین راه‌حلی ارائه می‌دهد.

راه‌حل ۳: ساختاردهی معنایی

به بسیاری از جهات، مشکل پیام خطا از این واقعیت ناشی می‌شود که اغلب دوگانگی کد قابل خواندن برای انسان و قابل خواندن برای ماشین داریم. واقعیت این است که اکنون در حالتی میانی هستیم، جایی که یک ماشین پاسخ را می‌خواند، اما مانند یک انسان. این چیزی شبیه به کد قابل خواندن برای هوش مصنوعی است و به همین دلیل، نیاز به یافتن راه‌حلی ساختاریافته‌تر و معنایی‌تر داریم. به جای ریختن کدهای خطا یا لاگ‌های متنی خام در بارهای خطا، باید به جای آن فیلدهای معنایی ساختاریافته‌تر برای کمک به دسته‌بندی و پاسخ به خطاها انتخاب کنیم. برای مثال، ساخت توابع خطای خود برای شامل کردن فیلدهای مستقیم و مفیدتر مانند trace_id یا پیشنهادها، به ما امکان می‌دهد هوش مصنوعی را به راه‌حل‌های خاص برای موارد استفاده خاص هدایت کنیم. مثال زیر فرض می‌کند که یک هوش مصنوعی با فیلدهای نامعتبر به مشکل خورده است. این یک مورد پیچیده است، زیرا شما به داده نامعتبر با ارائه آن به عنوان داده اشاره می‌کنید. برای سیستم هوش مصنوعی، باید به خاطر بیاورد که چه داده‌ای خیالی است و چه داده‌ای را باید کاملاً رد کند در حالی که داده‌های کاملاً جدیدی را به سیستم وارد می‌کند. برای حل این، می‌توانیم داده‌های معنایی پیوندی بسیار بیشتری در فیلدهای خود ارائه دهیم:

{
  "type": "https://example.com/probs/invalid-field",
  "title": "Invalid field value",
  "status": 400,
  "error_code": "E1007",
  "detail": "The provided category ID does not exist",
  "parameters": {
    "category_id": "xyz123"
  },
  "suggestions": [
    "electronics",
    "books",
    "clothing"
  ]
}

در این مورد، مقدار فیلد نامعتبر با تمام زمینه‌اش بیان شده است، اما پیشنهادهای اضافی برای نشان دادن به عامل هوش مصنوعی نه تنها برخی شناسه‌های پیشنهادی معتبر، بلکه انواع شناسه‌های موجود ارائه شده است. اگر عامل هوش مصنوعی چیزی مانند ISBNlist ارسال کرده باشد، به این لیست نگاه خواهد کرد و کتاب‌ها را تشخیص خواهد داد — و اگر مدل خود را به درستی پیکربندی و آموزش داده باشید، باید به طور معنایی کتاب‌ها را به ISBN پیوند دهد و در نتیجه درک و زمینه خود را بهبود بخشد. این نوع ساختار به عوامل هوش مصنوعی اجازه می‌دهد تا گزینه‌هایی را به کاربر ارائه دهند، با نزدیک‌ترین تطابق دوباره امتحان کنند یا مسئله را ارتقا دهند — بدون حدس زدن.

راه‌حل ۴: بهبود طبقه‌بندی خطای خود

در نهایت، توسعه‌دهندگان API باید در نظر بگیرند که طبقه‌بندی API آنها واقعاً چگونه است. در حالی که کدهای خطای HTTP خوب و عالی هستند، می‌توانید کدهای خطای خاص را نیز به کاربران ارائه دهید و با این کار، خطاها و مسائل خاص را تعریف کنید. کدهای خطای زیر را در نظر بگیرید که همه می‌توانند تحت خطای ۴۰۰ Bad Request قرار گیرند:

• فیلد ضروری گم شده: یک پارامتر ضروری ارسال نشده است.
• فرمت نامعتبر: فرمت پارامتر نادرست بود.
• نوع منبع نادرست: منبعی از نوع مشخص‌شده یافت نمی‌شود.

برای یک عامل هوش مصنوعی، فقط پاسخ دادن خطای ۴۰۰ کافی نیست. در برخی موارد، مشکل آنقدر خاص است که حتی ارائه محتوای معنایی خیلی کمک‌کننده نیست. حل این می‌تواند به شکل یک راه‌حل خطای طبقه‌بندی بسیار خاص‌تر باشد. برای مثال، ممکن است نوع منبع نادرست خود را به این شکل حل کنیم:

{
  "status_code": "400 Bad Request",
  "error_message": "Incorrect resource type provided",
  "internal_code": "E4001",
  "doc_uri": "https://docs.example.com/errors/400/E4001",
  "detail": "The provided resource type does not exist",
  "parameters": {
    "category_id": "xyz123"
  },
  "suggestions": [
    "electronics",
    "books",
    "clothing"
  ]
}
}

با نگاشت نزدیک‌تر کد خطا به کد وضعیت خاص و سپس ارائه اطلاعات زمینه‌ای اضافی، می‌توانیم مسیرهای منطقی برای دنبال کردن توسط عامل هوش مصنوعی برای حل مشکل ایجاد کنیم. اگر بداند بخشی از E4001 است، می‌تواند این را در مستندات با لینک ارائه‌شده جستجو کند و طبقه‌بندی مشکل را درک کند و از وقوع آن در آینده جلوگیری کند.

مدیریت خطا برای عوامل هوش مصنوعی

عوامل هوش مصنوعی ماشین هستند، اما در برخی جنبه‌های حیاتی مانند انسان عمل می‌کنند. با پیچیده‌تر و قدرتمندتر شدن این سیستم‌ها، باید در طراحی خدمات خود، به ویژه در مدیریت خطا، عمدی‌تر باشیم. درست انجام دادن این کار اکنون و آینده‌نگری سیستم‌هایتان، می‌تواند نعمت بزرگی برای تعاملات عامل‌محور و همچنین استفاده انسانی باشد.