Traceringsresultaten voor AI-toepassingen weergeven met behulp van OpenAI SDK

2025-09-22

Meer informatie over het weergeven van traceringsresultaten die inzicht bieden in de uitvoering van AI-toepassingen. Gebruik traceringen om onjuiste toolaanroepen, misleidende prompts, latentieknelpunten en evaluatiescores met lage kwaliteit te diagnosticeren.

In dit artikel leert u het volgende:

Tracering voor een project inschakelen.
Instrumenteer de OpenAI SDK.
Berichtinhoud vastleggen (optioneel).
Traceringstijdlijnen en -spanten weergeven.
Tracing verbinden met evaluatiecycli.

In dit artikel wordt uitgelegd hoe u traceringsresultaten voor AI-toepassingen kunt weergeven met behulp van de OpenAI SDK met OpenTelemetry in Azure AI Foundry.

Vereiste voorwaarden

U hebt het volgende nodig om deze zelfstudie te voltooien:

Een Azure AI Foundry-project gemaakt.
Een AI-toepassing die gebruikmaakt van OpenAI SDK om aanroepen te doen naar modellen die worden gehost in Azure AI Foundry.

Tracering inschakelen in uw project

Azure AI Foundry slaat traceringen op in Azure Application Insights met behulp van OpenTelemetry. Nieuwe resources richten Application Insights niet automatisch in. Koppel (of maak) een resource eenmaal per Azure AI Foundry-resource.

De volgende stappen laten zien hoe u uw resource configureert:

Ga naar de Azure AI Foundry-portal en navigeer naar uw project.
Selecteer Tracering op de navigatiebalk aan de zijkant.
Als een Azure Application Insights-resource niet is gekoppeld aan uw Azure AI Foundry-resource, koppelt u er een. Als u al een Application Insights-resource hebt gekoppeld, ziet u de pagina Inschakelen hieronder niet en kunt u deze stap overslaan.
1. Als u een bestaande Azure Application Insights opnieuw wilt gebruiken, gebruikt u de naam van de Application Insights-resource in de vervolgkeuzelijst om de resource te zoeken en Verbinding maken te selecteren.
  
  Aanbeveling
  
  Als u verbinding wilt maken met een bestaande Azure Application Insights, hebt u ten minste inzendertoegang nodig tot de Azure AI Foundry-resource (of Hub).
2. Als u verbinding wilt maken met een nieuwe Azure Application Insights-resource, selecteert u de optie Nieuwe maken.
  1. Gebruik de configuratiewizard om de naam van de nieuwe resource te configureren.
  2. De nieuwe resource wordt standaard gemaakt in dezelfde resourcegroep waarin de Azure AI Foundry-resource is gemaakt. Gebruik de optie Geavanceerde instellingen om een andere resourcegroep of een ander abonnement te configureren.
    
    Aanbeveling
    
    Als u een nieuwe Azure Application Insights-resource wilt maken, hebt u ook de rol van inzender nodig voor de resourcegroep die u hebt geselecteerd (of de standaardresource).
  3. Selecteer Maken om de resource te maken en deze te verbinden met de Azure AI Foundry-resource.
3. Zodra de verbinding is geconfigureerd, kunt u tracering in elk project binnen de resource gebruiken.
Aanbeveling

Zorg ervoor dat u de rol Log Analytics Reader hebt toegewezen in uw Application Insights-resource. Zie Azure-rollen toewijzen met behulp van Azure Portal voor meer informatie over het toewijzen van rollen. Gebruik Microsoft Entra-groepen om de toegang voor gebruikers gemakkelijker te beheren.
Ga naar de landingspagina van uw project en kopieer de eindpunt-URI van het project. U hebt het later nodig.

Belangrijk

Voor het gebruik van het eindpunt van een project moet u de Microsoft Entra-id configureren in uw toepassing. Als u Entra-id niet hebt geconfigureerd, gebruikt u de Azure Application Insights-verbindingsreeks zoals aangegeven in stap 3 van de zelfstudie.

Traceringsresultaten weergeven in de Azure AI Foundry-portal

Zodra u tracering hebt geconfigureerd en uw toepassing is geïnstrueerd, kunt u traceringsresultaten bekijken in de Azure AI Foundry-portal:

Ga naar de Azure AI Foundry-portal en navigeer naar uw project.
Selecteer Tracering op de navigatiebalk aan de zijkant.
U ziet een lijst met traceringsresultaten van uw geïnstrumenteerde applicaties. Elke trace toont:
- Tracerings-id: unieke id voor de tracering
- Begintijd: Wanneer de tracering is begonnen
- Duur: hoe lang de bewerking duurde
- Status: geslaagde of mislukte status
- Bewerkingen: Aantal spans in de trace
Kies een tracering om gedetailleerde resultaten van de tracering weer te geven, waaronder:
- Uitvoeringstijdlijn voltooien
- Invoer- en uitvoergegevens voor elke bewerking
- Metrische gegevens en timing voor prestaties
- Foutdetails als er iets is opgetreden
- Aangepaste kenmerken en metagegevens

Instrumenteer de OpenAI SDK

Bij het ontwikkelen met de OpenAI SDK kunt u uw code instrumenteren, zodat traceringen worden verzonden naar Azure AI Foundry. Volg deze stappen om uw code te instrumenteren:

Pakketten installeren:

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

(Optioneel) Berichtinhoud vastleggen:
- PowerShell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Haal de verbindingsreeks op voor de gekoppelde Application Insights-resource (Project > Tracing > Gegevensbron beheren > Verbindingsreeks):

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 configureren en OpenAI SDK instrumenteren:

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

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

Een aanvraag verzenden:

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)

Ga terug naar Tracering in de portal om nieuwe traceringen weer te geven.
Het kan handig zijn om secties van uw code vast te leggen die bedrijfslogica combineren met modellen bij het ontwikkelen van complexe toepassingen. OpenTelemetry maakt gebruik van het concept van "spans" om de secties vast te leggen waarin u geïnteresseerd bent. Om uw eigen spans te genereren, haalt u een exemplaar van het huidige tracer-object op.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Gebruik vervolgens decorators in uw methode om specifieke scenario's vast te leggen in uw code waarin u geïnteresseerd bent. Deze decorators genereren automatisch spanten. In het volgende codevoorbeeld wordt een methode gebruikt die wordt aangeroepen assess_claims_with_context om een lijst met claims te doorlopen en controleert of de claim wordt ondersteund door de context met behulp van een LLM. Alle aanroepen die in deze methode worden gedaan, worden binnen dezelfde periode vastgelegd:

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

Traceringsresultaten zien er als volgt uit:

Mogelijk wilt u ook extra informatie toevoegen aan het huidige bereik. OpenTelemetry gebruikt hiervoor het concept van kenmerken . Gebruik het trace object om ze te openen en extra informatie op te nemen. Bekijk hoe de assess_claims_with_context methode is gewijzigd om een kenmerk op te nemen:

@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

Log naar console

Het kan handig zijn om uw toepassing ook te traceren en de traceringen naar de lokale uitvoeringsconsole te verzenden. Deze benadering kan nuttig zijn bij het uitvoeren van eenheidstests of integratietests in uw toepassing met behulp van een geautomatiseerde CI/CD-pijplijn. Traceringen kunnen naar de console worden verzonden en vastgelegd door uw CI/CD-hulpprogramma voor verdere analyse.

Configureer tracering als volgt:

Instrumenteer de OpenAI SDK zoals gebruikelijk:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

OpenTelemetry configureren om traceringen naar de console te verzenden:

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)

OpenAI SDK zoals gebruikelijk gebruiken:

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

Lokaal traceren met AI Toolkit

AI Toolkit biedt een eenvoudige manier om lokaal te traceren in VS Code. Het maakt gebruik van een lokale OTLP-compatibele collector, waardoor het perfect is voor ontwikkeling en foutopsporing zonder cloudtoegang.

De toolkit ondersteunt de OpenAI SDK en andere AI-frameworks via OpenTelemetry. U kunt traceringen direct in uw ontwikkelomgeving zien.

Zie Tracering in AI Toolkit voor gedetailleerde installatie-instructies en SDK-specifieke codevoorbeelden.

Agents traceren met behulp van Azure AI Foundry SDK

Feedback

Is deze pagina nuttig?