Tracer des applications IA à l’aide du Kit de développement logiciel (SDK) OpenAI

2025-06-21

Le suivi offre une visibilité approfondie de l’exécution de votre application en capturant des données de télémétrie détaillées à chaque étape d’exécution. Cela permet de diagnostiquer les problèmes et d’améliorer les performances en identifiant des problèmes tels que des appels d’outils incorrects, des invites trompeuses, une latence élevée, des scores d’évaluation de faible qualité, etc.

Cet article explique comment implémenter le suivi pour les applications IA à l’aide du Kit de développement logiciel (SDK) OpenAI avec OpenTelemetry dans Azure AI Foundry.

Conditions préalables

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

Un projet Azure AI Foundry créé.
Application IA qui utilise openAI SDK pour effectuer des appels aux modèles hébergés dans Azure AI Foundry.

Activer le suivi dans votre projet

Azure AI Foundry stocke les traces dans les ressources Azure Application Insight à l’aide d’OpenTelemetry. Par défaut, les nouvelles ressources Azure AI Foundry ne provisionnent pas ces ressources. Vous pouvez connecter des projets à une ressource Azure Application Insights existante ou en créer un à partir du projet. Vous effectuez cette configuration une fois par ressource Azure AI Foundry.

Les étapes suivantes montrent comment configurer votre ressource :

Accédez au portail Azure AI Foundry et accédez à votre projet.
Dans la barre de navigation latérale, sélectionnez Suivi.
Si une ressource Azure Application Insights n’est pas associée à votre ressource Azure AI Foundry, associez-en une.
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.

Conseil / Astuce

Pour vous connecter à azure Application Insights existant, vous avez besoin d’au moins un accès contributeur à la ressource Azure AI Foundry (ou Hub).
Pour 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 la ressource Azure AI Foundry a été créée. Utilisez l’option Paramètres avancés pour configurer un autre groupe de ressources ou un autre abonnement.
  
  Conseil / Astuce
  
  Pour créer une ressource Azure Application Insight, 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 Azure AI Foundry.
Une fois la connexion configurée, vous êtes prêt à utiliser le suivi dans n’importe quel projet de la ressource.
Accédez à la page d’accueil de votre projet et copiez l’URI du point de terminaison du projet. Vous en avez besoin plus loin dans le tutoriel.

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.

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 à Azure AI Foundry. Procédez comme suit pour instrumenter votre code :

Installez azure-ai-projects, azure-monitor-opentelemetryet opentelemetry-instrumentation-openai-v2 dans votre environnement. L'exemple suivant utilise pip :
```
pip install azure-ai-projects azure-monitor-opentelemetry opentelemetry-instrumentation-openai-v2
```

Instrumentez le Kit de développement logiciel (SDK) OpenAI à l’aide de OpenAIInstrumentor() :

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Obtenez la chaîne de connexion à la ressource Azure Application Insights associée à votre projet. La ligne suivante utilise le client Azure AI Project, qui nécessite l’utilisation de Microsoft Entra ID pour l’authentification :
```
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_connection_string()
```
Conseil / Astuce

Les chaînes de connexion à Azure Application Insights ressemblent à InstrumentationKey=aaaa0a0a-bb1b-cc2c-dd3d-eeeee4e4e4e;.... Vous pouvez également accéder à la chaîne de connexion utilisée dans votre projet à partir de la section Suivi dans le portail Azure AI Foundry. Dans la barre de navigation supérieure, sélectionnez Gérer la source de données et copiez la chaîne de connexion. Configurez votre chaîne de connexion dans une variable d’environnement.

Configurez OpenTelemetry pour envoyer des traces à Azure Application Insights :

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(connection_string=connection_string)

Par défaut, OpenTelemetry ne capture pas les entrées et sorties. Utilisez la variable OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true d’environnement pour les capturer. Vérifiez que cette variable d’environnement est configurée au niveau de l’environnement où votre code est en cours d’exécution.

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

client = project_client.get_azure_openai_client()

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

Si vous revenez au portail Azure AI Foundry, vous devez voir la trace affichée :
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 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__)
```

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 automatiquement des étendues. L’exemple de code suivant instrumente une méthode appelée assess_claims_with_context qui itère sur une liste de déclarations et vérifie si la déclaration est soutenue 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.5-preview",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Les traces se présentent comme suit :

Vous pouvez également ajouter des informations supplémentaires à l’étendue en cours. 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.5-preview",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Suivi de 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 bénéfique 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 :

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

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

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)

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

Étapes suivantes

Tracer des agents en utilisant le SDK Azure AI Foundry