Compartilhar via


Rastrear aplicativos de IA usando o SDK do OpenAI

O rastreamento fornece visibilidade profunda da execução do aplicativo capturando telemetria detalhada em cada etapa de execução. Isso ajuda a diagnosticar problemas e melhorar o desempenho identificando problemas como chamadas de ferramenta imprecisas, prompts enganosos, alta latência, pontuações de avaliação de baixa qualidade e muito mais.

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

Pré-requisitos

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 no Azure AI Foundry.

Habilitar o rastreamento em seu projeto

O Azure AI Foundry armazena rastreamentos nos recursos do Azure Application Insight usando o OpenTelemetry. Por padrão, novos recursos do Azure AI Foundry não provisionam esses recursos. Você pode conectar projetos a um recurso existente do Azure Application Insights ou criar um novo de dentro do projeto. Você faz essa configuração uma vez por cada recurso do Azure AI Foundry.

As etapas a seguir mostram como configurar seu recurso:

  1. Acesse o portal do Azure AI Foundry e navegue até seu projeto.

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

  3. Se um recurso do Azure Application Insights não estiver associado ao recurso do Azure AI Foundry, associe um.

    Uma captura de tela mostrando como configurar o Azure Application Insights para o recurso do Azure AI Foundry.

  4. 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.

    Dica

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

  5. Para se conectar a um novo recurso do Azure Application Insights, selecione a opção Criar nova.

    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.

      Dica

      Para criar um novo recurso do Azure Application Insight, 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 do Azure AI Foundry.

  6. Depois que a conexão estiver configurada, você estará pronto para usar o rastreamento em qualquer projeto dentro do recurso.

  7. Vá para a página inicial do projeto e copie o URI do endpoint do projeto. Você precisará dele mais tarde no tutorial.

    Uma captura de tela mostrando como copiar o URI do ponto de extremidade do projeto.

    Importante

    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.

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:

  1. Instale azure-ai-projects, azure-monitor-opentelemetrye opentelemetry-instrumentation-openai-v2 em seu ambiente. O exemplo a seguir usa pip:

    pip install azure-ai-projects azure-monitor-opentelemetry opentelemetry-instrumentation-openai-v2
    
  2. Instrumentar o SDK do OpenAI usando OpenAIInstrumentor():

    from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
    
    OpenAIInstrumentor().instrument()
    
  3. Obtenha a cadeia de conexão para o recurso do Azure Application Insights associado ao seu projeto. A linha a seguir usa o cliente do Projeto de IA do Azure, que requer o uso da ID do Microsoft Entra para autenticaçã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_connection_string()
    

    Dica

    As strings de conexão do Azure Application Insights são como InstrumentationKey=aaaa0a0a-bb1b-cc2c-dd3d-eeeee4e4e4e;.... Você também pode acessar a cadeia de conexão usada em seu projeto na seção Rastreamento no portal do Azure AI Foundry. Na barra de navegação superior, selecione Gerenciar fonte de dados e copie a cadeia de conexão. Configure sua cadeia de conexão em uma variável de ambiente.

    Uma captura de tela mostrando como copiar a cadeia de conexão para o recurso subjacente do Azure Application Insights de um projeto.

  4. Configure o OpenTelemetry para enviar rastreamentos para o Azure Application Insights:

    from azure.monitor.opentelemetry import configure_azure_monitor
    
    configure_azure_monitor(connection_string=connection_string)
    
  5. Por padrão, o OpenTelemetry não captura entradas e saídas. Use a variável OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true de ambiente para capturá-las. Verifique se essa variável de ambiente está configurada no nível do ambiente em que o código está em execução.

  6. Use o SDK do OpenAI como de costume:

    client = project_client.get_azure_openai_client()
    
    response = client.chat.completions.create(
        model="deepseek-v3-0324",
        messages=[
            {"role": "user", "content": "Write a short poem on open telemetry."},
        ],
    )
    
  7. Se você voltar ao portal da Fábrica de IA do Azure, deverá ver o rastreamento exibido:

    Uma captura de tela mostrando como uma simples solicitação de conclusão de chat é exibida no rastreamento.

  8. 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 tracer atual.

    from opentelemetry import trace
    
    tracer = trace.get_tracer(__name__)
    
  9. Em seguida, use decoradores no seu método para capturar cenários específicos no seu código que lhe interessam. Esses decoradores geram spans automaticamente. O exemplo de código a seguir instrui um método chamado assess_claims_with_context que percorre uma lista de declarações e verifica se a declaração tem suporte no 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.5-preview",
                messages=build_prompt_with_context(claim=claim, context=context),
            )
            responses.append(response.choices[0].message.content.strip('., '))
    
        return responses
    
  10. Os traços são os seguintes:

    Uma captura de tela mostrando como um método usando um decorador é exibido no rastreamento.

  11. 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.5-preview",
                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 resultar em benefício ao executar testes de unidade ou testes de integração em seu aplicativo usando um pipeline de CI/CD automatizado. Os rastros podem ser enviados para o console e capturados pela sua ferramenta CI/CD para a análise posterior.

Configure o rastreamento da seguinte maneira:

  1. Implemente o SDK do OpenAI como de costume.

    from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
    
    OpenAIInstrumentor().instrument()
    
  2. 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)
    
  3. 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": ""
        }
    }
    

Próximas etapas