Compartir a través de

Tutorial: Corrección de un conjunto de aptitudes mediante sesiones de depuración

  • Artículo

En Búsqueda de Azure AI, un conjunto de aptitudes coordina las acciones de las aptitudes que analizan, transforman o crean contenido que se puede buscar. Con frecuencia, la salida de una aptitud se convierte en la entrada de otra. En los casos en que las entradas dependen de las salidas, los errores en las definiciones de los conjuntos de aptitudes y las asociaciones de campos pueden dar lugar a operaciones y datos que faltan.

Las sesiones de depuración son una herramienta de Azure Portal que proporcionan una visualización holística de un conjunto de aptitudes que se ejecuta en Búsqueda de Azure AI. Con esta herramienta, puede explorar en profundidad los pasos específicos para ver fácilmente dónde se puede estar produciendo un error en una acción.

En este artículo, se usan sesiones de depuración para buscar y reparar las entradas y salidas que faltan. Este es un tutorial completo. Proporciona datos de ejemplo, un archivo REST que crea objetos e instrucciones para depurar problemas en el conjunto de aptitudes.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Requisitos previos

  • Azure AI Search. Cree un servicio o busque uno existente en su suscripción actual. Puede usar un servicio gratuito para este tutorial. El nivel Gratis no proporciona compatibilidad con identidades administradas para un servicio de Búsqueda de Azure AI. Debe usar claves para las conexiones a Azure Storage.

  • Una cuenta de Azure Storage con Blob Storage que se usará para hospedar los datos de ejemplo y conservar los datos almacenados en la caché que se creen durante una sesión de depuración. Si usa un servicio de búsqueda gratuito, la cuenta de almacenamiento debe tener habilitadas las claves de acceso compartido y debe permitir el acceso a la red pública.

  • Visual Studio Code con un cliente REST.

  • Archivos PDF de ejemplo (ensayos clínicos).

  • Archivo depurar-sesiones.rest de ejemplo que se usa para crear la canalización de enriquecimiento.

Nota:

En este tutorial también se usan los servicios de Azure AI para la detección de idiomas, el reconocimiento de entidades y la extracción de frases clave. Dado que la carga de trabajo es tan pequeña, servicios de Azure AI se aprovechan en segundo plano del procesamiento gratuito de hasta 20 transacciones. Esto que significa que el ejercicio se puede completar sin tener que crear un recurso de servicios de Azure AI facturable.

Configurar la base de datos de muestra

En esta sección se crea el conjunto de datos de ejemplo en Azure Blob Storage para que el indexador y el conjunto de aptitudes tengan contenido con el que trabajar.

  1. Descargue los datos de ejemplo (clinical-trials-pdf-19), que constan de 19 archivos.

  2. Cree una cuenta de Azure Storage o busque una cuenta existente.

    • Para evitar cargos por el ancho de banda, elija la misma región que Azure AI Search.

    • Elija el tipo de cuenta StorageV2 (uso general V2).

  3. Vaya a las páginas de servicios de Azure Storage en el portal y cree un contenedor de blobs. El procedimiento recomendado es especificar el nivel de acceso "privado". Asigne al contenedor el nombre clinicaltrialdataset.

  4. En el contenedor, seleccione Cargar para cargar los archivos de ejemplo que descargó y descomprimió en el primer paso.

  5. Mientras se encuentra en el portal, copie la cadena de conexión de Azure Storage. Puede obtener la cadena de conexión en Configuración>Claves de acceso en el portal.

Copia de una clave y una dirección URL

En este tutorial se usan claves de API para la autenticación y autorización. Necesita el punto de conexión de servicio de búsqueda y una clave de API, que puede obtener en Azure Portal.

  1. En Azure Portal, inicie sesión, vaya a la página Información general y copie la dirección URL. Un punto de conexión de ejemplo podría ser similar a https://mydemo.search.windows.net.

  2. En Configuración>Claves, copie una clave de administrador. Las claves de administrador se utilizan para agregar, modificar y eliminar objetos. Hay dos claves de administrador intercambiables. Copie una de las dos.

    Captura de pantalla de la dirección URL y las claves de API en Azure Portal.

Una clave de API válida genera la confianza, solicitud a solicitud, entre la aplicación que la envía y el servicio que se encarga de ella.

