Visualizar resultados de rastreamento para aplicativos de IA usando o OpenAI SDK

Observação

Este documento refere-se ao portal Microsoft Foundry (clássico).

🔍 Consulte a documentação (nova) da Microsoft Foundry para saber mais sobre o novo portal.

Saiba como visualizar resultados de rastreamento que fornecem visibilidade na execução de aplicativos de IA. Use rastreamentos para diagnosticar chamadas de ferramentas imprecisas, sugestões enganosas, gargalos de latência e pontuações de avaliação de baixa qualidade.

Neste artigo, você aprenderá a:

Habilite o rastreamento para um projeto.
Implemente o SDK da OpenAI.
Capturar conteúdo da mensagem (opcional).
Visualizar linhas de tempo e segmentos de rastreamento.
Conecte a rastreação com ciclos de avaliação.

Este artigo explica como visualizar resultados de rastreamento para aplicações de IA usando o SDK OpenAI com OpenTelemetry no Microsoft Foundry.

Prerequisites

Você precisa do seguinte para concluir este tutorial:

Um projeto Foundry foi criado.
Uma aplicação de IA que utiliza o OpenAI SDK para fazer chamadas a modelos alojados no Foundry.

Habilitar o rastreamento em seu projeto

A Foundry armazena vestígios no Azure Application Insights usando OpenTelemetry. Os novos recursos não provisionam o Application Insights automaticamente. Associe (ou crie) um recurso uma única vez para cada recurso da Foundry.

As etapas a seguir mostram como configurar seu recurso:

Vai ao portal da Foundry e navega até ao teu projeto.
Na barra de navegação lateral, selecione Rastreamento.
Se um recurso Azure Application Insights não estiver associado ao seu recurso Foundry, associe um. Se você já tiver um recurso do Application Insights associado, não verá a página de habilitação abaixo e poderá ignorar esta etapa.
1. Para reutilizar um recurso do Azure Application Insights existente, use o menu suspenso nome do recurso Application Insights para localizar o recurso e selecione Conectar.
  
  Tip
  
  Para te ligares a um Azure Application Insights existente, precisas pelo menos de acesso dos colaboradores ao recurso (ou Hub) do Foundry.
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 defeito, o novo recurso é criado no mesmo grupo de recursos onde o recurso da Foundry foi criado. Use a opção Configurações avançadas para configurar um grupo de recursos ou 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 ligá-lo ao recurso Foundry.
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 Log Analytics Reader atribuída em seu recurso do 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 de destino do seu projeto e copie o URI do ponto de extremidade do projeto. Você precisa dele mais tarde.

Important

Usar o ponto de extremidade de um projeto requer a configuração do 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.

Ver resultados de rastreio no portal Foundry

Depois de configurar o traçado e da sua aplicação ser instrumentada, pode visualizar os resultados dos traços no portal Foundry:

Vai ao portal da Foundry e navega até ao teu projeto.
Na barra de navegação lateral, selecione Rastreamento.
Você verá uma lista de resultados de rastreamento de seus aplicativos instrumentados. Cada traço mostra:
- ID de rastreamento: identificador exclusivo para o rastreamento
- Hora de início: quando o rastreamento começou
- Duração: Quanto tempo demorou a operação
- Estado: Estado de sucesso ou falha
- Operações: Número de spans no traço
Selecione qualquer rastreamento para visualizar resultados detalhados do rastreamento, incluindo:
- Cronograma de execução completo
- Dados de entrada e saída para cada operação
- Métricas de desempenho e tempo
- Detalhes do erro, se algum ocorreu
- Atributos e metadados personalizados

Configurar o SDK da OpenAI

Ao desenvolver com o SDK OpenAI, pode instrumentar o seu código para que os traços sejam enviados para o 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 do Application Insights vinculado (Project > Tracing > Gerir 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()

Configurar o Azure Monitor e instrumentalizar o 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()

Envie um pedido:

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)

Volte para Rastreamento no portal para visualizar novos rastreamentos.
Pode ser útil capturar seções do seu código que misturam lógica de negócios com modelos ao desenvolver aplicativos complexos. O OpenTelemetry usa o conceito de extensões para capturar seções nas quais você está interessado. Para começar a gerar suas próprias extensões , 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 em seu código que você está interessado. Estes decoradores geram vãos automaticamente. O exemplo de código a seguir instrumenta um método chamado assess_claims_with_context que itera sobre uma lista de declarações e verifica se a declaração é suportada pelo contexto usando um LLM. Todas as chamadas feitas neste método são capturadas dentro do mesmo período:

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 rastreio têm a seguinte aparência:

Você também pode querer adicionar informações extras à extensão atual. OpenTelemetry usa o conceito de atributos para isso. Use o trace objeto 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

Rastrear para o 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 automatizado de CI/CD. Os vestígios podem ser enviados para a consola e capturados pela sua ferramenta CI/CD para análise posterior.

Configure o rastreamento da seguinte maneira:

Instrua o SDK da OpenAI como de costume.

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Configurar OpenTelemetry para enviar traços 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 OpenAI SDK 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": ""
    }
}

Rastreie localmente com o AI Toolkit

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

O kit de ferramentas suporta o OpenAI SDK e outras estruturas de IA através do OpenTelemetry. Você pode ver traços de imediato no seu ambiente de desenvolvimento.

Para obter instruções detalhadas de configuração e exemplos de código específicos do SDK, consulte Rastreamento no AI Toolkit.

Agentes de rastreamento usando o Microsoft Foundry SDK

Feedback

Esta página foi útil?

Last updated on 2025-11-22