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

S’applique uniquement au :Portail Foundry (classique). Cet article n’est pas disponible pour le nouveau portail Foundry. En savoir plus sur le nouveau portail.

Note

Les liens de cet article peuvent ouvrir du contenu dans la nouvelle documentation Microsoft Foundry au lieu de la documentation Foundry (classique) que vous affichez maintenant.

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 invites trompeuses, les goulots d’étranglement de latence et les scores d’évaluation de faible qualité.

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 chronologies et les plages 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 de OpenAI SDK avec OpenTelemetry dans Microsoft Foundry.

Conditions préalables

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 Suivi.

  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 verrez pas la page d’activation ci-dessous et vous pouvez ignorer cette étape.

    Une capture d’écran montrant comment configurer Azure Application Insights pour la ressource Foundry.

    1. Pour réutiliser un Azure Application Insights existant, utilisez le nom de la ressource Application Insights pour localiser la ressource et sélectionner Connect.

      Conseil

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

    2. Pour vous connecter à une nouvelle ressource Azure Application Insights, sélectionnez l’option Create new.

      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 un autre abonnement.

        Conseil

        Pour créer une ressource Azure Application Insights, vous avez également besoin d’un rôle contributeur au groupe de ressources que vous avez 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 suivi dans n’importe quel projet au sein de la ressource.

    Conseil

    Vérifiez que vous disposez du rôle Log Analytics Reader affecté dans votre ressource Application Insights. Pour en savoir plus sur l’attribution de rôles, consultez Assigner des rôles Azure à l’aide du portail Azure. Utilisez Microsoft Entra groupes 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 avez besoin plus tard.

    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 Microsoft Entra ID dans votre application. Si vous n'avez pas configuré Entra ID, utilisez l'Azure Application Insights chaîne de connexion 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 Suivi.

  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 trames 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 > Tracing > 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. Configurez Azure Monitor et instrumentez 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 consulter les nouvelles traces.

    Capture d’écran montrant une vue de trace d’une demande d’achèvement de conversation montrant des étendues et une latence.

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

    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 dans votre code qui vous intéressent. Ces décorateurs génèrent des plages automatiquement. L’exemple de code suivant illustre une méthode appelée assess_claims_with_context qui parcourt une liste de déclarations et vérifie si la déclaration est validée par le contexte à l’aide d’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 du tracé s'affichent de cette manière :

    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’étendue actuelle. OpenTelemetry utilise le concept d’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

Tracer vers la console

Il peut être utile de suivre également votre application et d’envoyer les traces à la console d’exécution locale. Cette approche peut être utile lors de l’exécution de tests unitaires ou de tests d’intégration dans votre application à l’aide d’un pipeline CI/CD automatisé. Les traces peuvent être envoyées à la console et capturées par votre outil CI/CD pour 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