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

Это важно

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

Замечание

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

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

Предпосылки

• Проект Foundry.
• Ресурс Azure Monitor Application Insights для хранения трассировок (создайте новую или подключите существующую).
• Доступ к ресурсу Application Insights, подключенного к проекту.

Подключение 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 в меню "Выбор подключения ".

Это важно

Убедитесь, что у вас есть разрешения, необходимые для запроса телеметрии.

• Для запросов на основе журнала начните с назначения роли Читателя Log Analytics.
• Сведения о назначении ролей см. в статье Назначение ролей Azure с помощью портала Azure.
• Для управления доступом в масштабе используйте группы Microsoft Entra.

Оснащение агентов ИИ

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

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

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

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

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

Установите OpenTelemetry и плагин трассировки Azure SDK с помощью:

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

Это важно

Использование конечной точки проекта в приложении требует настройки Microsoft Entra ID. Если вы не настроите идентификатор Microsoft Entra, используйте строку подключения Application Insights.

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

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

Локальная трассировка с помощью инструментария ИИ в VS Code

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

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

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

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

Просмотр трассировок на портале 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.

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

Проблема	Причина	Резолюция
На портале Foundry нет никаких следов	Отслеживание не подключено, нет недавнего трафика или задержана сбор данных.	Подтвердите подключение Application Insights, сгенерируйте новый трафик агента и обновите через несколько минут.
При запросе или просмотре телеметрии отображаются ошибки авторизации	Отсутствуют разрешения RBAC в Application Insights или Log Analytics	Подтвердите доступ в элементе управления доступом (IAM) для подключенных ресурсов. Для запросов журнала назначьте роль читателя Log Analytics.
Трассировки на стороне клиента не отображаются	Инструментирование не установлено или настроено	Перепроверьте установку пакета и следуйте руководству по SDK, указанному в трассировках на стороне клиента с использованием Microsoft Foundry SDK (Python).
Конфиденциальное содержимое отображается в трассировках	Запросы, аргументы инструментов или выходные данные содержат конфиденциальные данные	Перед передачей телеметрии редактируйте конфиденциальные данные и следуйте инструкциям в разделе «Безопасность и конфиденциальность».

Связанный контент

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

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