Partager via

Afficher les résultats de trace pour les applications IA à l’aide du Kit de développement logiciel (SDK) OpenAI

Note

Ce document fait référence au portail Microsoft Foundry (classique).

🔍 Consultez la documentation Microsoft Foundry (nouvelle) pour en savoir plus sur le nouveau portail.

Découvrez comment afficher les résultats de trace qui fournissent une visibilité sur l’exécution d’applications IA. Utilisez des traces pour diagnostiquer les appels d’outils incorrects, les messages trompeurs, les problèmes de latence, et les scores faibles d'évaluation.

Dans cet article, vous allez apprendre à :

  • Activez le suivi pour un projet.
  • Instrumentez le Kit de développement logiciel (SDK) OpenAI.
  • Capturer le contenu du message (facultatif).
  • Affichez les lignes de temps et les intervalles de trace.
  • Connectez le suivi avec des boucles d’évaluation.

Cet article explique comment afficher les résultats de trace pour les applications IA à l’aide du Kit de développement logiciel (SDK) OpenAI avec OpenTelemetry dans Microsoft Foundry.

Prerequisites

Vous avez besoin des éléments suivants pour suivre ce tutoriel :

  • Un projet Foundry a été créé.

  • Application IA qui utilise le Kit de développement logiciel (SDK) OpenAI pour effectuer des appels aux modèles hébergés dans Foundry.

Activer le suivi dans votre projet

Foundry stocke les traces dans Azure Application Insights à l’aide d’OpenTelemetry. Les nouvelles ressources ne provisionnent pas Application Insights automatiquement. Associez (ou créez) une ressource une seule fois par ressource Foundry.

Les étapes suivantes montrent comment configurer votre ressource :

  1. Accédez au portail Foundry et accédez à votre projet.

  2. Dans la barre de navigation latérale, sélectionnez Traçage.

  3. Si une ressource Azure Application Insights n’est pas associée à votre ressource Foundry, associez-en une. Si vous disposez déjà d’une ressource Application Insights associée, vous ne voyez pas la page d’activation ci-dessous et vous pouvez ignorer cette étape.

    Capture d’écran montrant comment configurer Azure Application Insights sur la ressource Foundry.

    1. Pour réutiliser un Azure Application Insights existant, utilisez le menu déroulant nom de ressource Application Insights pour localiser la ressource et sélectionnez Connecter.

      Tip

      Pour vous connecter à azure Application Insights existant, vous avez besoin d’au moins un accès contributeur à la ressource Foundry (ou Hub).

    2. Si vous souhaitez vous connecter à une nouvelle ressource Azure Application Insights, sélectionnez l’option Créer.

      1. Utilisez l’Assistant Configuration pour configurer le nom de la nouvelle ressource.

      2. Par défaut, la nouvelle ressource est créée dans le même groupe de ressources que celui où la ressource Foundry a été créée. Utilisez l’option Paramètres avancés pour configurer un autre groupe de ressources ou abonnement.

        Tip

        Pour créer une ressource Azure Application Insights, vous avez également besoin d’un rôle de contributeur dans le groupe de ressources sélectionné (ou celui par défaut).

      3. Sélectionnez Créer pour créer la ressource et la connecter à la ressource Foundry.

    3. Une fois la connexion configurée, vous êtes prêt à utiliser le traçage dans n’importe quel projet au sein de la ressource.

    Tip

    Assurez-vous que le rôle Lecteur Log Analytics est attribué dans votre ressource Application Insights. Pour en savoir plus sur l’attribution de rôles, consultez Affecter des rôles Azure à l’aide du portail Azure. Utilisez des groupes Microsoft Entra pour gérer plus facilement l’accès aux utilisateurs.

  4. Accédez à la page d’accueil de votre projet et copiez l’URI du point de terminaison du projet. Vous en aurez besoin ultérieurement.

    Capture d’écran montrant comment copier l’URI du point de terminaison de projet.

    Important

    L’utilisation du point de terminaison d’un projet nécessite la configuration de l’ID Microsoft Entra dans votre application. Si vous n’avez pas configuré l’ID Entra, utilisez la chaîne de connexion Azure Application Insights, comme indiqué à l’étape 3 du didacticiel.

Afficher les résultats de trace dans le portail Foundry

