Hacer referencia a una ruta de acceso a los nodos enriquecidos mediante las propiedades de contexto y origen de un conjunto de aptitudes de Azure AI Search

Artículo
01/19/2024

Durante la ejecución del conjunto de aptitudes, el motor compila un árbol de enriquecimiento en memoria que captura cada enriquecimiento, como entidades reconocidas o texto traducido. En este artículo, aprenderá a hacer referencia a un nodo de enriquecimiento en el árbol de enriquecimiento para que pueda pasar la salida a aptitudes de bajada o especificar una asignación de campos de salida para un campo de índice de búsqueda.

En este artículo se usan ejemplos para ilustrar varios escenarios. Para obtener la sintaxis completa, consulte Lenguaje de lenguaje de anotación de entrada y contexto de aptitudes.

Conceptos de fondo

Antes de revisar la sintaxis, repasemos algunos conceptos importantes para comprender mejor los ejemplos que se proporcionan más adelante en este artículo.

Término	Descripción
Documento enriquecido	Un documento enriquecido es una estructura en memoria que recopila la salida de la aptitud a medida que se crea y contiene todos los enriquecimientos relacionados con un documento. Piense en un documento enriquecido como un árbol. Por lo general, el árbol comienza en el nivel de documento raíz y cada nuevo enriquecimiento se ha creado a partir de un elemento anterior como su elemento secundario.
"node"	Dentro de un documento enriquecido, un nodo (a veces denominado "anotación") se crea y rellena mediante una aptitud, como "texto" y "layoutText" en la aptitud OCR. Un documento enriquecido se rellena tanto con enriquecimientos como con valores de campo de origen originales o metadatos copiados del origen.
Contexto	El ámbito del enriquecimiento, que es todo el documento, una parte de un documento o, si está trabajando con imágenes, las imágenes extraídas de un documento. De forma predeterminada, el contexto de enriquecimiento se establece en el nivel `"/document"`, dentro del alcance de los documentos individuales que contiene el origen de datos. Cuando se ejecuta una aptitud, los resultados de la misma se convierten en propiedades del contexto definido.

Rutas de acceso para diferentes escenarios

Las rutas de acceso se especifican en las propiedades "context" y "source" de un conjunto de aptitudes y en las asignaciones de campos de salida en un indexador.

En el ejemplo de la captura de pantalla se muestra la ruta de acceso de un elemento de una colección de Azure Cosmos DB.

context ruta de acceso es /document/HotelId porque el campo /HotelId divide la colección en documentos.
source ruta de acceso es /document/Description porque la aptitud es una aptitud de traducción y el campo que desea que la aptitud traduzca es el campo Description de cada documento.

Todas las rutas de acceso comienzan por /document. Un documento enriquecido se crea en la fase de "descifrado de documentos" de ejecución del indexador, cuando el indexador abre un documento o lee en una fila del origen de datos. Inicialmente, el único nodo de un documento enriquecido es el nodo raíz (/document) y es el nodo del que se producen todos los demás enriquecimientos.

En la lista siguiente se incluyen varios ejemplos comunes:

/document es el nodo raíz e indica un blob completo en Azure Storage o una fila de una tabla SQL.
/document/{key} es la sintaxis de un documento o elemento de una colección de Azure Cosmos DB, donde {key} es la clave real, como /document/HotelId en el ejemplo anterior.
/document/content especifica la propiedad "content" de un blob JSON.
/document/{field} es la sintaxis de una operación realizada en un campo específico, como traducir el campo/document/Description, visto en el ejemplo anterior.
/document/pages/* o /document/sentences/* se convierte en el contexto si va a dividir un documento grande en fragmentos más pequeños para su procesamiento. Si "context" es /document/pages/*, la aptitud se ejecuta una vez en cada página del documento. Dado que puede haber más de una página o frase, se anexará /* para capturarlas todas.
/document/normalized_images/* se crea durante el descifrado de documentos si el documento contiene imágenes. Todas las rutas de acceso a las imágenes comienzan con normalized_images. Dado que a menudo hay varias imágenes incrustadas en un documento, anexe /*.

Los ejemplos del resto de este artículo se basan en el campo "contenido" generado automáticamente por Indexadores de blobs de Azure como parte de la fase descifrado de documentos. Cuando consulte los documentos de un contenedor de blobs, use un formato como "/document/content", donde el campo de "contenido" forma parte del "documento".

Ejemplo 1: referencia de anotación simple

En Azure Blob Storage, supongamos que tiene ciertos archivos que contienen referencias a nombres de personas que quiere extraer mediante el reconocimiento de entidades. En la siguiente definición de aptitud, "/document/content" es la representación textual de todo el documento y "people" es una extracción de nombres completos para las entidades identificadas como personas.

Debido a que el contexto predeterminado es "/document", ahora se puede hacer referencia a la lista de personas como "/document/people". En este caso específico, "/document/people" es una anotación que puede asignarse a un campo en un índice, o usarse en otra aptitud en el mismo conjunto de aptitudes.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Ejemplo 2: hacer referencia a una matriz dentro de un documento

En este ejemplo, que se basa en el anterior, le mostramos cómo invocar varias veces un paso de enriquecimiento en el mismo documento. Suponga que en el ejemplo anterior generó una matriz de cadenas con los nombres de 10 personas de un solo documento. El próximo paso lógico es crear un segundo enriquecimiento que extraiga el apellido de un nombre completo. Como hay 10 nombres, le interesa realizar este paso 10 veces en el documento; esto es, una vez por cada persona.

Para invocar el número correcto de iteraciones, establezca el contexto como "/document/people/*", donde el asterisco ("*") representa todos los nodos del documento enriquecido como descendientes de "/document/people". Aunque esta aptitud solo se define una vez en el conjunto de aptitudes, se llama a cada miembro del documento hasta que se procesen todos ellos.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Cuando las anotaciones son matrices o colecciones de cadenas, tal vez quiera trabajar con miembros específicos en lugar de con la matriz completa. El ejemplo anterior se genera una anotación llamada "last" en cada nodo que representa el contexto. Si quiere hacer referencia a esta familia de anotaciones, puede usar la sintaxis "/document/people/*/last". Si por el contrario quiere hacer referencia a una anotación en particular, puede usar un índice explícito ""/document/people/1/last" para hacer referencia al apellido de la primera persona identificada en el documento. Tenga en cuenta que en esta sintaxis las matrices están "indexadas en 0".

Ejemplo 3: miembros de referencia de una matriz

A veces es necesario agrupar todas las anotaciones de un tipo en particular para pasarlas a una aptitud en particular. Pongamos como ejemplo una habilidad hipotética personalizada que identifica el apellido más común de todos los apellidos extraídos en el Ejemplo 2. Para proporcionar solo los apellidos a esa habilidad personalizada, debe especificar el contexto como "/document" y la entrada como "/document/people/*/lastname".

Tenga en cuenta que la cardinalidad de "/document/people/*/lastname" es mayor que la del documento. Hay 10 nodos de apellido, mientras que solo hay un nodo de documento para este documento. En ese caso, el sistema creará automáticamente una matriz de "/document/people/*/lastname" que contenga todos los elementos del documento.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Sugerencias para la solución de problemas de ruta de acceso de anotación

Si tiene problemas para especificar entradas de aptitudes, estas sugerencias pueden ayudarle a avanzar:

Ejecute el asistente para importar datos a través de los datos para revisar las definiciones del conjunto de aptitudes y las asignaciones de campos que genera el asistente.
Inicie una sesión de depuración en un conjunto de aptitudes para ver la estructura de un documento enriquecido. Puede editar las rutas de acceso y otras partes de la definición de la aptitud y, a continuación, ejecutar la aptitud para validar los cambios.