عامل AI را با OpenTelemetry ردگیری کنید؛ ورودی کامل را کورکورانه نفرستید

برای ردگیری عامل هوش مصنوعی با OpenTelemetry، یک span برای اجرای عامل بسازید و هر فراخوانی مدل و هر اجرای واقعی ابزار را در span جداگانه‌ای زیر آن ثبت کنید. این درخت نشان می‌دهد زمان پاسخ کجا صرف شده و خطا در کدام مرحله رخ داده است؛ برای دیدن این دو، لازم نیست متن کامل درخواست یا نتیجهٔ ابزار را به سامانهٔ مشاهده‌پذیری بفرستید.

در شروع، نام عملیات، نام مدل و ابزار، زمان اجرا و وضعیت خطا را ثبت کنید. شمار توکن‌ها را زمانی اضافه کنید که پاسخ معتبرِ ارائه‌دهنده در دسترس است. برای پرامپت، آرگومان ابزار و خروجی آن سیاست جداگانه‌ای دربارهٔ پالایش، دسترسی و نگهداری تعیین کنید؛ نمونه‌برداری جای این سیاست را نمی‌گیرد.

مرز هر span را با کار واقعی عامل هماهنگ کنید

span عامل را هنگام آغاز پردازش درخواست ایجاد کنید و پس از آماده‌شدن نتیجه پایان دهید. اگر اجرای عامل زیر span درخواست HTTP قرار دارد، همان درخواست می‌تواند والد آن باشد. مهم این است که فراخوانی‌های مدل و ابزار در یک trace و با رابطهٔ والد و فرزند درست دیده شوند؛ وقتی کار به سرویس دیگری می‌رود، context ردگیری را نیز منتقل کنید.

1. برای اجرای عامل، نامی پایدار مانند invoke_agent انتخاب کنید. متن درخواست، ایمیل یا شناسهٔ کاربر را وارد نام span نکنید، چون هر مقدار تازه یک نام تازه می‌سازد.
2. هر درخواست مستقل به مدل را با span خودش ثبت کنید. در چرخه‌ای که پس از دریافت نتیجهٔ ابزار دوباره مدل فراخوانی می‌شود، این درخواست دوم span جداگانه می‌خواهد.
3. span ابزار را هنگام اجرای کد ابزار باز کنید، نه صرفاً هنگام پیشنهاد استفاده از آن از سوی مدل. اگر ابزار سرویس دیگری را فرا می‌خواند، spanهای آن سرویس می‌توانند زیر اجرای ابزار قرار گیرند.
4. span عامل را با نتیجهٔ نهایی همان اجرا پایان دهید. خطای یک مرحله و شکست کل کار الزاماً یک وضعیت نیستند.

برای مثال فرضیِ پاسخ‌گویی به وضعیت سفارش، مسیر می‌تواند «مدل، جست‌وجوی سفارش، مدل، پاسخ عامل» باشد. اگر جست‌وجو کند شود، مدت span ابزار محل تأخیر را نشان می‌دهد. اگر جست‌وجو خطا بدهد ولی عامل پاسخ جایگزین مناسبی تولید کند، خطا روی span ابزار دیده می‌شود و وضعیت span عامل نتیجهٔ نهایی کار را بازتاب می‌دهد.

نام‌گذاری مشترک را از جزئیات ارائه‌دهنده جدا کنید

قرارداد GenAI در OpenTelemetry برای عملیات مدل نام‌هایی مانند chat و برای اجرای ابزار execute_tool را به کار می‌برد؛ gen_ai.operation.name، gen_ai.request.model و gen_ai.tool.name از ویژگی‌های مربوط به این مراحل‌اند. در span ابزار، gen_ai.tool.call.id را فقط وقتی ثبت کنید که مدل یا ارائه‌دهنده شناسه‌ای داده باشد. آرگومان و نتیجهٔ ابزار ویژگی‌های اختیاری‌اند و ممکن است دادهٔ حساس داشته باشند.

نام عامل و ابزار را از مجموعه‌ای محدود و پایدار انتخاب کنید تا بتوان اجراهای مشابه را کنار هم دید. مدلِ درخواستی را از مدلِ پاسخ‌دهنده جدا نگه دارید، زیرا ممکن است این دو یکسان نباشند. برای شمار توکن ورودی و خروجی نیز به دادهٔ همان عملیات تکیه کنید؛ اگر چند لایه برای یک درخواست مقدار مصرف ثبت می‌کنند، جمع‌زدن بی‌تمایز spanها مصرف را تکراری نشان می‌دهد.

پیشوندهای اختصاصی ارائه‌دهنده را برای جزئیاتی نگه دارید که فیلد مشترک ندارند. در عوض، پرسش‌های اصلی عیب‌یابی ــ عامل کدام ابزار را اجرا کرد، مدل چقدر طول کشید و کدام مرحله شکست خورد ــ باید با ساختار trace و ویژگی‌های مشترک پاسخ داده شوند. این تفکیک هنگام تغییر SDK یا ارائه‌دهنده، مقایسهٔ اجراهای قدیم و جدید را ساده‌تر می‌کند.

از Claude رابطهٔ مراحل را بگیرید، نه نام‌های اختصاصی‌اش را

مرجع spanهای Claude درخواست پیام، درخواست داخلی مدل و اجرای ابزار را از هم تفکیک می‌کند؛ ویژگی‌های مشترک آن با gen_ai.* و ویژگی‌های اختصاصی با anthropic.* آغاز می‌شوند. در چرخهٔ ابزارِ SDK، درخواست‌های مدل و ابزارهایی که اجرا می‌شوند زیر span چرخه قرار می‌گیرند. درخواست استفاده از ابزار و نتیجهٔ آن می‌توانند در بخش‌های پیام نیز نمایش یابند، اما صرفِ درخواست ابزار به معنای اجرای آن نیست.

در این نمونه، span سمت SDK و span سمت API می‌توانند دو سوی یک درخواست باشند. اگر هر دو را دریافت می‌کنید، به رابطهٔ والد و فرزند و مبدأ هر span توجه کنید تا آن‌ها را دو درخواست مستقل حساب نکنید. همچنین ابزار سفارشیِ اجراشده در برنامه باید از سمت همان برنامه ردگیری شود؛ وجود درخواست استفاده از ابزار در پاسخ مدل، خودبه‌خود span اجرای آن را ایجاد نمی‌کند.

محتوای حساس را پیش از خروج از برنامه کنترل کنید

سیاست پیش‌فرض مناسب برای trace عملیاتی، خالی‌گذاشتن gen_ai.system_instructions، gen_ai.input.messages، gen_ai.output.messages، gen_ai.tool.call.arguments و gen_ai.tool.call.result است. زمان، نوع عملیات و وضعیت خطا معمولاً برای یافتن مرحلهٔ مسئله‌دار کافی‌اند. اگر بررسی موردی به محتوا نیاز دارد، محدودهٔ ثبت را مشخص کنید و فقط فیلدهای مجاز را پس از پالایش و با دسترسی و مدت نگهداری جداگانه ذخیره کنید.

کوتاه‌کردن متن به‌تنهایی دادهٔ شخصی را حذف نمی‌کند؛ نام، نشانی یا اطلاعات سفارش ممکن است در همان بخش باقی‌مانده باشد. همین بررسی را به eventها، logهای وابسته و پیام استثنا گسترش دهید، چون محتوایی که از ویژگی‌های span حذف شده می‌تواند از مسیر دیگری صادر شود. اگر نگهداری محتوای کامل ضروری است، جداکردن محل ذخیره و کنترل دسترسی آن از دادهٔ عملیاتی، مرز روشن‌تری برای استفاده از trace می‌سازد.

خطا و نمونه‌برداری را در زمان درست ثبت کنید

وقتی درخواست مدل یا اجرای ابزار شکست می‌خورد، ERROR و یک error.type پایدار و کم‌تنوع را روی span همان مرحله قرار دهید. وضعیت span عامل را از سرانجام کار تعیین کنید: خطای بازیابی‌شدهٔ ابزار نباید به‌تنهایی کل اجرا را شکست‌خورده نشان دهد. برای عملیات موفق، معمولاً می‌توان وضعیت را در حالت پیش‌فرضِ unset گذاشت؛ قطع‌شدن یک جریان نیز باید از خطای واقعی جدا تشخیص داده شود.

مشخصات Trace API در OpenTelemetry می‌گوید sampler فقط ویژگی‌هایی را می‌بیند که هنگام ساخت span حاضرند. پس اگر انتخاب نمونه به نام عملیات، عامل یا مدل وابسته است، این ویژگی‌ها را همان زمان ایجاد span بدهید. خطایی که بعداً رخ می‌دهد تصمیم آغازین نمونه‌برداری را عوض نمی‌کند؛ برای نگه‌داشتن traceهای خطادار پس از پایان اجرا، باید پردازشی انتخاب شود که پیش از تصمیم نهایی، trace را دریافت کرده باشد.

پیش از استقرار، با دادهٔ ساختگی یک اجرای موفق، یک خطای ابزارِ بازیابی‌شده و یک شکست نهایی تولید کنید. در دادهٔ صادرشده ببینید spanها زیر والد درست قرار گرفته‌اند، زمان مدل و ابزار با مرز واقعی کار هماهنگ است و محتوای پیام از مسیر دیگری نشت نمی‌کند. نسخهٔ ابزار instrumenter و نسخه یا بازنگری قرارداد معناییِ مبنای پیاده‌سازی را نیز کنار تنظیمات ثبت نگه دارید تا تغییر نام فیلدها در ارتقای بعدی با تغییر رفتار عامل اشتباه نشود.

بیشتر بخوانید:

• Langfuse یا Helicone؛ ردگیری عمیق در برابر نصب یک‌خطی
• خطای 429 را کورکورانه تکرار نکنید؛ SDK شاید خودش دوباره تلاش کند
• عامل Gemini وارد محیط کار شد؛ پاسخ‌دادن دیگر پایان کار نیست