Solucionar problemas de avaliação e observabilidade

Este artigo fornece informações para ajudá-lo a resolver problemas comuns que você pode encontrar ao usar recursos de avaliação e observabilidade no Microsoft Foundry. Alguns problemas estão relacionados à configuração da conta de armazenamento, ao RBAC (controle de acesso baseado em função) ou às configurações de rede do projeto Foundry. Outros problemas ocorrem enquanto uma avaliação é executada, como falhas de autenticação, limites de capacidade ou cota do modelo, problemas de formato de dados ou pontuações ausentes.

Conta de armazenamento não vinculada ao projeto Foundry

Os recursos de avaliação exigem uma conta de armazenamento vinculada ao projeto do Foundry por meio de uma conexão. Se a conta de armazenamento não estiver conectada, as avaliações falharão porque o serviço não pode ler nem gravar dados de avaliação.

Sintomas:

• As avaliações falham com erros relacionados ao acesso ao armazenamento ou à falta de configuração de armazenamento.
• O serviço de avaliação não pode carregar resultados de avaliação ou baixar conjuntos de dados.

Conectar uma conta de armazenamento ao projeto foundry

Conecte sua conta de armazenamento ao projeto foundry criando uma conexão Armazenamento de Blobs do Azure. Para obter instruções passo a passo, consulte Adicionar uma nova conexão ao seu projeto.

Você pode autenticar a conexão usando uma chave contação ou Microsoft Entra ID (recomendado). Se você usar o Entra ID, consulte Atribuição ausente de função RBAC para autenticação do Entra ID para configurar as permissões necessárias.

Para obter mais detalhes sobre como trazer seu próprio armazenamento para avaliações, consulte limites de taxa, suporte à região e recursos corporativos para avaliação.

Ausência de atribuição de função RBAC para autenticação do Microsoft Entra ID

Se você conectar sua conta de armazenamento usando autenticação do Microsoft Entra ID, a identidade gerenciada do projeto Foundry deve ter a função Storage Blob Data Contributor na conta de armazenamento. Sem essa função, o serviço não pode ler ou gravar dados de blob e as avaliações falham.

Sintomas:

• As avaliações falham com erros 403 Forbidden ou AuthorizationPermissionMismatch.
• Você vê erros que indicam permissões insuficientes para acessar a conta de armazenamento.
• As operações de armazenamento expiram ou são negadas.

Verificar a atribuição de função de identidade gerenciada

Use os seguintes comandos de CLI do Azure para verificar se a função RBAC correta está atribuída à identidade gerenciada específica do projeto Foundry na conta de armazenamento.

Primeiro, obtenha o ID principal de identidade gerenciada para seu projeto Foundry.

az resource show \
  --resource-group <your-resource-group> \
  --name <your-foundry-account-name> \
  --resource-type "Microsoft.CognitiveServices/accounts" \
  --query "identity.principalId" \
  --output tsv

Em seguida, liste as atribuições de função na conta de armazenamento e filtre para a identidade gerenciada:

az role assignment list \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>" \
  --assignee <principal-id> \
  --output table

Verifique se a saída inclui uma atribuição de função com RoleDefinitionName definido como Colaborador de dados de blobs de armazenamento (ou Proprietário de dados de blobs de armazenamento).

Atribuir a função Colaborador de Dados do Blob de Armazenamento

Se a atribuição de função estiver ausente, atribua a função Colaborador de Dados do Blob de Armazenamento à identidade gerenciada do projeto Foundry:

az role assignment create \
  --assignee <principal-id> \
  --role "Storage Blob Data Contributor" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>"

Restrições de acesso à rede da conta de armazenamento

Quando você usa Microsoft Entra ID autenticação, a conta de armazenamento deve ter o acesso à rede pública habilitado. Se o acesso à rede for restrito, o serviço de avaliação do Foundry poderá não conseguir acessar a conta de armazenamento.

Sintomas:

• As avaliações falham com erros ou tempos limite relacionados à rede.
• Você vê 403 Forbidden erros mesmo quando as funções RBAC são atribuídas corretamente.
• As conexões com a conta de armazenamento são recusadas.

Verificar a configuração de rede da conta de armazenamento

Use o seguinte comando CLI do Azure para verificar as configurações de acesso à rede da sua conta de armazenamento:

az storage account show \
  --resource-group <resource-group> \
  --name <storage-account-name> \
  --query "{publicNetworkAccess: publicNetworkAccess, defaultAction: networkRuleSet.defaultAction, virtualNetworkRules: networkRuleSet.virtualNetworkRules, ipRules: networkRuleSet.ipRules}" \
  --output json

Verifique a saída para obter os seguintes valores:

Se publicNetworkAccess estiver definido Disabled como ou defaultAction for definido como Deny, o serviço de avaliação não poderá acessar a conta de armazenamento.

Habilitar o acesso à rede pública

Habilite o acesso à rede pública na conta de armazenamento:

az storage account update \
  --resource-group <resource-group> \
  --name <storage-account-name> \
  --public-network-access Enabled

Se você precisar manter o firewall habilitado, mas permitir o acesso, defina a ação padrão como Permitir:

az storage account update \
  --resource-group <resource-group> \
  --name <storage-account-name> \
  --default-action Allow

Lista de verificação de solução de problemas

Use esta lista de verificação para verificar rapidamente sua configuração de avaliação:

1. Storage connection exists: confirme se uma conexão Armazenamento de Blobs do Azure está configurada em seu projeto foundry. Navegue até Criar>Ferramentas no portal do Foundry para verificar.

2. Tipo de autenticação: identifique se a conexão usa uma chave de conta ou Microsoft Entra ID. Se houver um Entra ID, conclua as verificações restantes.

3. Função RBAC atribuída: verifique se a identidade gerenciada do projeto Foundry tem a função Colaborador de Dados de Blob de Armazenamento na conta de armazenamento.

   az role assignment list \
     --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>" \
     --assignee <principal-id> \
     --query "[].{Role:roleDefinitionName, Principal:principalId}" \
     --output table
   

4. Acesso à rede: verifique se a conta de armazenamento tem acesso à rede pública habilitado.

   az storage account show \
     --resource-group <resource-group> \
     --name <storage-account-name> \
     --query "publicNetworkAccess" \
     --output tsv
   

5. Atraso de propagação: se você fez alterações no RBAC ou na rede recentemente, aguarde pelo menos 10 minutos antes de tentar novamente.

A execução da avaliação é lenta, fica travada ou falha devido a erros de capacidade ou de cota

Uma execução de avaliação pode permanecer no estado em execução ou pendente por um longo tempo, ser executada lentamente ou falhar com erros de cota. Essa condição geralmente acontece quando a implantação do modelo de juiz não tem capacidade suficiente, portanto, o serviço limita ou tenta novamente as solicitações.

Sintomas:

• A execução permanece no estado em execução ou pendente por muito mais tempo do que o esperado.
• A execução falha com um 429 Too Many Requests erro.
• Você vê erros que mencionam limites de cota ou taxa.

Solução:

• Confirme se a implantação do modelo de juiz tem cota suficiente. O modelo avaliador usado em avaliadores assistidos por IA é contabilizado na sua cota do OpenAI do Azure.
• Aumente a cota de tokens por minuto (TPM) para a implantação do modelo no portal do Azure e execute a avaliação novamente.
• Reduza o tamanho do conjunto de dados ou divida-o em lotes menores. Para simulações, diminua as voltas máximas por conversa.
• Use uma implantação de modelo de juiz de menor ou menor custo para execuções mais rápidas e mais baratas.
• Para uma execução de SDK paralisada, cancele-a com client.evals.runs.cancel(run_id, eval_id=eval_id), aumente a capacidade e, em seguida, reenvie.
• Em caso de erro 429, verifique o cabeçalho retry-after para ver o tempo de espera recomendado e use backoff exponencial ao tentar novamente.

Erros de autenticação ou autorização (401 ou 403)

Se uma avaliação falhar com um erro 401 Unauthorized ou 403 Forbidden que não esteja relacionado ao armazenamento, a causa geralmente é a autenticação do projeto ou a ausência de uma atribuição de função.

Solução:

• DefaultAzureCredential Verifique se ele está configurado corretamente. Se você usar o CLI do Azure, execute az login. Se você usar a CLI do Desenvolvedor do Azure, execute azd auth login.
• Confirme se sua conta tem a função de Usuário do Foundry no projeto Foundry.
• Verifique se a URL do ponto de extremidade do projeto está correta e inclui os nomes da conta e do projeto.

Erros de mapeamento de campo ou formato de dados

Se uma avaliação falhar com um esquema, mapeamento de dados ou erro de mapeamento de campo, os dados de teste não corresponderão ao esperado pelos avaliadores.

Solução:

• Verifique se o arquivo JSONL tem exatamente um objeto JSON válido por linha.
• Confirme se os nomes de campo no mapeamento de dados correspondem exatamente aos nomes de campo em seu conjunto de dados. Os nomes de campo diferenciam maiúsculas de minúsculas.
• Verifique se o esquema definido, como item_schema no SDK, corresponde aos campos em seu conjunto de dados.
• Para avaliações do portal, verifique se o conjunto de dados contém as colunas necessárias para o escopo de avaliação. Para avaliações de conversa, verifique se a coluna de mensagens contém mensagens de chat formatadas corretamente.
• Se você avaliar no nível da conversa, remova os avaliadores apenas de turno ou altere para a avaliação no nível do turno. Um avaliador somente de turnos usado com avaliação no nível da conversa gera um erro de nível de avaliação incompatível.

Pontuações do avaliador ausentes ou iguais a zero

Após a execução ser concluída, as pontuações de alguns avaliadores podem estar ausentes ou inesperadamente com valor zero.

Erros da ferramenta avaliadora de agentes

Caso um avaliador de agente retorne um erro devido a ferramentas não suportadas:

• Verifique as ferramentas suportadas para avaliadores de agentes.
• Como solução alternativa, encapsule ferramentas sem suporte como ferramentas de função definidas pelo usuário para que o avaliador possa avaliá-las.

problemas de avaliação do Azure Developer CLI (azd)

Esses problemas se aplicam quando você executa avaliações de agente com os azd ai agent eval comandos.

Para obter o fluxo de trabalho de avaliação do azd completo, consulte Executar avaliações do agente com a CLI do azd.

Problemas de avaliação do rastreamento

Avaliação de rastros executa avaliadores nas interações do agente que o Application Insights já capturou, em vez de reexecutar solicitações.

A identidade gerenciada do projeto não tem permissões de leitura de rastreamento

A identidade gerenciada do projeto Foundry lê rastreamentos do Application Insights. Sem a função certa, o serviço não pode consultar os rastreamentos, e a avaliação de rastreamentos não retorna dados ou falha.

Sintomas:

• A avaliação do rastreamento falha devido a um erro de permissão ou autorização.
• A execução não encontra rastreamentos, mesmo que existam rastreamentos no Application Insights.

Solução:

Atribua a função Leitor do Log Analytics à identidade gerenciada do projeto em ambos: no recurso do Application Insights e no espaço de trabalho do Log Analytics vinculado. Para localizar a ID da entidade de identidade gerenciada, consulte Verificar a atribuição de função de identidade gerenciada.

az role assignment create \
  --assignee <principal-id> \
  --role "Log Analytics Reader" \
  --scope "<application-insights-or-log-analytics-resource-id>"

Execute o comando duas vezes: uma vez para o recurso do Application Insights e uma vez para o workspace Log Analytics ao qual ele está vinculado. As atribuições de função podem levar até 10 minutos para serem propagadas. Para obter detalhes de instalação, consulte Configurar o rastreamento no Microsoft Foundry.

Os rastreamentos recuperados não têm mensagens de entrada ou saída

Os avaliadores de qualidade leem a consulta e a resposta de cada rastreamento. Se os spans recuperados invoke_agent não tiverem nem o atributo gen_ai.input.messages nem o atributo gen_ai.output.messages, os avaliadores não terão conteúdo da conversa para avaliar.

Sintomas:

• Os avaliadores de qualidade, como coerência, fluência, relevância e resolução da intenção, retornam score=None.
• Os avaliadores de segurança são executados, mas não produzem resultados significativos.

Causa: O agente não emite os atributos de mensagem do GenAI nos seus invoke_agent spans, portanto os rastreamentos capturados não contêm o conteúdo da conversa. O serviço de avaliação lê somente intervalos em que gen_ai.operation.name é igual a invoke_agent.

Solução:

• Certifique-se de que seu agente emita spans do OpenTelemetry que sigam as convenções semânticas do GenAI, incluindo os atributos gen_ai.input.messages e gen_ai.output.messages nos spans invoke_agent.

• Para agentes Python criados com o SDK Azure AI Agent Server, instale o extra de rastreamento para que os spans sejam emitidos automaticamente:

  pip install "azure-ai-agentserver-core[tracing]"
  

• No Application Insights, confirme se os invoke_agent intervalos incluem os atributos de mensagem antes de executar novamente a avaliação.

Avaliação humana

Esta seção aborda problemas comuns com o recurso de avaliação humana para agentes do Foundry.

O botão comentários não aparece depois que o agente responde

Causa: Nenhum modelo de avaliação é definido como ativo para o agente.

Resolução: Na guia Avaliação Humana , selecione Definir como ativo para o modelo desejado. Somente um modelo pode estar ativo por vez. Para obter mais informações, consulte Configurar a avaliação humana para seus agentes.

Nenhum resultado visível na seção Resultados da Avaliação

Causa: O Application Insights não está configurado para o projeto ou há um atraso na ingestão de dados (até 5 minutos após o envio de uma avaliação).

Resolução: Verifique se o Application Insights está conectado ao seu projeto. Para obter instruções de instalação, consulte Configurar o Application Insights para rastreamento de agente. Se o Application Insights já estiver configurado, aguarde alguns minutos e atualize a página.

O revisor não pode acessar o aplicativo Web de visualização

Causa: O revisor não tem a função necessária no projeto Foundry.

Resolução: Atribua a função de Usuário do Foundry ao revisor no projeto Foundry. Para obter instruções, consulte o controle de acesso baseado em Role no Microsoft Foundry.

Conteúdo relacionado

• Adicionar uma nova conexão ao seu projeto
• Conectar-se ao seu próprio armazenamento
• Limites de taxa, suporte à região e recursos corporativos para avaliação
• Avaliar seus agentes de IA
• Executar avaliações de agente com a CLI do azd
• Executar avaliações do portal do Foundry
• Exibir os resultados da avaliação no portal do Foundry
• Configure o rastreamento no Microsoft Foundry
• Configurar avaliação humana para os seus agentes