Настройка трассировки в Microsoft Foundry

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

Рекомендуемая отправная точка — это трассировка на стороне сервера. Foundry включает его автоматически после подключения ресурса Application Insights к проекту. Изменения в коде не требуются, и трассировки доступны уже через несколько минут после активации. Серверная трассировка работает для любого агента, размещенного в Foundry. Если вам нужна наблюдаемость кода вашего приложения — например, для трассировки пользовательской логики, связанной с вызовом агента, — вы можете на втором этапе добавить клиентское инструментирование.

Навык Microsoft Foundry может помочь выбрать трассировку на стороне сервера или на стороне клиента и устранить неполадки, связанные с отсутствием данных телеметрии.

Необходимые условия

• Проект Foundry.
• Ресурс Azure Monitor Application Insights для хранения трассировок (создайте новую или подключите существующую).
• Доступ к ресурсу Application Insights, подключенного к проекту.
• Роль Log Analytics Reader на подключенном ресурсе Application Insights (требуется для выполнения запросов к телеметрии). Если базовые таблицы Log Analytics защищены, также назначьте роль "Читатель привилегированных данных мониторинга".

Подключение Application Insights к проекту Foundry

Foundry хранит трассировки в Application Insights с помощью семантических соглашений OpenTelemetry.

1. Войдите в Microsoft Foundry. Убедитесь, что переключатель New Foundry включен. Эти действия относятся к Foundry (new).

   

2. Откройте проект Foundry.

3. В области навигации слева выберите "Агенты".

4. В верхней части выберите Трассы.

5. Справа выберите "Подключиться" , чтобы создать или подключить ресурс Application Insights.

   

• Чтобы подключить существующий ресурс, выберите ресурс и нажмите кнопку "Подключить".
• Чтобы создать новый ресурс, нажмите кнопку "Создать", а затем завершите работу мастера.

При успешном выполнении подключения появится сообщение подтверждения.

Использование пути подключения сведений о проекте

Если вы не видите панель сообщений или кнопку "Подключить", используйте этот альтернативный способ, чтобы включить Azure Monitor Application Insights.

1. Выберите Управление в правом верхнем углу панели навигации, а затем выберите Сведения о проекте.
2. Перейдите на вкладку "Подключенные ресурсы " и нажмите кнопку "Добавить подключение".
3. В разделе "Выбор подключения" выберите Application Insights.

Сведения о приеме трассировок с аутентификацией Microsoft Entra см. в статье «Настройка аутентификации Microsoft Entra для приема трассировок агента Foundry (предварительная версия)».

После подключения ресурса проект готов к использованию трассировки.

Настройка агентов ИИ

Выберите подход, который соответствует тому, как вы разрабатываете и запускаете своего агента.

Трассировки на стороне сервера на портале Foundry

Начните с трассировки на стороне сервера. В Foundry ведется журналирование для распространенных сценариев агентов и рабочих процессов без необходимости изменения кода.

• Foundry автоматически записывает серверные трассировки для агентов Prompt, агентов Host и рабочих процессов в портале Foundry. После включения трассировки в вашем проекте Foundry вы получаете доступ к готовым трассировкам за последние 90 дней.
• Foundry также поддерживает простую интеграцию с топ-платформами агентов.

Трассировки на стороне клиента с пакетом SDK для Microsoft Foundry (Python)

Установите OpenTelemetry и плагин трассировки для Azure SDK, выполнив следующие действия:

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

Справочник: azure-ai-projects, azure-core-tracing-opentelemetry

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

Для получения подробных инструкций и примеров кода, специфичных для SDK, см. раздел Трассировка с помощью azure-ai-projects (Python SDK) и Примеры телеметрии для агентов.

Локальная трассировка с помощью расширения Microsoft Foundry Toolkit для Visual Studio Code

Расширение Microsoft Foundry Toolkit для Visual Studio Code позволяет выполнять локальную трассировку в VS Code с помощью локального сборщика, совместимого с OTLP. Этот подход идеально подходит для разработки и отладки.

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

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

Просмотр и анализ трассировок

Просмотр трассировок на портале Foundry

В проекте Foundry перейдите на вкладку "Трассировки" в агентах или рабочих процессах. Вы можете выполнять поиск, фильтрацию или сортировку собранных трассировок за последние 90 дней.

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

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

Ваши трассировки отправляются в Azure Monitor Application Insights, где вы можете их просматривать.

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

Просмотр результатов беседы

Беседа — это постоянный контекст сквозного журнала диалогов между пользователем и агентом. На портале Foundry можно просмотреть результаты беседы для агента, не выходя из поля, а также трассировки на странице трассировки .

Выполните поиск по идентификатору ответа или идентификатору трассировки, который сопоставляется с этой беседой. Затем выберите идентификатор беседы для проверки:

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

Проверка работы трассировки

1. Убедитесь, что проект подключен к Application Insights. При необходимости выполните действия, описанные в разделе Connect Application Insights к проекту Foundry.

2. Запустите агент или рабочий процесс по крайней мере один раз (например, с помощью портала или приложения).

3. В проекте Foundry откройте представление Traces и убедитесь, что появится новая трассировка.

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

Если вы не видите новых следов, подождите несколько минут и обновите их, и затем посмотрите раздел «Устранение неполадок».

Безопасность и конфиденциальность

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

• Не сохраняйте секреты, учетные данные или токены в запросах, аргументах инструментов или атрибутах области.
• Перед появлением в телеметрии редактируйте или сведите к минимуму персональные данные и другое конфиденциальное содержимое.
• Обрабатывать данные трассировки как рабочую телеметрию и применять те же политики управления доступом и хранения, которые используются для журналов и метрик.

Дополнительные рекомендации см. в разделе "Безопасность и конфиденциальность".

Хранение и стоимость данных

Foundry хранит трассировки в ресурсе Application Insights, подключенном к проекту. Хранение данных и выставление счетов следует за конфигурацией Application Insights и Log Analytics.

Устранение неполадок

Связанное содержимое

Теперь, когда вы настроили трассировку, изучите эти ресурсы, чтобы углубить понимание и расширить возможности наблюдаемости:

• Обзор трассировки агента
• Интеграции трассировки
• Мониторинг агентов ИИ с помощью панели мониторинга агента
• Наблюдаемость в генеративном ИИ