Depuración de un conjunto de aptitudes de Azure AI Search en Azure Portal

  • Artículo

Inicie una sesión de depuración basada en el portal para identificar y resolver errores, validar los cambios e insertar cambios en un conjunto de aptitudes publicado en un servicio Azure AI Search.

Una sesión de depuración es una ejecución de indexador y conjunto de aptitudes almacenada en caché, orientada a un único documento, que puede usar para editar y probar los cambios de forma interactiva. Cuando haya terminado de depurar, puede guardar los cambios en el conjunto de aptitudes.

Para obtener información sobre cómo funciona una sesión de depuración, consulte Sesiones de depuración en Azure AI Search. Para practicar un flujo de trabajo de depuración con un documento de ejemplo, consulte Tutorial: Sesiones de depuración.

Requisitos previos

  • Una canalización de enriquecimiento existente, que incluye un origen de datos, un conjunto de aptitudes, un indexador y un índice.

  • Una instancia del servicio Search con una asignación de roles del tipo Colaborador.

  • Una cuenta de Azure Storage, que se usa para guardar el estado de la sesión.

  • Una asignación de roles de Colaborador de datos de Storage Blob en Azure Storage si usa una identidad administrada por el sistema. De lo contrario, planee el uso de una cadena de conexión de acceso completo para la conexión de sesión de depuración a Azure Storage.

  • Si utiliza un firewall para proteger la cuenta de Azure Storage, configúrelo para que este permita el acceso al servicio de búsqueda.

Limitaciones

Las sesiones de depuración funcionan con todos los orígenes de datos del indexador disponibles en general y con la mayoría de los orígenes de datos de versión preliminar. En la lista siguiente se muestran las excepciones:

  • Actualmente no se admite Azure Cosmos DB for MongoDB.

  • En Azure Cosmos DB for NoSQL, si se produce un error en una fila durante la ejecución del indexado y no se encuentran metadatos correspondientes, es posible que la sesión de depuración no elija la fila correcta.

  • En el caso de la API de SQL de Azure Cosmos DB, si una colección con particiones anteriormente no tenía particiones, la sesión de depuración no encontrará el documento.

  • En el caso de las aptitudes personalizadas, no se admite una identidad administrada asignada por el usuario para una conexión de sesión de depuración a Azure Storage. Como se indica en los requisitos previos, puede usar una identidad administrada por el sistema o especificar una cadena de conexión de acceso completo que incluya una clave. Para más información, consulte Conexión de un servicio de búsqueda a otros recursos de Azure mediante una identidad administrada.

El portal no admite el cifrado de claves administradas por el cliente (CMK), lo que significa que las experiencias del portal, como las sesiones de depuración, no pueden tener cadenas de conexión cifradas con CMK u otros metadatos cifrados. Si el servicio de búsqueda está configurado para aplicación de CMK, las sesiones de depuración no funcionarán.

Creación de una sesión de depuración

  1. Inicie sesión en Azure Portal y busque su servicio de búsqueda.

  2. En la página de navegación izquierda, seleccione Sesiones de depuración.

  3. En la barra de acciones de la parte superior, seleccione Agregar sesión de depuración.

    Captura de pantalla de los comandos de sesiones de depuración en la página del portal.

  4. En Debug session name (Nombre de la sesión de depuración), proporcione un nombre que le ayude a recordar de qué conjunto de aptitudes, indexador y origen de datos trata la sesión de depuración.

  5. En Storage connection (Conexión de almacenamiento), busque una cuenta de almacenamiento de uso general para almacenar en caché la sesión de depuración. Se le pedirá que seleccione y, opcionalmente, cree un contenedor de blobs en Blob Storage o Azure Data Lake Storage Gen2. Puede reutilizar el mismo contenedor para todas las sesiones de depuración posteriores que cree. Un nombre de contenedor útil podría ser "cognitive-search-debug-sessions".

  6. En autenticación de identidad administrada, elija Ninguno si la conexión a Azure Storage no usa una identidad administrada. De lo contrario, elija la identidad administrada a la que ha concedido permisos de Colaborador de datos de Storage Blob.

  7. En Plantilla del indexador, seleccione el indexador que impulsa el conjunto de aptitudes que quiere depurar. Las copias tanto del indexador como del conjunto de aptitudes se usan para inicializar la sesión.

  8. En Document to debug (Documento que se va a depurar), elija el primer documento del índice o seleccione un documento específico. Si selecciona un documento específico, se le pide un URI o un identificador de fila en función del origen de datos.

    Si el documento específico es un blob, proporcione el URI del blob. Puede encontrar el URI en la página de propiedades del blob en el portal.

    Captura de pantalla de la propiedad URI en Blob Storage.

  9. Si lo desea, en Configuración del indexador, especifique cualquier configuración de ejecución del indexador usada para crear la sesión. La configuración debe imitar la configuración que utiliza el indexador real. Las opciones del indexador que especifique en una sesión de depuración no tienen ningún efecto en el propio indexador.

  10. La configuración debe tener un aspecto similar a esta captura de pantalla. Seleccione Guardar sesión para comenzar.

    Captura de pantalla de una página de sesión de depuración.

