Instalación y ejecución de contenedores de Text AnalyticsInstall and run Text Analytics containers

Los contenedores permiten ejecutar las API Text Analytics en su propio entorno y son ideales para sus requisitos específicos de seguridad y gobernanza de datos.Containers enable you to run the Text Analytic APIs in your own environment and are great for your specific security and data governance requirements. Los contenedores de Text Analytics proporcionan un procesamiento avanzado de lenguaje natural sobre texto sin formato, e incluye tres funciones principales: análisis de sentimiento, extracción de frases clave y detección de idioma.The Text Analytics containers provide advanced natural language processing over raw text, and include three main functions: sentiment analysis, key phrase extraction, and language detection. Actualmente no se admite la vinculación de entidad en un contenedor.Entity linking is not currently supported in a container.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Requisitos previosPrerequisites

Para ejecutar cualquiera de los contenedores de Text Analytics, debe tener un equipo host y los entornos de contenedores.To run any of the Text Analytics containers, you must have the host computer and container environments.

PreparaciónPreparation

Debe cumplir los siguientes requisitos previos para poder usar contenedores de Text Analytics:You must meet the following prerequisites before using Text Analytics containers:

ObligatorioRequired PropósitoPurpose
Motor de DockerDocker Engine Necesita que el motor de Docker esté instalado en un equipo host.You need the Docker Engine installed on a host computer. Docker dispone de paquetes que configuran el entorno de Docker en macOS, Windows y Linux.Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. Para conocer los principios básicos de Docker y de los contenedores, consulte Introducción a Docker.For a primer on Docker and container basics, see the Docker overview.

Docker debe configurarse para permitir que los contenedores se conecten con Azure y envíen datos de facturación a dicho servicio.Docker must be configured to allow the containers to connect with and send billing data to Azure.

En Windows, Docker también debe estar configurado de forma que admita los contenedores de Linux.On Windows, Docker must also be configured to support Linux containers.

Conocimientos sobre DockerFamiliarity with Docker Debe tener conocimientos básicos sobre los conceptos de Docker, como los registros, los repositorios, los contenedores y las imágenes de contenedor, así como conocer los comandos docker básicos.You should have a basic understanding of Docker concepts, like registries, repositories, containers, and container images, as well as knowledge of basic docker commands.
Recurso de Text AnalyticsText Analytics resource Para poder usar el contenedor, debe tener:In order to use the container, you must have:

Un recurso de Text Analytics de Azure para obtener la clave de API y el URI de punto de conexión asociados.An Azure Text Analytics resource to get the associated API key and endpoint URI. Ambos valores están disponibles en las páginas de claves y de información general de Text Analytics en Azure Portal y son necesarios para iniciar el contenedor.Both values are available on the Azure portal's Text Analytics Overview and Keys pages and are required to start the container.

{API_KEY} : una de las dos claves de recurso disponibles en la página Claves{API_KEY}: One of the two available resource keys on the Keys page

{ENDPOINT_URI} : el punto de conexión tal como se proporciona en la página de Información general.{ENDPOINT_URI}: The endpoint as provided on the Overview page

Recopilación de los parámetros obligatoriosGathering required parameters

Hay tres parámetros principales para todos los contenedores de Cognitive Services que son necesarios.There are three primary parameters for all Cognitive Services' containers that are required. El contrato de licencia para el usuario final (CLUF) debe estar presente con un valor de accept.The end-user license agreement (EULA) must be present with a value of accept. Además, se necesitan una dirección URL de punto de conexión y una clave de API.Additionally, both an Endpoint URL and API Key are needed.

Nota

La única excepción a estos tres parámetros necesarios es cuando los contenedores se consideran que están "sin conexión".The only exception to these three required parameters is when containers are considered "Offline" containers. Los contenedores sin conexión no informan del uso, no se miden y siguen una metodología de facturación diferente.Offline containers do not report usage, are not metered and follow a different billing methodology.

URI de punto de conexión {ENDPOINT_URI}Endpoint URI {ENDPOINT_URI}

