قراردادهای معنایی OpenTelemetry برای هوش مصنوعی زایا

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

کارگروه ویژه هوش مصنوعی زایا در OpenTelemetry با معرفی قراردادهای معنایی استاندارد (Semantic Conventions)، این ناهماهنگی را حل کرده است. این استاندارد مشخص می‌کند که اسپن‌های فراخوانی مدل، اجرای ایجنت و استفاده از ابزارها با چه نام‌ها و ویژگی‌هایی ثبت شوند تا در پلتفرم‌هایی مثل Jaeger، Grafana Tempo یا Datadog به‌طور یکدست تحلیل‌پذیر باشند.

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

کارگروه ویژه‌ی هوش مصنوعی زایا در OpenTelemetry (راه‌اندازی‌شده در آوریل 2024) اسکیمای استاندارد دورسنجی ایجنت‌ها را تعریف می‌کند. همگرا شدن نام اسپن‌ها، ویژگی‌ها (attributes) و قواعد ثبت محتوا (Content Capture) در میان ارائه‌دهندگان مختلف باعث می‌شود ردگیری محاسبات (trace) ایجنت در Datadog، Grafana، Jaeger و Honeycomb معنای یکسانی داشته باشد.

اهداف یادگیری

• نام بردن دسته‌بندی‌های اسپن GenAI: مدل/کلاینت، ایجنت، ابزار.
• تشخیص اسپن‌های invoke_agent از نوع CLIENT در برابر INTERNAL و زمان کاربرد هرکدام.
• فهرست کردن ویژگی‌های سطح بالای GenAI: نام ارائه‌دهنده، مدل درخواستی، شناسه‌ی منبع داده.
• توضیح سازوکار ثبت محتوا: اختیاری بودن (opt-in)، متغیر OTEL_SEMCONV_STABILITY_OPT_IN و توصیه‌ی استفاده از ارجاع خارجی.

صورت مسئله

هر ارائه‌دهنده‌ای نام‌های دلخواه خودش را برای اسپن‌ها ابداع می‌کند. در نتیجه، تیم‌های عملیات مجبور می‌شوند برای هر فریم‌ورک داشبوردهای جداگانه بسازند. کارگروه ویژه‌ی GenAI در OpenTelemetry با تعریف استانداردی واحد برای کل اکوسیستم، این مشکل را حل می‌کند.

مفاهیم پایه

دسته‌بندی‌های اسپن

1. اسپن‌های مدل / کلاینت. فراخوانی‌های خام مدل‌های زبانی بزرگ (LLM) را پوشش می‌دهند. این اسپن‌ها را SDKهای ارائه‌دهندگان (Anthropic، OpenAI، Bedrock) و تطبیق‌دهنده‌های (adapters) مدل در فریم‌ورک‌ها صادر می‌کنند.
2. اسپن‌های ایجنت. شامل create_agent (هنگام ساخت ایجنت) و invoke_agent (هنگام اجرای آن).
3. اسپن‌های ابزار. یک اسپن به‌ازای هر فراخوانی ابزار، که با رابطه‌ی والد-فرزندی به اسپن ایجنت متصل می‌شود.

نام‌گذاری اسپن‌های ایجنت

• نام اسپن: در صورت وجود نام، invoke_agent {gen_ai.agent.name}؛ وگرنه fallback به invoke_agent.
• نوع اسپن (Span Kind):
  • CLIENT — برای سرویس‌های ایجنت راه‌دور (OpenAI Assistants API، Bedrock Agents).
  • INTERNAL — برای فریم‌ورک‌های ایجنت درون‌فرآیندی (LangChain، CrewAI، حلقه‌ی محلی ReAct).

ویژگی‌های کلیدی

• gen_ai.provider.name — مقادیر anthropic، openai، aws.bedrock، google.vertex.
• gen_ai.request.model — شناسه‌ی مدل.
• gen_ai.response.model — مدل نهاییِ پاسخ‌دهنده (ممکن است به دلیل مسیریابی با مدل درخواستی تفاوت داشته باشد).
• gen_ai.agent.name — شناسه‌ی ایجنت.
• gen_ai.operation.name — مقادیر chat، completion، invoke_agent، tool_call.
• gen_ai.data_source.id — در RAG: مشخص می‌کند به کدام پایگاه داده یا مخزن متن مراجعه شده است.

قراردادهای معنایی اختصاصی نیز برای فنّاوری‌های Anthropic، Azure AI Inference، AWS Bedrock و OpenAI وجود دارد.

ثبت محتوا

قاعده‌ی پیش‌فرض: کدهای ابزار دقیق (instrumentation) نباید ورودی‌ها/خروجی‌ها را به‌طور پیش‌فرض ثبت کنند. ثبت محتوا کاملاً اختیاری است و از طریق این ویژگی‌ها انجام می‌شود:

• gen_ai.system_instructions
• gen_ai.input.messages
• gen_ai.output.messages

