Como rastrear seu aplicativo com o SDK de Inferência da IA do Azure

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Neste artigo, você aprenderá a rastrear seu aplicativo com o SDK de Inferência da IA do Azure, podendo escolher entre usar Python, JavaScript ou C#. A biblioteca de clientes de Inferência da IA do Azure dá suporte ao rastreamento com OpenTelemetry.

Habilitar rastreamento em seu aplicativo

Pré-requisitos

• Uma assinatura do Azure.
• Um projeto de IA do Azure, consulte Criar um projeto no portal do Azure AI Foundry.
• Um modelo de IA que dá suporte à API de inferência de modelo de IA do Azure implantado por meio do Azure AI Foundry.
• Se estiver usando o Python, você precisará ter o Python 3.8 ou posterior instalado, incluindo o pip.
• Se estiver usando JavaScript, os ambientes com suporte serão as versões LTS do Node.js.

Instalação

Python

Instale o pacote azure-ai-inference usando seu gerenciador de pacotes, como o pip:

  pip install azure-ai-inference[opentelemetry] 

Instale o plug-in Azure Core OpenTelemetry Tracing, o OpenTelemetry e o exportador OTLP para enviar telemetria ao back-end de observabilidade. Para instalar os pacotes necessários para Python, use os seguintes comandos pip:

pip install opentelemetry 

pip install opentelemetry-exporter-otlp 

Para saber mais sobre o SDK de Inferência da IA do Azure para Python e observabilidade, confira Rastreamento via SDK de Inferência para Python.

JavaScript

Instale o pacote @azure-rest/ai-inference para JavaScript usando o npm:

    npm install @azure-rest/ai-inference

Para saber mais sobre o SDK de Inferência da IA do Azure para JavaScript e observabilidade, confira Rastreamento via SDK de Inferência para JavaScript.

C#

Instale a biblioteca de clientes de Inferência da IA do Azure para .NET com o NuGet:

    dotnet add package Azure.AI.Inference --prerelease

Para saber mais sobre o SDK de Inferência da IA do Azure para C# e observabilidade, confira Rastreamento via SDK de Inferência para C#.

Para saber mais, confira a Referência do SDK de Inferência.

Configuração

Python

Você precisa adicionar as seguintes configurações de acordo com o caso de uso:

• Para capturar o conteúdo de prompt e conclusão, defina a variável de ambiente AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED como true (não diferencia maiúsculas de minúsculas). Por padrão, prompts, conclusões, nomes de função, parâmetros e saídas não são registrados.

• Para habilitar o rastreamento do SDK do Azure, defina a variável de ambiente AZURE_SDK_TRACING_IMPLEMENTATION como opentelemetry. Como alternativa, você pode configurá-lo no código com o seguinte snippet:

  from azure.core.settings import settings 
  
  settings.tracing_implementation = "opentelemetry" 
  

  Para saber mais, confira Biblioteca de clientes OpenTelemetry de Rastreamento do Azure Core para Python.

JavaScript

A instrumentação tem suporte apenas para Conclusão de Chat sem streaming. Para habilitar a instrumentação, você precisa registrar exportadores. Veja a seguir um exemplo de como adicionar um exportador de console.

Exportador de console:

import { ConsoleSpanExporter, NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node"; 

const provider = new NodeTracerProvider(); 

provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); 

provider.register(); 

C#

O rastreamento distribuído e as métricas com o OpenTelemetry têm suporte na Inferência da IA do Azure no modo experimental e podem ser habilitadas por meio de qualquer uma destas etapas:

• Definir a variável de ambiente AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE como true.
• Definir a opção de contexto Azure.Experimental.EnableActivitySource como true no código do aplicativo.

Habilitar a instrumentação

Python

A etapa final é habilitar a instrumentação da Inferência da IA do Azure com o seguinte snippet de código:

from azure.ai.inference.tracing import AIInferenceInstrumentor 

# Instrument AI Inference API 

AIInferenceInstrumentor().instrument() 

