Incorporación de analizadores personalizados a campos de cadena en un índice de Azure AI Search

Un analizador personalizado es un componente del análisis léxico sobre el contenido de texto sin formato. Se trata de una combinación definida por el usuario de un tokenizador, uno o varios filtros de token y uno o varios filtros de caracteres. Un analizador personalizado se especifica en un índice de búsqueda y, a continuación, se hace referencia a él por su nombre en las definiciones de campo que requieren un análisis personalizado. Se invoca un analizador personalizado por campo. Los atributos del campo determinan si se usa para la indexación, las consultas o ambos.

En un analizador personalizado, los filtros de caracteres preparan el texto de entrada antes de que lo procese el tokenizador (por ejemplo, la eliminación del marcado). A continuación, el tokenizador divide el texto en tokens. Por último, los filtros de token modifican los tokens emitidos por el tokenizador. Para obtener conceptos y ejemplos, consulte Analizadores en Búsqueda de Azure AI y Tutorial: Creación de un analizador personalizado para númerosde teléfono.

¿Por qué se debe usar un analizador personalizado?

Debe considerar un analizador personalizado en flujos de trabajo de búsqueda clásicos que no incluyan modelos de lenguaje grandes ni su capacidad para manejar anomalías de contenido.

En la búsqueda de clases, un analizador personalizado le proporciona control sobre el proceso de convertir texto sin formato en tokens indexables y buscables, permitiéndole elegir qué tipos de análisis o filtros se van a invocar y el orden en el que ocurren.

Cree y asigne un analizador personalizado si ninguno de los analizadores predeterminados (Lucene estándar), integrados o analizadores de lenguaje son suficientes para sus necesidades. También puede crear un analizador personalizado si desea usar un analizador integrado con opciones personalizadas. Por ejemplo, si desea cambiar el maxTokenLength en Standard Lucene, crearía un analizador personalizado, con un nombre definido por el usuario, para establecer esa opción.

Los siguientes son algunos de los escenarios en los que los analizadores personalizados pueden resultar útiles:

• Uso de filtros de caracteres para eliminar el marcado HTML antes de que se tokenicen las entradas de texto o para reemplazar ciertos caracteres o símbolos.

• Búsqueda fonética. Agregue un filtro fonético para habilitar la búsqueda basada en cómo suena una palabra en lugar de en cómo se escribe.

• Deshabilitar el análisis léxico. Use el analizador de palabras clave para crear campos de búsqueda que no se analizan.

• Búsqueda rápida de prefijo o sufijo. Agregue el filtro de token Edge N-gram para indexar prefijos en los índices de palabras y habilitar la coincidencia rápida de prefijos. Combínelo con el filtro de tokens Reverse para realizar coincidencia de sufijos.

• Tokenización personalizada. Por ejemplo, use el tokenizador Whitespace para dividir las oraciones en tokens usando el espacio en blanco como delimitador.

• Normalización de caracteres ASCII. Agregue el filtro de plegado ASCII estándar para normalizar los signos diacríticos como ö o ê en los términos de búsqueda.

Creación de un analizador personalizado

Para crear un analizador personalizado, especifíquelo en la sección analyzers de un índice en tiempo de diseño y, a continuación, haga referencia a él en los campos Edm.String en los que puedan realizarse búsquedas mediante la propiedad analyzer o el par indexAnalyzer y searchAnalyzer.

Una definición de analizador incluye un nombre, un tipo, uno o varios filtros de caracteres, un máximo de un tokenizador y uno o varios filtros de token para el procesamiento posterior a la tokenización. Los filtros de caracteres se aplican antes de la tokenización. Los filtros de token y los filtros de caracteres se aplican de izquierda a derecha.

• Los nombres de un analizador personalizado deben ser únicos y no pueden ser iguales que ninguno de los analizadores integrados, tokenizadores, filtros de token o caracteres. Los nombres constan de letras, dígitos, espacios, guiones o caracteres de subrayado. Los nombres deben comenzar y terminar con caracteres de texto plano. Los nombres deben tener menos de 128 caracteres de longitud.

• El tipo debe ser #Microsoft.Azure.Search.CustomAnalyzer.

• charFilters puede ser uno o varios filtros de Filtros de caracteres, procesados antes de la tokenización, en el orden proporcionado. Algunos filtros de caracteres tienen opciones que se pueden definir en una sección charFilters. Los filtros de caracteres son opcionales.

• tokenizer es exactamente un tokenizador. Se requiere un valor. Si necesita más de un tokenizer, puede crear varios analizadores personalizados y asignarlos campo por campo en el esquema de índice.

• tokenFilters puede ser uno o varios filtros de Filtros de token, procesados después de la tokenización, en el orden proporcionado. Para los filtros de token que tienen opciones, agregue una sección tokenFilter para especificar la configuración. Los filtros de token son opcionales.

Los analizadores no deben generar tokens de más de 300 caracteres; de lo contrario, se producirá un error de indexación. Para recortar tokens largos u omitirlos, utilice TruncateTokenFilter y LengthTokenFilter respectivamente. Consulte Filtros de token como referencia.

