Visualizzare i risultati della traccia per le applicazioni di intelligenza artificiale con OpenAI SDK (versione classica)

Si applica solo a:Portale di Foundry (versione classica). Questo articolo non è disponibile per il nuovo portale foundry. Altre informazioni sul nuovo portale.

Nota

I collegamenti in questo articolo potrebbero aprire contenuto nella nuova documentazione di Microsoft Foundry anziché nella documentazione di Foundry (versione classica) visualizzata.

Informazioni su come visualizzare i risultati della traccia che offrono visibilità sull'esecuzione dell'applicazione di intelligenza artificiale. Sono utilizzate le tracce per diagnosticare invocazioni di strumenti non accurate, messaggi di comando fuorvianti, colli di bottiglia della latenza e punteggi di valutazione della qualità bassa.

Questo articolo illustra come:

Abilitare il tracciamento per un progetto.
Integrare l'SDK di OpenAI.
Acquisire il contenuto del messaggio (facoltativo).
Visualizza le sequenze temporali e segmenti di traccia.
Connettere il tracciamento con i cicli di valutazione.

Questo articolo illustra come visualizzare i risultati della traccia per le applicazioni di intelligenza artificiale usando OpenAI SDK con OpenTelemetry in Microsoft Foundry.

Prerequisiti

Per completare questa esercitazione, è necessario quanto segue:

Un progetto Foundry creato.
Un'applicazione di intelligenza artificiale che usa OpenAI SDK per effettuare chiamate ai modelli ospitati in Foundry.

Abilitare il tracciamento nel progetto

Foundry archivia le tracce in applicazione Azure Insights usando OpenTelemetry. Le nuove risorse non effettuano automaticamente il provisioning di Application Insights. Associare (o creare) una risorsa una volta per ogni risorsa Foundry.

La procedura seguente illustra come configurare la risorsa:

Passare al portale di Foundry e passare al progetto.
Sulla barra di navigazione laterale, selezionare Tracing.
Se una risorsa applicazione Azure Insights non è associata alla risorsa Foundry, associarne una. Se è già associata una risorsa di Application Insights, non verrà visualizzata la pagina di abilitazione seguente ed è possibile ignorare questo passaggio.

Uno screenshot che mostra come configurare applicazione Azure Insights alla risorsa di Foundry.
1. Per riutilizzare un applicazione Azure Insights esistente, usare l'elenco a discesa Nome risorsa di Application Insights per individuare la risorsa e selezionare Connetti.
  
  Suggerimento
  
  Per connettersi a un applicazione Azure Insights esistente, è necessario almeno l'accesso collaboratore alla risorsa Foundry (o all'hub).
2. Per connettersi a una nuova risorsa applicazione Azure Insights, selezionare l'opzione Crea nuovo.
  1. Usare la configurazione guidata per configurare il nome della nuova risorsa.
  2. Per impostazione predefinita, la nuova risorsa viene creata nello stesso gruppo di risorse in cui è stata creata la risorsa Foundry. Usare l'opzione Impostazioni avanzate per configurare un gruppo di risorse o una sottoscrizione diversa.
    
    Suggerimento
    
    Per creare una nuova risorsa applicazione Azure Insights, è necessario anche il ruolo di collaboratore per il gruppo di risorse selezionato (o quello predefinito).
  3. Selezionare Crea per creare la risorsa e connetterla alla risorsa Foundry.
3. Dopo aver configurato la connessione, è possibile usare la traccia in qualsiasi progetto all'interno della risorsa.
Suggerimento

Assicurati che il ruolo di Lettore di Log Analytics sia assegnato nella tua risorsa di Application Insights. Per altre informazioni su come assegnare ruoli, vedere Assegnare ruoli Azure usando il portale di Azure. Usare Microsoft Entra gruppi per gestire più facilmente l'accesso per gli utenti.
Passare alla pagina di destinazione del progetto e copiare l'URI dell'endpoint del progetto. Sarà necessario in un secondo momento.

Importante

L'uso dell'endpoint di un progetto richiede la configurazione di Microsoft Entra ID nell'applicazione. Se non è stato configurato Entra ID, utilizzare la stringa di connessione di applicazione Azure Insights come indicato nel passaggio 3 della guida.