El valor del URI del punto de conexión está disponible en la página Información general de Azure Portal del recurso de Cognitive Services correspondiente.The Endpoint URI value is available on the Azure portal Overview page of the corresponding Cognitive Service resource. Vaya a la página Información general, mantenga el cursor sobre el punto de conexión y aparecerá un icono Copy to clipboard .Navigate to the Overview page, hover over the Endpoint, and a Copy to clipboard icon will appear. Cópielo y utilícelo cuando sea necesario.Copy and use where needed.

Recopilación el URI del punto de conexión para su uso posterior

Claves {API_KEY}Keys {API_KEY}

Esta clave se usa para iniciar el contenedor y está disponible en la página de claves de Azure Portal del recurso de Cognitive Services correspondiente.This key is used to start the container, and is available on the Azure portal's Keys page of the corresponding Cognitive Service resource. Vaya a la página Claves y haga clic en el icono Copy to clipboard .Navigate to the Keys page, and click on the Copy to clipboard icon.

Obtención de una de las dos claves para su uso posterior

Importante

Estas claves de suscripción se usan para tener acceso a la API de Cognitive Services.These subscription keys are used to access your Cognitive Service API. No comparta las claves.Do not share your keys. Almacénelas de forma segura, por ejemplo, con Azure Key Vault.Store them securely, for example, using Azure Key Vault. También se recomienda regenerar estas claves periódicamente.We also recommend regenerating these keys regularly. Solo se necesita una clave para realizar una llamada API.Only one key is necessary to make an API call. Al volver a generar la primera clave, puede usar la segunda clave para seguir teniendo acceso al servicio.When regenerating the first key, you can use the second key for continued access to the service.

El equipo hostThe host computer

El host es un equipo basado en x64 que ejecuta el contenedor de Docker.The host is a x64-based computer that runs the Docker container. Puede ser un equipo del entorno local o un servicio de hospedaje de Docker incluido en Azure, como:It can be a computer on your premises or a Docker hosting service in Azure, such as:

Recomendaciones y requisitos del contenedorContainer requirements and recommendations

En la tabla siguiente, se describe el número mínimo y recomendado de núcleos de CPU, por lo menos 2,6 gigahercios (GHz) o con mayor rapidez, y de memoria, en gigabytes (GB), para asignar a cada contenedor de Text Analytics.The following table describes the minimum and recommended CPU cores, at least 2.6 gigahertz (GHz) or faster, and memory, in gigabytes (GB), to allocate for each Text Analytics container.

ContenedorContainer MínimaMinimum RecomendadoRecommended TPSTPS
(mínimo, máximo)(Minimum, Maximum)
Extracción de frases claveKey Phrase Extraction 1 núcleo, 2 GB de memoria1 core, 2-GB memory 1 núcleos, 4 GB de memoria1 core, 4-GB memory 15, 3015, 30
  • Cada núcleo debe ser de 2,6 gigahercios (GHz) como mínimo.Each core must be at least 2.6 gigahertz (GHz) or faster.
  • TPS: transacciones por segundoTPS - transactions per second

El núcleo y la memoria se corresponden con los valores de --cpus y --memory que se usan como parte del comando docker run.Core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

Obtención de la imagen del contenedor con docker pullGet the container image with docker pull

Las imágenes de contenedor de Text Analytics están disponibles en Microsoft Container Registry.Container images for Text Analytics are available on the Microsoft Container Registry.

ContenedorContainer RepositorioRepository
Extracción de frases claveKey Phrase Extraction mcr.microsoft.com/azure-cognitive-services/keyphrase

Sugerencia

Puede usar el comando docker images para enumerar las imágenes de contenedor descargadas.You can use the docker images command to list your downloaded container images. Por ejemplo, el comando siguiente muestra el id., el repositorio y la etiqueta de cada imagen de contenedor descargada, con formato de tabla:For example, the following command lists the ID, repository, and tag of each downloaded container image, formatted as a table:

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Docker pull para los contenedores de Text AnalyticsDocker pull for the Text Analytics containers