"analyzers":(optional)[
   {
      "name":"name of analyzer",
      "@odata.type":"#Microsoft.Azure.Search.CustomAnalyzer",
      "charFilters":[
         "char_filter_name_1",
         "char_filter_name_2"
      ],
      "tokenizer":"tokenizer_name",
      "tokenFilters":[
         "token_filter_name_1",
         "token_filter_name_2"
      ]
   },
   {
      "name":"name of analyzer",
      "@odata.type":"#analyzer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"charFilters":(optional)[
   {
      "name":"char_filter_name",
      "@odata.type":"#char_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenizers":(optional)[
   {
      "name":"tokenizer_name",
      "@odata.type":"#tokenizer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenFilters":(optional)[
   {
      "name":"token_filter_name",
      "@odata.type":"#token_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
]

Dentro de una definición de índice, puede colocar esta sección en cualquier lugar del cuerpo de una solicitud de creación de índice, pero normalmente va al final:

{
  "name": "name_of_index",
  "fields": [ ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": (optional) "...",
  "corsOptions": (optional) { },
  "analyzers":(optional)[ ],
  "charFilters":(optional)[ ],
  "tokenizers":(optional)[ ],
  "tokenFilters":(optional)[ ]
}

La definición del analizador es una parte del índice más grande. Las definiciones para los filtros de caracteres, tokenizadores y filtros de token se agregan al índice solo si está configurando las opciones personalizadas. Para utilizar un filtro existente o tokenizador como está, especifíquelo por nombre en la definición del analizador. Para más información, consulte Creación de un índice (REST). Para ver más ejemplos, consulte Adición de analizadores en Azure AI Search.

Prueba de analizadores personalizados

Puede usar el analizador de pruebas (REST) para ver cómo un analizador descompone el texto dado en tokens.

Solicitar

  POST https://[search service name].search.windows.net/indexes/[index name]/analyze?api-version=[api-version]
    Content-Type: application/json
    api-key: [admin key]

  {
     "analyzer":"my_analyzer",
     "text": "Vis-à-vis means Opposite"
  }

Respuesta

  {
    "tokens": [
      {
        "token": "vis_a_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "vis_à_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "means",
        "startOffset": 10,
        "endOffset": 15,
        "position": 1
      },
      {
        "token": "opposite",
        "startOffset": 16,
        "endOffset": 24,
        "position": 2
      }
    ]
  }

Actualización de analizadores personalizados

Una vez definido un analizador, un tokenizador, un filtro de token o un filtro de caracteres, no se puede modificar. Se pueden agregar unos nuevos a un índice existente solo si la marca de allowIndexDowntime está establecida en true en la solicitud de actualización del índice:

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

Esta operación lleva su índice sin conexión durante al menos unos segundos, haciendo que sus solicitudes de indexación y consulta fallen. El rendimiento y la disponibilidad de escritura del índice pueden ser desiguales durante varios minutos después de que se actualice el índice, o durante más tiempo en el caso de índices muy grandes, pero estos efectos son temporales y, al final, se resuelven por sí solos.

Analizadores integrados

Si desea usar un analizador integrado con opciones personalizadas, la creación de un analizador personalizado es el mecanismo para especificar esas opciones. Por el contrario, para usar un analizador integrado tal cual, solo tiene que hacer referencia a él por su nombre en la definición del campo.

¹ Los tipos de analizador siempre van precedidos en el código por #Microsoft.Azure.Search de modo que PatternAnalyzer se especificaría realmente como #Microsoft.Azure.Search.PatternAnalyzer. Hemos quitado el prefijo por brevedad, pero es obligatorio en el código.

analyzer_type solo se proporciona para analizadores que se pueden personalizar. Si no hay opciones, como sucede con el analizador de palabras clave, no hay ningún tipo #Microsoft.Azure.Search asociado.

Filtros de caracteres

Los filtros de caracteres agregan procesamiento antes de que una cadena llegue al tokenizador.

Azure AI Search admite los filtros de caracteres de la lista siguiente. Puede encontrar más información sobre cada uno de ellos en la referencia de la API de Lucene.

¹ Los tipos de filtro de caracteres siempre van precedidos en el código por #Microsoft.Azure.Search de modo que MappingCharFilter se especificaría realmente como #Microsoft.Azure.Search.MappingCharFilter. Hemos quitado el prefijo para reducir el ancho de la tabla, pero no olvide incluirlo en el código. Tenga en cuenta que char_filter_type solo se proporciona para filtros que se pueden personalizar. Si no hay opciones, como sucede con html_strip, no hay ningún tipo #Microsoft.Azure.Search asociado.

Tokenizadores

Un tokenizador divide un texto continuo en una secuencia de tokens, como al dividir una frase en palabras o una palabra en sus formas raíz.

Azure AI Search admite los tokenizadores de la lista siguiente. Puede encontrar más información sobre cada uno de ellos en la referencia de la API de Lucene.

¹ Los tipos de tokenizador siempre van precedidos en el código por #Microsoft.Azure.Search de modo que ClassicTokenizer se especificaría realmente como #Microsoft.Azure.Search.ClassicTokenizer. Hemos quitado el prefijo para reducir el ancho de la tabla, pero no olvide incluirlo en el código. Tenga en cuenta que tokenizer_type solo se proporciona para tokenizadores que se puedan personalizar. Si no hay opciones, como sucede con el tokenizador de letras, no hay ningún tipo #Microsoft.Azure.Search asociado.

Filtros de token

Un filtro de token se utiliza para filtrar o modificar los tokens generados por un tokenizer. Por ejemplo, puede especificar un filtro en minúsculas que convierte todos los caracteres a minúsculas. Puede tener varios filtros de token en un analizador personalizado. Los filtros de token se ejecutan en el orden en que aparecen.

En la tabla siguiente, los filtros de token que se implementan mediante Apache Lucene están vinculados a la documentación de la API de Lucene.

¹ Los tipos de filtro de token siempre van precedidos en el código por #Microsoft.Azure.Search de modo que ArabicNormalizationTokenFilter se especificaría realmente como #Microsoft.Azure.Search.ArabicNormalizationTokenFilter. Hemos quitado el prefijo para reducir el ancho de la tabla, pero no olvide incluirlo en el código.

Consulte también

• API REST de Azure AI Search
• Analizadores en Azure AI Search (Ejemplos)
• Creación de índice (REST)