Avaliação de problemas e questões de observabilidade

Este artigo fornece informações para o ajudar a resolver problemas comuns que possa encontrar ao utilizar funcionalidades de avaliação e observabilidade no Microsoft Foundry. Algumas questões relacionam-se com a configuração da conta de armazenamento, controlo de acesso baseado em funções (RBAC) ou definições de rede para o projeto Foundry. Outros problemas ocorrem durante a execução da avaliação, como falhas de autenticação, limites de capacidade ou quotas do modelo, problemas no formato dos dados ou pontuações em falta.

Conta de armazenamento não ligada ao projeto Foundry

As funcionalidades de avaliação exigem uma conta de armazenamento ligada ao seu projeto Foundry através de uma ligação. Se a conta de armazenamento não estiver ligada, as avaliações falham porque o serviço não consegue ler ou escrever dados de avaliação.

Sintomas:

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

Liga uma conta de armazenamento ao projeto Foundry

Ligue a sua conta de armazenamento ao projeto Foundry criando uma ligação ao Armazenamento de Blobs do Azure. Para instruções passo a passo, veja Adicionar uma nova ligação ao seu projeto.

Pode autenticar a ligação usando uma chave conta ou Microsoft Entra ID (recomendado). Se usar Entra ID, consulte Atribuição de funções RBAC em falta para autenticação Entra ID para configurar as permissões necessárias.

Para mais detalhes sobre como trazer o seu próprio armazenamento para avaliações, consulte Limites de taxa, suporte regional e funcionalidades empresariais para avaliação.

Atribuição de funções RBAC em falta para autenticação do Microsoft Entra ID

Se conectar a sua conta de armazenamento usando autenticação do Microsoft Entra ID, a identidade gerida do projeto Foundry deve ter a função de Storage Blob Data Contributor na conta de armazenamento. Sem esta função, o serviço não consegue ler nem escrever dados de blob e as avaliações falham.

Sintomas:

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

Verifique a atribuição de papel de identidade gerida

Utilize os seguintes comandos do CLI do Azure para verificar se o papel RBAC correto está atribuído à identidade gerida do projeto Foundry na conta de armazenamento.

Primeiro, recupere o ID principal de identidade gerida para o 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

Depois, liste as atribuições de funções na conta de armazenamento e filtre pela identidade gerida:

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 Contribuidor de Dados do Blob de Armazenamento (ou Proprietário dos Dados do Blob de Armazenamento).

Atribuir o papel de Contribuidor de Dados do Blob de Armazenamento

Se faltar a atribuição de função, atribuir a função Contribuidor de Blob de Dados de Armazenamento à identidade gerida 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 de contas de armazenamento

Quando usa autenticação Microsoft Entra ID, a conta de armazenamento deve ter o acesso à rede pública ativado. Se o acesso à rede for restringido, o serviço de avaliação da Foundry pode não conseguir aceder à conta de armazenamento.

Sintomas:

• As avaliações falham devido a erros ou timeouts relacionados com a rede.
• Nota-se 403 Forbidden erros mesmo que as funções RBAC estejam corretamente atribuídas.
• As ligações à conta de armazenamento são recusadas.

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

Use o seguinte comando CLI do Azure para verificar as definiçõ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 os seguintes valores:

Se publicNetworkAccess estiver definido como Disabled ou defaultAction está definido como Deny, o serviço de avaliação não consegue aceder à conta de armazenamento.

Permitir o acesso à rede pública

Ative 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 precisares de manter o firewall ativado mas permitir o acesso, define a ação padrão para Permitir:

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

Lista de verificação para resolução de problemas

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

1. Existe uma ligação de armazenamento: Confirme que existe uma ligação Armazenamento de Blobs do Azure configurada no seu projeto Foundry. Navegue até Build>Tools no Portal Foundry para verificar.

2. Tipo de autenticação: Identifique se a ligação utiliza uma chave de conta ou Microsoft Entra ID. Se existir o Entra ID, complete as verificações restantes.

3. Função RBAC atribuída: Verificar se a identidade gerida do projeto Foundry tem a função Storage Blob Data Contributor 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 o acesso à rede pública ativado.

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

5. Atraso de propagação: Se recentemente fez alterações ao RBAC ou à rede, espere pelo menos 10 minutos antes de tentar novamente.

A execução da avaliação é lenta, fica encravada ou falha com erros de capacidade ou de quota

Uma execução de avaliação pode permanecer no estado Em execução ou em espera durante muito tempo, executar-se lentamente ou falhar com erros de quota. Esta condição normalmente acontece quando a implementação do modelo do juiz não tem capacidade suficiente, por isso o serviço limita ou tenta novamente os pedidos.

Sintomas:

• A execução permanece no estado Running ou em espera muito mais tempo do que o esperado.
• A execução falha com o erro 429 Too Many Requests.
• Vê-se erros que mencionam limites de quotas ou taxas.

Resolução:

• Confirma que a implementação do modelo de juiz tem quota suficiente. O modelo de juiz usado para avaliadores assistidos por IA conta para a sua quota do Azure OpenAI.
• Aumente a quota de tokens por minuto (TPM) para a implementação do modelo no portal do Azure e depois execute novamente a avaliação.
• Reduza o tamanho do seu conjunto de dados ou divida-o em lotes mais pequenos. Para simulações, reduza o número máximo de turnos por conversa.
• Use uma implementação de modelo de juízo mais pequena ou de menor custo para execuções mais rápidas e baratas.
• Para uma execução de SDK bloqueada, cancele-a com client.evals.runs.cancel(run_id, eval_id=eval_id), aumente a capacidade e, em seguida, submeta-a novamente.
• No caso de um erro 429, consulta o cabeçalho retry-after para conhecer o tempo de espera recomendado e usa uma estratégia de espera exponencial ao repetires a tentativa.

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 com o armazenamento, a causa é normalmente a autenticação do projeto ou uma atribuição de função em falta.

