Solución de problemas de evaluación y observabilidad

En este artículo se proporciona información para ayudarle a resolver problemas comunes que puede encontrar al usar características de evaluación y observabilidad en Microsoft Foundry. Algunos problemas se relacionan con la configuración de la cuenta de almacenamiento, el control de acceso basado en rol (RBAC) o la configuración de red del proyecto Foundry. Otros problemas se producen mientras se ejecuta una evaluación, como errores de autenticación, capacidad del modelo o límites de cuota, problemas de formato de datos o puntuaciones que faltan.

Cuenta de almacenamiento no vinculada al proyecto Foundry

Las características de evaluación requieren una cuenta de almacenamiento vinculada al proyecto foundry a través de una conexión. Si la cuenta de almacenamiento no está conectada, se producirá un error en las evaluaciones porque el servicio no puede leer ni escribir datos de evaluación.

Síntomas:

  • Las evaluaciones fallan con errores relacionados con el acceso al almacenamiento o una configuración de almacenamiento faltante.
  • El servicio de evaluación no puede cargar resultados de evaluación ni descargar conjuntos de datos.

Conexión de una cuenta de almacenamiento al proyecto Foundry

Conecte la cuenta de almacenamiento al proyecto Foundry mediante la creación de una conexión Azure Blob Storage. Para obtener instrucciones paso a paso, consulte Adición de una nueva conexión al proyecto.

Puede autenticar la conexión mediante una clave account o Microsoft Entra ID (recomendado). Si utiliza Entra ID, consulte Falta la asignación de roles RBAC para la autenticación con Entra ID para configurar los permisos necesarios.

Para obtener más información sobre cómo incorporar su propio almacenamiento para las evaluaciones, consulte Límites de velocidad, compatibilidad con regiones y características empresariales para la evaluación.

Falta de asignación de rol de RBAC para la autenticación de Microsoft Entra ID

Si conecta su cuenta de almacenamiento mediante la autenticación de Microsoft Entra ID, la identidad administrada del proyecto de Foundry debe tener el rol Colaborador de datos de Storage Blob en la cuenta de almacenamiento. Sin este rol, el servicio no puede leer ni escribir datos de blobs, y las evaluaciones fallan.

Síntomas:

  • Las evaluaciones fallan con errores 403 Forbidden o AuthorizationPermissionMismatch.
  • Verá errores que indican permisos insuficientes para acceder a la cuenta de almacenamiento.
  • Las operaciones de almacenamiento agotan el tiempo de espera o se deniegan.

Comprobación de la asignación de roles de identidad administrada

Use los siguientes comandos de CLI de Azure para comprobar si el rol RBAC correcto se asigna a la identidad administrada del proyecto Foundry en la cuenta de almacenamiento.

En primer lugar, recupere el ID de entidad de la identidad administrada de su proyecto de Foundry:

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

A continuación, enumere las asignaciones de roles en la cuenta de almacenamiento y filtre por la identidad administrada:

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

Compruebe que la salida incluye una asignación de roles con establecida en RoleDefinitionNameColaborador de datos de Storage Blob (o Propietario de datos de Storage Blob).

Asigne el rol Colaborador de datos de blobs de almacenamiento

Si falta la asignación de roles, asigne el rol Colaborador de datos de Storage Blob a la identidad administrada del proyecto 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>"

Nota

Las asignaciones de roles pueden tardar hasta 10 minutos en propagarse. Espere unos minutos después de asignar el rol antes de volver a intentar la evaluación.

Restricciones de acceso de red de la cuenta de almacenamiento

Cuando se usa Microsoft Entra ID autenticación, la cuenta de almacenamiento debe tener habilitado el acceso a la red pública. Si el acceso a la red está restringido, es posible que el servicio de evaluación de Foundry no pueda acceder a la cuenta de almacenamiento.

Síntomas:

  • Las evaluaciones fallan debido a errores de red o tiempos de espera.
  • Aparecen errores 403 Forbidden aunque los roles RBAC estén correctamente asignados.
  • Se rechazan las conexiones a la cuenta de almacenamiento.

Comprobación de la configuración de red de la cuenta de almacenamiento

