Compartilhar via

Rastrear seus agentes de IA usando o SDK do Azure AI Foundry (versão prévia)

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 para Versões Prévias do Microsoft Azure.

Este artigo orienta você sobre como instrumentar o rastreamento em agentes usando o SDK da Fábrica de IA do Azure com OpenTelemetry e Azure Monitor para observabilidade e depuração avançadas.

Aqui está uma breve visão geral dos principais conceitos antes de começar:

Conceitos principais Descrição
Vestígios Os rastreamentos capturam o percurso de uma solicitação ou fluxo de trabalho por meio de seu aplicativo registrando eventos e alterações de estado durante a execução, como chamadas de função, valores variáveis e eventos do sistema. Para saber mais, consulte Rastreamentos do OpenTelemetry.
Intervalos Os intervalos são blocos de construção dos rastreamentos, representando operações individuais dentro de um rastreamento. Cada intervalo captura horários de início e término, atributos e pode ser aninhado para mostrar relações hierárquicas, permitindo que você veja a pilha de chamadas completa e a sequência de operações.
Atributos Os atributos são pares chave-valor anexados a rastreamentos e intervalos, fornecendo metadados contextuais, como parâmetros de função, valores retornados ou anotações personalizadas. Eles enriquecem os dados de rastreamento, tornando-os mais informativos e úteis para análise.
Convenções semânticas O OpenTelemetry define convenções semânticas para padronizar nomes e formatos para atributos de dados de rastreamento, facilitando a interpretação e a análise entre ferramentas e plataformas. Para saber mais, confira As Convenções Semânticas do OpenTelemetry.
Rastrear exportadores Os exportadores de rastreamento enviam dados de rastreamento para sistemas de back-end para armazenamento e análise. A IA do Azure dá suporte à exportação de rastreamentos para o Azure Monitor e outras plataformas compatíveis com OpenTelemetry, permitindo a integração com várias ferramentas de observabilidade.

Configuração

Para as conclusões de chat ou criação de agentes com a Fábrica de IA do Azure, instale:

pip install azure-ai-projects azure-identity

Para instrumentar o rastreamento, você precisa instalar as seguintes bibliotecas de instrumentação:

pip install azure-monitor-opentelemetry opentelemetry-sdk

Para exibir rastreamentos no Azure AI Foundry, você precisa conectar um recurso do Application Insights ao seu projeto do Azure AI Foundry.

  1. Navegue até Rastreamento no painel de navegação esquerdo do portal do Azure AI Foundry.
  2. Crie um novo recurso do Application Insights se você ainda não tiver um.
  3. Conecte o recurso ao projeto do AI Foundry.

Rastreamento de instrumentos em seu código

Para rastrear o conteúdo das mensagens de chat, defina a variável de ambiente AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED como verdadeiro (sem distinção de maiúsculas e minúsculas). Tenha em mente que isso pode conter dados pessoais. Para saber mais, consulte Biblioteca de clientes OpenTelemetry de Rastreamento do Azure Core para Python.

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default

Vamos começar a instrumentar nosso agente com o rastreamento OpenTelemetry, começando com a autenticação e a conexão ao seu projeto de IA do Azure usando o AIProjectClient.

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

Em seguida, recupere a cadeia de conexão do recurso application insights conectado ao seu projeto e configure os exportadores OTLP para enviar telemetria para o Azure Monitor.

from azure.monitor.opentelemetry import configure_azure_monitor
connection_string = project_client.telemetry.get_connection_string()

if not connection_string:
    print("Application Insights is not enabled. Enable by going to Tracing in your Azure AI Foundry project.")
    exit()

configure_azure_monitor(connection_string=connection_string) #enable telemetry collection

Agora, rastreie o código em que você cria e executa sua mensagem de agente e usuário em seu Projeto de IA do Azure, para que você possa ver etapas detalhadas para solução de problemas ou monitoramento.

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.create_thread()
    message = project_client.agents.create_message(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)

Depois de executar seu agente, você pode começar a visualizar rastros no Portal Fábrica de IA do Azure.

Rastreamentos de log localmente

Para se conectar ao Aspire Dashboard ou a outro back-end compatível com OpenTelemetry, instale o exportador do Protocolo OpenTelemetry (OTLP). Isso permite que você imprima rastreamentos no console ou use um visualizador local, como o Aspire Dashboard.

pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk

Em seguida, você deseja configurar o rastreamento para seu aplicativo.

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

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# Setup tracing to console
span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

Use enable_telemetry para começar a coletar telemetria.

from azure.ai.projects import enable_telemetry
enable_telemetry(destination=sys.stdout)

# Logging to an OTLP endpoint, change the destination to
# enable_telemetry(destination="http://localhost:4317")

# Start tracing
from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.create_thread()
    message = project_client.agents.create_message(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)

Rastrear funções personalizadas

