Uso de contenedores Docker de resumen en el entorno local
Los contenedores le permiten alojar la API de resumen en su propia infraestructura. Si tiene requisitos de seguridad o de gobernanza de datos que no se pueden cumplir llamando a resumen de forma remota, entonces los contenedores podrían ser una buena opción.
Requisitos previos
- Si no tiene una suscripción a Azure, cree una cuenta gratuita.
- Docker instalado en un equipo host. Docker debe configurarse para permitir que los contenedores se conecten con Azure y envíen datos de facturación a dicho servicio.
- En Windows, Docker también debe estar configurado de forma que admita los contenedores de Linux.
- Debe estar familiarizado con los conceptos de Docker.
- Un recurso de idioma con el plan de tarifa gratis (F0) o estándar (S). En el caso de los contenedores desconectados, se requiere el nivel DC0.
Recopilación de todos los parámetros obligatorios
Se requieren tres parámetros principales para todos los contenedores Azure AI. Los Términos de licencia del software de Microsoft deben estar presentes con el valor Acepto. También se necesitan un URI de punto de conexión y una clave de API.
URI de punto de conexión
El valor de {ENDPOINT_URI} está disponible en la página Información general de Azure Portal del recurso de servicios de Azure AI correspondiente. Vaya a la página Información general, mantenga el puntero sobre el punto de conexión y aparecerá un icono Copiar en el Portapapeles. Copie y use el punto de conexión cuando sea necesario.
Teclas
El valor {API_KEY} se usa para iniciar el contenedor y está disponible en la página Claves de Azure Portal del recurso de servicios de Azure AI correspondiente. Vaya a la página Claves y seleccione el icono Copiar en el Portapapeles.
Importante
Estas claves de suscripción se usan para acceder a la API de servicios de Azure AI. No comparta sus claves. Almacénelas de forma segura. Por ejemplo, use Azure Key Vault. También se recomienda volver a generar estas claves con regularidad. Solo se necesita una clave para realizar una llamada API. Al volver a generar la primera clave, puede usar la segunda para seguir teniendo acceso al servicio.
Recomendaciones y requisitos del equipo host
El host es un equipo basado en x64 que ejecuta el contenedor de Docker. Puede ser un equipo del entorno local o un servicio de hospedaje de Docker incluido en Azure, como:
- Azure Kubernetes Service.
- Azure Container Instances.
- Un clúster de Kubernetes implementado en Azure Stack. Para obtener más información, consulte Implementación de Kubernetes en Azure Stack.
La siguiente tabla describe las especificaciones mínimas y recomendadas para el resumen del contenedor de integración. Las combinaciones de CPU/memoria enumeradas son para una entrada de token de 4000 (el consumo de conversación es para todos los aspectos de la misma solicitud).
| Tipo de contenedor | Número de núcleos de CPU recomendados | Memoria recomendada | Notas |
|---|---|---|---|
| Contenedor de CPU de resumen | 16 | 48 GB | |
| Contenedor de GPU de resumen | 2 | 24 GB | Requiere una GPU de Nvidia que admita Cuda 11.8 con VRAM de 16 GB. |
El núcleo de CPU y la memoria corresponden a los valores de --cpus y --memory que se usan como parte del comando docker run.
Obtención de la imagen del contenedor con docker pull
La imagen del contenedor de resumen puede encontrarse en el mcr.microsoft.com sindicato del registro de contenedores. Reside en el repositorio azure-cognitive-services/textanalytics/ y se denomina summarization. El nombre completo de la imagen de contenedor es mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization.
Para usar la versión más reciente del contenedor, puede usar la etiqueta latest. También puede encontrar una lista completa de etiquetas en el MCR.
Use el comando docker pull para descargar una imagen de contenedor desde Microsoft Container Registry.
docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu
para contenedores de CPU,
docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:gpu
para contenedores de GPU.
Sugerencia
Puede usar el comando docker images para enumerar las imágenes de contenedor descargadas. Por ejemplo, el comando siguiente muestra el id., el repositorio y la etiqueta de cada imagen de contenedor descargada, con formato de tabla:
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
<image-id> <repository-path/name> <tag-name>
Descarga de los modelos de contenedor de resumen
Un requisito previo para ejecutar el contenedor de resumen es descargar primero los modelos. Para ello, ejecute uno de los siguientes comandos mediante una imagen de contenedor de CPU como ejemplo:
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ExtractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=AbstractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ConversationSummarization billing={ENDPOINT_URI} apikey={API_KEY}
No se recomienda descargar modelos para todas las aptitudes dentro del mismo HOST_MODELS_PATH, ya que el contenedor carga todos los modelos dentro de HOST_MODELS_PATH. Si lo hace, usaría una gran cantidad de memoria. Se recomienda descargar solo el modelo para la aptitud que necesita en un determinado HOST_MODELS_PATH.
Para garantizar la compatibilidad entre los modelos y el contenedor, vuelva a descargar los modelos utilizados cada vez que cree un contenedor mediante una nueva versión de imagen. Al usar un contenedor desconectado, la licencia debería descargarse de nuevo después de descargar los modelos.
Ejecute el contenedor con docker run.
Una vez que el contenedor de resumen esté en el equipo host, use el siguiente comando docker run para ejecutar los contenedores. El contenedor continuará ejecutándose hasta que lo detenga. Reemplace los marcadores de posición por sus propios valores:
| Marcador de posición | Value | Formato o ejemplo |
|---|---|---|
| {HOST_MODELS_PATH} | El montaje de volumen del equipo host, que Docker usa para conservar el modelo. | Un ejemplo es c:\SummarizationModel donde la unidad c:\ se encuentra en el equipo host. |
| {URI_PUNTODECONEXIÓN} | Punto de conexión para acceder a la API de resumen. Puede encontrarla en la página Clave y punto de conexión del recurso en Azure Portal. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
| {CLAVE_API} | Clave del recurso de lenguaje. Puede encontrarla en la página Clave y punto de conexión del recurso en Azure Portal. | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
docker run -p 5000:5000 -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu eula=accept rai_terms=accept billing={ENDPOINT_URI} apikey={API_KEY}
O bien, si está ejecutando un contenedor de GPU, use este comando en su lugar.
docker run -p 5000:5000 --gpus all -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:gpu eula=accept rai_terms=accept billing={ENDPOINT_URI} apikey={API_KEY}
Si hay más de una GPU en la máquina, reemplace --gpus all por --gpus device={DEVICE_ID}.
Importante
- Los comandos de Docker de las secciones siguientes usan la barra diagonal inversa,
\, como un carácter de continuación de línea. Puede quitarla o reemplazarla en función de los requisitos del sistema operativo del host. - Para poder ejecutar el contenedor, las opciones
Eula,Billing,rai_termsyApiKeydeben estar especificadas; de lo contrario, el contenedor no se iniciará. Para obtener más información, vea Facturación.
Este comando:
- Ejecute un contenedor de resumen a partir de la imagen del contenedor
- Asigna un núcleo de CPU y 4 gigabytes (GB) de memoria.
- Expone el puerto TCP 5000 y asigna un seudo-TTY para el contenedor.
- Una vez que se produce la salida, quita automáticamente el contenedor. La imagen del contenedor sigue estando disponible en el equipo host.
Ejecución de varios contenedores en el mismo host
Si tiene pensado ejecutar varios contenedores con puertos expuestos, asegúrese de que ejecuta cada contenedor con un puerto expuesto diferente. Por ejemplo, ejecute el primer contenedor en el puerto 5000 y el segundo en el puerto 5001.
Puede tener este contenedor y un contenedor de servicios de Azure AI diferente en ejecución simultáneamente en el HOST. También puede tener varios contenedores del mismo contenedor de servicios de Azure AI en ejecución.
Consulta del punto de conexión de predicción del contenedor
El contenedor proporciona varias API de puntos de conexión de predicción de consultas basadas en REST.
Utilice el host, http://localhost:5000, con las API de contenedor.
Comprobación de que un contenedor está en ejecución
Hay varias maneras de comprobar que el contenedor está en ejecución. Busque la dirección IP externa y el puerto expuesto del contenedor en cuestión y abra el explorador web que prefiera. Use las distintas direcciones URL de solicitud que se indican a continuación para validar que el contenedor se está ejecutando. Las direcciones URL de solicitud de ejemplo que se enumeran aquí son http://localhost:5000, pero el contenedor específico puede variar. Asegúrese de confiar en la dirección IP externa y el puerto expuesto del contenedor.
| URL de la solicitud | Propósito |
|---|---|
http://localhost:5000/ |
El contenedor ofrece una página principal. |
http://localhost:5000/ready |
Esta URL, solicitada con GET, proporciona una comprobación de que el contenedor está listo para aceptar una consulta para el modelo. Esta solicitud se puede usar con los sondeos de ejecución y preparación de Kubernetes. |
http://localhost:5000/status |
Esta URL, también solicitada con GET, comprueba si el valor de api-key usado para iniciar el contenedor es válido sin generar una consulta de punto de conexión. Esta solicitud se puede usar con los sondeos de ejecución y preparación de Kubernetes. |
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. 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. 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. |
Ejecutar el contenedor desconectado de Internet
Para usar este contenedor desconectado de Internet, primero debe solicitar acceso rellenando una solicitud y comprando un plan de compromiso. Consulte Uso de contenedores de Docker en entornos desconectados para más información.
Si ha sido aprobado para ejecutar el contenedor desconectado de Internet, use el ejemplo siguiente que muestra el formato del comando docker run que se va a usar, con valores de marcador de posición. Reemplace estos valores por los suyos.
El parámetro DownloadLicense=True en el comando docker run descargará un archivo de licencia que permitirá que el contenedor de Docker se ejecute sin estar conectado a Internet. También contiene una fecha de expiración, tras la cual el archivo de licencia no será válido para ejecutar el contenedor. Los archivos de licencia solo se pueden con el contenedor adecuado para el que se ha recibido aprobación. Por ejemplo, no se puede usar un archivo de licencia para un contenedor de conversión de voz en texto con un contenedor de servicios de lenguaje.
Descarga de los modelos de contenedor de resumen desconectados
Un requisito previo para ejecutar el contenedor de resumen es descargar primero los modelos. Para ello, ejecute uno de los siguientes comandos mediante una imagen de contenedor de CPU como ejemplo:
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ExtractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=AbstractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ConversationSummarization billing={ENDPOINT_URI} apikey={API_KEY}
No se recomienda descargar modelos para todas las aptitudes dentro del mismo HOST_MODELS_PATH, ya que el contenedor carga todos los modelos dentro de HOST_MODELS_PATH. Si lo hace, usaría una gran cantidad de memoria. Se recomienda descargar solo el modelo para la aptitud que necesita en un determinado HOST_MODELS_PATH.
Para garantizar la compatibilidad entre los modelos y el contenedor, vuelva a descargar los modelos utilizados cada vez que cree un contenedor mediante una nueva versión de imagen. Al usar un contenedor desconectado, la licencia debería descargarse de nuevo después de descargar los modelos.
Ejecutar el contenedor desconectado con docker run
| Marcador | Value | Formato o ejemplo |
|---|---|---|
{IMAGE} |
Imagen de contenedor que desea usar. | mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu |
{LICENSE_MOUNT} |
Ruta de acceso en que se descargará y montará la licencia. | /host/license:/path/to/license/directory |
{HOST_MODELS_PATH} |
La ruta de acceso en que se descargará y montará la licencia. | /host/models:/models |
{ENDPOINT_URI} |
Punto de conexión para autenticar la solicitud de servicio. Puede encontrarla en la página Clave y punto de conexión del recurso en Azure Portal. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{API_KEY} |
Clave del recurso de Text Analytics. Puede encontrarla en la página Clave y punto de conexión del recurso en Azure Portal. | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
{CONTAINER_LICENSE_DIRECTORY} |
Ubicación de la carpeta de licencias en el sistema de archivos local del contenedor. | /path/to/license/directory |
docker run --rm -it -p 5000:5000 \
-v {LICENSE_MOUNT} \
-v {HOST_MODELS_PATH} \
{IMAGE} \
eula=accept \
rai_terms=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Una vez descargado el archivo de licencia, el contenedor se puede ejecutar en un entorno desconectado. En el ejemplo siguiente se muestra el formato del comando docker run que se va a usar, con valores de marcador de posición. Reemplace estos valores por los suyos.
Cada vez que se ejecute el contenedor, es preciso montar el archivo de licencia en el contenedor y la ubicación de la carpeta de licencias en el sistema de archivos local del contenedor debe especificarse con Mounts:License=. También se debe especificar un montaje de salida para que se puedan escribir registros de uso de facturación.
| Marcador de posición | Value | Formato o ejemplo |
|---|---|---|
{IMAGE} |
Imagen de contenedor que desea usar. | mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu |
{MEMORY_SIZE} |
Tamaño adecuado de la memoria que se asignará al contenedor. | 4g |
{NUMBER_CPUS} |
Número apropiado de procesadores que se asignan a un contenedor. | 4 |
{LICENSE_MOUNT} |
Ruta de acceso en la que se encontrará y montará la licencia. | /host/license:/path/to/license/directory |
{HOST_MODELS_PATH} |
La ruta de acceso en que se descargará y montará la licencia. | /host/models:/models |
{OUTPUT_PATH} |
Ruta de acceso de salida para registrar los registros de uso. | /host/output:/path/to/output/directory |
{CONTAINER_LICENSE_DIRECTORY} |
Ubicación de la carpeta de licencias en el sistema de archivos local del contenedor. | /path/to/license/directory |
{CONTAINER_OUTPUT_DIRECTORY} |
Ubicación de la carpeta de salida en el sistema de archivos local del contenedor. | /path/to/output/directory |
docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \
-v {LICENSE_MOUNT} \
-v {HOST_MODELS_PATH} \
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
rai_terms=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}
Detención del contenedor
Para apagar el contenedor, en el entorno de la línea de comandos donde se ejecuta el contenedor, seleccione Ctrl + C.
Solución de problemas
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.
Sugerencia
Para obtener más información y guía sobre la solución de problemas, consulte las Preguntas más frecuentes (FAQ) sobre los contenedores Azure AI.
Facturación
Los contenedores de resumen envían información de facturación a Azure, mediante un recurso Language de su cuenta Azure.
Las consultas en el contenedor se facturan con el plan de tarifa del recurso de Azure que se usa para el parámetro ApiKey.
Los contenedores de servicios de Azure AI no tienen licencia para ejecutarse si no están conectados al punto de conexión de medición o facturación. Debe habilitar los contenedores para que comuniquen la información de facturación al punto de conexión de facturación en todo momento. Los contenedores de servicios de Azure AI no envían datos de los clientes (por ejemplo, la imagen o el texto que se está analizando) a Microsoft.
Conexión con Azure
El contenedor necesita que se ejecuten los valores del argumento de facturación. Estos valores permiten al contenedor conectarse al punto de conexión de facturación. El contenedor informa sobre el uso cada 10 a 15 minutos. 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. Se intenta 10 veces la conexión en el mismo intervalo de tiempo de 10 a 15 minutos. Si no se puede conectar con el punto de conexión de facturación en esos 10 intentos, el contenedor deja de atender solicitudes. Consulte Preguntas más frecuentes acerca de los contenedores de servicios de Azure AI para obtener un ejemplo de la información que se envía a Microsoft para la facturación.
Argumentos de facturación
El comando docker run iniciará el contenedor cuando se especifiquen las tres opciones siguientes con valores válidos:
| Opción | Descripción |
|---|---|
ApiKey |
La clave de API del recurso de servicios de Azure AI que se usa para realizar un seguimiento de la información de facturación. El valor de esta opción se debe establecer en una clave de API para el recurso aprovisionado que se especifica en Billing. |
Billing |
El punto de conexión del recurso de servicios de Azure AI que se usa para realizar el seguimiento de la información de facturación. El valor de esta opción debe establecerse en el URI del punto de conexión de un recurso aprovisionado de Azure. |
Eula |
Indica que ha aceptado la licencia del contenedor. El valor de esta opción debe establecerse en accept. |
Para obtener más información acerca de estas opciones, consulte Configure containers (Configuración de contenedores).
Resumen
En este artículo, ha aprendido los conceptos y el flujo de trabajo para descargar, instalar y ejecutar contenedores de resumen. En resumen:
- El resumen proporciona contenedores Linux para Docker
- Las imágenes del contenedor se descargan desde Microsoft Container Registry (MCR).
- Las imágenes de contenedor se ejecutan en Docker.
- Debe especificar la información de facturación al crear una instancia de un contenedor.
Importante
Este contenedor no tiene licencia para ejecutarse sin estar conectado a Azure para realizar mediciones. Los clientes tienen que habilitar los contenedores para comunicar la información de facturación con el servicio de medición en todo momento. Los contenedores de Azure AI no envían datos de los clientes (por ejemplo, el texto que se está analizando) a Microsoft.
Pasos siguientes
- Para ver las opciones de configuración, consulte Configuración de contenedores.