Une fois le suivi configuré et que votre application est instrumentée, vous pouvez afficher les résultats de trace dans le portail Foundry :

  1. Accédez au portail Foundry et accédez à votre projet.

  2. Dans la barre de navigation latérale, sélectionnez Traçage.

  3. Vous verrez une liste des résultats de suivi de vos applications instrumentées. Chaque trace montre :

    • ID de trace : identificateur unique pour la trace
    • Heure de début : lorsque la trace a commencé
    • Durée : durée de l’opération
    • État : État de réussite ou d’échec
    • Opérations : nombre de segments dans la trace

  4. Sélectionnez une trace pour afficher les résultats de trace détaillés, notamment :

    • Chronologie d’exécution complète
    • Données d’entrée et de sortie pour chaque opération
    • Métriques et minutage des performances
    • Détails de l’erreur s’il s’est produit
    • Attributs et métadonnées personnalisés

Instrumenter le Kit de développement logiciel (SDK) OpenAI

Lors du développement avec le Kit de développement logiciel (SDK) OpenAI, vous pouvez instrumenter votre code afin que les traces soient envoyées à Foundry. Procédez comme suit pour instrumenter votre code :

  1. Installer des packages :

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

  2. (Facultatif) Capturer le contenu du message :

    • PowerShell : setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
    • Bash : export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

  3. Obtenez la chaîne de connexion de la ressource Application Insights liée (Projet > Suivi > Gérer la source de données > Chaîne de connexion) :

    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()

  4. Configurer Azure Monitor et instrumenter le Kit de développement logiciel (SDK) OpenAI :

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

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

  5. Envoyez une requête :

    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)

  6. Revenez au traçage dans le portail pour afficher les nouvelles traces.

    Capture d’écran montrant une vue de la trace d’une requête de finalisation de chat montrant des plages et une latence.

  7. Il pourrait être utile de capturer des sections de votre code qui combinent une logique métier avec des modèles lors du développement d’applications complexes. OpenTelemetry utilise le concept d’étendues pour capturer les sections qui vous intéressent. Pour commencer à générer vos propres étendues, obtenez une instance de l’objet de suivi en cours.

    from opentelemetry import trace

tracer = trace.get_tracer(__name__)

  8. Ensuite, utilisez des décorateurs dans votre méthode pour capturer des scénarios spécifiques utiles dans votre code. Ces décorateurs génèrent automatiquement des intervalles. L’exemple de code suivant instrumente une méthode appelée assess_claims_with_context qui itère sur une liste de revendications et vérifie si la revendication est prise en charge par le contexte en utilisant un LLM. Tous les appels effectués dans cette méthode sont capturés dans la même étendue :

    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

  9. Les résultats de la trace se présentent comme suit :

    Capture d’écran montrant comment une méthode utilisant un décorateur s’affiche dans la trace.

  10. Vous pouvez également ajouter des informations supplémentaires à l’intervalle actuel. OpenTelemetry utilise le concept des attributs pour cela. Utilisez l’objet trace pour y accéder et inclure des informations supplémentaires. Découvrez comment la assess_claims_with_context méthode a été modifiée pour inclure un attribut :

    @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

Suivi de la console

Il pourrait être utile de tracer également votre application et d’envoyer les traces à la console d’exécution locale. Il est possible que cette approche soit utile lors de l’exécution de tests unitaires ou de tests d’intégration dans votre application en tirant parti d’un pipeline CI/CD automatisé. Les traces peuvent être envoyées à la console et capturées par votre outil CI/CD pour obtenir une analyse plus approfondie.

Configurez le suivi comme suit :

  1. Instrumentez le Kit de développement logiciel (SDK) OpenAI comme d’habitude :

    from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

  2. Configurez OpenTelemetry pour envoyer des traces à la console :

    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)

  3. Utilisez le Kit de développement logiciel (SDK) OpenAI comme d’habitude :

    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": ""
    }
}

Trace localement avec AI Toolkit

AI Toolkit offre un moyen simple de suivre localement dans VS Code. Il utilise un collecteur compatible OTLP local, ce qui le rend parfait pour le développement et le débogage sans avoir besoin d’un accès cloud.

Le kit de ressources prend en charge le Kit de développement logiciel (SDK) OpenAI et d’autres frameworks IA via OpenTelemetry. Vous pouvez voir instantanément les traces dans votre environnement de développement.

Pour obtenir des instructions d’installation détaillées et des exemples de code spécifiques au Kit de développement logiciel (SDK), consultez Suivi dans AI Toolkit.

Contenu connexe

  • Last updated on