Visualizzare i risultati di traccia nel portale Foundry

Dopo aver configurato la traccia e aver instrumentato l'applicazione, è possibile visualizzare i risultati della traccia nel portale foundry:

Passare al portale di Foundry e passare al progetto.
Sulla barra di navigazione laterale, selezionare Tracing.
Verrà visualizzato un elenco di risultati di traccia dalle applicazioni strumentate. Ogni traccia mostra:
- ID traccia: identificatore univoco per la traccia
- Ora di inizio: inizio della traccia
- Durata: durata dell'operazione
- Stato: stato di esito positivo o negativo
- Operazioni: numero di intervalli nella traccia
Selezionare qualsiasi traccia per visualizzare i risultati dettagliati della traccia, tra cui:
- Sequenza temporale di esecuzione completa
- Dati di input e output per ogni operazione
- Metriche delle prestazioni e tempi
- Dettagli dell'errore se si verificano
- Attributi e metadati personalizzati

Implementare l'SDK di OpenAI

Quando si sviluppa con OpenAI SDK, è possibile instrumentare il codice in modo che le tracce vengano inviate a Foundry. Seguire questa procedura per instrumentare il codice:

Installare i pacchetti:

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

(Facoltativo) Acquisire il contenuto del messaggio:
- Powershell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Ottieni la stringa di connessione per la risorsa di Application Insights collegata (Progetto > Tracing > Gestisci origine dati > Stringa di connessione):

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

Configurare Monitoraggio di Azure e instrumentare 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()

Inviare una richiesta:

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)

Tornare a Traccia nel portale per visualizzare nuove tracce.
Potrebbe essere utile acquisire sezioni del codice che combinano la logica di business con i modelli durante lo sviluppo di applicazioni complesse. OpenTelemetry usa il concetto di intervalli per acquisire sezioni a cui si è interessati. Per iniziare a generare i propri span, ottenete un'istanza dell'oggetto tracer corrente.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Usa quindi i decoratori nel tuo metodo per acquisire scenari specifici nel codice che ti interessano. Questi decoratori generano automaticamente segmenti. L'esempio di codice seguente implementa un metodo denominato assess_claims_with_context che scorre un elenco di richieste e verifica se la richiesta è supportata dal contesto usando un modello linguistico di grandi dimensioni. Tutte le chiamate effettuate in questo metodo vengono acquisite nello stesso intervallo:

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

I risultati della traccia hanno l'aspetto seguente:

È anche possibile aggiungere informazioni aggiuntive all'intervallo corrente. OpenTelemetry usa il concetto di attributi per tale attributo. Usare l'oggetto trace per accedervi e includere informazioni aggiuntive. Vedere come il assess_claims_with_context metodo è stato modificato per includere un attributo:

@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

Traccia nella console

Può essere utile anche tracciare l'applicazione e inviare le tracce alla console di esecuzione locale. Questo approccio può essere utile quando si eseguono unit test o test di integrazione nell'applicazione usando una pipeline CI/CD automatizzata. Le tracce possono essere inviate alla console e acquisite dallo strumento CI/CD per ulteriori analisi.

Configurare la traccia come indicato di seguito:

Abilitare il SDK di OpenAI come di consueto:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Configurare OpenTelemetry per inviare tracce alla console:

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)

Usare OpenAI SDK come di consueto:

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

Traccia in locale con AI Toolkit

AI Toolkit offre un modo semplice per tracciare localmente in VS Code. Usa un agente di raccolta compatibile con OTLP locale, rendendolo perfetto per lo sviluppo e il debug senza bisogno di accesso al cloud.

Il toolkit supporta OpenAI SDK e altri framework di intelligenza artificiale tramite OpenTelemetry. È possibile visualizzare le tracce immediatamente nell'ambiente di sviluppo.

Per istruzioni dettagliate sulla configurazione e esempi di codice specifici dell'SDK, vedere Tracing in AI Toolkit.

Traccia agenti usando Microsoft Foundry SDK

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-05-01