مشاركة عبر


تكوين التتبع لأطر عمل وكلاء الذكاء الاصطناعي (معاينة)

مهم

العناصر التي تم وضع علامة عليها (إصدار أولي) في هذه المقالة موجودة حالياً في الإصدار الأولي العام. يتم توفير هذه المعاينة دون اتفاقية على مستوى الخدمة، ولا نوصي بها لأحمال عمل الإنتاج. بعض الميزات ربما لا تكون مدعمة أو بها بعض القدرات المقيدة. لمزيد من المعلومات، راجع شروط الاستخدام الإضافية لمعاينات مايكروسوفت Azure.

‏‫ملاحظة‬

التتبع متاح عادة لوكلاء الملاحقة فقط. الوكلاء المخصصون لسير العمل، والمستضافة، والوكلاء المخصصون في مرحلة المعاينة.

عندما يتصرف وكلاء الذكاء الاصطناعي بشكل غير متوقع في الإنتاج، يمنحك التتبع الرؤية لتحديد السبب الجذري بسرعة. يلتقط التتبع بيانات التليمترية التفصيلية—بما في ذلك استدعاءات نماذج اللغة الكبيرة (LLM)، واستدعاءات الأدوات، وتدفقات قرارات الوكلاء—بحيث يمكنك تصحيح المشكلات، ومراقبة التأخير، وفهم سلوك الوكلاء عبر الطلبات.

توفر Microsoft Foundry تكاملات تتبع لأطر عمل الوكلاء الشائعة التي تتطلب تغييرات طفيفة في الكود. في هذه المقالة، ستتعرف على كيفية:

  • تكوين التتبع التلقائي لإطار عمل Microsoft Agent
  • قم بإعداد متتبع langchain-azure-ai ل LangChain و LangGraph
  • أداة أداة تطوير تطوير اللعبة لOpenAI Agents باستخدام OpenTelemetry
  • تحقق من ظهور آثار في بوابة Foundry
  • استكشاف مشاكل التتبع الشائعة

المتطلبات المسبقه

  • مشروع Foundry مع تتبع متصل بAzure Monitor Application Insights.
  • مساهم أو دور أعلى في مورد Application Insights لاستيعاب الأثر.
  • Access إلى مورد Application Insights المتصل لعرض المسارات. بالنسبة للاستعلامات القائمة على السجل، قد تحتاج أيضا إلى access إلى مساحة عمل Log Analytics المرتبطة.
  • بايثون 3.10 أو أحدث (مطلوب لجميع عينات الكود في هذا المقال).
  • حزمة langchain-azure-ai إصدار 0.1.0 أو أحدثها (مطلوب لعينات LangChain وLangGraph).
  • إذا كنت تستخدم LangChain أو LangGraph، فستكون بيئة بايثون مع pip مثبت.

أكد أنك تستطيع عرض بيانات التليمترية

لعرض بيانات التتبع، تأكد من أن حسابك لديه access إلى مورد Application Insights المتصل بحسابك.

  1. في Azure portal، افتح مورد Application Insights المتصل ب project Foundry الخاص بك.

  2. اختر Access control (IAM).

  3. خصص دورا مناسبا لمستخدمك أو مجموعتك.

    إذا كنت تستخدم استعلامات قائمة على السجل، ابدأ بمنح دور قارئ تحليلات السجلات Log Analytics.

الأمان والخصوصية

يمكن للتتبع التقاط معلومات حساسة (على سبيل المثال، مدخلات المستخدم، ومخرجات النماذج، وأدوات الحجج والنتائج).

  • فعل تسجيل المحتوى أثناء التطوير والتصحيح لرؤية بيانات الطلبات والاستجابات الكاملة. تعطيل تسجيل المحتوى في بيئات الإنتاج لحماية البيانات الحساسة. في العينات الواردة في هذا المقال، يتم التحكم في تسجيل المحتوى بواسطة إعدادات مثل enable_content_recording و OTEL_RECORD_CONTENT.
  • لا تخزن الأسرار أو بيانات الاعتماد أو الرموز في المحفزات أو أدوات التوجيه.

لمزيد من الإرشادات، راجع الأمان والخصوصية.

‏‫ملاحظة‬

تتبع البيانات المخزنة في Application Insights تخضع لإعدادات الاحتفاظ بالبيانات في مساحة العمل الخاصة بك وتسعير Azure Monitor. لإدارة التكاليف، فكر في تعديل معدلات أخذ العينات أو فترات الاحتفاظ في الإنتاج. انظر Azure مراقبة التسعير و تكوين الاحتفاظ بالبيانات وأرشفتها.

تكوين التتبع لإطار عمل Microsoft Agent

يحتوي مايكروسوفت فاوندري على تكاملات أصلية مع كل من إطار عمل مايكروسوفت وكيل الآن. الوكلاء المبنيون بأي من الإطارين يصدرون تلقائيا تتبعات عند تفعيل التتبع في project Foundry الخاص بك—لا حاجة لكود أو حزم إضافية.

للتحقق من أن التتبع يعمل:

  1. افحص وكيلك مرة واحدة على الأقل.
  2. في بوابة المصنع، اذهب إلىمسارات>.
  3. تأكد من ظهور تتبع جديد مع فترات لعمليات وكيلك.

عادة ما تظهر الآثار خلال 2–5 دقائق بعد تنفيذ الوكيل. للتكوين المتقدم، راجع الوثائق الخاصة بإطار العمل:

تكوين التتبع لسلسلة LangChain وLangGraph

‏‫ملاحظة‬

يتوفر تكامل التتبع ل LangChain و LangGraph حاليا في Python فقط.

استخدم حزمة langchain-azure-ai لإصدار امتدادات متوافقة مع OpenTelemetry لعمليات LangChain وLangGraph. تظهر هذه الآثار في عرضآثار> في بوابة المصنع.

عينة: وكيل LangChain v1 مع تتبع الذكاء الاصطناعي Azure

استخدم هذه العينة من طرف إلى طرف لأداة لأداة لوكيل LangChain v1 (المعاينة) باستخدام langchain-azure-ai tracer. يقوم هذا المتتبع بتنفيذ أحدث قواعد الدلالة OpenTelemetry (OTel)، بحيث يمكنك عرض الآثار الغنية في عرض الملاحظة الخاص ب Foundry.

LangChain v1: تثبيت الحزم

pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich

LangChain v1: تكوين البيئة

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Azure مراقبة رؤى التطبيقات connection string للتتبع.
  • AZURE_OPENAI_ENDPOINT: رابط نقطة النهاية Azure OpenAI الخاص بك.
  • AZURE_OPENAI_CHAT_DEPLOYMENTاسم نشر نموذج الدردشة.:
  • AZURE_OPENAI_VERSIONإصدار واجهة برمجة التطبيقات، على سبيل المثال 2024-08-01-preview.
  • تقوم مجموعة تطوير البرمجيات بحل بيانات اعتماد Azure باستخدام DefaultAzureCredential، الذي يدعم متغيرات البيئة، والهوية المدارة، وتسجيل الدخول إلى VS Code.

تخزين هذه القيم في .env ملف للتطوير المحلي.

LangChain v1: إعداد التتبع

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

LangChain v1: إعداد النماذج (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
)

LangChain v1: تحديد الأدوات والمطالبة

from dataclasses import dataclass
from langchain_core.tools import tool

system_prompt = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""

# Mock user locations keyed by user id (string)
USER_LOCATION = {
    "1": "Florida",
    "2": "SF",
}

@dataclass
class UserContext:
    user_id: str

@tool
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

LangChain v1: استخدم سياق وقت التشغيل وحدد أداة معلومات المستخدم

from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig

@tool
def get_user_info(config: RunnableConfig) -> str:
    """Retrieve user information based on user ID."""
    runtime = get_runtime(UserContext)
    user_id = runtime.context.user_id
    return USER_LOCATION[user_id]

LangChain v1: إنشاء العامل

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass

@dataclass
class WeatherResponse:
    conditions: str
    punny_response: str

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    prompt=system_prompt,
    tools=[get_user_info, get_weather],
    response_format=WeatherResponse,
    checkpointer=checkpointer,
)

LangChain v1: تشغيل العامل باستخدام التتبع

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))

if __name__ == "__main__":
    main()

مع تفعيل langchain-azure-ai، تصدر جميع عمليات LangChain v1 (استدعاءات LLM، استدعاءات الأدوات، خطوات الوكيل) امتدادات OpenTelemetry باستخدام أحدث القواعد الدلالية. تظهر هذه الآثار في عرضآثار> في بوابة Foundry وترتبط بمورد Application Insights الخاص بك.

نصيحة

بعد تشغيل الوكيل، انتظر بضع دقائق حتى تظهر الآثار. إذا لم تر آثارا، تحقق من صحة connection string Application Insights وتحقق من قسم Mistake common issues.

تحقق من تتبع LangChain v1 الخاص بك

بعد تشغيل الوكيل:

  1. انتظر من 2 إلى 5 دقائق حتى تنتشر الآثار.
  2. في بوابة المصنع، اذهب إلىمسارات>.
  3. ابحث عن تتبع بالاسم الذي حددته (على سبيل المثال، "وكيل معلومات الطقس").
  4. وسع التتبع لرؤية امتدادات لاستدعاءات نماذج اللغة الكبيرة، استدعاءات الأدوات، وخطوات الوكيل.

إذا لم تر آثارا، تحقق من قسم استكشاف المشاكل الشائعة .

عينة: وكيل LangGraph مع تتبع Azure AI

تظهر هذه العينة وكيل LangGraph بسيط مزود ب langchain-azure-ai لإصدار مسارات متوافقة مع OpenTelemetry لخطوات الرسم البياني، واستدعاءات الأدوات، واستدعاءات النماذج.

LangGraph: تثبيت الحزم

pip install \
  langchain-azure-ai \
  langgraph>=1.0.0 \
  langchain>=1.0.0 \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: تكوين البيئة

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Azure مراقبة رؤى التطبيقات connection string للتتبع.
  • AZURE_OPENAI_ENDPOINT: رابط نقطة النهاية Azure OpenAI الخاص بك.
  • AZURE_OPENAI_CHAT_DEPLOYMENTاسم نشر نموذج الدردشة.:
  • AZURE_OPENAI_VERSIONإصدار واجهة برمجة التطبيقات، على سبيل المثال 2024-08-01-preview.

تخزين هذه القيم في .env ملف للتطوير المحلي.

إعداد متتبع LangGraph

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=os.getenv("OTEL_RECORD_CONTENT", "true").lower() == "true",
    name="Music Player Agent",
)

LangGraph: أدوات

from langchain_core.tools import tool

@tool
def play_song_on_spotify(song: str):
    """Play a song on Spotify"""
    # Integrate with Spotify API here.
    return f"Successfully played {song} on Spotify!"

@tool
def play_song_on_apple(song: str):
    """Play a song on Apple Music"""
    # Integrate with Apple Music API here.
    return f"Successfully played {song} on Apple Music!"

tools = [play_song_on_apple, play_song_on_spotify]

LangGraph: إعداد النموذج (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)

بناء سير عمل LangGraph

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver

tool_node = ToolNode(tools)

def should_continue(state: MessagesState):
    messages = state["messages"]
    last_message = messages[-1]
    return "continue" if getattr(last_message, "tool_calls", None) else "end"

def call_model(state: MessagesState):
    messages = state["messages"]
    response = model.invoke(messages)
    return {"messages": [response]}

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)

workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

LangGraph: تشغيل مع التتبع

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

مع تفعيل langchain-azure-ai، يصدر تنفيذ LangGraph امتدادات متوافقة مع OpenTelemetry لاستدعاءات النماذج، واستدعاءات الأدوات، وانتقالات الرسوم البيانية. تتدفق هذه الآثار إلى Application Insights وتظهر في عرضآثار> في بوابة Foundry.

نصيحة

كل عقدة رسم بياني وانتقال حافة يخلق امتدادا منفصلا، مما يسهل تصور تدفق قرارات الوكيل.

تحقق من مسارات LangGraph الخاصة بك

بعد تشغيل الوكيل:

  1. انتظر من 2 إلى 5 دقائق حتى تنتشر الآثار.
  2. في بوابة المصنع، اذهب إلىمسارات>.
  3. ابحث عن تتبع بالاسم الذي حددته (مثلا "وكيل مشغل الموسيقى").
  4. وسع التتبع لرؤية امتدادات لعقد الرسوم البيانية، واستدعاءات الأدوات، واستدعاءات النماذج.

إذا لم تر آثارا، تحقق من قسم استكشاف المشاكل الشائعة .

عينة: إعداد LangChain 0.3 مع تتبع Azure AI

يوضح هذا الإعداد البسيط كيفية تمكين تتبع الذكاء الاصطناعي Azure في تطبيق LangChain 0.3 باستخدام langchain-azure-ai tracer و AzureChatOpenAI.

LangChain 0.3: تثبيت الحزم

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv

LangChain 0.3: تكوين البيئة

  • APPLICATION_INSIGHTS_CONNECTION_STRING: رؤى التطبيقات connection string للتتبع. للعثور على هذه القيمة، افتح مورد Application Insights الخاص بك في Azure portal، واختر نظرة عامة، وانسخ Connection String.
  • AZURE_OPENAI_ENDPOINT: Azure رابط نقطة نهاية OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENTاسم نشر نموذج الدردشة.:
  • AZURE_OPENAI_VERSIONإصدار واجهة برمجة التطبيقات، على سبيل المثال 2024-08-01-preview.
  • AZURE_OPENAI_API_KEY: Azure مفتاح واجهة برمجة التطبيقات OpenAI.