Docker pull para el contenedor de extracción de frases claveDocker pull for the Key Phrase Extraction container

Use el comando docker pull para descargar la imagen de contenedor del Registro de contenedor de Microsoft.Use the docker pull command to download a container image from Microsoft Container Registry.

Para obtener una descripción completa de las etiquetas disponibles para los contenedores de Text Analytics, consulte el contenedor Extracción de frases clave en Docker Hub.For a full description of available tags for the Text Analytics containers, see the Key Phrase Extraction container on the Docker Hub.

docker pull mcr.microsoft.com/azure-cognitive-services/keyphrase:latest

Uso del contenedorHow to use the container

Una vez que el contenedor esté en el equipo host, utilice el siguiente proceso para trabajar con el contenedor.Once the container is on the host computer, use the following process to work with the container.

  1. Ejecute el contenedor con la configuración de facturación requerida.Run the container, with the required billing settings. Hay más ejemplos del comando docker run disponibles.More examples of the docker run command are available.
  2. Consulta del punto de conexión de predicción del contenedor.Query the container's prediction endpoint.

Ejecute el contenedor con docker run.Run the container with docker run

Utilice el comando docker run para ejecutar cualquiera de los tres contenedores.Use the docker run command to run any of the three containers. Consulte Recopilación de los parámetros obligatorios para obtener más información sobre cómo obtener los valores de {ENDPOINT_URI}y {API_KEY}.Refer to Gathering required parameters for details on how to get the {ENDPOINT_URI} and {API_KEY} values.

Hay disponibles ejemplos del comando docker run.Examples of the docker run command are available.

Para ejecutar el contenedor Extracción de frases clave, ejecute el siguiente comando docker run.To run the Key Phrase Extraction container, execute the following docker run command.

docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/keyphrase \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Este comando:This command:

  • Ejecuta un contenedor de extracción de frases clave desde la imagen de contenedor.Runs a Key Phrase Extraction container from the container image
  • Asigna un núcleo de CPU y 4 gigabytes (GB) de memoria.Allocates one CPU core and 4 gigabytes (GB) of memory
  • Expone el puerto TCP 5000 y asigna un seudo-TTY para el contenedor.Exposes TCP port 5000 and allocates a pseudo-TTY for the container
  • Una vez que se produce la salida, quita automáticamente el contenedor.Automatically removes the container after it exits. La imagen del contenedor sigue estando disponible en el equipo host.The container image is still available on the host computer.

Importante

Para poder ejecutar el contenedor, las opciones Eula, Billing y ApiKey deben estar especificadas; de lo contrario, el contenedor no se iniciará.The Eula, Billing, and ApiKey options must be specified to run the container; otherwise, the container won't start. Para obtener más información, vea Facturación.For more information, see Billing.

Ejecución de varios contenedores en el mismo hostRun multiple containers on the same host

Si tiene pensado ejecutar varios contenedores con puertos expuestos, asegúrese de que ejecuta cada contenedor con un puerto expuesto diferente.If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. Por ejemplo, ejecute el primer contenedor en el puerto 5000 y el segundo en el puerto 5001.For example, run the first container on port 5000 and the second container on port 5001.

Puede tener este contenedor y un contenedor de Azure Cognitive Services diferente en ejecución simultáneamente en el HOST.You can have this container and a different Azure Cognitive Services container running on the HOST together. También puede tener varios contenedores del mismo contenedor de Cognitive Services en ejecución.You also can have multiple containers of the same Cognitive Services container running.

Consulta del punto de conexión de predicción del contenedorQuery the container's prediction endpoint

El contenedor proporciona varias API de puntos de conexión de predicción de consultas basadas en REST.The container provides REST-based query prediction endpoint APIs.

Utilice el host, http://localhost:5000, con las API de contenedor.Use the host, http://localhost:5000, for container APIs.

Comprobación de que un contenedor está en ejecuciónValidate that a container is running

