Поделиться через


Трассировка и наблюдение за агентами ИИ в Microsoft Foundry (предварительная версия)

Замечание

Этот документ относится к порталу Microsoft Foundry (классическая модель).

🔍 Ознакомьтесь с документацией по Microsoft Foundry (новая), чтобы узнать о новом портале.

Это важно

Элементы, обозначенные в этой статье как (предварительная версия), сейчас предлагаются в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.

В этой статье вы узнаете, как:

  • Основные понятия трассировки ключей.
  • Отслеживание и наблюдение за агентами ИИ на платформе Foundry.
  • Изучите новые семантические соглашения с многопользовательской наблюдаемостью.
  • Интеграция с популярными фреймворками агентов.
  • Просмотр трассировок в портале Foundry и Azure Monitor.
  • Просмотр потоков агента на игровой площадке Агентов.

Определение причин выполнения агента важно для устранения неполадок и отладки. Тем не менее, это может быть трудно для сложных агентов по многим причинам:

  • Существует большое количество шагов, связанных с созданием ответа, что затрудняет отслеживание всех из них.
  • Последовательность шагов может отличаться в зависимости от входных данных пользователя.
  • Входные данные и выходные данные на каждом этапе могут быть длинными и заслуживают более подробной проверки.
  • Каждый шаг среды выполнения агента также может включать вложение. Например, агент может вызвать средство, которое использует другой процесс, который затем вызывает другое средство. Если вы заметите странные или неправильные выходные данные из запуска агента верхнего уровня, может быть трудно определить, где именно в выполнении возникла проблема.

Результаты трассировки решают эту проблему, позволяя просматривать входные и выходные данные каждого примитива, связанного с определенным запуском агента. Результаты отображаются в порядке вызова примитивов, что упрощает понимание и отладку поведения агента ИИ.

Общие сведения о ключевых понятиях трассировки

Ниже приведен краткий обзор ключевых понятий перед началом работы:

Основные понятия Описание
Следы Трассировки фиксируют прохождение запроса или рабочего процесса в вашем приложении посредством записи событий и изменений состояния, таких как вызовы функций, значения и системные события. См. статью "Трассировка OpenTelemetry".
Диапазоны Диапазоны — это основные компоненты трассировок, обозначающие отдельные операции внутри трассы. Каждый диапазон фиксирует время начала и окончания, атрибуты и может быть вложен для отображения иерархических связей. Вы можете увидеть полный стек вызовов и последовательность операций.
Атрибуты Атрибуты — это пары "ключ-значение", присоединенные к трассировкам и диапазонам. Они предоставляют контекстные метаданные, такие как параметры функции, возвращаемые значения или пользовательские заметки. Это обогащают данные трассировки, делая их более информативными и полезными для анализа.
Семантические соглашения OpenTelemetry определяет семантические соглашения для стандартизации имен и форматов для атрибутов данных трассировки. Эти соглашения упрощают интерпретацию и анализ данных на разных платформах и средствах. Дополнительные сведения см. в семантических соглашениях OpenTelemetry.
Экспортеры трассировки Экспортеры трассировки отправляют данные трассировки в серверные системы для хранения и анализа. Azure AI поддерживает экспорт трассировок в Azure Monitor и другие платформы, совместимые с OpenTelemetry, что обеспечивает интеграцию с различными средствами наблюдения.

Лучшие практики

  • Используйте согласованные атрибуты диапазона.
  • Сопоставляйте идентификаторы выполнения оценки для анализа качества и производительности.
  • Редактировать чувствительное содержимое. Избегайте хранения секретов в атрибутах.

Расширение OpenTelemetry с возможностью наблюдения с несколькими агентами