Para rastrear suas funções personalizadas, use o SDK do OpenTelemetry para instrumentar seu código.

  1. Configurar um provedor de rastreamento: inicialize um provedor de rastreamento para gerenciar e criar intervalos.
  2. Criar intervalos: encapsular o código que você deseja rastrear com intervalos. Cada segmento representa uma unidade de trabalho e pode ser aninhado para formar uma árvore de rastreamento.
  3. Adicionar atributos: enriquecer intervalos com atributos para fornecer mais contexto para os dados de rastreamento.
  4. Configurar um exportador: envie os dados de rastreamento para um back-end para análise e visualização.

Aqui está um exemplo de rastreamento de uma função personalizada:

from opentelemetry import trace
from opentelemetry.trace import SpanKind

# Initialize tracer
tracer = trace.get_tracer(__name__)

def custom_function():
    with tracer.start_as_current_span("custom_function") as span:
        span.set_attribute("custom_attribute", "value")
        # Your function logic here
        print("Executing custom function")

custom_function()

Para obter instruções detalhadas e informações sobre o uso avançado, confira a documentação do OpenTelemetry.

Anexar comentários do usuário a rastreamentos

Para anexar comentários do usuário aos rastreamentos e visualizá-los no portal do Azure AI Foundry, você pode instrumentar seu aplicativo para habilitar o rastreamento e registrar comentários do usuário usando as convenções semânticas do OpenTelemetry.

Ao correlacionar rastreamentos de comentários com seus respectivos rastreamentos de solicitação de chat usando a ID de resposta ou a ID do thread, você pode exibir e gerenciar esses rastreamentos 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.

Para registrar comentários do usuário, siga este formato:

O evento de avaliação do feedback do usuário poderá ser capturado se e somente se o usuário tiver fornecido uma reação à resposta do modelo GenAI. Ele deve, quando possível, ser pai do intervalo GenAI que descreve essa resposta.

O corpo do evento de comentários do usuário tem a seguinte estrutura:

Campo corpo Tipo Descrição Exemplos Nível de requisito
comment cadeia de caracteres Detalhes adicionais sobre os comentários do usuário "I did not like it" Opt-in

Usar o nome do serviço em dados de rastreamento

Para identificar seu serviço por uma ID exclusiva no Application Insights, você pode usar a propriedade OpenTelemetry do nome do serviço nos seus dados de rastreamento. Isso é útil se você estiver registrando dados de vários aplicativos no mesmo recurso do Application Insights e quiser diferenciá-los.

Por exemplo, digamos que você tenha dois aplicativos: App-1 e App-2, com rastreamento configurado para registrar dados no mesmo recurso do Application Insights. Talvez você queira configurar o App-1 para ser avaliado continuamente por Relevância e App-2 para ser avaliado continuamente pela Relevância. Você pode usar o nome do serviço para filtrar por Application ao monitorar seu aplicativo no Portal da Fábrica de IA.

Para configurar a propriedade de nome de serviço, você pode fazer isso diretamente no código do aplicativo seguindo as etapas. Consulte Usar vários provedores de rastreamento com diferentes Recursos. Como alternativa, você pode definir a variável OTEL_SERVICE_NAME de ambiente antes de implantar seu aplicativo. Para saber mais sobre como trabalhar com o nome do serviço, consulte Variáveis de Ambiente OTEL e Convenções semânticas de recursos de serviço.

Para consultar dados de rastreamento de um determinado nome de serviço, consulte a propriedade cloud_roleName.

| where cloud_RoleName == "service_name"

Habilitar o rastreamento para Langchain

Você pode habilitar o rastreamento para Langchain que segue os padrões OpenTelemetry de acordo com opentelemetry-instrumentation-langchain. Para habilitar o rastreamento para Langchain, instale o pacote opentelemetry-instrumentation-langchain usando o gerenciador de pacotes, como pip:

pip install opentelemetry-instrumentation-langchain

Depois que os pacotes necessários forem instalados, você poderá facilmente começar a Instrumentar o rastreamento em seu código.

Exibir rastreamentos no portal do Azure AI Foundry

Em seu projeto, acesse Tracing para filtrar seus rastreamentos conforme achar adequado.

Selecionando um rastreamento, você pode percorrer cada intervalo e identificar problemas ao observar como seu aplicativo está respondendo. Isso pode ajudá-lo a depurar e identificar problemas em seu aplicativo.

Exibir rastreamentos no Azure Monitor

Se você registrou rastreamentos usando o snippet de código anterior, está pronto para exibir os rastreamentos no Application Insights do Azure Monitor. Você pode abrir no Application Insights usando Gerenciar fonte de dados e usar a Exibição de detalhes da transação de ponta a ponta para investigar mais.

Para obter mais informações sobre como enviar rastreamentos de inferência de IA do Azure para o Azure Monitor e criar um recurso do Azure Monitor, consulte Documentação do OpenTelemetry do Azure Monitor.

Conteúdo relacionado