Hay varias maneras de comprobar que el contenedor está en ejecución.There are several ways to validate that the container is running. Busque la dirección IP externa y el puerto expuesto del contenedor en cuestión y abra el explorador web que prefiera.Locate the External IP address and exposed port of the container in question, and open your favorite web browser. Use las distintas direcciones URL de solicitud para validar que el contenedor se está ejecutando.Use the various request URLs below to validate the container is running. Las direcciones URL de solicitud de ejemplo que se enumeran a continuación son http://localhost:5000, pero el contenedor específico puede variar.The example request URLs listed below are http://localhost:5000, but your specific container may vary. Tenga en cuenta que va a confiar en la dirección IP externa y el puerto expuesto del contenedor.Keep in mind that you're to rely on your container's External IP address and exposed port.

URL de la solicitudRequest URL PropósitoPurpose
http://localhost:5000/ El contenedor ofrece una página principal.The container provides a home page.
http://localhost:5000/status Se solicitó con HTTP GET, para comprobar que el contenedor está en ejecución sin causar una consulta al punto de conexión.Requested with an HTTP GET, to validate that the container is running without causing an endpoint query. Esta solicitud se puede usar con los sondeos de ejecución y preparación de Kubernetes.This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger El contenedor cuenta con un completo conjunto de documentación sobre los puntos de conexión y una característica de prueba.The container provides a full set of documentation for the endpoints and a Try it out feature. Esta característica le permite especificar la configuración en un formulario HTML basado en web y realizar la consulta sin necesidad de escribir código.With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. Una vez que la consulta devuelve resultados, se proporciona un ejemplo del comando CURL para mostrar los encabezados HTTP y el formato de cuerpo requeridos.After the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format that's required.

Página principal del contenedor

Detención del contenedorStop the container

Para apagar el contenedor, en el entorno de la línea de comandos donde se ejecuta el contenedor, seleccione Ctrl + C.To shut down the container, in the command-line environment where the container is running, select Ctrl+C.

solución de problemasTroubleshooting

Si ejecuta el contenedor con un montaje de salida y el registro habilitados, el contenedor genera archivos de registro que resultan útiles para solucionar problemas que se producen al iniciar o ejecutar el contenedor.If you run the container with an output mount and logging enabled, the container generates log files that are helpful to troubleshoot issues that happen while starting or running the container.

Sugerencia

Para más información e instrucciones para solución de problemas, vea Preguntas frecuentes de los contenedores de Cognitive Services .For more troubleshooting information and guidance, see Cognitive Services containers frequently asked questions (FAQ).

FacturaciónBilling

Los contenedores de Text Analytics envían información de facturación a Azure mediante un recurso de Text Analytics en la cuenta de Azure.The Text Analytics containers send billing information to Azure, using a Text Analytics resource on your Azure account.

Las consultas en el contenedor se facturan con el plan de tarifa del recurso de Azure que se usa para <ApiKey>.Queries to the container are billed at the pricing tier of the Azure resource that's used for the <ApiKey>.

Los contenedores de Azure Cognitive Services no tienen licencia para ejecutarse si no están conectados al punto de conexión de facturación para las mediciones.Azure Cognitive Services containers aren't licensed to run without being connected to the billing endpoint for metering. Debe habilitar los contenedores para que comuniquen la información de facturación al punto de conexión de facturación en todo momento.You must enable the containers to communicate billing information with the billing endpoint at all times. Los contenedores de Cognitive Services no envían datos de los clientes (por ejemplo, la imagen o el texto que se está analizando) a Microsoft.Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Conexión a AzureConnect to Azure

El contenedor necesita que se ejecuten los valores del argumento de facturación.The container needs the billing argument values to run. Estos valores permiten al contenedor conectarse al punto de conexión de facturación.These values allow the container to connect to the billing endpoint. El contenedor informa sobre el uso cada 10 a 15 minutos.The container reports usage about every 10 to 15 minutes. Si el contenedor no se conecta a Azure en la ventana de tiempo permitida, continuará ejecutándose pero no atenderá las consultas hasta que se restaure el punto de conexión de facturación.If the container doesn't connect to Azure within the allowed time window, the container continues to run but doesn't serve queries until the billing endpoint is restored. Se intenta 10 veces la conexión en el mismo intervalo de tiempo de 10 a 15 minutos.The connection is attempted 10 times at the same time interval of 10 to 15 minutes. Si no se puede conectar con el punto de conexión de facturación en esos 10 intentos, el contenedor deja de ejecutarse.If it can't connect to the billing endpoint within the 10 tries, the container stops running.