Корпорация Майкрософт повышает мультиагентную наблюдаемость путем внедрения новых семантических соглашений в OpenTelemetry, разработанных совместно с Outshift, обработчиком инкубации Cisco. Эти дополнения, основанные на OpenTelemetry и контексте трассировки W3C, устанавливают стандартные методики трассировки и телеметрии в системах с несколькими агентами. Они упрощают согласованное ведение журнала ключевых метрик для качества, производительности, безопасности и стоимости. Этот системный подход обеспечивает более полную видимость рабочих процессов с несколькими агентами, включая вызовы инструментов и совместную работу. Корпорация Майкрософт интегрирует эти улучшения в Microsoft Foundry, Microsoft Agent Framework, семантические ядра и пакеты ИИ Azure для LangChain, LangGraph и пакета SDK для агентов OpenAI. С помощью Foundry клиенты могут получить унифицированную наблюдаемость для агентических систем, созданных с помощью любой из этих платформ. Узнайте больше об интеграциях трассировки.

Тип Контекст или родительский диапазон Имя/Атрибут/Событие Цель
Пядь выполнить_задачу Записывает планирование задач и распространение событий, предоставляя аналитические сведения о том, как задачи декомпоируются и распределяются.
Дочерний диапазон вызов_агента взаимодействие_агента_с_агентом Трассирует взаимодействие между агентами.
Дочерний диапазон вызов_агента agent.state.management Эффективное использование контекста, кратковременное или долгосрочное управление памятью.
Дочерний диапазон вызов_агента планирование агента Регистрирует внутренние шаги планирования агента.
Дочерний диапазон вызов_агента оркестрация агента Осуществляет оркестрацию между агентами.
Свойство вызов_агента определения инструментов Описывает назначение или конфигурацию средства.
Свойство вызов_агента llm_spans Записывает диапазоны вызовов модели.
Свойство выполнить_инструмент tool.call.arguments Регистрирует аргументы, передаваемые во время вызова средства.
Свойство выполнить_инструмент инструмент.вызов.результаты Записывает результаты, возвращаемые средством.
Event Оценка (имя, тип_ошибки, метка) Включает структурированную оценку производительности агента и принятия решений.

Настройка трассировки в пакете SDK для Microsoft Foundry

Для завершения чата или создания агентов с помощью Foundry установите:

pip install azure-ai-projects azure-identity

Чтобы включить трассировку, установите следующие библиотеки инструментирования:

pip install azure-monitor-opentelemetry opentelemetry-sdk

Чтобы просмотреть трассировки в Foundry, подключите ресурс Application Insights к проекту Foundry.

  1. Перейдите к Прослеживание в левой панели навигации портала Foundry.
  2. Создайте ресурс Application Insights, если у вас еще нет ресурса.
  3. Подключите ресурс к проекту Foundry.

Инструментирование трассировки в коде

Чтобы отслеживать содержимое сообщений чата, задайте AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED для переменной среды значение true (без учета регистра). Это содержимое может содержать персональные данные. Дополнительные сведения см. в библиотеке клиента OpenTelemetry для трассировки Azure Core на Python.

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default

Начнем инструментирование нашего агента с помощью трассировки OpenTelemetry, начиная с проверки подлинности и подключения к проекту ИИ Azure с AIProjectClient.

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

Затем получите строку подключения из ресурса Application Insights, подключенного к проекту, и настройте экспортеров OTLP для отправки данных телеметрии в Azure Monitor.

from azure.monitor.opentelemetry import configure_azure_monitor

connection_string = project_client.telemetry.get_application_insights_connection_string()
configure_azure_monitor(connection_string=connection_string) #enable telemetry collection

Теперь трассируйте код, где вы создаете и выполняете сообщение агента и пользователя в проекте ИИ Azure, чтобы просмотреть подробные инструкции по устранению неполадок или мониторингу.

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

После запуска агента можно начать просмотр трассировок на портале Foundry.

Логи записываются локально

Чтобы подключиться к панели мониторинга Aspire или другой серверной части, совместимой с OpenTelemetry, установите экспортер Протокола OpenTelemetry (OTLP). С помощью этого экспортера можно вывести трассировки в консоль или использовать локальное средство просмотра, например панель мониторинга Aspire.

pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk

Затем настройте трассировку для выходных данных консоли:

from azure.core.settings import settings
settings.tracing_implementation = "opentelemetry"

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# Setup tracing to console
span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

Или измените предыдущий код на основе Aspire Dashboard, чтобы осуществить трассировку в локальном средстве просмотра OTLP.

Теперь включите инструментирование агента и запустите агент:

from azure.ai.agents.telemetry import AIAgentsInstrumentor
AIAgentsInstrumentor().instrument()

# Start tracing
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

Альтернатива: набор средств ИИ для VS Code

AI Toolkit предоставляет простой способ для локальной трассировки в VS Code. Он использует локальный сборщик, совместимый с OTLP, что делает его идеальным для разработки и отладки.

Набор средств поддерживает платформы ИИ, такие как Служба агентов Foundry, OpenAI, Anthropic и LangChain через OpenTelemetry. Трассировки можно мгновенно увидеть в VS Code без необходимости доступа к облаку.

Подробные инструкции по настройке и примеры кода, относящиеся к пакету SDK, см. в разделе «Трассировка» в инструментарии ИИ.

Трассировка пользовательских функций

Чтобы отслеживать пользовательские функции, используйте пакет SDK OpenTelemetry для инструментирования кода.

  1. Настройка поставщика трассировки: инициализация поставщика трассировки для управления и создания диапазонов.
  2. Создание интервалов: оберните код, который нужно трассировать, с помощью интервалов. Каждый диапазон представляет единицу работы, и можно вложить диапазоны для формирования дерева трассировки.
  3. Добавление атрибутов: обогащение диапазонов атрибутами для предоставления дополнительных контекстов для данных трассировки.
  4. Настройка экспортера: отправка данных трассировки в серверную часть для анализа и визуализации.

Ниже приведен пример трассировки пользовательской функции:

from opentelemetry import trace
from opentelemetry.trace import SpanKind

# Initialize tracer
tracer = trace.get_tracer(__name__)

def custom_function():
    with tracer.start_as_current_span("custom_function") as span:
        span.set_attribute("custom_attribute", "value")
        # Your function logic here
        print("Executing custom function")

custom_function()

Подробные инструкции и расширенное использование см. в документации по OpenTelemetry.

Присоединение отзывов пользователей к трассировкам

Чтобы присоединить отзывы пользователей к трассировкам и визуализировать их на портале Foundry, настройте приложение для включения отслеживания и регистрации обратной связи от пользователей, используя семантические соглашения OpenTelemetry.

Коррелируя трассировки отзывов с соответствующими трассировками запросов чата с помощью идентификатора ответа или идентификатора потока, вы можете просматривать эти трассировки и управлять ими на портале Foundry. Спецификация OpenTelemetry позволяет стандартизировать и обогащенные данные трассировки, которые можно проанализировать на портале Foundry для оптимизации производительности и аналитики взаимодействия с пользователем. Этот подход помогает использовать полную мощность OpenTelemetry для повышения наблюдаемости в приложениях.

Чтобы оставить отзыв пользователей, выполните следующий формат:

Событие оценки отзывов пользователей фиксируется только в том случае, если пользователь предоставляет реакцию на ответ модели GenAI. Сделайте это событие родительским для отрезка GenAI, описывающего такой ответ, по возможности.

Текст события обратной связи пользователя имеет следующую структуру:

Поле тела Тип Описание Примеры Уровень требования
comment струна Дополнительные сведения о отзыве пользователя "I did not like it" Opt-in

Использование имени службы в данных трассировки

Чтобы идентифицировать вашу службу с помощью уникального идентификатора в Application Insights, используйте свойство имени службы OpenTelemetry в ваших данных трассировки. Это свойство полезно, если вы регистрируете данные из нескольких приложений в один ресурс Application Insights и хотите различать их.

Например, предположим, что у вас есть два приложения: App-1 и App-2, с трассировкой, настроенной для записи данных в один ресурс Application Insights. Возможно, вы хотите настроить App-1 для непрерывной оценки релевантности и App-2 для непрерывной оценки по релевантности. Вы можете использовать имя службы для фильтрации по Application, когда мониторите свое приложение на портале Foundry.

