Como rastrear seu aplicativo com o SDK de fluxo de prompt | Estúdio de IA do Azure
Importante
Alguns dos recursos descritos nesse artigo podem estar disponíveis apenas na versão prévia. 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.
O rastreamento é uma ferramenta poderosa que oferece aos desenvolvedores uma compreensão detalhada do processo de execução de seus aplicativos de IA generativa, como agentes, AutoGen e casos de uso de RAG (geração aumentada de recuperação). Ele fornece uma exibição detalhada do fluxo de execução, incluindo as entradas e saídas de cada nó dentro do aplicativo. Essas informações essenciais são críticas ao depurar aplicativos complexos ou otimizar o desempenho.
Enquanto mais desenvolvedores estão usando várias estruturas, como Langchain, Kernel Semântico, OpenAI e vários tipos de agentes para criar aplicativos baseados em LLM. O rastreamento com o SDK do prompt flow oferece visibilidade aprimorada e solução de problemas simplificada para aplicativos baseados em LLM, dando suporte efetivamente ao desenvolvimento, à iteração e ao monitoramento de produção. O rastreamento no Estúdio de IA segue a especificação do OpenTelemetry, capturando e visualizando os detalhes de execução interna de qualquer aplicativo de IA, aprimorando a experiência de desenvolvimento geral.
Benefícios do rastreamento do Estúdio de IA na plataforma de nuvem de nível empresarial
Além disso, agora oferecemos testes locais persistentes no Estúdio de IA, que é a plataforma de nuvem de nível empresarial, aprimorando significativamente a colaboração, a persistência e o gerenciamento do histórico de testes.
Com o rastreamento, você pode:
- Ter um local baseado em nuvem para persistir e acompanhar seus testes históricos.
- Extrair e visualizar facilmente os resultados do teste, comparando as saídas de diferentes casos de teste.
- Reutilizar ativos de teste anteriores para uso posterior, por exemplo, comentários humanos, curadoria de dados etc.
- Facilitar uma melhor utilização de recursos no futuro.
- Depurar e otimizar seu aplicativo com facilidade. Para começar a depurar cenários de aplicativo LLM, consulte Rastreamento com o aplicativo LLM
- Analisar os processos de recuperação e geração em aplicativos RAG.
- Observar as interações de vários agentes nos cenários de vários agentes. Para começar a usar o rastreamento em cenários de vários agentes, consulte Rastreamento com AutoGen.
Registrar e exibir rastreamentos de seus aplicativos
O Estúdio de IA fornece a capacidade de rastreamento para registrar em log e gerenciar testes e avaliações de aplicativos LLM, ao mesmo tempo em que depura e analisa detalhadamente a exibição de rastreamento.
O rastreamento de qualquer recurso de aplicativo hoje é implementado no pacote de código aberto do prompt flow, para permitir que o usuário rastreie a função ou chamada LLM e estruturas LLM como LangChain e AutoGen, independentemente de qual estrutura você usa, seguindo a especificação do OpenTelemetry.
Habilitar rastreamento em seu aplicativo
Código primeiro: verifique se você anotou seu código para rastreamento no prompt flow!
- Instalar prompt flow: exigir o rastreamento de prompt flow
- Instrumentar o código do aplicativo: usando
@traceestart_trace(). - Testar e exibir rastreamento no local
Mais detalhes sobre o rastreamento no prompt flow, consulte esta documentação do prompt flow.
Registrar o rastreamento no Estúdio de IA
Definir o destino do rastreamento
Por padrão, o rastreamento é registrado em log e exibido em seu ambiente local. Para registrá-lo no Estúdio de IA na nuvem, você precisará definir o trace destination como um projeto do Estúdio de IA especificado.
Você pode consultar as etapas a seguir para definir o destino de rastreamento para o projeto do Estúdio de IA.
Primeiro, verifique se a CLI do Azure está instalada e conectada:
az login
Depois, execute o seguinte comando para definir o destino do rastreamento. Substitua <your_subscription_id>, <your_resourcegroup_name> e <your_studio_project_name> por sua ID da assinatura específica, o nome do grupo de recursos e o nome do projeto do Estúdio de IA:
pf config set trace.destination=azureml://subscriptions/<your_subscription_id>/resourcegroups/<your_resourcegroup_name>/providers/Microsoft.MachineLearningServices/workspaces/<your_studio_project_name>
Observação
A região Oeste dos EUA 3 (westus3) não dá suporte ao rastreamento.
Coleções
Uma coleção é um grupo de rastreamentos associados. No Estúdio de IA, essas coleções, juntamente com seus rastreamentos internos, são gerenciadas e armazenadas no módulo Rastreamento na guia Coleções.
Vá para o seu projeto no Estúdio de IA.
No painel à esquerda, selecione Rastreamento. Você pode ver a guia Coleções. Você só pode ver suas coleções na lista de coleções. Neste exemplo, ainda não há nenhuma coleção.
A guia coleção exibe uma lista abrangente de todas as coleções que você criou. Ela mostra metadados essenciais de cada coleção, incluindo seu nome, local de execução, hora da última atualização e hora de criação.
- Executar local: indica se o aplicativo é executado localmente ou na nuvem. A coleção na nuvem está associada ao histórico de teste de criação de nuvem de prompt flow específico e aos rastreamentos gerados. Nesse caso, o nome da coleção é o mesmo que o nome de exibição do prompt flow.
- Atualizado em: mostra a hora mais recente em que um novo rastreamento foi registrado em uma coleção. Por padrão, as coleções são classificadas em ordem decrescente com base em suas horas de atualização.
- Criado em: a hora em que a coleção foi criada inicialmente.
Selecionando o nome de uma coleção, você pode acessar uma lista de todos os rastreamentos dentro dessa coleção. Somente um subconjunto de rastreamentos pode ser compartilhado com outras pessoas. Confira mais informações em Compartilhar rastreamento.
Ao registrar em log um rastreamento, você tem a opção de especificar um nome de coleção para agrupá-lo com outros rastreamentos relacionados. Você pode criar várias coleções para melhor organização de seus rastreamentos. Se o nome de uma coleção não for especificado ao registrar em log um rastreamento, ele usará o nome da pasta do projeto ou a coleção padrão.
Personalizar as coleções
Para uma melhor organização de seus rastreamentos, você pode especificar um nome de coleção personalizado ao registrar em log um rastreamento.
Se você estiver rastreando seu próprio aplicativo, poderá definir o nome da coleção na função start_trace() em seu código:
from promptflow.tracing import start_trace, trace
@trace
def my_function(input: str) -> str:
output = input + "Hello World!"
return output
my_function("This is my function")
start_trace(collection="my_custom_collection")
Mais detalhes sobre como personalizar coleções, consulte tutorial de rastreamento e comando de prompt flow.
Exibir os rastreamentos
Primeiro, você deve concluir as etapas anteriores para ver os rastreamentos na nuvem:
Agora, execute seu script do Python diretamente. Após a execução bem-sucedida, um link de rastreamento na nuvem aparece na saída. Poderá ser semelhante ao seguinte:
Starting prompt flow service...
...
You can view the traces in cloud from AI Studio: https://ai.azure.com/projecttrace/detail/....
Selecione a URL para navegar até uma página de detalhes de rastreamento no portal na nuvem. Esta página é semelhante ao modo de exibição de rastreamento local.
O modo de exibição de detalhes de rastreamento fornece uma visão geral abrangente e estruturada das operações em seu aplicativo.
Entender o modo de exibição de detalhes de rastreamento
No canto superior direito do modo de exibição de rastreamento, você encontra:
- Nome do rastreamento: é o mesmo que o nome do intervalo raiz, representando o nome da função de entrada do aplicativo.
- Status: pode ser "concluído" ou "com falha".
- Duração total: é o tempo de duração total da execução do teste. Passe o mouse para exibir os horários de início e término.
- Total de tokens: é o custo total do token do teste. Passe o mouse para exibir os tokens de prompt e os tokens concluídos.
- Hora em que foi criado: a hora em que o rastreamento foi criado.
No lado esquerdo, você pode ver uma estrutura de árvore hierárquica. Essa estrutura mostra a sequência de chamadas de função. Os metadados de cada chamada de função são organizados em intervalos. Esses intervalos são vinculados em uma estrutura semelhante a uma árvore, ilustrando a sequência de execução.
No SDK de prompt flow, definimos vários tipos de intervalo, incluindo LLM, Função, Inserção, Recuperação e Fluxo. E o sistema cria automaticamente intervalos com informações de execução em atributos e eventos designados.
Cada intervalo permite que você veja:
- Nome da função: por padrão, esse é o nome da função conforme definido no seu código. No entanto, também pode ser um nome de intervalo personalizado definido por meio do OpenTelemetry.
- Duração: representa a duração para a qual a função foi executada. Passe o mouse para exibir os horários de início e término.
- Tokens para chamadas LLM: é o custo do token da chamada LLM. Passe o mouse para exibir os tokens de prompt e os tokens concluídos.
Ao selecionar um intervalo específico, você pode mudar para exibir suas informações detalhadas associadas no lado direito. Essas informações incluem entrada, saída, JSON bruto, logse exceções, que são essenciais para observar e depurar seu aplicativo.
Para o intervalo de LLM, uma exibição de conversa clara é fornecida. Isso inclui o prompt do sistema, prompt do usuário e resposta do assistente. Essas informações são especialmente cruciais em casos de vários agentes, pois permitem que você entenda o fluxo da conversa e a interação dentro da chamada automática intermediária de LLM.
Você pode selecionar a guia JSON bruto para ver os dados json do intervalo. Esse formato pode ser mais adequado para desenvolvedores quando se trata de depuração e solução de problemas.
Compartilhar rastreamento
Se você quiser compartilhar o rastreamento com outras pessoas que têm a permissão do projeto, selecione o botão Compartilhar no canto direito da página de detalhes do rastreamento e, em seguida, você terá o link da página copiado para compartilhar com outras pessoas.
Observação
O rastreamento compartilhado é somente leitura e somente as pessoas que têm a permissão do projeto podem exibi-lo por meio do link.