Trasování aplikací AI pomocí sady OpenAI SDK

2025-06-16

Trasování poskytuje podrobný přehled o provádění vaší aplikace zachycením podrobné telemetrie v každém kroku spuštění. To pomáhá diagnostikovat problémy a zvýšit výkon tím, že identifikuje problémy, jako jsou nepřesná volání nástrojů, zavádějící výzvy, vysoká latence, skóre hodnocení nízké kvality a další.

Tento článek vysvětluje, jak implementovat trasování pro aplikace AI pomocí sady OpenAI SDK s OpenTelemetry v Azure AI Foundry.

Požadavky

K dokončení tohoto kurzu potřebujete následující:

Vytvořil se projekt Azure AI Foundry.
Aplikace AI, která používá sadu OpenAI SDK k volání modelů hostovaných v Azure AI Foundry.

Povolení trasování v projektu

Azure AI Foundry ukládá stopy v prostředcích služby Azure Application Insight pomocí OpenTelemetry. Ve výchozím nastavení nové prostředky Azure AI Foundry tyto prostředky nezřizují. Projekty můžete připojit k existujícímu prostředku Azure Application Insights nebo vytvořit nový z projektu. Tuto konfiguraci provedete jednou pro každý prostředek Azure AI Foundry.

Následující kroky ukazují, jak nakonfigurovat prostředek:

Přejděte na portál Azure AI Foundry a přejděte do svého projektu.
Na bočním navigačním panelu vyberte Trasování.
Pokud prostředek Azure Application Insights není přidružený k vašemu prostředku Azure AI Foundry, přidružte ho.
Pokud chcete použít již existující službu Azure Application Insights, pomocí rozevíracího seznamu Název prostředku Application Insights vyhledejte prostředek a vyberte Připojit.

Návod

Pokud se chcete připojit k existující službě Azure Application Insights, potřebujete alespoň přístup přispěvatele k prostředku Azure AI Foundry (nebo centru).
Pokud se chcete připojit k novému prostředku Azure Application Insights, vyberte možnost Vytvořit nový.
1. Pomocí průvodce konfigurací nakonfigurujte název nového prostředku.
2. Ve výchozím nastavení se nový prostředek vytvoří ve stejné skupině prostředků, ve které byl vytvořen prostředek Azure AI Foundry. Pomocí možnosti Upřesnit nastavení nakonfigurujte jinou skupinu prostředků nebo předplatné.
  
  Návod
  
  Pokud chcete vytvořit nový prostředek Azure Application Insight, potřebujete také roli přispěvatele do vybrané skupiny prostředků (nebo výchozího prostředku).
3. Výběrem Vytvořit vytvořte prostředek a připojte ho k prostředku Azure AI Foundry.
Jakmile je připojení nakonfigurované, můžete použít trasování v jakémkoli projektu v rámci prostředku.
Přejděte na cílovou stránku projektu a zkopírujte identifikátor URI koncového bodu projektu. Budete ho potřebovat později v tomto kurzu.

Důležité

Použití koncového bodu projektu vyžaduje konfiguraci ID Microsoft Entra ve vaší aplikaci. Pokud nemáte nakonfigurované ID Entra, použijte připojovací řetězec Azure Application Insights, jak je uvedeno v kroku 3 kurzu.

Instrumentace sady OpenAI SDK

Při vývoji pomocí sady OpenAI SDK můžete instrumentovat kód, aby se trasování odesílaly do Azure AI Foundry. K instrumentaci kódu použijte tento postup:

Nainstalujte azure-ai-projects, azure-monitor-opentelemetrya opentelemetry-instrumentation-openai-v2 ve svém prostředí. Následující příklad používá pip:
```
pip install azure-ai-projects azure-monitor-opentelemetry opentelemetry-instrumentation-openai-v2
```

Instrumentace sady OpenAI SDK pomocí OpenAIInstrumentor():

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Získejte připojovací řetězec k prostředku Azure Application Insights přidruženému k vašemu projektu. Následující řádek používá klienta projektu Azure AI, který k ověřování vyžaduje použití ID Microsoft Entra:
```
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()
```
Návod

Připojovací řetězce ke službě Azure Application Insights vypadají takto InstrumentationKey=aaaa0a0a-bb1b-cc2c-dd3d-eeeee4e4e4e;.... K připojovacímu řetězci použitému v projektu se dostanete také z části Trasování na portálu Azure AI Foundry. V horním navigačním panelu vyberte Spravovat zdroj dat a zkopírujte připojovací řetězec. Nakonfigurujte připojovací řetězec v proměnné prostředí.

Konfigurace OpenTelemetry pro odesílání trasování do Azure Application Insights:

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(connection_string=connection_string)

OpenTelemetry ve výchozím nastavení nezachytává vstupy a výstupy. Pomocí proměnné OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true prostředí je zachyťte. Ujistěte se, že je tato proměnná prostředí nakonfigurovaná na úrovni prostředí, ve které je váš kód spuštěný.

Sadu OpenAI SDK používejte obvyklým způsobem:

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

Pokud se vrátíte na portál Azure AI Foundry, mělo by se zobrazit trasování.
Při vývoji složitých aplikací může být užitečné zachytit části kódu, které kombinují obchodní logiku s modely. OpenTelemetry používá koncept "spans" k zachycení úseků, které vás zajímají. Pokud chcete začít generovat vlastní rozsahy, získejte instanci aktuálního objektu traceru .
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Pak pomocí dekorátorů v metodě zachyťte konkrétní scénáře v kódu, které vás zajímají. Tyto dekorátory generují úseky automaticky. Následující příklad kódu instrumentuje metodu assess_claims_with_context, která prochází seznam nároků a ověřuje, zda je nárok podporován kontextem pomocí LLM. Všechna volání provedená v této metodě jsou zaznamenána ve stejném rozsahu:

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

Trasování vypadá takto:

Do aktuálního rozsahu můžete také přidat další informace. OpenTelemetry používá pro to koncept atributů . trace Objekt použijte pro přístup k nim a uveďte další informace. Podívejte se, assess_claims_with_context jak byla metoda upravena tak, aby zahrnovala atribut:

@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

Trasování do konzoly

Je užitečné také sledovat vaši aplikaci a posílat sledování do místní konzoly pro spuštění. Takový přístup může být užitečný při spouštění testů jednotek nebo integračních testů ve vaší aplikaci pomocí automatizovaného kanálu CI/CD. Stopy mohou být odeslány do konzole a zachyceny vaším nástrojem CI/CD pro další analýzu.

Trasování nakonfigurujte následujícím způsobem:

Instrumentace sady OpenAI SDK jako obvykle:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Nakonfigurujte OpenTelemetry tak, aby odesílala trasování do konzoly:

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)

Použijte SDK OpenAI obvyklým způsobem:

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

Další kroky

Trasování agentů pomocí sady Azure AI Foundry SDK