Чтобы настроить свойство имени службы, добавьте его непосредственно в код приложения согласно шагам, описанным в разделе "Использование нескольких поставщиков трассировки с разными ресурсами". Кроме того, задайте переменную OTEL_SERVICE_NAME среды перед развертыванием приложения. Дополнительные сведения о работе с именем службы см. в статье OTEL Environment Variables and Service Resource Semantic Conventions.

Чтобы запросить данные трассировки для заданного имени службы, выполните запрос к свойству cloud_roleName .

| where cloud_RoleName == "service_name"

Integrations

Foundry упрощает логирование трассировок с минимальными изменениями благодаря интеграции с Microsoft Agent Framework, Semantic Kernel, LangChain, LangGraph и OpenAI Agent SDK.

Агенты трассировки, созданные на базе Microsoft Agent Framework и Semantic Kernel

Foundry имеет собственные интеграции с Microsoft Agent Framework и Semantic Kernel. Агенты, созданные на этих двух платформах, получают готовую к использованию трассировку в системе Наблюдаемость.

  • Дополнительные сведения о трассировке и наблюдаемости в семантическом ядре и Microsoft Agent Framework.

Включение трассировки для агентов, созданных на основе LangChain и LangGraph

Замечание

Интеграция трассировки для LangChain и LangGraph, описанная здесь, доступна только в Python.

Вы можете включить трассировку для LangChain, которая соответствует стандартам OpenTelemetry, используя opentelemetry-инструментирование-langchain.

После установки необходимых пакетов можно легко внедрить трассировку в ваш код.

Замечание

Выпуски LangChain и LangGraph версии 1 в настоящее время находятся в активной разработке. Поведение поверхности API и трассировки может измениться в рамках этого выпуска. Отслеживайте обновления на странице заметок о выпуске LangChain версии 1.0.

Пример: агент LangChain версии 1 с трассировкой ИИ Azure

Используйте этот пример "от начала до конца" для инструментирования агента LangChain версии 1 с помощью трассировщика langchain-azure-ai. Он реализует последнюю спецификацию OpenTelemetry (OTel), чтобы вы могли просматривать насыщенные трассировки в системах наблюдаемости.

Установка пакетов
pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich
Настройка среды
  • APPLICATION_INSIGHTS_CONNECTION_STRING: строка подключения Azure Monitor Application Insights для трассировки.
  • AZURE_OPENAI_ENDPOINT: URL-адрес конечной точки Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: название развертывания модели чата.
  • AZURE_OPENAI_VERSION: версия API, например 2024-08-01-preview.
  • Учетные данные Azure определяются посредством DefaultAzureCredential (поддерживаются переменные окружения, управляемое удостоверение, вход в VS Code и многое другое).

Эти значения можно хранить в файле для локальной .env разработки.

Настройка трассировки
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]
Настройка модели (Azure OpenAI)
import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://cognitiveservices.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,
)
Определение инструментов и подсказки
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}!"
Использование контекста среды выполнения и определение средства сведений о пользователе
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]
Создать агента
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,
)
Запуск агента с трассировкой
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 версии 1 (вызовы LLM, вызовы инструментов, шаги агента) трассируются с помощью последних соглашений семантики OpenTelemetry. Они отображаются в разделе 'Наблюдаемость', связаны с вашим ресурсом Application Insights.

Пример: агент LangGraph с трассировкой ИИ Azure

В этом примере показан простой агент LangGraph, инструментированный с помощью langchain-azure-ai для выдачи трассировок, соответствующих стандартам OpenTelemetry, для шагов графа, вызовов инструментов и вызовов моделей.

Установка пакетов
pip install \
  langchain-azure-ai \
  langgraph==1.0.0a4 \
  langchain==1.0.0a10 \
  langchain-openai \
  azure-identity \
  python-dotenv
Настройка среды
  • APPLICATION_INSIGHTS_CONNECTION_STRING: строка подключения Azure Monitor Application Insights для трассировки.
  • AZURE_OPENAI_ENDPOINT: URL-адрес конечной точки Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: название развертывания модели чата.
  • AZURE_OPENAI_VERSION: версия API, например 2024-08-01-preview.

Эти значения можно хранить в файле для локальной .env разработки.

Настройка трассировки
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",
)
Tools
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]
Настройка модели (Azure OpenAI)
import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://cognitiveservices.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)
Запуск с трассировкой
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 и отображаются в системе наблюдаемости.

Пример: настройка LangChain 0.3 с трассировкой Azure AI

Эта минимальная настройка показывает, как включить трассировку ИИ Azure в приложении LangChain 0.3 с помощью трассировщика langchain-azure-ai и AzureChatOpenAI.

Установка пакетов
pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv
Настройка среды
  • APPLICATION_INSIGHTS_CONNECTION_STRING: строка подключения Application Insights для трассировки.
  • AZURE_OPENAI_ENDPOINT: URL-адрес конечной точки Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: имя развертывания модели чата.
  • AZURE_OPENAI_VERSION: версия API, например 2024-08-01-preview.
  • AZURE_OPENAI_API_KEY: ключ API OpenAI Для Azure.
Настройка трассировщика и модели
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 в Observability.

Включение трассировки для агентов, созданных на основе пакета SDK для агентов OpenAI

Используйте этот фрагмент кода для настройки трассировки OpenTelemetry для пакета SDK для агентов OpenAI и инструментирования платформы. Он экспортируется в Azure Monitor, если APPLICATION_INSIGHTS_CONNECTION_STRING задан; в противном случае он возвращается в консоль.

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

В проекте перейдите в раздел "Трассировка", чтобы отфильтровать трассировки по вашему усмотрению.

Выбрав трассировку, вы можете выполнить шаги по каждому диапазону и определить проблемы при наблюдении за реагированием приложения. Этот процесс помогает отлаживать и выявлять проблемы в вашем приложении.

Просмотр трассировок в Azure Monitor

Если вы зарегистрировали трассировки с помощью предыдущего фрагмента кода, вы готовы к просмотру трассировок в Azure Monitor Application Insights. Вы можете открыть Application Insights из источника данных manage и использовать комплексное представление сведений о транзакциях для дальнейшего изучения.

Дополнительные сведения о отправке трассировок вывода ИИ Azure в Azure Monitor и создании ресурса Azure Monitor см. в документации по Azure Monitor OpenTelemetry.

Просмотр результатов потока на игровой площадке Агентов Foundry

Платформа агентов на портале Foundry позволяет просматривать результаты для потоков и запусков, создаваемых агентами. Чтобы увидеть результаты потока, выберите журналы потоков в активном потоке. Кроме того, можно выбрать метрики , чтобы включить автоматическую оценку производительности модели в нескольких измерениях качества ИИ и риска и безопасности.

Замечание

Как описано в разделе "Доверие и наблюдаемость" на странице цен, за оценку на тестовой площадке взимается плата. Результаты доступны в течение 24 часов до истечения срока действия. Чтобы получить результаты оценки, выберите нужные метрики и общаться с агентом.

  • Оценки недоступны в следующих регионах.
    • australiaeast
    • japaneast
    • southindia
    • uksouth

Снимок экрана: игровая площадка агента на портале Foundry.

После выбора журналов потоков проверьте:

  • Сведения о потоке
  • Сведения о запуске
  • Упорядоченные шаги выполнения и вызовы инструментов
  • Входные и выходные данные между пользователем и агентом
  • Связанные метрики оценки (если включено)

Снимок экрана трассировки.

Подсказка

Если вы хотите просмотреть результаты потока из предыдущего потока, выберите "Мои потоки " на экране "Агенты ". Выберите тему и нажмите Попробовать на игровой площадке. Снимок экрана: экран потоков. В верхней части экрана можно увидеть кнопку "Журналы потоков" , чтобы просмотреть результаты трассировки.

Замечание

Платежи за функции наблюдаемости, такие как оценка рисков и безопасности, выставляются на основе потребления, как указано на странице цен Azure.