Anzeigen von Trace-Ergebnissen für KI-Anwendungen mit dem OpenAI SDK

Hinweis

Dieses Dokument bezieht sich auf das Microsoft Foundry(klassische) Portal.

🔍 Zeigen Sie die Microsoft Foundry-Dokumentation (neu) an, um mehr über das neue Portal zu erfahren.

Erfahren Sie, wie Sie Ablaufverfolgungsergebnisse anzeigen, die Einblicke in die KI-Anwendungsausführung bieten. Verwenden Sie Tracing, um ungenaue Toolaufrufe, irreführende Eingabeaufforderungen, Latenzprobleme und niedrigwertige Bewertungsergebnisse zu diagnostizieren.

In diesem Artikel erfahren Sie, wie Sie:

Aktivieren Sie die Ablaufverfolgung für ein Projekt.
Instrumentierung des OpenAI SDK.
Erfassen von Nachrichteninhalten (optional).
Zeigen Sie Ablaufverfolgungszeitachsen und Spannen an.
Verbinden sie die Ablaufverfolgung mit Auswertungsschleifen.

In diesem Artikel wird erläutert, wie mithilfe des OpenAI SDK und OpenTelemetry Trace-Ergebnisse für KI-Anwendungen in Microsoft Foundry angezeigt werden.

Prerequisites

Sie benötigen Folgendes, um dieses Lernprogramm abzuschließen:

Ein Foundry-Projekt wurde erstellt.
Eine KI-Anwendung, die openAI SDK verwendet, um Aufrufe an Modelle zu tätigen, die in Foundry gehostet werden.

Aktivieren Sie die Ablaufverfolgung in Ihrem Projekt

Foundry speichert Ablaufverfolgungen in Azure Application Insights mithilfe von OpenTelemetry. Neue Ressourcen stellen Application Insights nicht automatisch bereit. Weisen Sie einmal pro Foundry-Ressource eine Ressource zu (oder erstellen Sie eine).

Die folgenden Schritte zeigen, wie Sie Ihre Ressource konfigurieren:

Wechseln Sie zum Foundry-Portal , und navigieren Sie zu Ihrem Projekt.
Wählen Sie auf der seitlichen Navigationsleiste Ablaufverfolgungaus.
Wenn eine Azure Application Insights-Ressource nicht mit Ihrer Foundry-Ressource verknüpft ist, ordnen Sie eine Ressource zu. Wenn Sie bereits über eine Application Insights-Ressource verfügen, wird die Seite „Aktivieren“ unten nicht angezeigt, und Sie können diesen Schritt überspringen.
1. Um eine vorhandene Azure Application Insights wiederzuverwenden, verwenden Sie den Ressourcennamen in der Dropdownliste "Application Insights ", um die Ressource zu suchen und "Verbinden" auszuwählen.
  
  Tip
  
  Um eine Verbindung mit einer vorhandenen Azure Application Insights herzustellen, benötigen Sie mindestens einen Mitwirkendenzugriff auf die Foundry-Ressource (oder den Hub).
2. Um eine Verbindung mit einer neuen Azure Application Insights-Ressource herzustellen, wählen Sie die Option Neu erstellen aus.
  1. Verwenden Sie den Konfigurations-Assistenten, um den Namen der neuen Ressource zu konfigurieren.
  2. Standardmäßig wird die neue Ressource in derselben Ressourcengruppe erstellt, in der die Foundry-Ressource erstellt wurde. Verwenden Sie die Option Erweiterte Einstellungen, um eine andere Ressourcengruppe oder ein anderes Abonnement zu konfigurieren.
    
    Tip
    
    Um eine neue Azure Application Insights-Ressource zu erstellen, benötigen Sie auch eine Mitwirkendenrolle für die von Ihnen ausgewählte Ressourcengruppe (oder die Standardressource).
  3. Wählen Sie "Erstellen" aus, um die Ressource zu erstellen und mit der Foundry-Ressource zu verbinden.
3. Nachdem die Verbindung konfiguriert wurde, können Sie die Ablaufverfolgung in jedem Projekt innerhalb der Ressource verwenden.
Tip

Stellen Sie sicher, dass die Log Analytics Reader-Rolle in Ihrer Application Insights-Ressource zugewiesen ist. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zuweisen von Azure-Rollen mithilfe des Azure-Portals. Verwenden Sie Microsoft Entra-Gruppen , um den Zugriff für Benutzer einfacher zu verwalten.
Wechseln Sie zur Zielseite Ihres Projekts, und kopieren Sie den Endpunkt-URI des Projekts. Sie benötigen ihn später.

Important

Für die Verwendung des Endpunkts eines Projekts ist die Konfiguration der Microsoft Entra-ID in Ihrer Anwendung erforderlich. Wenn Sie Entra ID nicht konfiguriert haben, verwenden Sie die Azure Application Insights-Verbindungszeichenfolge, wie in Schritt 3 des Tutorials angegeben.

Ergebnisse der Ablaufverfolgung im Foundry-Portal anzeigen

Nachdem Sie die Ablaufverfolgung konfiguriert haben und Ihre Anwendung instrumentiert ist, können Sie Ablaufverfolgungsergebnisse im Foundry-Portal anzeigen:

Wechseln Sie zum Foundry-Portal , und navigieren Sie zu Ihrem Projekt.
Wählen Sie auf der seitlichen Navigationsleiste Ablaufverfolgungaus.
Eine Liste der Ablaufverfolgungsergebnisse Ihrer instrumentierten Anwendungen wird angezeigt. Jede Ablaufverfolgung zeigt:
- Ablaufverfolgungs-ID: Der eindeutige Bezeichner für die Ablaufverfolgung
- Startzeit: Wann die Ablaufverfolgung begonnen hat
- Dauer: Dauer des Vorgangs
- Status: Erfolgs- oder Fehlerstatus
- Operationen: Anzahl der Spans in der Ablaufverfolgung
Wählen Sie eine beliebige Ablaufverfolgung aus, um detaillierte Ergebnisse der Ablaufverfolgung anzuzeigen, einschließlich:
- Zeitachse der vollständigen Ausführung
- Eingabe- und Ausgabedaten für jeden Vorgang
- Leistungsmetriken und Timing
- Fehlerdetails, falls vorhanden
- Benutzerdefinierte Attribute und Metadaten

Instrument des OpenAI SDK

Bei der Entwicklung mit dem OpenAI SDK können Sie Ihren Code so instrumentieren, dass Tracing-Daten an Foundry gesendet werden. Führen Sie die folgenden Schritte aus, um Ihren Code zu instrumentieren:

Installieren von Paketen:

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

(Optional) Nachrichteninhalt erfassen:
- PowerShell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Rufen Sie die Verbindungszeichenfolge für die verknüpfte Application Insights-Ressource ab (Projekt > Ablaufverfolgung > Datenquelle verwalten > Verbindungszeichenfolge):

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

Konfigurieren Sie Azure Monitor und instrumentieren Sie das 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()

Senden einer Anforderung:

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)

Kehren Sie zu Ablaufverfolgung im Portal zurück, um neue Einträge anzuzeigen.
Es kann hilfreich sein, Abschnitte Ihres Codes zu erfassen, die Geschäftslogik mit Modellen kombinieren, wenn Sie komplexe Anwendungen entwickeln. OpenTelemetry verwendet das Konzept der "Spans", um Abschnitte zu erfassen, die für Sie von Interesse sind. Rufen Sie eine Instanz des aktuellen Tracer-Objekts ab, um mit dem Generieren eigener Spannen zu beginnen.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Verwenden Sie dann Decorators in Ihrer Methode, um bestimmte Szenarien in Ihrem Code zu erfassen, an denen Sie interessiert sind. Diese Decorators generieren automatisch Spannen. Im folgenden Codebeispiel wird eine Methode namens assess_claims_with_context instrumentiert, die eine Liste von Ansprüchen durchläuft und mithilfe eines LLM überprüft, ob der Anspruch vom Kontext unterstützt wird. Alle in dieser Methode getätigten Aufrufe werden innerhalb derselben Zeitspanne erfasst:

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

Die Ergebnisse der Ablaufverfolgung sehen wie folgt aus:

Möglicherweise sollten Sie der aktuellen Spanne auch zusätzliche Informationen hinzufügen. OpenTelemetry verwendet dazu das Konzept von Attributen. Verwenden Sie das trace Objekt, um auf sie zuzugreifen und zusätzliche Informationen einzuschließen. Erfahren Sie, wie die assess_claims_with_context Methode geändert wurde, um ein Attribut einzuschließen:

@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

Ablaufverfolgung auf Konsole

Es kann hilfreich sein, ihre Anwendung auch zu verfolgen und die Ablaufverfolgungen an die lokale Ausführungskonsole zu senden. Dieser Ansatz kann nützlich sein, wenn Komponententests oder Integrationstests in Ihrer Anwendung mithilfe einer automatisierten CI/CD-Pipeline ausgeführt werden. Ablaufverfolgungen können zur weiteren Analyse an die Konsole gesendet und von Ihrem CI/CD-Tool erfasst werden.

Konfigurieren Sie die Ablaufverfolgung wie folgt:

Implementieren Sie das OpenAI SDK wie gewohnt:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Konfigurieren Sie OpenTelemetry zum Senden von Traces an die Konsole.

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)

Verwenden Sie openAI SDK wie gewohnt:

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

Lokale Ablaufverfolgung mit KI-Toolkit

AI Toolkit bietet eine einfache Möglichkeit, lokal in VS Code nachzuverfolgen. Es verwendet einen lokalen OTLP-kompatiblen Sammler, sodass er perfekt für Entwicklung und Debugging geeignet ist, ohne cloudbasierten Zugriff zu benötigen.

Das Toolkit unterstützt das OpenAI SDK und andere AI-Frameworks über OpenTelemetry. Sie können Traces sofort in Ihrer Entwicklungsumgebung sehen.

Ausführliche Einrichtungsanweisungen und SDK-spezifische Codebeispiele finden Sie unter "Tracing in AI Toolkit".

Agenten mit dem Microsoft Foundry SDK nachverfolgen

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-18