Como rastrear seu aplicativo com o SDK do Azure AI Inference

Importante

Os itens marcados (visualização) neste artigo estão atualmente em visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Neste artigo, você aprenderá como rastrear seu aplicativo com o SDK de inferência do Azure AI com sua escolha entre usar Python, JavaScript ou C#. A biblioteca de cliente do Azure AI Inference fornece suporte para rastreamento com OpenTelemetry.

Habilitar o 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 suporta a API de inferência de modelo de IA do Azure implementada através do Azure AI Foundry.
• Se estiver usando Python, você precisará do Python 3.8 ou posterior instalado, incluindo pip.
• Se estiver usando JavaScript, os ambientes suportados são versões LTS do Node.js.

Instalação

Python

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

  pip install azure-ai-inference[opentelemetry] 

Instale o plug-in de rastreamento OpenTelemetry do Azure Core, o OpenTelemetry e o exportador de OTLP para enviar telemetria para seu 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 de IA do Azure para Python e a observabilidade, consulte Rastreamento via SDK de Inferência para Python.

JavaScript

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

    npm install @azure-rest/ai-inference

Para saber mais sobre o SDK de inferência do Azure AI para JavaScript e observabilidade, consulte Rastreamento via SDK de inferência para JavaScript.

C#

Instale a biblioteca de cliente do Azure AI Inference para .NET com NuGet:

    dotnet add package Azure.AI.Inference --prerelease

Para saber mais sobre o SDK de inferência do Azure AI para C# e observabilidade, consulte Rastreamento via SDK de inferência para C#.

Para saber mais, consulte a referência do SDK de inferência.

Configuração

Python

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

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

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

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

  Para saber mais, consulte Biblioteca de cliente OpenTelemetry do Azure Core Tracing para Python.

JavaScript

A instrumentação só é suportada para Conclusão de Chat sem streaming. Para habilitar a instrumentação, você precisa registrar o(s) exportador(es). A seguir está 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 OpenTelemetry têm suporte no Azure AI Inference no modo experimental e podem ser habilitados por meio de uma destas etapas:

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

Ativar instrumentação

Python

A etapa final é habilitar a instrumentação do Azure AI Inference com o seguinte trecho de código:

from azure.ai.inference.tracing import AIInferenceInstrumentor 

# Instrument AI Inference API 

AIInferenceInstrumentor().instrument() 

Também é possível desinstrumentar a API de Inferência de IA do Azure usando a chamada uninstrument. Após essa chamada, os rastreamentos não serão mais emitidos pela API de Inferência de 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 quaisquer dependências do @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 as opções de rastreamento com o contexto de 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 do Azure AI Inference, siga estas etapas:

1. Instalar pacotes OpenTelemetry : instale as seguintes dependências para rastreamento HTTP e instrumentação de métricas, 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. Ativar gravação de conteúdo: por padrão, a instrumentação captura mensagens de bate-papo 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 provedor de rastreamento: configure o provedor de rastreador para exportar rastreamentos e métricas para o console e para o destino OTLP local, conforme necessário.

Rastreando suas próprias funções

Para rastrear suas próprias funções personalizadas, você pode aproveitar o OpenTelemetry, você precisará instrumentar seu código com o SDK do OpenTelemetria. Isso envolve a configuração de um provedor de rastreador e a criação de extensões em torno do código que você deseja rastrear. Cada span representa uma unidade de trabalho e pode ser aninhado para formar uma árvore de traços. Você pode adicionar atributos a extensões para enriquecer os dados de rastreamento com contexto adicional. Uma vez instrumentado, 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 uso avançado, consulte a documentação do OpenTelemetry . Isso ajudará você a monitorar o desempenho de suas funções personalizadas e obter informações sobre sua execução.

Anexar comentários do usuário a rastreamentos

Para anexar 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 registrando comentários do usuário. Ao correlacionar rastreamentos de feedback com seus respetivos rastreamentos de solicitação de chat usando a ID de resposta, você pode usar a exibição e gerenciar esses rastreamentos no portal do Azure AI Foundry. A especificação do OpenTelemetry permite dados de rastreamento padronizados e enriquecidos, que podem ser analisados no portal do Azure AI Foundry para otimização de desempenho e insights da experiência do usuário. Essa abordagem ajuda você a usar todo o poder do OpenTelemetry para melhorar a observabilidade em seus aplicativos.

Conteúdos relacionados

• Exemplos 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.