Spåra AI-program med OpenAI SDK

2025-06-16

Spårning ger djup insyn i körningen av ditt program genom att samla in detaljerad telemetri vid varje körningssteg. Detta hjälper till att diagnostisera problem och förbättra prestanda genom att identifiera problem som felaktiga verktygsanrop, vilseledande uppmaningar, hög svarstid, utvärderingspoäng av låg kvalitet med mera.

Den här artikeln beskriver hur du implementerar spårning för AI-program med OpenAI SDK med OpenTelemetry i Azure AI Foundry.

Förutsättningar

Du behöver följande för att slutföra den här självstudien:

Ett Azure AI Foundry-projekt har skapats.
Ett AI-program som använder OpenAI SDK för att göra anrop till modeller som finns i Azure AI Foundry.

Aktivera spårning i projektet

Azure AI Foundry lagrar spårningar i Azure Application Insight-resurser med hjälp av OpenTelemetry. Som standard etablerar inte nya Azure AI Foundry-resurser dessa resurser. Du kan ansluta projekt till en befintlig Azure Application Insights-resurs eller skapa en ny inifrån projektet. Du gör en sådan konfiguration en gång per varje Azure AI Foundry-resurs.

Följande steg visar hur du konfigurerar din resurs:

Gå till Azure AI Foundry-portalen och gå till projektet.
I sidonavigeringsfältet väljer du Spårning.
Om en Azure Application Insights-resurs inte är associerad med din Azure AI Foundry-resurs associerar du en.
Om du vill återanvända en befintlig Azure Application Insights använder du det nedrullningsbara Resursnamnet för Application Insights för att hitta resursen och väljer Anslut.

Tips/Råd

För att ansluta till en befintlig Azure Application Insights behöver du minst deltagaråtkomst till Azure AI Foundry-resursen (eller hubben).
Om du vill ansluta till en ny Azure Application Insights-resurs väljer du alternativet Skapa ny.
1. Använd konfigurationsguiden för att konfigurera den nya resursens namn.
2. Som standard skapas den nya resursen i samma resursgrupp där Azure AI Foundry-resursen skapades. Använd alternativet Avancerat inställningar för att konfigurera en annan resursgrupp eller prenumeration.
  
  Tips/Råd
  
  Om du vill skapa en ny Azure Application Insight-resurs behöver du också deltagarrollen till den resursgrupp som du har valt (eller standardresursen).
3. Välj Skapa för att skapa resursen och ansluta den till Azure AI Foundry-resursen.
När anslutningen har konfigurerats är du redo att använda spårning i alla projekt i resursen.
Gå till projektets landningssida och kopiera projektets slutpunkts-URI. Du behöver det senare i självstudien.

Viktigt!

Om du använder ett projekts slutpunkt måste du konfigurera Microsoft Entra-ID i ditt program. Om du inte har konfigurerat Etttra-ID använder du Anslutningssträngen för Azure Application Insights enligt beskrivningen i steg 3 i självstudien.

Instrumentera OpenAI SDK

När du utvecklar med OpenAI SDK kan du instrumentera koden så att spårningar skickas till Azure AI Foundry. Följ dessa steg för att instrumentera koden:

Installera azure-ai-projects, azure-monitor-opentelemetryoch opentelemetry-instrumentation-openai-v2 i din miljö. I följande exempel används pip:
```
pip install azure-ai-projects azure-monitor-opentelemetry opentelemetry-instrumentation-openai-v2
```

Instrumentera OpenAI SDK med hjälp av OpenAIInstrumentor().

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Hämta anslutningssträngen till Azure Application Insights-resursen som är associerad med projektet. Följande rad använder Azure AI Project-klienten, som kräver användning av Microsoft Entra-ID för autentisering:
```
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()
```
Tips/Råd

Anslutningssträngar till Azure Application Insights ser ut som InstrumentationKey=aaaa0a0a-bb1b-cc2c-dd3d-eeeee4e4e4e;.... Du kan också komma åt anslutningssträngen som används i projektet från avsnittet Spårning i Azure AI Foundry-portalen. I det övre navigeringsfältet väljer du Hantera datakälla och kopierar anslutningssträngen. Konfigurera anslutningssträngen i en miljövariabel.

Konfigurera OpenTelemetry för att skicka spårningar till Azure Application Insights:

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(connection_string=connection_string)

Som standard samlar OpenTelemetry inte in indata och utdata. Använd miljövariabeln OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true för att samla in dem. Kontrollera att den här miljövariabeln är konfigurerad på den miljönivå där koden körs.

Använd OpenAI SDK som vanligt:

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."},
    ],
)

Om du går tillbaka till Azure AI Foundry-portalen bör du se spårningen som visas:
Det kan vara användbart att samla in delar av koden som blandar affärslogik med modeller när du utvecklar komplexa program. OpenTelemetry använder begreppet spans för att samla in avsnitt som du är intresserad av. Om du vill börja generera dina egna intervall hämtar du en instans av det aktuella spårningsobjektet.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Använd sedan dekoratörer i din metod för att samla in specifika scenarier i din kod som du är intresserad av. Sådana dekoratörer genererar intervall automatiskt. Följande kodexempel instrumenterar en metod som heter assess_claims_with_context med itererar över en lista över anspråk och kontrollerar om anspråket stöds av kontexten med hjälp av en LLM. Alla anrop som görs i den här metoden samlas in inom samma intervall:

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

Spårningar ser ut så här:

Du kanske också vill lägga till extra information i det aktuella intervallet. OpenTelemetry använder begreppet attribut för detta. Använd objektet trace för att komma åt dem och inkludera extra information. Se hur assess_claims_with_context metoden har ändrats för att inkludera ett 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

Skriv ut till konsolen

Det kan vara användbart att även spåra ditt program och skicka spårningarna till den lokala körningskonsolen. En sådan metod kan leda till fördelar när du kör enhetstester eller integreringstester i ditt program med hjälp av en automatiserad CI/CD-pipeline. Spårningar kan skickas till konsolen och samlas in av ditt CI/CD-verktyg för ytterligare analys.

Konfigurera spårning på följande sätt:

Instrumentera OpenAI SDK som vanligt:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Konfigurera OpenTelemetry för att skicka spårningar till konsolen:

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)

Använd OpenAI SDK som vanligt:

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

Nästa steg

Spåra agenter med Azure AI Foundry SDK