Argumentos de facturaciónBilling arguments

Para que el comando docker run inicie el contenedor, se deben especificar las tres opciones siguientes se deben especificar con valores válidos:For the docker run command to start the container, all three of the following options must be specified with valid values:

OpciónOption DESCRIPCIÓNDescription
ApiKey La clave de API del recurso de Cognitive Services que se usa para realizar un seguimiento de la información de facturación.The API key of the Cognitive Services resource that's used to track billing information.
El valor de esta opción se debe establecer en una clave de API para el recurso aprovisionado que se especifica en Billing.The value of this option must be set to an API key for the provisioned resource that's specified in Billing.
Billing El punto de conexión del recurso de Cognitive Services que se usa para realizar el seguimiento de la información de facturación.The endpoint of the Cognitive Services resource that's used to track billing information.
El valor de esta opción debe establecerse en el URI del punto de conexión de un recurso aprovisionado de Azure.The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula Indica que ha aceptado la licencia del contenedor.Indicates that you accepted the license for the container.
El valor de esta opción debe establecerse en accept.The value of this option must be set to accept.

Para obtener más información acerca de estas opciones, consulte Configure containers (Configuración de contenedores).For more information about these options, see Configure containers.

Publicaciones de blogBlog posts

Ejemplos para desarrolladoresDeveloper samples

Hay ejemplos para desarrolladores disponibles en nuestro repositorio de GitHub.Developer samples are available at our GitHub repository.

Ver seminario webView webinar

Únase al seminario web para más información sobre:Join the webinar to learn about:

  • Implementación de Cognitive Services en cualquier máquina con DockerHow to deploy Cognitive Services to any machine using Docker
  • Implementación de Cognitive Services en AKSHow to deploy Cognitive Services to AKS

ResumenSummary

En este artículo, ha aprendido los conceptos y el flujo de trabajo para la descarga, instalación y ejecución de contenedores de Text Analytics.In this article, you learned concepts and workflow for downloading, installing, and running Text Analytics containers. En resumen:In summary:

  • Text Analytics proporciona tres contenedores Linux para Docker, que encapsulan varias funcionalidades:Text Analytics provides three Linux containers for Docker, encapsulating various capabilities:
    • Extracción de frases claveKey Phrase Extraction
    • Detección de idiomaLanguage Detection
    • Análisis de sentimientoSentiment Analysis
  • Las imágenes del contenedor se descargan desde Microsoft Container Registry (MCR) en Azure.Container images are downloaded from the Microsoft Container Registry (MCR) in Azure.
  • Las imágenes de contenedor se ejecutan en Docker.Container images run in Docker.
  • Puede usar la API REST o el SDK para llamar a operaciones en contenedores de Text Analytics mediante la especificación del URI del host del contenedor.You can use either the REST API or SDK to call operations in Text Analytics containers by specifying the host URI of the container.
  • Debe especificar la información de facturación al crear una instancia de un contenedor.You must specify billing information when instantiating a container.

Importante

Los contenedores de Cognitive Services no tienen licencia para ejecutarse sin estar conectados a Azure para realizar mediciones.Cognitive Services containers are not licensed to run without being connected to Azure for metering. Los clientes tienen que habilitar los contenedores para comunicar la información de facturación con el servicio de medición en todo momento.Customers need to enable the containers to communicate billing information with the metering service at all times. Los contenedores de Cognitive Services no envían datos de los clientes (por ejemplo, la imagen o el texto que se está analizando) a Microsoft.Cognitive Services containers do not send customer data (e.g., the image or text that is being analyzed) to Microsoft.

Pasos siguientesNext steps