Creación de un origen de datos, un conjunto de aptitudes, un índice y un indexador

En esta sección, cree un flujo de trabajo "con errores" que puede corregir en este tutorial.

  1. Inicie Visual Studio Code y abra el archivo debug-sessions.rest.

  2. Proporcione las siguientes variables: dirección URL del servicio de búsqueda, clave de API de administración de servicios de búsqueda, cadena de conexión de almacenamiento y el nombre del contenedor de blobs que almacena los ARCHIVOS PDF.

  3. Envíe cada solicitud a su vez. La creación del indexador tarda varios minutos en completarse.

  4. Cierre el archivo .

Comprobación de los resultados en el portal

El código de ejemplo crea intencionadamente un índice erróneo como consecuencia de problemas que se produjeron durante la ejecución del conjunto de aptitudes. El problema en el índice es que faltan datos.

  1. En Azure Portal, en la página Información general del servicio de búsqueda, seleccione la pestaña Índices.

  2. Seleccione clinical-trials.

  3. Escriba esta cadena de consulta JSON en la vista JSON del Explorador de búsqueda. Devuelve campos para documentos específicos (identificados por el campo de metadata_storage_path único).

    "search": "*",
"select": "metadata_storage_path, organizations, locations",
"count": true

  4. Ejecute la consulta. Debería ver valores vacíos para organizations y locations.

    Estos campos se deben haber rellenado mediante la aptitud Reconocimiento de entidades del conjunto de aptitudes, que se usa para detectar organizaciones y ubicaciones en el contenido del blob. En el siguiente ejercicio, se usará la depuración del conjunto de aptitudes para determinar qué salió mal.

Otra manera de investigar los errores y advertencias es mediante Azure Portal.

  1. Abra la pestaña Indizadores y seleccione clinical-trials-idxr.

    Tenga en cuenta que aunque el trabajo del indexador se completó correctamente en general, hubo advertencias.

  2. Seleccione Operación correcta para ver las advertencias (si se hubieran producido principalmente errores, el vínculo de detalle sería Con errores). Verá una lista larga de cada advertencia que emite el indexador.

    Captura de pantalla de Visualización de advertencias.

Inicio de la sesión de depuración

  1. En el panel de navegación izquierdo del servicio de búsqueda, en Administración de búsquedas, seleccione Sesiones de depuración.

  2. Seleccione + Agregar sesión de depuración.

  3. Asigne un nombre a la sesión.

  4. En la plantilla del indexador, proporcione el nombre de este. El indexador hace referencia al origen de datos, al conjunto de aptitudes y al índice.

  5. Seleccione la cuenta de almacenamiento.

  6. Guarde la sesión.

    Recorte de pantalla de la página Definición de sesión de depuración.

  7. Se abre una sesión de depuración en la página de configuración. Puede realizar modificaciones en la configuración inicial y reemplazar los valores predeterminados. Una sesión de depuración solo funciona con un único documento. Por defecto, se acepta el primer documento de la colección como base de las sesiones de depuración. Puede elegir un documento específico para depurar proporcionando su URI en Azure Storage.

  8. Cuando la sesión de depuración haya terminado de inicializarse, debería ver un flujo de trabajo de aptitudes con asignaciones y un índice de búsqueda. La estructura de datos enriquecidos del documento aparece en un panel lateral de detalles. Lo hemos excluido del siguiente recorte de pantalla para que pueda ver mejor el flujo de trabajo.

    Captura de pantalla del editor visual Debug Session.

Búsqueda de los problemas del conjunto de aptitudes

Los problemas notificados por el indexador se indican como Errores y Advertencias.

Observe que el número de errores y advertencias es una lista mucho más pequeña que la mostrada anteriormente porque esta lista solo detalla los errores de un único documento. Al igual que la lista mostrada por el indexador, puede seleccionar en un mensaje de advertencia y ver los detalles de esta advertencia.

