Sesiones de depuración en Búsqueda de Azure AI

Debug Sessions es un editor visual que funciona con un conjunto de aptitudes existente en Azure Portal, que expone la estructura y el contenido de un único documento enriquecido, tal como lo genera un indexador y un conjunto de aptitudes, durante la sesión. Dado que se está trabajando con un documento en directo, la sesión es interactiva: puedes identificar errores, modificar e invocar la ejecución de aptitudes y validar los resultados en tiempo real. Si los cambios resuelven el problema, puede confirmarlos en un conjunto de aptitudes publicado para aplicar las correcciones globalmente.

En este artículo se explican los escenarios admitidos y cómo se organiza el editor. Las pestañas y secciones del editor desempaquetan diferentes capas del conjunto de aptitudes para que pueda examinar la estructura, el flujo y el contenido que genera en tiempo de ejecución.

Escenarios admitidos

Use sesiones de depuración para investigar y resolver problemas con:

• Aptitudes integradas que se usan para el enriquecimiento con IA, como OCR, análisis de imágenes, reconocimiento de entidades y extracción de palabras clave.

• Aptitudes integradas usadas para la vectorización integrada, con fragmentación de datos a través de división de texto y vectorización a través de una aptitud de inserción.

• Aptitudes personalizadas que se usan para integrar el procesamiento externo que proporcione.

Compare las siguientes imágenes de sesión de depuración para los dos primeros escenarios. En ambos escenarios, el área expuesta muestra la progresión de las aptitudes que generan o transforman contenido en ruta desde el documento de origen al índice de búsqueda. El flujo incluye opciones de asignación de índices y puede realizar un seguimiento de las flechas para seguir la pista de procesamiento. El panel de detalles a la derecha distingue el contexto. Muestra una representación del documento enriquecido creado por la canalización o los detalles de una aptitud o asignación.

La primera imagen muestra un patrón para el enriquecimiento de IA aplicado (sin vectores). Las aptitudes se pueden ejecutar secuencialmente o en paralelo si no hay dependencias. Las asignaciones de índices muestran cómo el contenido enriquecido o generado viaja desde estructuras de datos en memoria a campos de un índice. El documento enriquecido muestra la estructura de datos que crea el conjunto de aptitudes.

La segunda imagen muestra un patrón típico para la vectorización integrada. Las aptitudes para la vectorización integrada suelen incluir una aptitud División de texto y una aptitud de inserción. Una aptitud División de texto divide un documento en fragmentos. Una aptitud de inserción llama a una API de inserción para vectorizar esos fragmentos. Este conjunto de aptitudes concreto fragmenta el contenido en una matriz de "páginas". Para la vectorización integrada, las asignaciones de proyección controlan cómo se asignan los fragmentos a los campos del índice.

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, con las siguientes excepciones:

• Indexador de SharePoint.

• Indexador de 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.

• Orígenes de datos con cifrado habilitado a través de claves administradas por el cliente (CMK).

• No se admiten vínculos privados compartidos. Si el servicio de búsqueda usa conectividad de punto de conexión privado para acceder a orígenes de datos u otros recursos, las sesiones de depuración no pueden acceder a esos recursos. Como solución alternativa, consulte Sesiones de depuración y conectividad privada.

• Actualmente, la capacidad de seleccionar el documento que se va a depurar no está disponible. Esta limitación no es permanente y debe levantarse pronto. En este momento, Debug Sessions selecciona el primer documento del contenedor o la carpeta de datos de origen.

Funcionamiento de una sesión de depuración

Al iniciar una sesión, el servicio de búsqueda crea una copia del conjunto de aptitudes, del indexador y de un origen de datos que contiene un único documento que se usa para probar el conjunto de aptitudes. El servicio Búsqueda de Azure AI guarda todo el estado de sesión en un nuevo contenedor de blobs que crea en una cuenta de Azure Storage que proporcione. El nombre del contenedor generado tiene un prefijo de ms-az-cognitive-search-debugsession. Este prefijo reduce la posibilidad de exportar accidentalmente los datos de sesión a otro contenedor de la cuenta.

Si configura la conexión de la cuenta de almacenamiento mediante una identidad administrada, asigne a la identidad del servicio de búsqueda de la cuenta de almacenamiento el rol Storage Blob Data Contributor. En la cuenta de almacenamiento, habilite los servicios de confianza para permitir el acceso de escritura desde Búsqueda de Azure AI.

Se carga una copia en caché del documento enriquecido y del conjunto de aptitudes en el editor visual para que pueda inspeccionar el contenido y los metadatos del documento enriquecido, con la capacidad de comprobar cada nodo de documento y editar cualquier aspecto de la definición del conjunto de aptitudes. Los cambios realizados dentro de la sesión se almacenan en caché. Estos cambios no afectarán al conjunto de aptitudes publicado a menos que los confirme. Al confirmar los cambios, se sobrescribirá el conjunto de aptitudes de producción.

Si la canalización de enriquecimiento no tiene errores, se puede usar una sesión de depuración para enriquecer incrementalmente un documento, y probar y validar cada cambio antes de confirmarlo.

Las sesiones de depuración ayudan a identificar la causa principal de errores o advertencias mediante el análisis de datos, entradas y salidas de aptitudes y asignaciones de campos. Use el panel de detalles de la aptitud para inspeccionar lo que cada aptitud recibe como entrada y genera como salida. Esta inspección ayuda a comprobar que las definiciones de aptitudes, las expresiones y las asignaciones de campos están formadas correctamente. Si el indexador encuentra problemas de configuración, como errores de configuración de red o errores de acceso relacionados con permisos, revise el mensaje de error específico y la documentación vinculada. Para obtener instrucciones de solución de problemas, consulte Errores y advertencias comunes del indexador.

Sesiones de depuración y conectividad privada

Las sesiones de depuración no admiten vínculos privados compartidos. Si el servicio de búsqueda en producción usa conectividad de extremo privado para acceder a orígenes de datos u otros recursos, las sesiones de depuración no pueden ejecutarse en ese servicio.

Solución alternativa: uso de un servicio de búsqueda de pruebas

Para depurar el conjunto de habilidades, cree un servicio de Búsqueda de Azure AI independiente sin restricciones de conectividad privada. Para mantener los datos de producción y los detalles del esquema fuera de un entorno no privado, cree la configuración de prueba con documentos sintéticos:

• Cree documentos de prueba que coincidan con los tipos de campo y la estructura de los datos de producción, pero use nombres de campo genéricos (por ejemplo, content, title, category) y valores de marcador de posición en lugar de datos reales. La lógica del conjunto de aptitudes depende de los tipos de contenido y la estructura, no de nombres de campo específicos.
• Copie el JSON del conjunto de habilidades de su servicio de producción. Si las entradas de aptitud hacen referencia a nombres de campo de producción, actualice esas referencias para que coincidan con los nombres de campo de prueba genéricos. Utilice asignaciones de campos en el indexador de prueba para alinear los nombres de los campos de prueba con las entradas del conjunto de aptitudes.
• Configure un indexador para ejecutarlo con el origen de datos de prueba.

Ejecute la sesión de depuración en el servicio de prueba para inspeccionar entradas y salidas de aptitudes, validar expresiones de aptitud y asignaciones de campos e identificar errores. Una vez validados los cambios, restaure las referencias originales a los nombres de los campos de producción en el JSON del conjunto de habilidades y vuelva a aplicarlo a su servicio de producción.

Diseño de la sesión de depuración

El editor visual se organiza en un área expuesta que muestra una progresión de las operaciones, empezando por el descifrado de documentos, seguido de aptitudes, asignaciones y un índice.

Seleccione cualquier aptitud o asignación y se abrirá un panel para mostrar información relevante.

Siga los vínculos para profundizar más en el procesamiento de aptitudes. Por ejemplo, en la captura de pantalla siguiente se muestra la salida de la primera iteración de la aptitud división de texto.

Panel de detalles de la aptitud

El panel Detalles de la aptitud tiene las secciones siguientes:

• Iteraciones: muestra cuántas veces se ejecuta una aptitud. Puede comprobar las entradas y salidas de cada una.
• Configuración de aptitudes: vea o edite la definición del conjunto de aptitudes JSON.
• Errores y advertencias: muestra los errores o advertencias específicos de esta aptitud.

Panel de estructura de datos enriquecidos

El panel Estructura de datos enriquecidos se desliza hacia el lado al seleccionar el símbolo de flecha azul mostrar u ocultar. Es una representación legible de lo que contiene el documento enriquecido. Las capturas de pantalla anteriores de este artículo muestran ejemplos de la estructura de datos enriquecida.

Pasos siguientes

Ahora que comprende los elementos de las sesiones de depuración, inicie la primera sesión de depuración en un conjunto de aptitudes existente.