Resolução:

• Verifica se está DefaultAzureCredential configurado corretamente. Se utilizar a CLI do Azure, execute az login. Se usares a CLI do Azure Developer, executa azd auth login.
• Confirme que a sua conta tem a função Foundry User no projeto Foundry.
• Verifique se o URL do endpoint do projeto está correto e inclui tanto a conta como o nome do projeto.

Erros no formato dos dados ou no mapeamento de campos

Se uma avaliação falhar com um erro de esquema, mapeamento de dados ou mapeamento de campos, os dados de teste não correspondem ao que os avaliadores esperam.

Resolução:

• Verifica se o teu ficheiro JSONL tem exatamente um objeto JSON válido por linha.
• Confirma que os nomes dos campos no teu mapeamento de dados correspondem exatamente aos nomes dos campos no teu conjunto de dados. Os nomes dos campos são sensíveis a maiúsculas e minúsculas.
• Verifique se o esquema que define, como item_schema no SDK, corresponde aos campos do seu conjunto de dados.
• Para avaliações do portal, verifique se o seu conjunto de dados contém as colunas necessárias para o âmbito da avaliação. Para avaliações de conversas, certifique-se de que a coluna de mensagens contém mensagens de chat devidamente formatadas.
• Se avaliares ao nível da conversa, remove avaliadores só por turnos ou muda para avaliação por turnos. Um avaliador por turnos usado com avaliação ao nível da conversa causa um erro incompatível ao nível da avaliação.

Pontuações dos avaliadores em falta ou a zero

Após a conclusão de uma corrida, algumas pontuações dos avaliadores podem falhar ou ser inesperadamente zero.

Erros na ferramenta avaliadora de agentes

Se um avaliador de agente retornar um erro devido a ferramentas não suportadas:

• Verifique as ferramentas suportadas para avaliadores de agentes.
• Como solução alternativa, envolva ferramentas não suportadas como ferramentas de função definidas pelo utilizador para que o avaliador as possa avaliar.

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

Estes problemas aplicam-se quando executas avaliações de agentes com os azd ai agent eval comandos.

Para o fluxo de trabalho completo de avaliação azd, veja Executar avaliações de agentes com a CLI azd.

Problemas de avaliação de rastreio

A avaliação de rastreamento executa avaliadores contra interações com agentes que o Application Insights já capturou, em vez de repetir pedidos.

A identidade gerida do Project está sem permissões de leitura de traços

A identidade gerida do projeto Foundry lê rastreios do Application Insights. Sem a função certa, o serviço não consegue consultar os rastreios, e a avaliação dos rastreios não devolve dados ou falha.

Sintomas:

• A avaliação de traços falha devido a um erro de permissão ou autorização.
• A execução não encontra rastos, embora existam vestígios no Application Insights.

Resolução:

Atribua o papel Log Analytics Reader à identidade gerida do projeto tanto no recurso Application Insights como no respetivo espaço de trabalho do Log Analytics associado. Para encontrar o ID do principal da identidade gerida, consulte Verificar a atribuição de função da identidade gerida.

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 para o recurso Application Insights e outra para o espaço de trabalho Log Analytics a que está ligado. As atribuições de funções podem demorar até 10 minutos a propagar-se. Para detalhes de configuração, consulte Configurar traçado no Microsoft Foundry.

Os rastos obtidos não têm mensagens de entrada nem de saída

Os avaliadores de qualidade leem a consulta e a resposta de cada traço. Se os spans obtidos invoke_agent não tiverem nem o atributo gen_ai.input.messages nem o atributo gen_ai.output.messages, os avaliadores não têm conteúdo da conversa para avaliar.

Sintomas:

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

Causa: O agente não emite os atributos da mensagem GenAI nos seus invoke_agent spans, por isso as pistas capturadas não contêm o conteúdo da conversa. O serviço de avaliação lê apenas os segmentos em que gen_ai.operation.name é igual a invoke_agent.

Resolução:

• Certifique-se de que o seu agente emite spans do OpenTelemetry em conformidade com 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 construídos com o Azure AI Agent Server SDK, instale o rastreamento extra para que os spans sejam emitidos automaticamente:

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

• No Application Insights, confirme que os invoke_agent spans incluem os atributos da mensagem antes de reexecutar a avaliação.

Avaliação humana

Esta secção aborda questões comuns com a funcionalidade de avaliação humana para agentes da Foundry.

O botão de feedback não aparece depois da resposta do agente

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

Resolução: No separador Avaliação Humana , selecione Definir como ativo para o modelo desejado. Só pode estar ativo um template de cada vez. Para mais informações, consulte Configurar avaliação humana para os seus agentes.

Não há resultados visíveis na secção de Resultados de 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 a submissão da avaliação).

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

O revisor não consegue aceder à aplicação web de pré-visualização

Causa: O revisor não tem o papel exigido no projeto Foundry.

Resolução: Atribuir o papel de Utilizador Foundry ao revisor do projeto Foundry. Para instruções, veja Controlo de acesso baseado em funções no Microsoft Foundry.

Conteúdo relacionado

• Adicione uma nova ligação ao seu projeto
• Liga-te ao teu próprio armazenamento
• Limites de taxa, suporte regional e funcionalidades empresariais para avaliação
• Avalie os seus agentes de IA
• Executa avaliações de agentes com o CLI azd
• Executar avaliações no portal da Foundry
• Consulte os resultados das avaliações no portal da Foundry
• Configurar o traçado no Microsoft Foundry
• Marque uma avaliação humana para os seus agentes