Também é possível desfazer a instrumentação da API de Inferência da IA do Azure usando a chamada uninstrument. Após essa chamada, os rastreamentos deixarão de ser emitidos pela API de Inferência da IA do Azure até que o instrumento seja chamado novamente:

AIInferenceInstrumentor().uninstrument() 

JavaScript

Para usar a instrumentação para o SDK do Azure, você precisa registrá-la antes de importar as dependências de @azure/core-tracing, como @azure-rest/ai-inference.

import { registerInstrumentations } from "@opentelemetry/instrumentation"; 

import { createAzureSdkInstrumentation } from "@azure/opentelemetry-instrumentation-azure-sdk"; 


registerInstrumentations({ 

  instrumentations: [createAzureSdkInstrumentation()], 

}); 

import ModelClient from "@azure-rest/ai-inference"; 

Ao fazer uma chamada para conclusão do chat, você precisa incluir tracingOptions com o contexto do rastreamento ativo:

import { context } from "@opentelemetry/api"; 

client.path("/chat/completions").post({ 

      body: {...}, 

      tracingOptions: { tracingContext: context.active() } 

}); 

C#

Para configurar o OpenTelemetry e habilitar o rastreamento da Inferência da IA do Azure, siga estas etapas:

1. Instalar pacotes do OpenTelemetry: instale as seguintes dependências para a instrumentação de métricas e rastreamento HTTP, bem como exportadores de console e OTLP:

      dotnet add package OpenTelemetry.Instrumentation.Http 
   
      dotnet add package OpenTelemetry.Exporter.Console 
   
      dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol 
   

2. Habilitar a observabilidade experimental do SDK do Azure: defina a opção de contexto para habilitar a observabilidade experimental do SDK do Azure:

      AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true); 
   

3. Habilitar a gravação de conteúdo: por padrão, a instrumentação captura mensagens de chat sem conteúdo. Para habilitar a gravação de conteúdo, defina a seguinte opção de contexto:

    AppContext.SetSwitch("Azure.Experimental.TraceGenAIMessageContent", true);
   

4. Configurar o provedor do rastreador: configure o provedor do rastreador para exportar rastreamentos e métricas para o console e para o destino de OTLP local, conforme necessário.

Rastreamento de suas funções

Para rastrear suas funções personalizadas, você pode aproveitar o OpenTelemetry. Você precisará instrumentar o código com o SDK do OpenTelemetry. Isso envolve a configuração de um provedor de rastreamento e a criação de intervalos em torno do código que você deseja rastrear. Cada intervalo representa uma unidade de trabalho e pode ser aninhada de modo a formar uma árvore de rastreamento. Você pode adicionar atributos a intervalos para enriquecer os dados de rastreamento com contexto adicional. Após a instrumentação, configure um exportador para enviar os dados de rastreamento para um back-end para análise e visualização. Para obter instruções detalhadas e informações sobre o uso avançado, confira a documentação do OpenTelemetry. Isso ajudará você a monitorar o desempenho de suas funções personalizadas e obter insights sobre a execução.

Anexar comentários do usuário a rastreamentos

Para anexar os comentários do usuário a rastreamentos e visualizá-los no portal do Azure AI Foundry usando as convenções semânticas do OpenTelemetry, você pode instrumentar seu aplicativo habilitando o rastreamento e o registro de comentários do usuário. Ao correlacionar traces de comentários com seus respectivos rastreamentos de solicitação de chat usando a ID de resposta, você pode visualizar e gerenciar esses traces no portal do Azure AI Foundry. A especificação do OpenTelemetry permite dados de rastreamento padronizados e avançados, que podem ser analisados no portal do Azure AI Foundry para otimização de desempenho e insights sobre a experiência do usuário. Essa abordagem ajuda você a usar toda a potência do OpenTelemetry para ter maior observabilidade em seus aplicativos.

Conteúdo relacionado

• Exemplos de Python contendo código Python totalmente executável para rastreamento usando clientes síncronos e assíncronos.
• Exemplos de JavaScript contendo código JavaScript totalmente executável para rastreamento usando clientes síncronos e assíncronos.
• Exemplos de C# contendo código C# totalmente executável para fazer inferência usando métodos síncronos e assíncronos.