Use el siguiente comando CLI de Azure para comprobar la configuración de acceso a la red de la cuenta de almacenamiento:

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 la salida para los siguientes valores:

Propiedad Valor esperado Descripción
publicNetworkAccess Enabled El acceso a la red pública debe estar habilitado.
defaultAction Allow La regla de red predeterminada debe permitir el acceso.

Si publicNetworkAccess se establece en Disabled o defaultAction se establece en Deny, el servicio de evaluación no puede acceder a la cuenta de almacenamiento.

Nota

En el caso de las configuraciones de agente basadas en redes virtuales (aisladas de red) en las que se espera que los recursos funcionen con el acceso a la red pública deshabilitado y dependen de la red virtual de conectividad de puntos de conexión privados en su lugar, consulte Configuración de redes privadas.

Habilitación del acceso a la red pública

Habilite el acceso a la red pública en la cuenta de almacenamiento:

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

Si necesita mantener habilitado el firewall, pero permitir el acceso, establezca la acción predeterminada en Permitir:

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

Importante

Habilitar el acceso a la red pública o establecer la acción predeterminada en Permitir hace que la cuenta de almacenamiento sea accesible desde todas las redes. Evalúe este cambio con respecto a los requisitos de seguridad de su organización.

Lista de comprobación de solución de problemas

Use esta lista de comprobación para comprobar rápidamente la configuración de evaluación:

  1. Conexión de almacenamiento existe: Confirme que hay una conexión de Azure Blob Storage configurada en el proyecto Foundry. Vaya a Herramientas de compilación>en el portal de Foundry para comprobarlo.

  2. Tipo de autenticación: identifique si la conexión usa una clave de cuenta o Microsoft Entra ID. Si se utiliza Entra ID, complete las comprobaciones restantes.

  3. Rol RBAC asignado: compruebe que la identidad administrada del proyecto Foundry tiene el rol Colaborador de datos de Storage Blob en la cuenta de almacenamiento.

    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. Acceso a la red: compruebe que la cuenta de almacenamiento tiene habilitado el acceso a la red pública.

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

  5. Retraso de propagación: si ha realizado cambios de RBAC o de red recientemente, espere al menos 10 minutos antes de volver a intentarlo.

La ejecución de la evaluación es lenta, se bloquea o falla debido a errores de capacidad o de cuota

Una ejecución de evaluación puede permanecer durante mucho tiempo en estado Running o pendiente, ejecutarse lentamente o fallar por errores de cuota. Esta situación suele producirse cuando la implementación del modelo de referencia no dispone de suficiente capacidad, por lo que el servicio limita el flujo de solicitudes o las reenvía.

Síntomas:

  • La ejecución permanece en el estado Running o en estado pendiente durante mucho más tiempo del esperado.
  • Se produce un 429 Too Many Requests error en la ejecución.
  • Verá errores que mencionan límites de cuota o tasa.

Solución:

  • Compruebe que la implementación del modelo de evaluación disponga de suficiente cuota. El modelo de evaluación que se usa para los evaluadores asistidos por IA se descuenta de la cuota de Azure OpenAI.
  • Aumente la cuota de tokens por minuto (TPM) para la implementación del modelo en el portal de Azure y vuelva a ejecutar la evaluación.
  • Reduzca el tamaño del conjunto de datos o divida en lotes más pequeños. En el caso de las simulaciones, reduzca los turnos máximos por conversación.
  • Utilice una implementación de modelo de evaluación más pequeño o de menor coste para ejecuciones más rápidas y económicas.
  • Para una ejecución de SDK bloqueada, cancele con client.evals.runs.cancel(run_id, eval_id=eval_id), aumente la capacidad y vuelva a enviarla.
  • En caso de error 429, consulte el encabezado retry-after para ver el tiempo de espera recomendado y aplique una espera exponencial al reintentar.

Errores de autenticación o autorización (401 o 403)

Si una evaluación falla con un error 401 Unauthorized o 403 Forbidden que no está relacionado con el almacenamiento, la causa suele ser un problema de autenticación del proyecto o la falta de una asignación de roles.

Nota

Si el error menciona 403 blob o el acceso al almacenamiento, consulte Falta la asignación de roles de RBAC para la autenticación de Entra ID en su lugar.

Solución:

  • Compruebe que DefaultAzureCredential está configurado correctamente. Si usa el CLI de Azure, ejecute az login. Si usa la CLI para desarrolladores de Azure, ejecute azd auth login.
  • Confirme que la cuenta tiene el rol Foundry User en el proyecto Foundry.
  • Compruebe que la dirección URL del punto de conexión del proyecto es correcta e incluya los nombres de la cuenta y del proyecto.

Importante

Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

Errores de asignación de campos o formato de datos

Si se produce un error de evaluación con un error de esquema, asignación de datos o asignación de campos, los datos de prueba no coinciden con lo que esperan los evaluadores.

Solución:

  • Compruebe que el archivo JSONL tiene exactamente un objeto JSON válido por línea.
  • Confirme que los nombres de campo en su asignación de datos coinciden exactamente con los nombres de campo de su conjunto de datos. Los nombres de campo distinguen entre mayúsculas y minúsculas.
  • Compruebe que el esquema que defina, como item_schema en el SDK, coincida con los campos del conjunto de datos.
  • Para las evaluaciones del portal, compruebe que el conjunto de datos contiene las columnas necesarias para el ámbito de evaluación. Para las evaluaciones de conversación, asegúrese de que la columna mensajes contiene mensajes de chat con formato correcto.
  • Si realiza la evaluación en el nivel de conversación, elimine los evaluadores que solo tienen en cuenta los turnos o cambie a una evaluación en el nivel de turno. Un evaluador de turnos individuales utilizado con una evaluación en el nivel de conversación provoca un error por incompatibilidad del nivel de evaluación.

Faltan o cero puntuaciones del evaluador

Una vez finalizada una ejecución, es posible que falten algunas puntuaciones del evaluador o que sean cero de forma inesperada.

Síntoma Causa posible Acción
Falta la métrica de un evaluador El evaluador no se seleccionó cuando se creó la evaluación. Vuelva a ejecutar la evaluación y seleccione los evaluadores necesarios.
Todas las métricas de seguridad son cero La categoría de seguridad está desactivada o el modelo no es compatible con el evaluador. Confirme la compatibilidad de modelos y evaluadores en Evaluadores de riesgo y seguridad.
El nivel de fundamentación es inesperadamente bajo El contexto de recuperación está incompleto Compruebe cómo se construye el contexto y compruebe la latencia de recuperación.
Muchas filas muestran errores o puntuaciones bajas Errores de respuesta del agente o del evaluador durante la ejecución Abra el informe de ejecución, revise las filas con errores, corrija los errores subyacentes y vuelva a ejecutarse.

Errores de la herramienta de evaluador de agentes

Si un evaluador de agentes devuelve un error cuando las herramientas no son compatibles:

  • Compruebe las herramientas admitidas para los evaluadores de agentes.
  • Como solución alternativa, encapsula las herramientas no admitidas como herramientas de función definidas por el usuario para que el evaluador pueda evaluarlas.

problemas de evaluación de la CLI para desarrolladores (azd) de Azure

Estos problemas se aplican al ejecutar evaluaciones del agente con los azd ai agent eval comandos .

Issue Solución
azd ai agent eval el comando no se encuentra o falla Ejecute azd ext list y compruebe que la azd ai agent extensión es 0.1.40-versión preliminar o posterior. Actualice con azd ext upgrade azure.ai.agents.
Destino de evaluación no encontrado o agente no invocable Confirme que el agente está implementado e invocable con azd ai agent show. Vuelva a implementar con azd deploy si es necesario.
No se encontró la implementación del modelo de evaluación Compruebe que el nombre de implementación de finalización de chat existe en su proyecto, en Compilación>Implementaciones.

Para obtener el flujo de trabajo completo de evaluación de azd, consulte Ejecución de evaluaciones del agente con la CLI de azd.

Problemas de evaluación de seguimiento

La evaluación de trazas ejecuta evaluadores sobre las interacciones del agente que Application Insights ya ha capturado, en lugar de volver a ejecutar solicitudes.

