Просмотр результатов трассировки для приложений ИИ с помощью пакета SDK OpenAI

Замечание

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

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

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

Включите трассировку для проекта.
Инструментирование пакета SDK OpenAI.
Запись содержимого сообщения (необязательно).
Просматривайте временные интервалы и сегменты трассировки.
Подключите отслеживание с процессами оценки.

В этой статье объясняется, как просматривать результаты трассировки AI-приложений с использованием OpenAI SDK и OpenTelemetry в Microsoft Foundry.

Prerequisites

Для выполнения этого руководства вам потребуется следующее:

Проект Foundry создан.
Приложение ИИ, использующее пакет SDK OpenAI для вызова моделей, размещенных в Foundry.

Включите трассировку в вашем проекте

Foundry хранит трассировки в Azure Application Insights, используя OpenTelemetry. Новые ресурсы не подготавливают Application Insights автоматически. Ассоциируйте (или создайте) ресурс по одному разу для каждого ресурса Foundry.

Ниже показано, как настроить ресурс.

Перейдите на портал Foundry и перейдите к проекту.
На боковой панели навигации выберите "Трассировка".
Если ресурс Azure Application Insights не связан с ресурсом Foundry, свяжите его. Если у вас уже есть связанный ресурс Application Insights, вы не увидите приведенную ниже страницу включения и пропустить этот шаг.
1. Чтобы повторно использовать существующую службу Azure Application Insights, используйте раскрывающееся имя ресурса Application Insights, чтобы найти ресурс и выбрать "Подключить".
  
  Tip
  
  Чтобы подключиться к существующему Azure Application Insights, необходимо иметь по крайней мере доступ участника к ресурсу Foundry (или Hub).
2. Чтобы подключиться к новому ресурсу Azure Application Insights, выберите параметр "Создать".
  1. Используйте мастер конфигурации, чтобы настроить имя нового ресурса.
  2. По умолчанию новый ресурс создается в той же группе ресурсов, где был создан ресурс Foundry. Используйте параметр "Заранее" , чтобы настроить другую группу ресурсов или подписку.
    
    Tip
    
    Чтобы создать ресурс Azure Application Insights, вам также нужна роль участника в выбранной группе ресурсов (или по умолчанию).
  3. Выберите "Создать ", чтобы создать ресурс и подключить его к ресурсу Foundry.
3. После настройки подключения можно будет использовать трассировку в любом проекте в ресурсе.
Tip

Убедитесь, что в ресурсе Application Insights назначена роль Log Analytics Reader. Дополнительные сведения о назначении ролей см. в статье "Назначение ролей Azure" с помощью портала Azure. Используйте группы Microsoft Entra для более простого управления доступом для пользователей.
Перейдите на целевую страницу проекта и скопируйте URI конечной точки проекта. Вам потребуется позже.

Important

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

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

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

Перейдите на портал Foundry и перейдите к проекту.
На боковой панели навигации выберите "Трассировка".
Вы увидите список результатов трассировки из инструментализированных приложений. Каждая трассировка показывает:
- Идентификатор трассы: уникальный идентификатор трассы
- Время начала: начало трассировки
- Длительность: продолжительность операции
- Статус: статус успеха или неудачи
- Операции: количество отрезков в трассировке
Выберите любую трассировку для просмотра подробных результатов трассировки, включая:
- Полное временное представление выполнения
- Входные и выходные данные для каждой операции
- Метрики производительности и время
- Сведения об ошибке при возникновении каких-либо ошибок
- Пользовательские атрибуты и метаданные

Настройка пакета SDK OpenAI

При разработке с помощью SDK OpenAI можно настраивать код так, чтобы трассировки пересылались в Foundry. Выполните следующие действия, чтобы инструментировать код:

Установка пакетов:

pip install azure-ai-projects azure-monitor-opentelemetry opentelemetry-instrumentation-openai-v2

(Необязательно) Запись содержимого сообщения:
- PowerShell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Баш: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Получите строку подключения для связанного ресурса Application Insights (Проект > Трассировка > Управление источником данных > Строка подключения):

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
     credential=DefaultAzureCredential(),
     endpoint="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>",
)
connection_string = project_client.telemetry.get_application_insights_connection_string()

Настройте Azure Monitor и инструмент OpenAI SDK:

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

configure_azure_monitor(connection_string=connection_string)
OpenAIInstrumentor().instrument()

Отправьте запрос:

client = project_client.get_openai_client()
response = client.chat.completions.create(
     model="gpt-4o-mini", 
     messages=[{"role": "user", "content": "Write a short poem on open telemetry."}],
)
print(response.choices[0].message.content)

Вернитесь к трассировке на портале, чтобы просмотреть новые следы.
Это может быть полезно для записи разделов кода, которые смешивают бизнес-логику с моделями при разработке сложных приложений. OpenTelemetry использует концепцию диапазонов для отслеживания интересующих вас разделов. Чтобы начать создание собственных диапазонов, получите экземпляр текущего объекта трассировки .
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Затем используйте декораторы в методе для отслеживания конкретных сценариев в интересующем вас коде. Эти декораторы автоматически создают диапазоны. В следующем примере кода метод, называемый assess_claims_with_context итерирует список утверждений и проверяет, поддерживается ли утверждение контекстом с помощью LLM. Все вызовы, выполненные в этом методе, фиксируются в одном диапазоне:

def build_prompt_with_context(claim: str, context: str) -> str:
    return [{'role': 'system', 'content': "I will ask you to assess whether a particular scientific claim, based on evidence provided. Output only the text 'True' if the claim is true, 'False' if the claim is false, or 'NEE' if there's not enough evidence."},
            {'role': 'user', 'content': f"""
                The evidence is the following: {context}

                Assess the following claim on the basis of the evidence. Output only the text 'True' if the claim is true, 'False' if the claim is false, or 'NEE' if there's not enough evidence. Do not output any other text.

                Claim:
                {claim}

                Assessment:
            """}]

@tracer.start_as_current_span("assess_claims_with_context")
def assess_claims_with_context(claims, contexts):
    responses = []
    for claim, context in zip(claims, contexts):
        response = client.chat.completions.create(
            model="gpt-4.1",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Результаты трассировки выглядят следующим образом:

Вы также можете добавить дополнительные сведения в текущий диапазон. OpenTelemetry использует концепцию атрибутов для этого. trace Используйте объект для доступа к ним и включения дополнительных сведений. Узнайте, как assess_claims_with_context метод был изменен для включения атрибута:

@tracer.start_as_current_span("assess_claims_with_context")
def assess_claims_with_context(claims, contexts):
    responses = []
    current_span = trace.get_current_span()

    current_span.set_attribute("operation.claims_count", len(claims))

    for claim, context in zip(claims, contexts):
        response = client.chat.completions.create(
            model="gpt-4.1",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Трассировка в консоль

Это может быть полезно также для трассировки приложения и отправки трассировок в локальную консоль выполнения. Этот подход может оказаться полезным при выполнении модульных тестов или тестов интеграции в приложении с помощью автоматизированного конвейера CI/CD. Трассировки можно отправлять в консоль и записывать с помощью средства CI/CD для дальнейшего анализа.

Настройте трассировку следующим образом:

Настройте пакет SDK OpenAI как обычно.

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Настройте OpenTelemetry для отправки трассировок в консоль:

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

span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

Используйте пакет SDK OpenAI как обычно:

response = client.chat.completions.create(
    model="deepseek-v3-0324",
    messages=[
        {"role": "user", "content": "Write a short poem on open telemetry."},
    ],
)

{
    "name": "chat deepseek-v3-0324",
    "context": {
        "trace_id": "0xaaaa0a0abb1bcc2cdd3d",
        "span_id": "0xaaaa0a0abb1bcc2cdd3d",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-06-13T00:02:04.271337Z",
    "end_time": "2025-06-13T00:02:06.537220Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.operation.name": "chat",
        "gen_ai.system": "openai",
        "gen_ai.request.model": "deepseek-v3-0324",
        "server.address": "my-project.services.ai.azure.com",
        "gen_ai.response.model": "DeepSeek-V3-0324",
        "gen_ai.response.finish_reasons": [
            "stop"
        ],
        "gen_ai.response.id": "aaaa0a0abb1bcc2cdd3d",
        "gen_ai.usage.input_tokens": 14,
        "gen_ai.usage.output_tokens": 91
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.31.1",
            "service.name": "unknown_service"
        },
        "schema_url": ""
    }
}

Локальная трассировка с помощью AI Toolkit

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

Набор средств поддерживает пакет SDK OpenAI и другие платформы ИИ с помощью OpenTelemetry. Вы можете мгновенно увидеть трассировки в своей среде разработки.

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

Агенты трассировки с помощью пакета SDK Microsoft Foundry

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-11-18