Biblioteca cliente de Azure Text Analytics para Java: versión 5.4.0

  • Artículo

Azure Cognitive Service for Language es un servicio basado en la nube que proporciona características de procesamiento de lenguaje natural (NLP) para comprender y analizar texto, e incluye las siguientes características principales:

  • Análisis de sentimiento
  • Reconocimiento de entidades (entidades con nombre, vinculadas e información de identificación personal (PII)
  • Detección de idiomas
  • Extracción de frases clave
  • Análisis de varias acciones por documento
  • Análisis de entidades sanitarias
  • Resumen de texto abstracto
  • Resumen de texto extractivo
  • Reconocimiento de entidades con nombre personalizado
  • Clasificación de texto personalizada

Código | fuentePaquete (Maven) | Documentación | de referencia de APIDocumentación | del productoMuestras

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
    <version>5.4.0</version>
</dependency>

Nota: Esta versión de la biblioteca cliente tiene como valor predeterminado la 2023-04-01 versión del servicio. Es una versión más reciente que 3_0, 3_1 y 2022-05-01.

En esta tabla se muestra la relación entre los servicios del SDK y las versiones de API compatibles del servicio:

Versión del SDK Versión de la API admitidas del servicio
5.3.x 3.0, 3.1, 2022-05-01, 2023-04-01 (valor predeterminado)
5.2.x 3.0, 3.1, 2022-05-01
5.1.x 3.0, 3.1
5.0.x 3.0

Creación de un recurso de Cognitive Services o Language Service

El servicio language admite el acceso de varios servicios y de un solo servicio. Cree un recurso de Cognitive Services si tiene previsto acceder a varios servicios de Cognitive Services en un único punto de conexión o clave. Solo para el acceso al servicio de idioma, cree un recurso de servicio de idioma.

Puede crear el recurso mediante Azure Portal o la CLI de Azure siguiendo los pasos descritos en este documento.

Autenticar el cliente

Para interactuar con el servicio language, deberá crear una instancia del cliente de Text Analytics, tanto los clientes asincrónicos como sincrónicos se pueden crear mediante TextAnalyticsClientBuilder la invocación buildClient() de crea un cliente sincrónico mientras buildAsyncClient() crea su homólogo asincrónico.

Necesitará un punto de conexión y una clave o TokenCredential de AAD para crear instancias de un objeto de cliente.

Búsqueda del punto de conexión

Puede encontrar el punto de conexión del recurso del servicio de lenguaje en Azure Portal en "Claves y punto de conexión" o la CLI de Azure.

# Get the endpoint for the Language service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

Creación de un cliente Text Analytics con credenciales de clave

Una vez que tenga el valor de la clave, escrébalo como una cadena para AzureKeyCredential. Esto se puede encontrar en Azure Portal en la sección "Claves y punto de conexión" del recurso del servicio de lenguaje creado o ejecutando el siguiente comando de la CLI de Azure:

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Use la clave como parámetro de credencial para autenticar el cliente:

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

La biblioteca cliente de Azure Text Analytics proporciona una manera de rotar la clave existente.

AzureKeyCredential credential = new AzureKeyCredential("{key}");
TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(credential)
    .endpoint("{endpoint}")
    .buildClient();

credential.update("{new_key}");

Creación de un cliente Text Analytics con credenciales de Azure Active Directory

El SDK de Azure para Java admite un paquete de identidad de Azure, lo que facilita la obtención de credenciales de Plataforma de identidad de Microsoft.

La autenticación con AAD requiere una configuración inicial:

  • Adición del paquete de identidad de Azure
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.4</version>
</dependency>

Después de la instalación, puede elegir el tipo de credencial de azure.identity que se va a usar. Por ejemplo, DefaultAzureCredential se puede usar para autenticar al cliente: establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

La autorización es más fácil mediante DefaultAzureCredential. Encuentra la mejor credencial para usar en su entorno en ejecución. Para más información sobre el uso de la autorización de Azure Active Directory con el servicio de lenguaje, consulte la documentación asociada.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .endpoint("{endpoint}")
    .credential(defaultCredential)
    .buildAsyncClient();

Conceptos clave

cliente de Text Analytics

La biblioteca cliente de Text Analytics proporciona textAnalyticsClient y TextAnalyticsAsyncClient para realizar análisis en lotes de documentos. Proporciona operaciones sincrónicas y asincrónicas para acceder a un uso específico del servicio language, como la detección de idioma o la extracción de frases clave.

Entrada

Una entrada de texto, también denominada documento, es una única unidad de documento que analizarán los modelos predictivos en el servicio Language. Las operaciones en un cliente de Text Analytics pueden tomar un único documento o una colección de documentos que se van a analizar como un lote. Consulte las limitaciones del servicio para el documento, incluidos los límites de longitud del documento, el tamaño máximo del lote y la codificación de texto admitida.

Operación en varios documentos

Para cada operación admitida, el cliente de Text Analytics proporciona sobrecargas de método para tomar un solo documento, un lote de documentos como cadenas o un lote de cualquiera TextDocumentInput de los objetos o DetectLanguageInput . La sobrecarga que toma el TextDocumentInput lote o DetectLanguageInput permite a los autores de las llamadas proporcionar a cada documento un identificador único, indicar que los documentos del lote se escriben en distintos idiomas o proporcionan una sugerencia de país sobre el idioma del documento.

Valor devuelto

Un resultado de operación, como AnalyzeSentimentResult, es el resultado de una operación de servicio de lenguaje, que contiene una predicción o predicciones sobre un único documento y una lista de advertencias dentro de ella. Opcionalmente, el tipo de resultado de una operación también puede incluir información sobre el documento de entrada y cómo se procesó. Un resultado de la operación contiene una isError propiedad que permite identificar si una operación ejecutada se ejecutó correctamente o no se realizó correctamente para el documento especificado. Cuando la operación produce un error, simplemente puede llamar getError() a para obtener TextAnalyticsError , que contiene el motivo por el que no se realiza correctamente. Si está interesado en cuántos caracteres se encuentran en el documento o el número de transacciones de operación que han pasado, simplemente llame getStatistics() a para obtener la TextDocumentStatistics que contiene ambas informaciones.

Colección de valores devueltos

Colección de resultados de la operación, como AnalyzeSentimentResultCollection, que es la colección del resultado de la operación de análisis de opiniones. También incluye la versión del modelo de la operación y las estadísticas de los documentos por lotes.

Nota: Se recomienda usar los métodos por lotes al trabajar en entornos de producción, ya que permiten enviar una solicitud con varios documentos. Esto es más eficaz que enviar una solicitud por cada documento.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de Language Service, entre las que se incluyen:

cliente de Text Analytics

El servicio de lenguaje admite la creación de cliente sincrónica y asincrónica mediante TextAnalyticsClientBuilder,

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

o

TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildAsyncClient();

Análisis de opinión

Ejecute un modelo predictivo para identificar las opiniones positivas, negativas, neutras o mixtas contenidas en el documento o lote de documentos proporcionados.

String document = "The hotel was dark and unclean. I like microsoft.";
DocumentSentiment documentSentiment = textAnalyticsClient.analyzeSentiment(document);
System.out.printf("Analyzed document sentiment: %s.%n", documentSentiment.getSentiment());
documentSentiment.getSentences().forEach(sentenceSentiment ->
    System.out.printf("Analyzed sentence sentiment: %s.%n", sentenceSentiment.getSentiment()));

Para obtener ejemplos sobre cómo usar la opción AnalyzeSentimentBatch recomendada de producción, consulte aquí.

Para obtener información más detallada sobre las opiniones relacionadas con aspectos de un producto o servicio, también conoce como Análisis de sentimiento basado en aspectos en procesamiento de lenguaje natural (NLP), consulte el ejemplo sobre el análisis de opiniones con minería de opiniones aquí.

Consulte la documentación del servicio para obtener una explicación conceptual del análisis de opiniones.

Detectar idioma

Ejecute un modelo predictivo para determinar el lenguaje en el que se escribe el documento o el lote de documentos proporcionados.

String document = "Bonjour tout le monde";
DetectedLanguage detectedLanguage = textAnalyticsClient.detectLanguage(document);
System.out.printf("Detected language name: %s, ISO 6391 name: %s, confidence score: %f.%n",
    detectedLanguage.getName(), detectedLanguage.getIso6391Name(), detectedLanguage.getConfidenceScore());

Para obtener ejemplos sobre cómo usar la opción DetectLanguageBatch recomendada de producción, consulte aquí. Consulte la documentación del servicio para obtener una explicación conceptual de la detección de idioma.

Extracción de frases clave

Ejecute un modelo para identificar una colección de frases significativas que se encuentran en el documento o lote de documentos proporcionados.

String document = "My cat might need to see a veterinarian.";
System.out.println("Extracted phrases:");
textAnalyticsClient.extractKeyPhrases(document).forEach(keyPhrase -> System.out.printf("%s.%n", keyPhrase));

Para obtener ejemplos sobre cómo usar la opción ExtractKeyPhrasesBatch recomendada de producción, consulte aquí. Consulte la documentación del servicio para obtener una explicación conceptual de la extracción de frases clave.

Reconocimiento de entidades con nombre

Ejecute un modelo predictivo para identificar una colección de entidades con nombre en el documento o lote de documentos proporcionados y clasificar esas entidades en categorías como persona, ubicación u organización. Para obtener más información sobre las categorías disponibles, consulte Categorías de entidad con nombre.

String document = "Satya Nadella is the CEO of Microsoft";
textAnalyticsClient.recognizeEntities(document).forEach(entity ->
    System.out.printf("Recognized entity: %s, category: %s, subcategory: %s, confidence score: %f.%n",
        entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

Para obtener ejemplos sobre cómo usar la opción RecognizeEntitiesBatch recomendada de producción, consulte aquí. Consulte la documentación del servicio para obtener una explicación conceptual del reconocimiento de entidades con nombre.

Reconocimiento de entidades de información de identificación personal

Ejecute un modelo predictivo para identificar una colección de entidades de información de identificación personal (PII) en el documento proporcionado. Reconoce y clasifica las entidades PII en su texto de entrada, como números de seguridad social, información de cuenta bancaria, números de tarjeta de crédito, etc. Este punto de conexión solo se admite para las versiones de API v3.1-preview.1 y posteriores.

String document = "My SSN is 859-98-0987";
PiiEntityCollection piiEntityCollection = textAnalyticsClient.recognizePiiEntities(document);
System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
piiEntityCollection.forEach(entity -> System.out.printf(
    "Recognized Personally Identifiable Information entity: %s, entity category: %s, entity subcategory: %s,"
        + " confidence score: %f.%n",
    entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

Para obtener ejemplos sobre cómo usar la opción RecognizePiiEntitiesBatch recomendada de producción, consulte aquí. Consulte la documentación del servicio para conocer los tipos de entidad PII admitidos.

Reconocer entidades vinculadas

Ejecute un modelo predictivo para identificar una colección de entidades que se encuentran en el documento o lote de documentos proporcionados e incluya información que vincule las entidades a sus entradas correspondientes en un knowledge base conocido.

String document = "Old Faithful is a geyser at Yellowstone Park.";
textAnalyticsClient.recognizeLinkedEntities(document).forEach(linkedEntity -> {
    System.out.println("Linked Entities:");
    System.out.printf("Name: %s, entity ID in data source: %s, URL: %s, data source: %s.%n",
        linkedEntity.getName(), linkedEntity.getDataSourceEntityId(), linkedEntity.getUrl(), linkedEntity.getDataSource());
    linkedEntity.getMatches().forEach(match ->
        System.out.printf("Text: %s, confidence score: %f.%n", match.getText(), match.getConfidenceScore()));
});

Para obtener ejemplos sobre cómo usar la opción RecognizeLinkedEntitiesBatch recomendada de producción, consulte aquí. Consulte la documentación del servicio para obtener una explicación conceptual de la vinculación de entidades.

Análisis de entidades sanitarias

Text Analytics para el estado es un servicio de contenedor que extrae y etiqueta información médica pertinente de textos no estructurados, como notas del doctor, resúmenes de descarga, documentos clínicos y registros electrónicos de salud.

Para obtener más información, vea Cómo: Usar Text Analytics para el estado.

Reconocimiento de entidades personalizadas

Reconocimiento de entidades con nombre personalizadas es una de las características que ofrece Azure Cognitive Service para lenguaje. Se trata de un servicio de API basado en la nube que aplica inteligencia de aprendizaje automático que le permite crear modelos personalizados para tareas de reconocimiento de entidades con nombre personalizadas.

Para obtener más información, vea Cómo usar: Reconocimiento de entidades personalizadas.

Clasificación de texto personalizada

La clasificación de texto personalizado es una de las características personalizadas que ofrece Azure Cognitive Service for Language. Se trata de un servicio de API basado en la nube que aplica inteligencia de aprendizaje automático para permitirle crear modelos personalizados para tareas de clasificación de texto.

Para obtener más información, vea How to use: Custom Text Classification.

Análisis de varias acciones

La Analyze funcionalidad permite elegir cuál de las características de servicio de lenguaje admitidas se ejecutará en el mismo conjunto de documentos. Actualmente, las características admitidas son:

  • Reconocimiento de entidades con nombre
  • Reconocimiento de entidades de PII
  • Reconocimiento de entidades vinculadas
  • Extracción de frases clave
  • Análisis de sentimiento
  • Análisis de atención sanitaria
  • Reconocimiento de entidades personalizados (versión de API 2022-05-01 y versiones posteriores)
  • Clasificación de Single-Label personalizada (API versión 2022-05-01 y posteriores)
  • Clasificación personalizada de varias etiquetas (API versión 2022-05-01 y posteriores)
  • Resumen de texto abstracto (versión de API 2023-04-01 y versiones posteriores)
  • Resumen de texto extractivo (versión de API 2023-04-01 y versiones posteriores)

Ejemplo: Análisis de varias acciones

Para obtener más ejemplos, como ejemplos asincrónicos, consulte aquí.

Solución de problemas

General

Text Analytics clientes generan excepciones. Por ejemplo, si intenta detectar los idiomas de un lote de texto con los mismos identificadores de documento, 400 se devuelve un error que indica una solicitud incorrecta. En el siguiente fragmento de código, el error se controla correctamente mediante la captura y presentación de la información adicional sobre el error.

List<DetectLanguageInput> documents = Arrays.asList(
    new DetectLanguageInput("1", "This is written in English.", "us"),
    new DetectLanguageInput("1", "Este es un documento  escrito en Español.", "es")
);

try {
    textAnalyticsClient.detectLanguageBatchWithResponse(documents, null, Context.NONE);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
}

Habilitación del registro de cliente

Puede establecer la variable de entorno AZURE_LOG_LEVEL para ver las instrucciones de registro realizadas en la biblioteca cliente. Por ejemplo, al establecer AZURE_LOG_LEVEL=2, se mostrarán todos los mensajes informativos, de advertencia y de registro de errores. Los niveles de registro se pueden encontrar aquí: niveles de registro.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca Boring SSL es un archivo uber-jar que contiene bibliotecas nativas para Linux, macOS o Windows, que proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

  • Los ejemplos se explican detalladamente aquí.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones