سؤال مصاحبه

کدام اسپن‌های ایجنت از نوع CLIENT و کدام INTERNAL هستند؟

Which agent spans are CLIENT and which are INTERNAL

  • سطح ۱: غربالگری
  • مفهومی
  • ۵ دقیقه

ردگیری محاسبات (tracing) را به یک ایجنت اضافه می‌کنید. این ایجنت در یک بار اجرا، دو بار API یک مدل را صدا می‌زند، دو ابزار را درون فرایند (process) خودش اجرا می‌کند و یک درخواست هم برای سرور ابزار روی ماشینی دیگر می‌فرستد. کدام‌یک از این عملیات اسپن (span) از نوع CLIENT می‌گیرند، کدام اسپن INTERNAL دریافت می‌کنند و اصلاً چرا باید به این موضوع اهمیت داد؟

اول خودتان جواب بدهید، بعد پاسخ را باز کنید.

پاسخ کوتاه

هر فراخوانی که از فرایند خارج شود، اسپن CLIENT می‌گیرد: یعنی دو فراخوانی API مدل و درخواست ارسالی به سرور ابزار راه‌دور. گام‌های حلقه‌ی ایجنت (agent loop) و ابزاری که داخل فرایند خودتان اجرا می‌شود، اسپن‌های INTERNAL می‌گیرند. این نوع اسپن، جهت هر فراخوانی را به بک‌اند اعلام می‌کند تا بتواند نشان دهد کدام عملیات از فرایند خارج شده‌اند و کدام داخل آن مانده‌اند.

پاسخ کامل

درخت اسپن‌ها برای این اجرا

invoke_agent            INTERNAL
 ├── chat               CLIENT
 ├── execute_tool       INTERNAL
 │    └── remote call   CLIENT
 ├── execute_tool       INTERNAL
 └── chat               CLIENT

همه‌ی اسپن‌ها شناسه‌ی ردگیری (trace ID) مشترکی دارند. هر اسپن فرزند، شناسه‌ی والد خود را به همراه دارد. همین نکته باعث می‌شود این اجرا به‌جای شش رکورد مجزا، به یک درخت واحد تبدیل شود.

قاعده کلی

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

مشخصه‌های مربوط به هر نوع اسپن

اسپن مشخصه‌ها (Attributes)
فراخوانی مدل gen_ai.operation.name، gen_ai.provider.name، gen_ai.request.model، gen_ai.response.model، gen_ai.usage.input_tokens، gen_ai.usage.output_tokens، gen_ai.response.id
فراخوانی ابزار gen_ai.tool.name، gen_ai.tool.call.id
اجرای ایجنت gen_ai.agent.name، gen_ai.agent.id

چرا این موضوع اهمیت دارد؟

بک‌اندها نمودار آبشاری (waterfall) را بر اساس همین نوع اسپن‌ها و پیوندهای والد رسم می‌کنند. اسپن CLIENT بدون شناسه‌ی پاسخ (response id) را نمی‌توان با لاگ ارائه‌دهنده تطبیق داد. اسپن ابزارِ بدون والد هم یتیم (orphan) می‌شود و دیگر نمی‌توان فهمید کدام گام ایجنت باعث فراخوانی آن شده است.

سؤال‌های تکمیلی مصاحبه‌گر
  • سطح 1: چه چیزی اسپن‌ها را به یک درخت واحد پیوند می‌دهد؟ پاسخ مورد انتظار: یک شناسه‌ی ردگیری مشترک و شناسه‌ی اسپن والد روی هر فرزند.
  • سطح 2: ایجنت به‌جای سرویس محلی، یک سرویس ایجنت میزبانی‌شده را صدا می‌زند. نوع این اسپن چیست؟ پاسخ مورد انتظار: CLIENT، چون ایجنت در فرایند دیگری اجرا می‌شود.
  • سطح 2: کدام مشخصه به داشبورد اجازه می‌دهد هزینه‌ها را بر اساس ارائه‌دهنده تفکیک کند؟ پاسخ مورد انتظار: gen_ai.provider.name؛ داشبوردهای چندارائه‌دهنده‌ای در صورت نبود آن کار نمی‌کنند.
  • سطح 3: یک زیرایجنت درون همان فرایند اجرا می‌شود. آیا ردگیری محاسبات جدیدی شروع می‌کند؟ پاسخ مورد انتظار: خیر. این اسپن به‌صورت فرزند زیر اسپن ایجنت والد قرار می‌گیرد، بنابراین کل اجرا در یک ردگیری محاسبات باقی می‌ماند.
جواب‌های اشتباهی که مصاحبه‌گرها زیاد می‌شنوند
  • «هر فراخوانی ابزار یک اسپن CLIENT است.» ابزاری که داخل فرایند شما اجرا می‌شود INTERNAL است. فقط فراخوانی خارج از فرایند CLIENT محسوب می‌شود.
  • «نوع اسپن صرفاً جنبه‌ی تزیینی دارد.» بک‌اندها نوع اسپن را برای نشان‌دادن جهت فراخوانی می‌خوانند و استانداردها آن را برای هر دسته‌بندی اسپن تعیین کرده‌اند.
  • «برای ایزوله‌سازی، به ازای هر فراخوانی ابزار یک ردگیری محاسبات جدید بسازید.» ردگیری‌های جداگانه پیوند والد را از دست می‌دهند و دیگر نمی‌توانید ببینید کدام گام باعث اجرای آن فراخوانی شده است.

کجای دوره آموزش داده می‌شود

درس OpenTelemetry GenAI سلسله‌مراتب اسپن‌ها را رسم می‌کند و درس قراردادها دسته‌بندی اسپن‌ها و نوع آن‌ها را نام می‌برد.