Ver resultados de rastreamento para aplicações de IA usando OpenAI SDK (clássico)

Aplica-se apenas a:Portal Foundry (clássico). Este artigo não está disponível para o novo portal da Foundry. Saiba mais sobre o novo portal.

Nota

Os links neste artigo podem abrir conteúdo na nova documentação do Microsoft Foundry em vez da documentação do Foundry (clássico) que está a ver agora.

Aprenda a visualizar resultados de rastreamento que proporcionam visibilidade sobre a execução de aplicações de IA. Use traços para diagnosticar chamadas de ferramentas imprecisas, prompts enganadores, gargalos de latência e pontuações de avaliação de baixa qualidade.

Neste artigo, aprende como:

  • Ativar o rastreamento para um projeto.
  • Configure o SDK da OpenAI.
  • Capturar conteúdo da mensagem (opcional).
  • Ver linhas temporais e intervalos de rastreio.
  • Liga o rastreio com os ciclos de avaliação.

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

Pré-requisitos

Precisa do seguinte para completar 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.

Ative o rastreamento no seu projeto

Foundry armazena traces no Aplicação Azure Insights usando OpenTelemetry. Os novos recursos não fornecem o Application Insights automaticamente. Associe (ou crie) um recurso uma vez por recurso da Foundry.

Os passos seguintes mostram como configurar o seu recurso:

  1. Vai ao portal da Foundry e navega até ao teu projeto.

  2. Na barra de navegação lateral, selecione Traçar.

  3. Se um recurso do Aplicação Azure Insights não estiver associado ao seu recurso Foundry, associe um. Se já tiver um recurso do Application Insights associado, não verá a página de ativação abaixo e pode saltar este passo.

    Uma captura de ecrã que mostra como configurar Aplicação Azure Insights para o recurso Foundry.

    1. Para reutilizar um Aplicação Azure Insights existente, utilize o menu suspenso nome do recurso Application Insights para localizar o recurso e selecionar Conectar.

      Dica

      Para se ligar a um Aplicação Azure Insights existente, precisa pelo menos de acesso de contribuidor ao recurso Foundry (ou Hub).

    2. Para se ligar a um novo recurso Aplicação Azure 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 de definições Avançadas para configurar um grupo de recursos diferente ou subscrição.

        Dica

        Para criar um novo recurso do Aplicação Azure Insights, também precisa de uma função de colaborador para o grupo de recursos que selecionou (ou o padrão).

      3. Selecione Criar para criar o recurso e ligá-lo ao recurso Foundry.

    3. Depois de configurada a ligação, está pronto para usar o rastreamento em qualquer projeto dentro do recurso.

    Dica

    Certifica-te de que tens atribuído o papel Log Analytics Reader no teu recurso Application Insights. Para saber mais sobre como atribuir funções, consulte Atribuir Azure funções usando o portal Azure. Use Microsoft Entra groups para gerir o acesso dos utilizadores de forma mais fácil.

  4. Vai à página inicial do teu projeto e copia o URI do endpoint do projeto. Vais precisar disso mais tarde.

    Uma captura de ecrã que mostra como copiar o URI do endpoint do projeto.

    Importante

    Usar o endpoint de um projeto requer configurar o Microsoft Entra ID na sua aplicação. Se não tiver o Entra ID configurado, use a string de conexão do Aplicação Azure Insights como indicado no passo 3 do tutorial.

Ver resultados de rastreamento 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:

  1. Vai ao portal da Foundry e navega até ao teu projeto.

  2. Na barra de navegação lateral, selecione Traçar.

  3. Verá uma lista de resultados de rastreamento das suas aplicações configuradas com instrumentos. Cada traço mostra:

    • ID do traço: Identificador único para o traço
    • Hora de início: Quando o traçado começou
    • Duração: Quanto tempo demorou a operação
    • Estado: Estado de sucesso ou fracasso
    • Operações: Número de partes no traço

  4. Selecione qualquer rastreio para visualizar resultados detalhados de rastreamento, incluindo:

    • Cronograma completa de execução
    • Dados de entrada e saída para cada operação
    • Métricas de desempenho e temporização
    • Detalhes de erro, se algum ocorreu
    • Atributos personalizados e metadados

Instrumente o SDK OpenAI

Ao desenvolver com o SDK OpenAI, pode instrumentar o seu código para que os traços sejam enviados para o Foundry. Siga estes passos para instrumentar o seu código:

  1. Pacotes de instalação:

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

  2. (Opcional) Capturar conteúdo da mensagem:

    • PowerShell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
    • Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

  3. Obtenha a cadeia de conexão do recurso Application Insights ligado (projecto > Rastreamento > Gerir a 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()

  4. Configure o Azure Monitor e o instrumento 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()

  5. 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)

  6. Voltar ao Rastreamento no portal para ver novos rastreios.

    Captura de ecrã que mostra uma visualização de rastreio de um pedido de conclusão de chat, mostrando segmentos e latência.

  7. Pode ser útil captar secções do seu código que misturam lógica de negócio com modelos ao desenvolver aplicações complexas. A OpenTelemetry usa o conceito de spans para captar secções que te interessam. Para começar a gerar os teus próprios spans, obtém uma instância do objeto traçador atual.

    from opentelemetry import trace

tracer = trace.get_tracer(__name__)

  8. Depois, use decoradores no seu método para captar cenários específicos no seu código que lhe interessam. Estes decoradores geram vãos automaticamente. O exemplo de código seguinte utiliza um método chamado assess_claims_with_context que itera sobre uma lista de reivindicações e verifica se a reivindicação é suportada 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

  9. Os resultados do rastreio aparecem da seguinte forma:

    Uma captura de ecrã que mostra como um método usando um decorador é apresentado no traço.

  10. Também podes querer adicionar informação extra ao intervalo atual. A OpenTelemetry usa o conceito de atributos para isso. Use o trace objeto para aceder a eles e inclua informações extra. 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 a consola

Pode ser útil também rastrear a sua aplicação e enviar os traços para a consola de execução local. Esta abordagem pode ser benéfica ao executar testes unitários ou testes de integração na sua aplicação 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 adicional.

Configure o rastreamento da seguinte forma:

  1. Instrumente o SDK OpenAI como habitual:

    from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

  2. Configure o OpenTelemetry para enviar traços para a consola:

    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)

  3. Usa o SDK OpenAI como habitual:

    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 forma simples de rastrear localmente no VS Code. Utiliza um coletor local compatível com OTLP, tornando-o perfeito para desenvolvimento e depuração sem necessidade de acesso à cloud.

O kit de ferramentas suporta o SDK OpenAI e outros frameworks de IA através do OpenTelemetry. É possível ver traços instantaneamente no seu ambiente de desenvolvimento.

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

Conteúdo relacionado

  • Last updated on