‏‫ملاحظة‬

تستخدم هذه العينة مصادقة مفاتيح API للبساطة. بالنسبة لأعباء العمل الإنتاجية، استخدم DefaultAzureCredential مع get_bearer_token_provider كما هو موضح في عينات LangChain v1 و LangGraph.

LangChain 0.3: إعداد التتبع والنموذج

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Tracer: emits spans conforming to updated OTel spec
azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Trip Planner Orchestrator",
    id="trip_planner_orchestrator_v3",
)
tracers = [azure_tracer]

# Model: Azure OpenAI with callbacks for tracing
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
    callbacks=tracers,
)

قم بتوصيلها callbacks=[azure_tracer] بسلاسلك أو أدواتك أو وكلائك لضمان تتبع عمليات LangChain 0.3. بعد تشغيل سلسلة أو وكيلك، تظهر الآثار في عرضآثار> في بوابة Foundry خلال 2-5 دقائق.

تكوين التتبع لمجموعة تطوير البرمجيات لعملاء OpenAI

تدعم مجموعة تطوير الوسائط الخاصة ب OpenAI Agents أجهزة قياس OpenTelemetry. استخدم المقتطف التالي لتكوين التتبع والتصدير إلى Azure Monitor. إذا APPLICATION_INSIGHTS_CONNECTION_STRING لم يكن الأمر مضبوطا، يعود المصدر إلى وحدة التحكم للتصحيح المحلي.

قبل تشغيل العينة، قم بتركيب الحزم المطلوبة:

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter
import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Configure tracer provider + exporter
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)

conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
    from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
    provider.add_span_processor(
        BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
    )
else:
    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())

# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
    # ... run your agent here
    pass

تحقق من الآثار في بوابة Foundry

  1. تسجيل الدخول إلى Microsoft Foundry. تأكد من تفعيل مفتاح New Foundry . تشير هذه الخطوات إلى Foundry (جديد).
  2. تأكد من أن التتبع متصل بمشروعك project. إذا لزم الأمر، تابع تتبع الإعدادات في Microsoft Foundry.
  3. افحص وكيلك مرة واحدة على الأقل.
  4. في بوابة المصنع، اذهب إلىمسارات>.
  5. تأكد من ظهور تتبع جديد مع فترات لعمليات وكيلك.

عادة ما تظهر الآثار خلال 2–5 دقائق بعد تنفيذ الوكيل. إذا لم تظهر الآثار بعد هذه الفترة، راجع استكشاف الأخطاء الشائعة.

استكشاف الأخطاء الشائعة وإصلاحها

مشكلة السبب الحل
لا ترى آثارا في Foundry التتبع غير متصل، ولا توجد حركة مرور حديثة، أو تأخر الإدخال تأكد من اتصال Application Insights وتوليد حركة مرور جديدة، وتحديث بعد 2–5 دقائق.
أنت لا ترى امتدادات LangChain أو LangGraph استدعاءات تتبع النقاط غير مرتبطة بالجولة تأكد من أنك مررت جهاز التتبع callbacks (على سبيل المثال، config = {"callbacks": [azure_tracer]}) للجولة التي تريد تتبعها.
تظهر امتدادات LangChain لكن استدعاءات الأدوات مفقودة الأدوات ليست مرتبطة بالنموذج أو أن عقدة الأدوات غير مهيأة تحقق من تمرير الأدوات إلى bind_tools() النموذج وأن عقد الأدوات تضاف إلى الرسم البياني الخاص بك.
تظهر آثار لكنها غير مكتملة أو مفقودة تم تعطيل تسجيل المحتوى، أو أن بعض العمليات غير مزودة بالأدوات تفعيل enable_content_recording=True القياس الكامل. للعمليات المخصصة، أضف امتدادات يدوية باستخدام حزمة تطوير البرمجيات OpenTelemetry.
ترى أخطاء في التفويض عند الاستعلام عن التليمترية أذونات RBAC مفقودة في Application Insights أو تحليلات السجلات أكد access في Access control (IAM) للموارد المتصلة. بالنسبة لاستعلامات السجل، قم بتعيين دور قارئ تحليلات السجلات log.
يظهر المحتوى الحساس في الآثار يتم تفعيل تسجيل المحتوى وتشمل المطالبات أو أدوات الوسائط أو المخرجات بيانات حساسة قم بتعطيل تسجيل المحتوى في الإنتاج وحجب البيانات الحساسة قبل دخولها إلى التليمترية.

الخطوات التالية