Aptitud cognitiva de búsqueda de entidades personalizadas
La aptitud Búsqueda de entidades personalizadas se usa para detectar o reconocer entidades que defina. Durante la ejecución del conjunto de aptitudes, la aptitud busca texto de una lista de palabras y frases personalizada definida por el usuario. La aptitud usa esta lista para etiquetar las entidades coincidentes que se encuentran en los documentos de origen. La aptitud también admite un grado de coincidencia aproximada que se puede aplicar para buscar coincidencias similares, pero no exactas.
Nota:
Esta aptitud no está enlazada a ninguna API de los servicios de Azure AI, pero necesita una clave de los servicios de Azure AI para que se puedan efectuar más de 20 transacciones. Azure AI Search es el servicio que mide esta aptitud.
@odata.type
Microsoft.Skills.Text.CustomEntityLookupSkill
Límites de datos
- El tamaño máximo de registro de entrada admitido es 256 MB. Si necesita desglosar los datos antes de enviarlos a la aptitud de búsqueda de entidades personalizadas, puede usar la aptitud de división de texto. Si usa una aptitud de división de texto, establezca la longitud de la página en 5000 para obtener el mejor rendimiento.
- El tamaño máximo de la definición de entidad personalizada es de 10 MB si se proporciona como un archivo externo, especificado a través del parámetro "entitiesDefinitionUri".
- Si las entidades se definen en línea, con el parámetro «inlineEntitiesDefinition», el tamaño máximo es de 10 KB.
Parámetros de la aptitud
Los parámetros distinguen mayúsculas de minúsculas.
| Nombre de parámetro | Descripción |
|---|---|
entitiesDefinitionUri |
Ruta de acceso externa a un archivo JSON o CSV que contiene todo el texto de destino con el que debe coincidir. Esta definición de entidad se lee al principio de una ejecución del indexador; las actualizaciones en medio de la ejecución de este archivo no se realizarán hasta posteriores ejecuciones. Este archivo debe ser accesible mediante HTTPS. Consulte Formato de definición de entidad personalizada que aparece más adelante para ver el esquema CSV o JSON esperado. |
inlineEntitiesDefinition |
Definiciones de entidades JSON insertadas. Este parámetro reemplaza al parámetro entitiesDefinitionUri si existe. No se pueden proporcionar más de 10 KB de configuración en línea. Consulte Definición de entidad personalizada que aparece más adelante para ver el esquema JSON esperado. |
defaultLanguageCode |
(Opcional) Código de idioma del texto de entrada que se utiliza para dividir en tokens y definir el texto de entrada. Se admiten los siguientes idiomas: da, de, en, es, fi, fr, it, pt. El idioma predeterminado es inglés (en). Si pasa el formato languagecode-countrycode, solo se usará la parte languagecode del formato. |
globalDefaultCaseSensitive |
(Opcional) Valor predeterminado que distingue mayúsculas y minúsculas en la aptitud. Si no se especifica el valor defaultCaseSensitive de una entidad, este se convertirá en el valor defaultCaseSensitive de esa entidad. |
globalDefaultAccentSensitive |
(Opcional) Valor predeterminado que distingue acentos en la aptitud. Si no se especifica el valor defaultAccentSensitive de una entidad, este se convertirá en el valor defaultAccentSensitive de esa entidad. |
globalDefaultFuzzyEditDistance |
(Opcional) Valor predeterminado de la distancia de edición de coincidencias parciales en la aptitud. Si no se especifica el valor defaultFuzzyEditDistance de una entidad, este se convertirá en el valor defaultFuzzyEditDistance de esa entidad. |
Entradas de la aptitud
| Nombre de entrada | Descripción |
|---|---|
text |
Texto que se analizará. |
languageCode |
Opcional. El valor predeterminado es "en". |
Salidas de la aptitud
| Nombre de salida | Descripción |
|---|---|
entities |
Una matriz de tipos complejos, que contiene los siguientes campos:
|
Formato de definición de entidad personalizada
Hay tres enfoques diferentes para proporcionar la lista de entidades personalizadas a la aptitud de búsqueda de entidades personalizadas:
- archivo .CSV (codificado con UTF-8)
- archivo JSON (codificado con UTF-8)
- Insertado dentro de la definición de la aptitud
Si el archivo de definición está en un .CSV o archivo .JSON, proporcione la ruta de acceso completa en el parámetro "entitiesDefinitionUri". El archivo se ha descargado al inicio de cada ejecución indizador. Debe permanecer accesible hasta que se detenga el indexador.
Si usa una definición insertada, especifíquela en el parámetro de aptitud "inlineEntitiesDefinition".
Nota:
Los indexadores admiten modos de análisis especializados para archivos JSON y CSV. Al usar la aptitud de búsqueda de entidades personalizadas, mantenga "parsingMode" establecido en "default". La aptitud espera JSON y CSV en un estado sin analizar.
Formato CSV
Puede proporcionar la definición de las entidades personalizadas que se van a buscar en un archivo de valores separados por comas (CSV); para ello, especifique la ruta de acceso al archivo y configúrelo en el parámetro «entitiesDefinitionUri» de la aptitud. La ruta de acceso debe estar en una ubicación https. El archivo de definición puede tener un tamaño máximo de 10 MB.
El formato CSV es sencillo. Cada línea representa una entidad única, como se muestra a continuación:
Bill Gates, BillG, William H. Gates
Microsoft, MSFT
Satya Nadella
En este caso, hay tres entidades que pueden devolverse (Bill Gates, Satya Nadella, Microsoft). Los alias siguen después de la entidad principal. Una coincidencia en un alias se agrupa en la entidad principal. Por ejemplo, si se encuentra la cadena "William H. Gates" en un documento, se devolverá una coincidencia para la entidad "Bill Gates".
Formato JSON
También puede proporcionar la definición de las entidades personalizadas que desea buscar mediante un archivo JSON. El formato JSON proporciona un poco más de flexibilidad, ya que permite definir reglas de coincidencia por término. Por ejemplo, puede especificar la distancia de las coincidencias aproximadas (distancia Damerau-Levenshtein) para cada término o si la coincidencia debe distinguir entre mayúsculas y minúsculas o no.
Al igual que con los archivos CSV, debe proporcionar la ruta de acceso al archivo JSON y configurarlo en el parámetro «entitiesDefitionUri» de la aptitud. La ruta de acceso debe estar en una ubicación https. El archivo de definición puede tener un tamaño máximo de 10 MB.
La definición de lista de entidades personalizadas JSON más básica puede ser una lista de entidades que deben coincidir:
[
{
"name" : "Bill Gates"
},
{
"name" : "Microsoft"
},
{
"name" : "Satya Nadella"
}
]
Las definiciones más complejas pueden proporcionar un identificador, una descripción, un tipo, un subtipo y alias definidos por el usuario. Si se encuentra una coincidencia con un término de alias, la entidad se devolverá también:
[
{
"name" : "Bill Gates",
"description" : "Microsoft founder." ,
"aliases" : [
{ "text" : "William H. Gates", "caseSensitive" : false },
{ "text" : "BillG", "caseSensitive" : true }
]
},
{
"name" : "Xbox One",
"type": "Hardware",
"subtype" : "Gaming Device",
"id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
"description" : "The Xbox One product"
},
{
"name" : "LinkedIn" ,
"description" : "The LinkedIn company",
"id" : "differentIdentifyingScheme123",
"fuzzyEditDistance" : 0
},
{
"name" : "Microsoft" ,
"description" : "Microsoft Corporation",
"id" : "differentIdentifyingScheme987",
"defaultCaseSensitive" : false,
"defaultFuzzyEditDistance" : 1,
"aliases" : [
{ "text" : "MSFT", "caseSensitive" : true }
]
}
]
Las tablas que se muestran a continuación describen los parámetros de configuración que puede establecer cuando se definen entidades personalizadas:
| Nombre del campo | Descripción |
|---|---|
name |
El descriptor de entidad de nivel superior. Las coincidencias en la salida de la aptitud se agruparán por este nombre y este debe representar la forma "normalizada" del texto que se encuentra. |
description |
(Opcional) Este campo se puede usar como paso a través de los metadatos personalizados acerca de los textos coincidentes. El valor de este campo aparecerá con cada coincidencia de su entidad en la salida de la aptitud. |
type |
(Opcional) Este campo se puede usar como paso a través de los metadatos personalizados acerca de los textos coincidentes. El valor de este campo aparecerá con cada coincidencia de su entidad en la salida de la aptitud. |
subtype |
(Opcional) Este campo se puede usar como paso a través de los metadatos personalizados acerca de los textos coincidentes. El valor de este campo aparecerá con cada coincidencia de su entidad en la salida de la aptitud. |
id |
(Opcional) Este campo se puede usar como paso a través de los metadatos personalizados acerca de los textos coincidentes. El valor de este campo aparecerá con cada coincidencia de su entidad en la salida de la aptitud. |
caseSensitive |
(Opcional) El valor predeterminado es "false". Valor booleano que indica si las comparaciones con el nombre de la entidad deben distinguir entre mayúsculas y minúsculas. Las coincidencias de "Microsoft" de ejemplo que no distinguen mayúsculas de minúsculas podrían ser: microsoft, microSoft, MICROSOFT |
accentSensitive |
(Opcional) El valor predeterminado es "false". Valor booleano que indica si las letras acentuadas y no acentuadas, como "é" y "e", deben ser idénticas. |
fuzzyEditDistance |
(Opcional) El valor predeterminado es 0. El valor máximo es 5. Indica el número aceptable de caracteres diferentes que seguirán constituyendo una coincidencia con el nombre de la entidad. Se devuelve el valor mínimo de coincidencia aproximada posible para cualquier coincidencia determinada. Por ejemplo, si la distancia de edición se establece en 3, "Windows 10" todavía coincidiría con "Windows", "Windows10" y "Windows 7". Si la distinción entre mayúsculas y minúsculas está establecida en false, las diferencias entre mayúsculas y minúsculas NO cuentan para la tolerancia con la coincidencia aproximada. En caso contrario, sí lo hacen. |
defaultCaseSensitive |
(Opcional) Cambia el valor predeterminado de distinción entre mayúsculas y minúsculas para esta entidad. Se puede usar para cambiar el valor predeterminado de todos los valores caseSensitive de los alias. |
defaultAccentSensitive |
(Opcional) Cambia el valor predeterminado de distinción de acentos para esta entidad. Se puede usar para cambiar el valor predeterminado de todos los valores accentSensitive de los alias. |
defaultFuzzyEditDistance |
(Opcional) Cambia el valor predeterminado de la distancia de edición de la coincidencia aproximada para esta entidad. Se puede utilizar para cambiar el valor predeterminado de todos los valores fuzzyEditDistance de los alias. |
aliases |
(Opcional) Matriz de objetos complejos que se pueden usar para especificar ortografías o sinónimos alternativos al nombre de la entidad raíz. |
| Propiedades de alias | Descripción |
|---|---|
text |
Ortografía o representación alternativa de algún nombre de entidad de destino. |
caseSensitive |
(Opcional) Actúa igual que el parámetro "caseSensitive" de la entidad raíz anterior, pero solo se aplica a este alias. |
accentSensitive |
(Opcional) Actúa igual que el parámetro "accentSensitive" de la entidad raíz anterior, pero solo se aplica a este alias. |
fuzzyEditDistance |
(Opcional) Actúa igual que el parámetro "fuzzyEditDistance" de la entidad raíz anterior, pero solo se aplica a este alias. |
Formato en línea
En algunos casos, puede ser más conveniente insertar la definición de entidad personalizada para que esté alineada con la definición de aptitud. Puede usar el mismo formato JSON que el descrito anteriormente, salvo que se incluye dentro de la definición de aptitud. Solo las configuraciones que tienen un tamaño inferior a 10 KB (tamaño serializado) se pueden definir en línea.
Ejemplo de definición de la aptitud
A continuación se muestra un ejemplo de definición de aptitud con un formato en línea:
{
"@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
"context": "/document",
"inlineEntitiesDefinition":
[
{
"name" : "Bill Gates",
"description" : "Microsoft founder." ,
"aliases" : [
{ "text" : "William H. Gates", "caseSensitive" : false },
{ "text" : "BillG", "caseSensitive" : true }
]
},
{
"name" : "Xbox One",
"type": "Hardware",
"subtype" : "Gaming Device",
"id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
"description" : "The Xbox One product"
}
],
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "entities",
"targetName": "matchedEntities"
}
]
}
Como alternativa, puede apuntar a un archivo de definición de entidades externas. A continuación se muestra un ejemplo de definición de aptitud con un formato entitiesDefinitionUri:
{
"@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
"context": "/document",
"entitiesDefinitionUri": "https://myblobhost.net/keyWordsConfig.csv",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "entities",
"targetName": "matchedEntities"
}
]
}
Definición de índice de ejemplo
En esta sección se proporciona una definición de índice de ejemplo. Las "entidades" y las "coincidencias" son matrices de tipos complejos. Puede tener varias entidades por documento y varias coincidencias para cada entidad.
{
"name": "entities",
"type": "Collection(Edm.ComplexType)",
"fields": [
{
"name": "name",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": true,
"sortable": false,
},
{
"name": "id",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": false,
"sortable": false,
},
{
"name": "description",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": true,
"sortable": false,
},
{
"name": "type",
"type": "Edm.String",
"facetable": true,
"filterable": true,
"retrievable": true,
"searchable": false,
"sortable": false,
},
{
"name": "subtype",
"type": "Edm.String",
"facetable": true,
"filterable": true,
"retrievable": true,
"searchable": false,
"sortable": false,
},
{
"name": "matches",
"type": "Collection(Edm.ComplexType)",
"fields": [
{
"name": "text",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": true,
"sortable": false,
},
{
"name": "offset",
"type": "Edm.Int32",
"facetable": true,
"filterable": true,
"retrievable": true,
"sortable": false,
},
{
"name": "length",
"type": "Edm.Int32",
"facetable": true,
"filterable": true,
"retrievable": true,
"sortable": false,
},
{
"name": "matchDistance",
"type": "Edm.Double",
"facetable": true,
"filterable": true,
"retrievable": true,
"sortable": false,
}
]
}
]
}
Muestreo de los datos de entrada
{
"values": [
{
"recordId": "1",
"data":
{
"text": "The company, Microsoft, was founded by Bill Gates. Microsoft's gaming console is called Xbox",
"languageCode": "en"
}
}
]
}
Salida de muestra
{
"values" :
[
{
"recordId": "1",
"data" : {
"entities": [
{
"name" : "Microsoft",
"description" : "This document refers to Microsoft the company",
"id" : "differentIdentifyingScheme987",
"matches" : [
{
"text" : "microsoft",
"offset" : 13,
"length" : 9,
"matchDistance" : 0
},
{
"text" : "Microsoft",
"offset" : 49,
"length" : 9,
"matchDistance" : 0
}
]
},
{
"name" : "Bill Gates",
"description" : "William Henry Gates III, founder of Microsoft.",
"matches" : [
{
"text" : "Bill Gates",
"offset" : 37,
"length" : 10,
"matchDistance" : 0
}
]
}
]
}
}
]
}
Advertencias
"Reached maximum capacity for matches, skipping all further duplicate matches."
Esta advertencia se emitirá si el número de coincidencias detectadas es mayor que el máximo permitido. No se devolverán más coincidencias duplicadas. Si necesita un umbral superior, puede presentar una incidencia de soporte técnico para obtener ayuda con su caso de uso individual.