Para empezar la sesión de depuración, se ejecuta el indexador y el conjunto de aptitudes en el documento seleccionado. El contenido y los metadatos del documento creados estarán visibles y disponibles en la sesión.

Se puede cancelar una sesión de depuración mientras se ejecuta mediante el botón Cancelar. Si presiona el botón Cancelar, debería poder analizar los resultados parciales.

Se espera que una sesión de depuración tarde más tiempo en ejecutarse que el indexador, ya que pasa por un procesamiento adicional.

Inicio con errores y advertencias

El historial de ejecución del indexador del portal proporciona la lista completa de errores y advertencias para todos los documentos. En una sesión de depuración, los errores y advertencias se limitarán a un documento. Recorrerá esta lista, hará los cambios y, después, volverá a la lista para comprobar si se resuelven los problemas.

Para ver los mensajes, seleccione una aptitud en AI Enrichment > Skill Graph (Enriquecimiento de IA > Grafo de aptitudes) y, después, seleccione Errors/Warnings (Errores o advertencias) en el panel de detalles.

Como procedimiento recomendado, resuelva los problemas con las entradas antes de pasar a las salidas.

Para demostrar si una modificación resuelve un error, siga estos pasos:

  1. Seleccione Guardar en el panel de detalles de la aptitud para conservar los cambios.

  2. Seleccione Ejecutar en la ventana de sesión para invocar la ejecución del conjunto de aptitudes mediante la definición modificada.

  3. Vuelva a Errores o advertencias para ver si se reduce el recuento. La lista no se actualizará hasta que abra la pestaña.

Visualización del contenido de los nodos de enriquecimiento

Las canalizaciones de enriquecimiento con inteligencia artificial extraen o deducen la información y estructura de los documentos de origen, creando un documento enriquecido en el proceso. La primera vez que se crea un documento enriquecido es durante el descifrado de documentos y se rellena con un nodo raíz (/document), además de nodos para cualquier contenido que se extraiga directamente del origen de datos, como los metadatos y la clave de documento. Las aptitudes crean más nodos durante la ejecución de aptitudes, donde la salida de cada aptitud agrega un nuevo nodo al árbol de enriquecimiento.

Los documentos enriquecidos son internos, pero una sesión de depuración proporciona acceso al contenido generado durante la ejecución de la aptitud. Para ver el contenido o la salida de cada aptitud, siga estos pasos:

  1. Comience con las vistas predeterminadas: AI enrichment > Skill Graph (Enriquecimiento con IA > Grafo de IA), con el tipo de grafo establecido en Dependency Graph (Grafo de dependencia).

  2. Seleccione una aptitud.

  3. En el panel de detalles de la derecha, seleccione Executions (Ejecuciones), seleccione una salida y, después, abra el evaluador de expresiones (</>) para ver la expresión y su resultado.

    Captura de pantalla de una ejecución de aptitudes en la que se muestran los valores de salida.

  4. Como alternativa, abra AI enrichment > Enriched Data Structure (Enriquecimiento con IA > Estructura de datos enriquecida) para desplazarse hacia abajo en la lista de nodos. La lista incluye nodos potenciales y reales, con una columna para la salida, y otra columna que indica el objeto ascendente que se utiliza para generar la salida.

    Captura de pantalla del documento enriquecido que muestra los valores de salida.

Edición de definiciones de aptitud

Si las asignaciones de campos son correctas, compruebe la configuración y el contenido de las aptitudes individuales. Si una aptitud no genera resultados, es posible que falte una propiedad o un parámetro, que se puede determinar a través de mensajes de error y validación.

Otros problemas, como un contexto no válido o una expresión de entrada, pueden ser más difíciles de resolver porque el error le mostrará lo que está mal, pero no cómo corregirlo. Para obtener ayuda con el contexto y la sintaxis de entrada, consulte Enriquecimientos de referencia en un conjunto de aptitudes de Azure AI Search. Para obtener ayuda con mensajes individuales, consulte Solución de errores y advertencias del indexador comunes.

