Wyświetlanie wyników śledzenia aplikacji sztucznej inteligencji przy użyciu zestawu OpenAI SDK

Uwaga / Notatka

Ten dokument odnosi się do portalu Microsoft Foundry (klasycznego).

🔍 Zapoznaj się z dokumentacją rozwiązania Microsoft Foundry (nową), aby dowiedzieć się więcej o nowym portalu.

Dowiedz się, jak wyświetlać wyniki śledzenia, które zapewniają wgląd w wykonywanie aplikacji sztucznej inteligencji. Użyj śladów, aby zdiagnozować niedokładne wywołania narzędzi, mylące komunikaty, wąskie gardła przepustowości i niskiej jakości oceny wyników.

W tym artykule dowiesz się, jak:

Włącz śledzenie projektu.
Zainstrumentuj OpenAI SDK.
Przechwyć zawartość wiadomości (opcjonalnie).
Wyświetl osie czasu śledzenia i zakresy.
Połącz śledzenie z pętlami oceny.

W tym artykule wyjaśniono, jak wyświetlać wyniki śledzenia aplikacji sztucznej inteligencji przy użyciu zestawu OpenAI SDK z funkcją OpenTelemetry w rozwiązaniu Microsoft Foundry.

Prerequisites

Do ukończenia tego samouczka potrzebne są następujące elementy:

Utworzono projekt Foundry.
Aplikacja sztucznej inteligencji korzystająca z zestawu OpenAI SDK do nawiązywania wywołań do modeli hostowanych w rozwiązaniu Foundry.

Włączanie śledzenia w projekcie

Foundry przechowuje ślady w Azure Application Insights, korzystając ze specyfikacji OpenTelemetry. Nowe zasoby nie aprowizują automatycznie usługi Application Insights. Skojarz (lub utwórz) zasób jeden raz na zasób Foundry.

W poniższych krokach pokazano, jak skonfigurować zasób:

Przejdź do portalu Foundry i przejdź do projektu.
Na pasku nawigacyjnym po stronie wybierz pozycję Śledzenie.
Jeśli zasób usługi Azure Application Insights nie jest skojarzony z zasobem usługi Foundry, skojarz go. Jeśli masz już skojarzony zasób usługi Application Insights, nie zobaczysz poniższej strony włączania i możesz pominąć ten krok.
1. Aby ponownie użyć istniejącej usługi Azure Application Insights, użyj nazwy zasobu usługi Application Insights z listy rozwijanej, aby zlokalizować zasób i wybrać pozycję Połącz.
  
  Tip
  
  Aby nawiązać połączenie z istniejącą usługą Azure Application Insights, musisz mieć co najmniej dostęp współtwórcy do zasobu Foundry (lub hubu).
2. Aby nawiązać połączenie z nowym zasobem usługi Azure Application Insights, wybierz opcję Utwórz nowy.
  1. Użyj kreatora konfiguracji, aby skonfigurować nazwę nowego zasobu.
  2. Domyślnie nowy zasób jest tworzony w tej samej grupie zasobów, w której został utworzony zasób foundry. Użyj opcji Ustawienia zaawansowane , aby skonfigurować inną grupę zasobów lub subskrypcję.
    
    Tip
    
    Aby utworzyć nowy zasób usługi Azure Application Insights, musisz również mieć rolę współautora do wybranej grupy zasobów (lub domyślnej).
  3. Wybierz pozycję Utwórz , aby utworzyć zasób i połączyć go z zasobem Foundry.
3. Po skonfigurowaniu połączenia możesz używać śledzenia w dowolnym projekcie w ramach zasobu.
Tip

Upewnij się, że w zasobie Application Insights masz przypisaną rolę Log Analytics Reader. Aby dowiedzieć się więcej na temat przypisywania ról, zobacz Przypisywanie ról platformy Azure przy użyciu witryny Azure Portal. Użyj grup Firmy Microsoft Entra , aby łatwiej zarządzać dostępem dla użytkowników.
Przejdź do strony docelowej projektu i skopiuj identyfikator URI punktu końcowego projektu. Potrzebujesz go później.

Important

Korzystanie z punktu końcowego projektu wymaga skonfigurowania identyfikatora Entra firmy Microsoft w aplikacji. Jeśli nie masz skonfigurowanego identyfikatora Entra, użyj parametrów połączenia usługi Azure Application Insights wskazanych w kroku 3 samouczka.

Wyświetlanie wyników śledzenia w portalu Foundry

Po skonfigurowaniu śledzenia i instrumentacji aplikacji możesz wyświetlić wyniki śledzenia w portalu Foundry:

Przejdź do portalu Foundry i przejdź do projektu.
Na pasku nawigacyjnym po stronie wybierz pozycję Śledzenie.
Zostanie wyświetlona lista wyników śledzenia z instrumentowanych aplikacji. Każdy ślad pokazuje:
- Trace ID: unikatowy identyfikator śladu
- Godzina rozpoczęcia: kiedy rozpoczęto śledzenie
- Czas trwania: jak długo trwała operacja
- Stan: Stan powodzenia lub niepowodzenia
- Operacje: liczba zakresów w śladzie
Wybierz dowolny ślad, aby wyświetlić szczegółowe wyniki śledzenia, w tym:
- Kompletny harmonogram wykonania
- Dane wejściowe i wyjściowe dla każdej operacji
- Metryki wydajności i czas
- Szczegóły błędu, jeśli wystąpiły
- Atrybuty niestandardowe i metadane

Instrumentacja zestawu OpenAI SDK

Podczas opracowywania za pomocą zestawu OpenAI SDK można instrumentować kod, aby ślady zostały wysłane do rozwiązania Foundry. Wykonaj następujące kroki, aby instrumentować kod:

Instalowanie pakietów:

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

(Opcjonalnie) Przechwyć zawartość wiadomości:
- PowerShell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Pobierz ciąg połączenia dla połączonego zasobu usługi Application Insights (Projekt > Śledzenie > Zarządzanie źródłem danych > Ciąg połączenia):

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

Konfigurowanie usługi Azure Monitor i instrumentacja zestawu 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()

Wyślij żądanie:

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)

Wróć do Śledzenia w portalu, aby wyświetlić nowe ślady.
Przydatne może być przechwytywanie sekcji kodu, które mieszają logikę biznesową z modelami podczas tworzenia złożonych aplikacji. OpenTelemetry używa koncepcji odcinków do przechwytywania sekcji, które Cię interesują. Aby rozpocząć generowanie własnych zakresów, pobierz wystąpienie bieżącego obiektu tracer .
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Następnie użyj dekoratorów w metodzie, aby przechwycić określone scenariusze w kodzie, który Cię interesuje. Te dekoratory generują zakresy automatycznie. Poniższy przykład kodu instrumentuje metodę o nazwie assess_claims_with_context , która iteruje listę oświadczeń i sprawdza, czy oświadczenie jest obsługiwane przez kontekst przy użyciu usługi LLM. Wszystkie wywołania realizowane przez tę metodę są rejestrowane w tym samym zakresie.

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

Wyniki śledzenia wyglądają następująco:

Możesz również dodać dodatkowe informacje do bieżącego zakresu. Funkcja OpenTelemetry używa dla tego pojęcia atrybutów . Użyj obiektu , trace aby uzyskać do nich dostęp i dołączyć dodatkowe informacje. Zobacz, jak metoda w assess_claims_with_context została zmodyfikowana, aby uwzględnić atrybut:

@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

Śledzenie do konsoli

Przydatne może być również śledzenie aplikacji i wysyłanie śladów do lokalnej konsoli wykonywania. Takie podejście może być korzystne podczas uruchamiania testów jednostkowych lub testów integracji w aplikacji przy użyciu zautomatyzowanego potoku ciągłej integracji/ciągłego wdrażania. Ślady można wysyłać do konsoli i przechwytywane przez narzędzie ciągłej integracji/ciągłego wdrażania w celu dalszej analizy.

Skonfiguruj śledzenie w następujący sposób:

Zainstaluj ten zestaw SDK OpenAI w zwykły sposób.

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Skonfiguruj usługę OpenTelemetry, aby wysyłać ślady do konsoli:

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)

Użyj zestawu OpenAI SDK w zwykły sposób:

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

Śledzenie lokalnie za pomocą zestawu narzędzi AI Toolkit

Zestaw narzędzi AI Toolkit oferuje prosty sposób śledzenia lokalnie w programie VS Code. Używa on lokalnego modułu zbierającego zgodnego z protokołem OTLP, dzięki czemu doskonale nadaje się do programowania i debugowania bez konieczności uzyskiwania dostępu do chmury.

Zestaw narzędzi obsługuje zestaw OpenAI SDK i inne struktury sztucznej inteligencji za pośrednictwem biblioteki OpenTelemetry. Ślady są widoczne natychmiast w środowisku projektowym.

Aby uzyskać szczegółowe instrukcje dotyczące konfiguracji i przykłady kodu specyficzne dla zestawu SDK, zobacz Śledzenie w zestawie narzędzi AI Toolkit.

Śledzenie agentów przy użyciu zestawu Microsoft Foundry SDK

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-22