La identidad administrada del proyecto no tiene permisos de lectura de seguimiento

La identidad administrada del proyecto de Foundry lee las trazas de Application Insights. Sin el rol correcto, el servicio no puede consultar seguimientos y la evaluación de seguimiento no devuelve datos ni produce errores.

Síntomas:

  • La evaluación del seguimiento falla con un error de permisos o de autorización.
  • La ejecución no encuentra ningún seguimiento aunque existan seguimientos en Application Insights.

Solución:

Asigne el rol Lector de Log Analytics a la identidad administrada del proyecto tanto en el recurso de Application Insights como en su área de trabajo de Log Analytics vinculada. Para buscar el identificador de entidad de seguridad de identidad administrada, consulte Comprobación de la asignación de roles de identidad administrada.

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

Ejecute el comando dos veces: una para el recurso de Application Insights y una vez para el área de trabajo de Log Analytics a la que está vinculado. Las asignaciones de roles pueden tardar hasta 10 minutos en propagarse. Para obtener más información sobre la configuración, consulte Configuración del seguimiento en Microsoft Foundry.

Nota

Si las tablas de Log Analytics que almacenan los seguimientos están protegidas (su nivel de protección está establecido en Protegido), el rol lector de Log Analytics no puede leerlos. En ese caso, asigne también el rol Lector de datos de supervisión con privilegios a la identidad administrada en los mismos ámbitos para que la evaluación de seguimiento pueda leer las tablas de seguimiento protegidas.

Las trazas obtenidas no tienen mensajes de entrada ni de salida

Los evaluadores de calidad leen la consulta y la respuesta de cada traza. Si los segmentos obtenidos invoke_agent no tienen ni el atributo gen_ai.input.messages ni el atributo gen_ai.output.messages, los evaluadores no tienen contenido de la conversación que evaluar.

Síntomas:

  • Los evaluadores de calidad, como la coherencia, la fluidez, la relevancia y la resolución de intenciones, devuelven score=None.
  • Los evaluadores de seguridad se ejecutan, pero no generan resultados significativos.

Causa: El agente no emite los atributos de mensaje de GenAI en sus invoke_agent tramos, por lo que las trazas capturadas no contienen el contenido de la conversación. El servicio de evaluación solo lee intervalos donde gen_ai.operation.name es igual a invoke_agent.

Solución:

  • Asegúrese de que su agente emita spans de OpenTelemetry que sigan las convenciones semánticas de GenAI, incluidos los atributos gen_ai.input.messages y gen_ai.output.messages en los spans invoke_agent.

  • Para agentes de Python creados con el SDK de Azure AI Agent Server, instale el complemento de seguimiento para que las trazas se emitan automáticamente:

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

  • En Application Insights, confirma que los invoke_agent tramos incluyen los atributos del mensaje antes de volver a ejecutar la evaluación.

Evaluación humana

En esta sección se tratan los problemas comunes con la característica de evaluación humana para agentes de Foundry.

El botón Comentarios no aparece después de que el agente responda

Causa: No hay ninguna plantilla de evaluación establecida como activa para el agente.

Resolución: En la pestaña Evaluación humana , seleccione Establecer como activo para la plantilla deseada. Solo una plantilla puede estar activa a la vez. Para obtener más información, consulte Configuración de la evaluación humana para los agentes.

No hay resultados visibles en la sección Resultados de evaluación

Causa: Application Insights no está configurado para el proyecto o hay un retraso de ingesta de datos (hasta 5 minutos después de enviar una evaluación).

Resolución: Compruebe que Application Insights está conectado al proyecto. Para obtener instrucciones de configuración, consulte Configuración de Application Insights para el seguimiento de agentes. Si Application Insights ya está configurado, espere unos minutos y actualice la página.

El revisor no puede acceder a la aplicación web en versión preliminar

Causa: El revisor no tiene el rol necesario en el proyecto Foundry.

Resolución: Asigne el rol Foundry User al revisor en el proyecto Foundry. Para obtener instrucciones, consulte control de acceso basado en roles en Microsoft Foundry.

Contenido relacionado

  • Last updated on