En los pasos siguientes se muestra cómo obtener información sobre una aptitud.

  1. En AI enrichment > Skill Graph (Enriquecimiento con IA > Grafo de aptitudes), seleccione una aptitud. El panel Skill Details (Detalles de la aptitud) se abre a la derecha.

  2. Edite una definición de aptitud mediante cualquiera de estos enfoques:

    • Configuración de aptitud si prefiere un editor visual
    • Editor JSON de aptitudes para editar el documento JSON directamente

  3. Compruebe la sintaxis de la ruta de acceso para hacer referencia a los nodos de un árbol de enriquecimiento. A continuación se muestran algunas de las rutas de acceso de entrada más comunes:

    • /document/content para fragmentos de texto. Este nodo se rellena a partir de la propiedad content del blob.
    • /document/merged_content para fragmentos de texto en conjuntos de aptitudes que incluyen la aptitud Combinación de texto.
    • /document/normalized_images/* para el texto que se reconoce o se deduce de las imágenes.

Comprobación de asignaciones de campos

Si las aptitudes generan una salida, pero el índice de búsqueda está vacío, compruebe las asignaciones de campos. Las asignaciones de campos especifican cómo el contenido sale de la canalización y entra en un índice de búsqueda.

  1. Comience con las vistas predeterminadas: AI enrichment > Skill Graph (Enriquecimiento con IA > Grafo de IA), con el tipo de grafo establecido en Dependency Graph (Grafo de dependencia).

  2. Seleccione Asignaciones de campos cerca de la parte superior. Debe encontrar al menos la clave del documento que identifica y asocia de forma única cada documento de búsqueda del índice de búsqueda con su documento de origen en el origen de datos.

    Si va a importar contenido sin procesar directamente desde el origen de datos y omite el enriquecimiento, debe buscar esos campos en Asignaciones de campos.

  3. Seleccione Asignaciones de campos de salida cerca de la parte inferior del grafo. Aquí encontrará asignaciones de salidas de aptitudes a campos de destino en el índice de búsqueda. A menos que haya usado el Asistente para importar datos, las asignaciones de campos de salida se definen manualmente y podrían estar incompletas o mal escritas.

    Compruebe que los campos de Asignaciones de campos de salida existen en el índice de búsqueda según lo especificado, para lo que comprueba la ortografía y la sintaxis de la ruta de acceso del nodo de enriquecimiento.

    Captura de pantalla del nodo Asignaciones de campos de salida y detalles.

Depurar una capacidad personalizada localmente

Las aptitudes personalizadas pueden ser más difíciles de depurar porque el código se ejecuta externamente, por lo que la sesión de depuración no se puede usar para depurarlas. En esta sección se describe cómo depurar localmente la aptitud de API web personalizada, la sesión de depuración, Visual Studio Code y ngrok o Tunnelmole. Esta técnica funciona con capacidades personalizadas que se ejecutan en Azure Functions o cualquier otro Web Framework que se ejecuta localmente (por ejemplo, FastAPI).

Obtener una dirección URL pública

Uso de Tunnelmole

Tunnelmole es una herramienta de tunelización de código abierto que puede crear una dirección URL pública que reenvía las solicitudes a la máquina local a través de un túnel.

  1. Instalar Tunnelmole:

    • npm: npm install -g tunnelmole
    • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
    • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
    • Windows: instalación mediante npm. O bien, si no tiene NodeJS instalado, descargue el archivo .exe precompilado para Windows y colóquelo en algún lugar de la ruta de acceso.

  2. Ejecute este comando para crear un nuevo túnel:

    tmole 7071

    Debería ver una respuesta similar a la siguiente:

    http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071

    En el ejemplo anterior, https://m5hdpb-ip-49-183-170-144.tunnelmole.net reenvía al puerto 7071 en el equipo local, que es el puerto predeterminado donde se exponen las funciones de Azure.

Uso de ngrok

ngrok es una aplicación popular, de código cerrado y multiplataforma que puede crear una dirección URL de tunelización o reenvío, de modo que las solicitudes de Internet lleguen a la máquina local. Use ngrok para reenviar solicitudes de una canalización de enriquecimiento en el servicio de búsqueda a la máquina para permitir la depuración local.

  1. Instalar ngrok.

  2. Abra un terminal y vaya a la carpeta con el ejecutable ngrok.

  3. Ejecute ngrok con el siguiente comando para crear un nuevo túnel:

    ngrok http 7071

    Nota:

    De forma predeterminada, las funciones de la solución Función de Azure se encuentran en el puerto 7071. Otras herramientas y configuraciones pueden requerir que proporcione un puerto diferente.

  4. Cuando se inicia ngrok, copie y guarde la dirección URL de reenvío pública para el paso siguiente. La dirección URL de reenvío se genera aleatoriamente.

    Captura de pantalla del terminal ngrok.

Configuración en Azure Portal

En la sesión de depuración, modifique el URI de la aptitud de API web personalizada para llamar a la dirección URL de reenvío de Tunnelmole o ngrok. Asegúrese de anexar "/api/FunctionName" al usar la función de Azure para ejecutar el código del conjunto de aptitudes.

Se puede editar la capacidad en el Portal.

Prueba del código

En este momento, las nuevas solicitudes de la sesión de depuración ahora se deben enviar a la función local de Azure. Puede usar puntos de interrupción en el Visual Studio Code para depurar el código o ejecutar paso a paso.

Pasos siguientes

Ahora que conoce el diseño y las funcionalidades del editor visual de Sesiones de depuración, pruebe el tutorial para obtener una experiencia práctica.

Tutorial: Exploración de sesiones de depuración