Anzeigen von Tracing-Ergebnissen für KI-Anwendungen mithilfe des OpenAI SDK (klassisch)

Gilt nur für:klassisches Foundry Portal. Dieser Artikel ist für das neue Foundry-Portal nicht verfügbar. Erfahren Sie mehr über das neue Portal.

Hinweis

Links in diesem Artikel können Inhalte in der neuen Microsoft Foundry-Dokumentation anstelle der jetzt angezeigten Foundry-Dokumentation (klassisch) öffnen.

Erfahren Sie, wie Sie Ablaufverfolgungsergebnisse anzeigen, die Einblicke in die KI-Anwendungsausführung bieten. Verwenden Sie Traces, um ungenaue Toolaufrufe, irreführende Eingabeaufforderungen, Latenzengpässe und niedrige Qualitätsbewertungsergebnisse zu diagnostizieren.

In diesem Artikel erfahren Sie, wie Sie:

  • Aktivieren Sie die Ablaufverfolgung für ein Projekt.
  • Implementieren Sie das OpenAI SDK.
  • Erfassen von Nachrichteninhalten (optional).
  • Anzeigen von Ablaufverfolgungszeitleisten und Spannen.
  • Verbinden Sie die Ablaufverfolgung mit Evaluationsschleifen.

In diesem Artikel wird erläutert, wie Tracing-Ergebnisse für KI-Anwendungen mithilfe des OpenAI SDK unter Verwendung von OpenTelemetry in Microsoft Foundry angezeigt werden können.

Voraussetzungen

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-Anwendung Insights mithilfe von OpenTelemetry. Neue Ressourcen stellen Application Insights nicht automatisch bereit. Zuordnen (oder Erstellen) einer Ressource einmal pro Foundry-Ressource.

Die folgenden Schritte zeigen, wie Sie Ihre Ressource konfigurieren:

  1. Wechseln Sie zum Foundry-Portal , und navigieren Sie zu Ihrem Projekt.

  2. Wählen Sie auf der Seitennavigationsleiste Ablaufverfolgung aus.

  3. Wenn eine Azure-Anwendung Insights-Ressource nicht ihrer Foundry-Ressource zugeordnet ist, ordnen Sie eine Ressource zu. Wenn Sie bereits über eine Application Insights-Ressource verfügen, wird unten die Seite "Aktivieren" nicht angezeigt, und Sie können diesen Schritt überspringen.

    Ein Screenshot, der zeigt, wie Azure-Anwendung Insights für die Foundry-Ressource konfiguriert wird.

    1. Um eine vorhandene Azure-Anwendung Insights wiederzuverwenden, verwenden Sie das Dropdown-Menü Application Insights Ressourcennamen, um die Ressource zu suchen, und wählen Sie Verbinden aus.

      Tipp

      Um eine Verbindung mit einer vorhandenen Azure-Anwendung Insights herzustellen, benötigen Sie mindestens Mitwirkendenzugriff auf die Foundry-Ressource (oder hub).

    2. Um eine Verbindung mit einer neuen Azure-Anwendung Insights-Ressource herzustellen, wählen Sie die Option Neue 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 "Einstellungen im Voraus" , um eine andere Ressourcengruppe oder ein anderes Abonnement zu konfigurieren.

        Tipp

        Um eine neue Azure-Anwendung Insights-Ressource zu erstellen, benötigen Sie auch die Mitwirkenderolle 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.

    Tipp

    Stellen Sie sicher, dass Die Rolle Log Analytics Reader in Ihrer Application Insights-Ressource zugewiesen ist. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Assign Azure Rollen mithilfe des Azure Portals. Verwenden Sie Microsoft Entra-Gruppen, um den Zugriff für Benutzer einfacher zu verwalten.

  4. Wechseln Sie zur Zielseite Ihres Projekts, und kopieren Sie den Endpunkt-URI des Projekts. Sie benötigen es später.

    Screenshot, der zeigt, wie der Projektendpunkt-URI kopiert wird.

    Wichtig

    Für die Verwendung des Endpunkts eines Projekts muss Microsoft Entra ID in Ihrer Anwendung konfiguriert werden. Wenn Sie nicht Entra ID konfiguriert haben, verwenden Sie die Azure-Anwendung Insights Verbindungszeichenfolge, wie in Schritt 3 des Lernprogramms 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:

  1. Wechseln Sie zum Foundry-Portal , und navigieren Sie zu Ihrem Projekt.

  2. Wählen Sie auf der seitlichen Navigationsleiste "Ablaufverfolgung" aus.

  3. Sie sehen eine Liste der Ergebnisse der Ablaufverfolgung Ihrer instrumentierten Anwendungen. Jede Spur zeigt:

    • Protokollierungs-ID: Eindeutige Kennung für die Protokollierung
    • Startzeit: Zu welchem Zeitpunkt das Tracing begonnen hat
    • Dauer: Dauer des Vorgangs
    • Status: Erfolgs- oder Fehlerstatus
    • Vorgänge: Anzahl der Spannen in der Ablaufverfolgung

  4. Wählen Sie eine beliebige Trace aus, um detaillierte Tracergebnisse anzuzeigen, einschließlich:

    • Vollständige Ausführungszeitlinie
    • Eingabe- und Ausgabedaten für jeden Vorgang
    • Leistungsmetriken und Zeitmessung
    • Fehlerdetails, falls vorhanden
    • Benutzerdefinierte Attribute und Metadaten

Integrieren Sie das OpenAI SDK

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

  1. Installieren von Paketen:

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

  2. (Optional) Nachrichteninhalt erfassen:

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

  3. Rufen Sie die Verbindungszeichenfolge für die verknüpfte Application Insights-Ressource ab (Projekt > Tracing > 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()

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

  5. 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)

  6. Kehren Sie zu Tracing im Portal zurück, um neue Traces anzuzeigen.

    Screenshot einer Trace-Ansicht einer Chat-Vervollständigungsanforderung mit Spannen und Latenzzeiten.

  7. Es kann hilfreich sein, Abschnitte Ihres Codes zu erfassen, die Geschäftslogik mit Modellen bei der Entwicklung komplexer Anwendungen kombinieren. OpenTelemetry verwendet das Konzept von Spans, um Abschnitte zu erfassen, die Sie interessieren. Rufen Sie eine Instanz des aktuellen Tracer-Objekts ab, um mit dem Generieren eigener Spans zu beginnen.

    from opentelemetry import trace

tracer = trace.get_tracer(__name__)

  8. Verwenden Sie dann Dekoratoren in Ihrer Methode, um bestimmte Szenarien in Ihrem Code zu erfassen, an dem Sie interessiert sind. Diese Dekoratoren generieren automatisch Spannweiten. Im folgenden Codebeispiel wird eine Methode namens assess_claims_with_context instrumentiert, die eine Liste von Claims durchläuft und überprüft, ob der Claim durch den Kontext mithilfe eines Sprachmodells gestü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

  9. Tracing-Ergebnisse sehen folgendermaßen aus:

    Ein Screenshot, der zeigt, wie eine Methode mit einem Dekorator im Trace angezeigt wird.

  10. Möglicherweise möchten 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 ebenfalls zu verfolgen und die Logs 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:

  1. Instrumentieren Sie das OpenAI SDK wie gewohnt.

    from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

  2. Konfigurieren von 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)

  3. 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 Ablaufverfolgungen sofort in Ihrer Entwicklungsumgebung sehen.

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

Verwandte Inhalte

  • Last updated on