الگوی توصیه‌شده برای محیط پروداکشن: محتوا را در جایی خارج از این سیستم ذخیره کنید (مثل S3 یا مخزن لاگ‌های خودتان) و فقط شناسه‌های ارجاع را روی اسپن‌ها بیاورید (شناسه‌های اشاره‌گر، نه متن کامل پیام‌ها). این رویکرد در واقع همان سازوکار دفاعی در برابر آلوده‌سازی محتوا در درس 27 است که این بار درون سامانه‌ی مشاهده‌پذیری به کار می‌رود.

پایداری

بیشتر قراردادهای معنایی تا مارس 2026 در وضعیت آزمایشی (experimental) هستند. برای فعال‌سازی پیش‌نمایش پایدار، این متغیر را مقداردهی کنید:

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

سامانه‌ی Datadog نسخه 1.37 به بالا ویژگی‌های GenAI را به‌صورت بومی روی اسکیمای LLM Observability خود نگاشت می‌کند. سایر بک‌اندها (Grafana، Honeycomb، Jaeger) نیز از ویژگی‌های خام پشتیبانی می‌کنند.

جاهایی که این الگو به خطا می‌رود

• ثبت پرامپت‌های کامل درون اسپن‌ها. نشت اطلاعات هویتی حساس (PII)، کلیدهای محرمانه و داده‌های مشتری درون ردگیری‌ها، به‌طوری که تیم عملیات بتواند آن‌ها را بخواند. داده‌ها را در مخزن خارجی ذخیره کنید.
• ننوشتن gen_ai.provider.name. در صورت نبود انتساب مناسب، داشبوردهای چندارائه‌دهنده‌ای مختل می‌شوند.
• اسپن‌های بدون پیوند به والد. رها شدن اسپن‌های ابزار به‌صورت یتیم (orphan). همیشه کانتکست را منتقل کنید.
• تنظیم نکردن متغیر اختیاری‌سازی پایداری (stability opt-in). ممکن است هنگام ارتقای بک‌اند، نام ویژگی‌های شما تغییر کند.

پیاده‌سازی از صفر

فایل code/main.py یک صادرکننده‌ی اسپن را با کتابخانه‌ی استاندارد پیاده می‌کند که با قراردادهای معنایی GenAI همخوانی دارد:

• ساختار Span همراه با اسکیمای ویژگی‌های GenAI.
• ساختار Tracer با متد start_span و کانتکست‌های تودرتو.
• سناریوی اجرای اسکریپتی ایجنت که این موارد را صادر می‌کند: create_agent، invoke_agent (از نوع INTERNAL)، اسپن‌های مجزا برای هر ابزار، و اسپن‌های chat برای فراخوانی‌های LLM.
• حالت ثبت محتوا که پرامپت‌ها را در مخزنی خارجی ذخیره می‌کند و شناسه‌ها را روی اسپن‌ها قرار می‌دهد.

اجرای برنامه:

python3 code/main.py

خروجی: درخت اسپن‌ها همراه با تمام ویژگی‌های الزامی GenAI، به‌اضافه‌ی یک «مخزن خارجی» که ارجاعات محتوای ثبت‌شده را نشان می‌دهد.

استفاده از ابزارهای واقعی

• Datadog LLM Observability (نسخه 1.37 به بالا) ویژگی‌ها را به‌طور بومی نگاشت می‌کند.
• Langfuse / Phoenix / Opik (درس 24) — ابزار دقیق‌سازی خودکار در کل اکوسیستم.
• Jaeger / Honeycomb / Grafana Tempo — ردگیری‌های خام OTel؛ ساخت داشبورد با استفاده از ویژگی‌های GenAI.
• سرویس میزبانی شخصی (Self-hosted) — اجرای OTel Collector همراه با پردازنده‌ی GenAI.

خروجی این درس

فایل outputs/skill-otel-genai.md اسپن‌های OTel GenAI را همراه با پیش‌فرض‌های ثبت محتوا و ذخیره‌سازی ارجاعات خارجی به یک ایجنت موجود متصل می‌کند.

تمرین‌ها

1. حلقه‌ی ReAct درس 01 را با اسپن invoke_agent (از نوع INTERNAL) و اسپن‌های اختصاصی هر ابزار مجهز کنید و خروجی را به یک نمونه‌ی Jaeger بفرستید.
2. ثبت محتوا را در حالت «فقط ارجاع» پیاده کنید: پرامپت‌ها درون SQLite ذخیره شوند و ویژگی‌های اسپن تنها شناسه‌ی ردیف‌ها (row IDs) را نگه دارند.
3. مشخصات فنی gen_ai.data_source.id را بخوانید و آن را به جستجوی Mem0 در درس 09 وصل کنید.
4. متغیر محیطی OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental را تنظیم کنید و مطمئن شوید کلکتور نام ویژگی‌های شما را تغییر نمی‌دهد.
5. یک داشبورد بسازید که صرفاً با ویژگی‌های GenAI مشخص کند: «خطاهای هر ابزار با کدام مدل‌ها همبستگی دارد».

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• قراردادهای معنایی OpenTelemetry GenAI — مستندات استاندارد
• OpenAI Agents SDK — تولید اسپن‌های GenAI به‌صورت پیش‌فرض
• AutoGen v0.4 محصول Microsoft Research — اسپن‌های OTel توکار
• Claude Agent SDK — انتقال کانتکست ردگیری محاسبات بر اساس استاندارد W3C