Seleccione Advertencias para revisar las notificaciones. Debería ver cuatro:

  • "No se pudo ejecutar la aptitud porque una o varias entradas de aptitud no eran válidas. Falta la entrada de aptitud requerida. Nombre: 'text', Origen: '/document/content'."

  • "No se pudo asignar el campo de salida "locations" al índice de búsqueda. Compruebe la propiedad "outputFieldMappings" del indexador. Falta el valor "/document/merged_content/locations"."

  • "No se pudo asignar el campo de salida "organizations" al índice de búsqueda. Compruebe la propiedad "outputFieldMappings" del indexador. Falta el valor "/document/merged_content/organizations"."

  • "La aptitud se ejecutó pero puede tener resultados inesperados porque una o varias entradas de aptitudes no eran válidas. Falta la entrada de aptitud opcional. Nombre: "languageCode", origen: "/document/languageCode". Problemas de análisis del lenguaje de expresiones: Falta el valor "/document/languageCode"."

Muchas aptitudes tienen un parámetro "languageCode". Al inspeccionar la operación, puede ver que falta esta entrada de código de idioma de la aptitud EntityRecognitionSkill.#1, que es la misma aptitud de reconocimiento de entidades que tiene problemas con la salida de "ubicaciones" y "organizaciones".

Dado que las cuatro notificaciones son sobre esta aptitud, el siguiente paso es depurarla. Si es posible, resuelva los problemas de la entrada antes de pasar a los de salida.

Corrección de valores de entrada de las aptitudes que faltan

  1. En la superficie de trabajo, seleccione la aptitud que notifica las advertencias. En este tutorial, es la aptitud de reconocimiento de entidades.

  2. El panel Detalles de aptitudes se abre a la derecha con secciones para iteraciones y sus respectivas entradas y salidas, la configuración de aptitudes para la definición JSON de la aptitud y mensajes para los errores y advertencias que esta aptitud esté emitiendo.

    Recorte de pantalla del panel de detalles de aptitudes.

  3. Mantenga el puntero sobre cada entrada (o seleccione una entrada) para mostrar los valores del evaluador de expresiones. Observe que el resultado mostrado para esta entrada no parece una entrada de texto. Más bien parece una serie de caracteres de línea nuevos, \n \n\n\n\n, en lugar de texto. La falta de texto significa que no se puede identificar ninguna entidad, por lo que este documento no cumple los requisitos previos de la aptitud o hay otra entrada que se debe usar en su lugar.

    Recorte de pantalla de la entrada de aptitud que muestra valores NULL.

  4. Vuelva a Estructura de datos enriquecidos y revise los nodos de enriquecimiento de este documento. Observe que los caracteres \n \n\n\n\n de "content" no tienen ningún origen, pero otro valor de "merged_content" tiene salida OCR. Aunque no hay ninguna indicación, el contenido de este PDF parece ser un archivo JPEG, como lo evidencia el texto extraído y procesado en "merged_content".

    Captura de pantalla de la pestaña Estructura de datos enriquecidos.

  5. Vuelva a la aptitud y seleccione Configuración del conjunto de aptitudes para abrir la definición JSON.

  6. Cambie la expresión de /document/content a /document/merged_content y seleccione Guardar. Observe que la advertencia ya no aparece.

    Captura de pantalla del evaluador de expresiones para la entrada de merged_content fija.

  7. Seleccione Run (Ejecutar) en el menú de la ventana de la sesión. Esto inicia otra ejecución del conjunto de aptitudes con el documento.

  8. Una vez completada la ejecución de la sesión de depuración, observe que el número de advertencias se ha reducido en uno. Las advertencias muestran que el error de la entrada de texto ha desaparecido, pero las otras advertencias permanecen. El siguiente paso es solucionar la advertencia sobre el valor /document/languageCode que falta o está vacío.

    Captura de pantalla de errores y advertencias actualizados.

  9. Seleccione la aptitud y mantenga el puntero sobre /document/languageCode. El valor de esta entrada es NULL, que no es una entrada válida.

  10. Al igual que con el problema anterior, empiece por revisar la estructura de datos enriquecidos para obtener pruebas de sus nodos. Observe que no hay ningún nodo "languageCode", pero hay uno para "lenguaje". Por lo tanto, hay un error tipográfico en la configuración de aptitudes.

  11. Copie la expresión /document/language.

  12. En el panel Detalles de aptitudes, seleccione Configuración de aptitudes para la aptitud #1 y pegue el nuevo valor: /document/language.

  13. Seleccione Guardar.

  14. Seleccione Run (Ejecutar).

  15. Una vez completada la ejecución de la sesión de depuración, puede comprobar los resultados en el panel Detalles de aptitudes. Al mantener el puntero sobre /document/language, debería ver en como valor en el evaluador de expresiones.

Observe que las advertencias de entrada han desaparecido. Solo quedan las dos advertencias sobre los campos de salida de las organizaciones y las ubicaciones.

Corrección de valores de salida de aptitud que faltan

Los mensajes indican que se compruebe la propiedad "outputFieldMappings" del indexador, así que vamos a empezar por ahí.

  1. Seleccione Asignaciones de campos de salida en la superficie de trabajo. Observe que faltan las asignaciones de campos de salida.

    Captura de pantalla del nodo Asignaciones de campos de salida.

  2. Como primer paso, confirme que el índice de búsqueda tiene los campos esperados. En este caso, el índice tiene campos para "ubicaciones" y "organizaciones".

  3. Si no hay ningún problema con el índice, el siguiente paso es comprobar las salidas de aptitud. Como antes, seleccione Estructura de datos enriquecidos y desplácese por los nodos para buscar "ubicaciones" y "organizaciones". Observe que el elemento primario es "content", en lugar de "merged_content". El contexto es incorrecto.

  4. Vuelva al panel Detalles de aptitudes para la aptitud de reconocimiento de entidades.

  5. En Configuración de aptitudes, cambie context a document/merged_content. En este momento, debe tener tres modificaciones de la definición de aptitud en total.

    Recorte de pantalla de la definición de la aptitud con todas las modificaciones indicadas.

  6. Seleccione Guardar.

  7. Seleccione Run (Ejecutar).

Todos los errores se han resuelto.

Confirmación de los cambios en el conjunto de aptitudes

Cuando se inició la sesión de depuración, el servicio de búsqueda creó una copia del conjunto de aptitudes. Esto se hizo para proteger el conjunto de aptitudes original en el servicio de búsqueda. Ahora que ha finalizado la depuración del conjunto de aptitudes, las correcciones se pueden confirmar (sobrescribir el conjunto de aptitudes original).

Como alternativa, si no está listo para confirmar los cambios, puede guardar la sesión de depuración y volver a abrirla más adelante.

  1. Seleccione Commit changes (Confirmar cambios) en el menú principal de Sesiones de depuración.

  2. Selecciones OK (Aceptar) para confirmar que desea actualizar el conjunto de aptitudes.

  3. Cierre la sesión de depuración y abra Indexadores en el panel de navegación izquierdo.

  4. Seleccione "clinical-trials-idxr".

  5. Seleccione Restablecer.

  6. Seleccione Run (Ejecutar).

  7. Seleccione Actualizar para mostrar el estado de los comandos de restablecimiento y ejecución.

Cuando el indexador haya terminado de ejecutarse, aparecerá una marca de verificación verde y la palabra Correcto junto a la marca de tiempo de la última ejecución en la pestaña Historial de ejecución. Para asegurarse de que se han aplicado los cambios:

  1. En el panel de navegación izquierdo, abra Índices.

  2. Abra el índice de "clinical-trials" y, en la pestaña Explorador de búsqueda, escriba esta cadena de consulta: $select=metadata_storage_path, organizations, locations&$count=true para que devuelva los campos de documentos específicos (identificados mediante el campo metadata_storage_path único).

  3. Seleccione Search.

Los resultados deberían mostrar que las organizaciones y las ubicaciones ahora contienen los valores esperados.

Limpieza de recursos

Cuando trabaje con su propia suscripción, es una buena idea al final de un proyecto identificar si todavía se necesitan los recursos que ha creado. Los recursos que se dejan en ejecución pueden costarle mucho dinero. Puede eliminar los recursos de forma individual o eliminar el grupo de recursos para eliminar todo el conjunto de recursos.

Puede encontrar y administrar recursos en el portal, mediante el vínculo Todos los recursos o Grupos de recursos en el panel de navegación izquierdo.

El servicio gratuito se limita a tres índices, indexadores y orígenes de datos. Puede eliminar elementos individuales en el portal para mantenerse por debajo del límite.

Pasos siguientes

Este tutorial ha tratado sobre varios aspectos de la definición y el procesamiento de los conjuntos de aptitudes. Para más información sobre conceptos y flujos de trabajo, consulte los siguientes artículos: