Exibir resultados de rastreamento para aplicativos de IA usando o SDK do OpenAI

2025-09-22

Saiba como exibir resultados de rastreamento que fornecem visibilidade da execução do aplicativo de IA. Use rastreamentos para diagnosticar chamadas de ferramenta imprecisas, prompts enganosos, gargalos de latência e pontuações de avaliação de baixa qualidade.

Neste artigo, você aprenderá a:

Habilite o rastreamento para um projeto.
Instrumente o SDK do OpenAI.
Capturar o conteúdo da mensagem (opcional).
Exibir linhas do tempo e intervalos de rastreamento.
Conecte o rastreamento com ciclos de avaliação.

Este artigo explica como exibir resultados de rastreamento para aplicativos de IA usando o SDK do OpenAI com o OpenTelemetry no Azure AI Foundry.

Prerequisites

Você precisa do seguinte para concluir este tutorial:

Um projeto do Azure AI Foundry foi criado.
Um aplicativo de IA que usa o SDK do OpenAI para fazer chamadas a modelos hospedados na Fábrica de IA do Azure.

Habilitar o rastreamento em seu projeto

O Azure AI Foundry armazena rastreamentos no Azure Application Insights usando o OpenTelemetry. Novos recursos não provisionam o Application Insights automaticamente. Associe (ou crie) um recurso uma vez por recurso do Azure AI Foundry.

As etapas a seguir mostram como configurar seu recurso:

Acesse o portal do Azure AI Foundry e navegue até seu projeto.
Na barra de navegação lateral, selecione Rastreamento.
Se um recurso do Azure Application Insights não estiver associado ao recurso do Azure AI Foundry, associe um. Se você já tiver um recurso do Application Insights associado, a página de habilitação abaixo não será exibida e você poderá ignorar esta etapa.
1. Para reutilizar um Application Insights do Azure existente, use o menu suspenso Nome do recurso do Application Insights para localizar o recurso e selecione Conectar.
  
  Tip
  
  Para se conectar a um Azure Application Insights existente, você precisa de pelo menos acesso de colaborador ao recurso do Azure AI Foundry (ou Hub).
2. Para se conectar a um novo recurso do Azure Application Insights, selecione a opção Criar novo.
  1. Use o assistente de configuração para configurar o nome do novo recurso.
  2. Por padrão, o novo recurso é criado no mesmo grupo de recursos em que o recurso Azure AI Foundry foi criado. Use a opção Configurações avançadas para configurar um grupo de recursos ou uma assinatura diferente.
    
    Tip
    
    Para criar um novo recurso do Azure Application Insights, você também precisa da função de colaborador para o grupo de recursos selecionado (ou o padrão).
  3. Selecione Criar para criar o recurso e conectá-lo ao recurso da Fábrica de IA do Azure.
3. Depois que a conexão estiver configurada, você estará pronto para usar o rastreamento em qualquer projeto dentro do recurso.
Tip

Verifique se você tem a função leitor do Log Analytics atribuída no recurso application insights. Para saber mais sobre como atribuir funções, consulte Atribuir funções do Azure usando o portal do Azure. Use os grupos do Microsoft Entra para gerenciar mais facilmente o acesso dos usuários.
Vá para a página inicial do projeto e copie o URI do endpoint do projeto. Isso será necessário mais tarde.

Important

Usar um endpoint de projeto requer configurar o Microsoft Entra ID em seu aplicativo. Se você não tiver a ID do Entra configurada, use a cadeia de conexão do Azure Application Insights, conforme indicado na etapa 3 do tutorial.

Exibir resultados de rastreamento no portal do Azure AI Foundry

Depois de configurar o rastreamento e o aplicativo ser instrumentado, você poderá exibir os resultados do rastreamento no portal do Azure AI Foundry:

Acesse o portal do Azure AI Foundry e navegue até seu projeto.
Na barra de navegação lateral, selecione Rastreamento.
Você verá uma lista de resultados de rastreamento de seus aplicativos instrumentados. Cada rastreamento mostra:
- ID de rastreamento: identificador exclusivo para o rastreamento
- Hora de início: quando o rastreamento começou
- Duração: quanto tempo a operação levou
- Status: Êxito ou status de falha
- Operações: Número de intervalos no rastreamento
Selecione qualquer rastreamento para exibir os resultados detalhados do rastreamento, incluindo:
- Linha completa do tempo de execução
- Dados de entrada e saída para cada operação
- Métricas de desempenho e tempo
- Detalhes do erro se ocorreu algum
- Atributos e metadados personalizados

Instrumentar o SDK do OpenAI

Ao desenvolver com o SDK do OpenAI, você pode instrumentar seu código para que os rastreamentos sejam enviados ao Azure AI Foundry. Siga estas etapas para instrumentar seu código:

Instalar pacotes:

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

(Opcional) Capturar conteúdo da mensagem:
- PowerShell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Obtenha a cadeia de conexão para o recurso vinculado do Application Insights (Projeto > Rastreamento > Gerenciar fonte de dados > Cadeia de conexão):

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

Configure o Azure Monitor e instrumente o SDK do OpenAI.

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

configure_azure_monitor(connection_string=connection_string)
OpenAIInstrumentor().instrument()

Enviar uma solicitação:

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)

Retorne ao Rastreamento no portal para exibir novos rastreamentos.
Pode ser útil capturar seções do código que misturam lógica de negócios com modelos ao desenvolver aplicativos complexos. O OpenTelemetry usa o conceito de intervalos para capturar seções nas quais você está interessado. Para começar a gerar seus próprios intervalos, obtenha uma instância do objeto rastreador atual.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Em seguida, use decoradores em seu método para capturar cenários específicos no código em que você está interessado. Esses decoradores geram intervalos automaticamente. O exemplo de código a seguir instrumenta um método chamado assess_claims_with_context que itera em uma lista de declarações e verifica se a declaração tem suporte pelo contexto usando um LLM. Todas as chamadas feitas neste método são capturadas no mesmo intervalo:

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

Os resultados do rastreamento são os seguintes:

Talvez você também queira adicionar informações extras ao intervalo atual. O OpenTelemetry usa o conceito de atributos para isso. Use o objeto trace para acessá-los e incluir informações extras. Veja como o assess_claims_with_context método foi modificado para incluir um atributo:

@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

Rastreamento para console

Pode ser útil também rastrear seu aplicativo e enviar os rastreamentos para o console de execução local. Essa abordagem pode ser benéfica ao executar testes de unidade ou testes de integração em seu aplicativo usando um pipeline de CI/CD automatizado. Os rastreamentos podem ser enviados para o console e capturados pela ferramenta CI/CD para análise adicional.

Configure o rastreamento da seguinte maneira:

Implemente o SDK do OpenAI como de costume.

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Configure o OpenTelemetry para enviar rastreamentos para o 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)

Use o SDK do OpenAI como de costume:

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

Rastrear localmente com o Kit de Ferramentas de IA

O Kit de Ferramentas de IA oferece uma maneira simples de rastrear localmente no VS Code. Ele usa um coletor compatível com OTLP local, tornando-o perfeito para desenvolvimento e depuração sem precisar de acesso à nuvem.

O kit de ferramentas dá suporte ao SDK do OpenAI e a outras estruturas de IA por meio do OpenTelemetry. Você pode ver os traços instantaneamente em seu ambiente de desenvolvimento.

Para obter instruções de instalação detalhadas e exemplos de código específicos do SDK, consulte Rastreamento no Kit de Ferramentas de IA.

Rastrear agentes usando o SDK do Azure AI Foundry

Comentários

Esta página foi útil?