Partekatu honen bidez:

Instalación y ejecución del contenedor de Traductor de Azure AI

  • Artikulua

Los contenedores le permiten alojar la API de Traductor de Azure AI en su propia infraestructura. La imagen de contenedor incluye todas las bibliotecas, herramientas y dependencias necesarias para ejecutar una aplicación de forma coherente en cualquier entorno informático privado, público o personal. Si los requisitos de seguridad o gobernanza de datos no se pueden cumplir llamando a la API de Traductor de Azure AI de forma remota, los contenedores son una buena opción.

En este artículo, aprenderá a instalar y ejecutar el contenedor de Traductor en línea con la API de Docker. El contenedor de Traductor de Azure AI admite las siguientes operaciones:

  • Traducción de texto. Traduzca el significado contextual de palabras o frases de source compatibles con idiomas de target en tiempo real. Para obtener más información, vea Contenedor: traducción de texto.

  • 🆕transliteración de texto. Convierta texto de un sistema de escritura o script de un idioma al sistema de escritura o script de otro idioma en tiempo real. Para obtener más información, vea Contenedor: transliteración de texto.

  • 🆕 Traducción de documentos. Traduzca documentos sincrónicamente mientras conserva la estructura y el formato en tiempo real. Para obtener más información, vea Contenedor: traducción de documentos.

Requisitos previos

Para empezar, necesita los siguientes recursos, aprobación de acceso controlado y herramientas:

Recursos de Azure

  • Una suscripción a Azure activa. En caso de no tener ninguna, puede crear una cuenta gratuita de 12 meses.

  • Una solicitud de acceso aprobada a un contenedor conectado de Traductor o un contenedor desconectado de Traductor.

  • Un recursos de Traductor de Azure AI (no un recurso de servicios de Azure AI de varios servicios) creado bajo el identificador de suscripción aprobado. Necesita la clave de API y el URI del punto de conexión asociados al recurso. Ambos valores son necesarios para iniciar el contenedor y se pueden encontrar en la página de información general del recurso en Azure Portal.

    • Para los contenedores conectados de Traductor, seleccione el plan de tarifa S1.

      Captura de pantalla de la selección del plan de tarifa para el contenedor conectado de Translator

    • Para los contenedores desconectados de Traductor, seleccione Commitment tier disconnected containers como plan de tarifa. Solo verá la opción de comprar un nivel de compromiso si se aprueba la solicitud de acceso a un contenedor desconectado.

      Captura de pantalla que muestra la creación de un recurso en Azure Portal.

Herramientas de Docker

Debe tener una comprensión básica de conceptos de Docker, como los registros, los repositorios, los contenedores y las imágenes de contenedor, así como conocimientos de terminología y comandos básicos de docker. Para conocer los principios básicos de Docker y de los contenedores, consulte Introducción a Docker.

Sugerencia

Considere la posibilidad de agregar Docker Desktop a su entorno informático. Docker Desktop es una interfaz gráfica de usuario (GUI) que permite compilar, ejecutar y compartir aplicaciones en contenedores directamente desde el escritorio.

DockerDesktop incluye el motor de Docker, el cliente de la CLI de Docker y Docker Compose, y proporciona paquetes que configuran Docker para su sistema operativo preferido:

Herramienta Descripción Condición
Motor de Docker El motor de Docker es el componente principal de la plataforma de contenedorización de Docker. Debe instalarse en un equipo host para permitirle compilar, ejecutar y administrar los contenedores. Obligatorio para todas las operaciones.
Docker Compose La herramienta Docker Compose se usa para definir y ejecutar aplicaciones de varios contenedores. Obligatorio para los contenedores auxiliares.
CLI de Docker La interfaz de la línea de comandos de Docker permite interactuar con el motor de Docker y administrar contenedores de Docker directamente desde la máquina local. Recomendado
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 uno de estos servicios de hospedaje de Docker incluido en Azure:

Sistema operativo Requisitos del sistema
Windows • Windows 10 o Windows 11 instalado
• Un procesador de 64 bits
• Un mínimo de 4 GB de RAM
• Características de Hyper-V y contenedor de Windows y virtualización de hardware de nivel de BIOS
• Para obtener más información, consulte Instalación de Docker Desktop en Windows.
Mac • Modelo de equipo de 2010 o posterior
• Sistema operativo 10.13 o posterior
• Un mínimo de 4 GB de RAM
• Para obtener más información, consulte Instalación de Docker Desktop en Mac.
Linux • Versión de 64 bits de Ubuntu (versión LTS [soporte a largo plazo] más reciente o versión actual no LTS), Debian 12, Fedora 38 o Fedora 39
• Compatibilidad de CPU con la virtualización
• Un mínimo de 4 GB de RAM
• Para obtener más información, consulte Instalación de Docker Desktop en Linux.

Nota:

Las especificaciones mínima y recomendada se basan en los límites de Docker, no en los recursos del equipo host.

En la tabla siguiente se describen las especificaciones mínimas y recomendadas y las transacciones permitidas por segundo (TPS) para cada contenedor.

Función Mínimo recomendado Notas
Traducción de texto 4 núcleos, 4 GB de memoria
Transliteración de texto 4 Núcleos, 2 GB de memoria
Traducción de documentos 4 núcleos, 6 GB de memoria El número de documentos que se pueden procesar simultáneamente se puede calcular con la fórmula siguiente: [mínimo de (n-2), (m-6)/4)].
• n es el número de núcleos de CPU.
• m son los GB de memoria.
• Ejemplo: 8 núcleos, memoria de 32 GB puede procesar seis (6) documentos simultáneos [mínimo de (8-2), (36-6)/4)].

  • Cada núcleo debe ser de 2,6 gigahercios (GHz) como mínimo.

  • Para cada par de idiomas, se recomiendan 2 GB de memoria.

  • Además de los requisitos de línea base, 4 GB de memoria para cada procesamiento simultáneo de documentos.

    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>

Entrada necesaria

Todos los contenedores de Azure AI requieren los siguientes valores de entrada:

  • Valor de aceptación de los términos de licencia. Debe tener un contrato de licencia para el usuario final (CLUF) establecido con un valor de Eula=accept.

  • Clave de API y Dirección URL de punto de conexión. La clave de API se usa para iniciar el contenedor. Para recuperar los valores de clave de API y dirección URL de punto de conexión, vaya a la página Claves y punto de conexión del recurso de Traductor de Azure AI y seleccione el icono Copy to clipboard.

  • Si va a traducir documentos, asegúrese de usar el punto de conexión de traducción de documentos.

Importante

  • Las claves se usan para acceder al recurso de Azure AI. No comparta las claves. Almacénelas de forma segura, por ejemplo, con Azure Key Vault.

  • También se recomienda regenerar estas claves periódicamente. Solo se necesita una clave para realizar una llamada API. Al volver a generar la primera clave, puede usar la segunda clave para seguir teniendo acceso al servicio.

Facturación

  • Las consultas en el contenedor se facturan con el plan de tarifa del recurso de Azure que se usa para la API Key.

  • Se le factura por cada instancia de contenedor que se utilice para procesar los documentos e imágenes.

  • El comando docker run descarga una imagen del Registro de artefactos de Microsoft e inicia el contenedor cuando las tres opciones siguientes se proporcionan con valores válidos:

Opción Descripción
ApiKey La clave 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 debe establecerse en una clave del recurso aprovisionado especificado 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.

Conexión con Azure

  • Los valores del argumento de facturación del contenedor permiten al contenedor conectarse al punto de conexión de facturación y ejecutarse.

  • 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 una 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 Azure AI para obtener un ejemplo de la información que se envía a Microsoft para la facturación.

Imágenes y etiquetas de contenedor

Las imágenes de contenedor de servicios de Azure AI se pueden encontrar en el catálogo del Registro de artefactos Microsoft. El contenedor de Traductor de Azure AI reside en el repositorio azure-cognitive-services/translator y se denomina text-translation. El nombre completo de la imagen de contenedor es mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest.

Para usar la versión más reciente del contenedor, use la etiqueta más reciente. Puede ver la lista completa de etiquetas de versión de traducción de texto de servicios de Azure AI en MCR.

Uso de contenedores

Seleccione una pestaña para elegir el entorno de contenedor de Traductor de Azure AI:

Los contenedores de Traductor de Azure AI permiten ejecutar el servicio Traductor de Azure AI on-premise en un entorno propio. Los contenedores conectados se ejecutan localmente y envían información de uso a la nube para la facturación.

Descarga y ejecución de la imagen de contenedor

El comando docker run descarga una imagen del Registro de artefactos de Microsoft e inicia el contenedor.

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 y ApiKey deben estar especificadas; de lo contrario, el contenedor no se iniciará.
  • Si va a traducir documentos, asegúrese de usar el punto de conexión de traducción de documentos.
docker run --rm -it -p 5000:5000 --memory 12g --cpus 4 \
-v /mnt/d/TranslatorContainer:/usr/local/models \
-e apikey={API_KEY} \
-e eula=accept \
-e billing={ENDPOINT_URI} \
-e Languages=en,fr,es,ar,ru  \
mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

El comando de Docker:

  • Crea y ejecuta un contenedor de Traductor a partir de una imagen de contenedor descargada.
  • Asigna 12 gigabytes (GB) de memoria y cuatro núcleos de CPU.
  • Expone el puerto de protocolo de control de transmisión (TCP) 5000 y asigna un seudo-TTY para el contenedor. Ahora, la dirección localhost apunta al propio contenedor, no al equipo host.
  • Acepta el contrato de usuario final (CLUF).
  • Configura el punto de conexión de facturación.
  • Descarga modelos de traducción para los idiomas inglés, francés, español, árabe y ruso.
  • Una vez que se produce la salida, quita automáticamente el contenedor. La imagen del contenedor sigue estando disponible en el equipo host.

Sugerencia

Comando de Docker adicional:

  • docker ps enumera los contenedores en ejecución.
  • docker pause {your-container name} pone en pausa un contenedor en ejecución.
  • docker unpause {your-container-name} reactiva un contenedor en pausa.
  • docker restart {your-container-name} reinicia un contenedor en ejecución.
  • docker exec permite ejecutar comandos para desasociar o establecer variables de entorno en un contenedor en ejecución.

Para obtener más información, consulte Referencia de la CLI de Docker.

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 Azure AI diferente ejecutándose en el HOST juntos. También puede tener varios contenedores del mismo contenedor Azure AI en ejecución.

Consulta del punto de conexión del contenedor de Traductor

El contenedor proporciona una API de punto de conexión de Translator basada en REST. Esta es una solicitud de ejemplo con el idioma de origen (from=en) especificado:

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

Nota:

  • La detección de idioma de origen requiere un contenedor adicional. Para obtener más información, consulte Contenedores auxiliares

  • Si la solicitud POST de cURL devuelve una respuesta Service is temporarily unavailable, el contenedor no está listo. Espere unos minutos y vuelva a intentarlo.

Comprobación de que un contenedor está en ejecución

Hay varias maneras de comprobar que el contenedor se está ejecutando:

  • El contenedor proporciona una página principal en / como validación visual de que se está ejecutando.

  • Puede abrir el explorador web que prefiera e ir a la dirección IP externa y el puerto expuesto del contenedor en cuestión. Use las siguientes URLs de petición para validar que el contenedor está ejecutándose. Las URL de solicitud de ejemplo indicadas apuntan ahttp://localhost:5000, pero su contenedor específico puede variar. Tenga en cuenta que va a ir a la dirección IP externa y al puerto expuesto del contenedor.

URL de la solicitud Propósito
http://localhost:5000/ El contenedor proporciona una página principal.
http://localhost:5000/ready Solicitado con GET. Proporciona una comprobación de que el contenedor está listo para aceptar una consulta en el modelo. Esta solicitud se puede usar con los sondeos de ejecución y preparación de Kubernetes.
http://localhost:5000/status Solicitado con GET. Comprueba si la clave de API usada para iniciar el contenedor es válida 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. Después de que la consulta devuelve resultados, se proporciona un ejemplo del comando CURL para mostrar los encabezados HTTP y el formato de cuerpo requeridos.

Captura de pantalla de la página de inicio de un contenedor.

Si tiene problemas al ejecutar un contenedor de servicios de Azure AI, puede intentar usar el contenedor de diagnósticos de Microsoft. Utilice este contenedor para diagnosticar errores comunes en su entorno de implementación que podrían impedir que los contenedores de Azure AI funcionen como se espera.

Para obtener el contenedor, use el comando docker pull siguiente:

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

A continuación, ejecute el contenedor. Reemplace {ENDPOINT_URI} por el punto de conexión y {API_KEY} por la clave del recurso:

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

El contenedor prueba la conectividad de red con el punto de conexión de facturación.

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.

Casos de uso para contenedores auxiliares

Algunas consultas de Traductor requieren que los contenedores auxiliares completen correctamente las operaciones. Si usa documentos de Office y no requiere detección de idioma de origen, solo se requiere el contenedor de Traductor. Sin embargo, si se requiere la detección de idioma de origen o se usan documentos PDF escaneados, se requieren contenedores auxiliares:

En la tabla siguiente se enumeran los contenedores auxiliares necesarios para las operaciones de traducción de texto y documentos. El contenedor de Traductor envía información de facturación a Azure mediante un recurso de Traductor de Azure AI de la cuenta de Azure.

Operación Consulta de solicitud Tipo de documento Contenedores auxiliares
• Traducción de texto
• Traducción de documentos		 from especificado. Documentos de Office None
• Traducción de texto
• Traducción de documentos		 from no especificado. Requiere detección de idioma automática para determinar el idioma de origen. Documentos de Office ✔️ Contenedor de Text Analytics: idioma
• Traducción de texto
• Traducción de documentos		 from especificado. Documentos PDF escaneados ✔️ Contenedor de Vision: lectura
• Traducción de texto
• Traducción de documentos		 from no especificado que requiera detección automática de idioma para determinar el idioma de origen. Documentos PDF escaneados ✔️ Contenedor de Text Analytics: idioma

✔️ Contenedor de Vision: lectura

Funcionamiento de contenedores auxiliares con docker compose

Docker Compose es una herramienta que permite configurar aplicaciones de varios contenedores mediante un único archivo YAML denominado normalmente compose.yaml. Use el comando docker compose up para iniciar la aplicación de contenedor y el comando docker compose down para detener y quitar los contenedores.

Si ha instalado la CLI de Docker Desktop, incluye Docker Compose y sus requisitos previos. Si no tiene Docker Desktop, consulte la Introducción a la instalación de Docker Compose.

Creación de una aplicación

  1. Utilice el editor o IDE que prefiera para crear un directorio para la aplicación denominado container-environment o asígnele un nombre.

  2. Cree un nuevo archivo YAML denominado compose.yaml. Las extensiones .yml o .yaml se pueden usar para el archivo compose.

  3. Copie y pegue el siguiente ejemplo de código YAML en el archivo compose.yaml. Reemplace {TRANSLATOR_KEY} y {TRANSLATOR_ENDPOINT_URI} por los valores de clave y punto de conexión de la instancia de Traductor de Azure Portal. Si va a traducir documentos, asegúrese de usar document translation endpoint.

  4. El nombre de nivel superior (azure-ai-translator, azure-ai-language, azure-ai-read) es el parámetro que especifique.

  5. container_name es un parámetro opcional que establece un nombre para el contenedor cuando se ejecuta, en lugar de permitir que docker compose genere un nombre.

    services:
  azure-ai-translator:
    container_name: azure-ai-translator
    image: mcr.microsoft.com/azure-cognitive-services/translator/text-translation::latest
    environment:
        - EULA=accept
        - billing={TRANSLATOR_ENDPOINT_URI}
        - apiKey={TRANSLATOR_KEY}
        - ladurl=http://azure-ai-language:5000
        - VISIONURL=http://azure-ai-read:5000
    ports:
          - "5000:5000"
    volumes:
          - {your local folder}:/usr/local/models
    azure-ai-language:
      container_name: azure-ai-language
      image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
      environment:
          - EULA=accept
          - billing={LANGUAGE_RESOURCE_ENDPOINT_URI}
          - apiKey={LANGUAGE_RESOURCE_KEY}
          - Languages=en,es
          - LADINCLUSTER=true 
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={COMPUTER_VISION_ENDPOINT_URI}
          - apiKey={COMPUTER_VISION_KEY}

  6. Abra un terminal, vaya a la carpeta container-environment e inicie los contenedores con el siguiente comando docker-compose:

    docker compose up

  7. Para detener los contenedores, use el comando siguiente:

    docker compose down

    Sugerencia

    Comandos útiles de Docker:

    • docker compose pause pone en pausa los contenedores en ejecución.
    • docker compose unpause {your-container-name} reactiva los contenedores en pausa.
    • docker compose restart reinicia todo el contenedor detenido y en ejecución con todos sus cambios anteriores intactos. Si realiza cambios en la configuración de compose.yaml, estos cambios no se actualizan con el comando docker compose restart. Debe usar el comando docker compose up para reflejar las actualizaciones y los cambios en el archivo compose.yaml.
    • docker compose ps -a enumera todos los contenedores, incluidos los que están detenidos.
    • docker compose exec permite ejecutar comandos para desasociar o establecer variables de entorno en un contenedor en ejecución.

    Para obtener más información, consulte Referencia de la CLI de Docker.

Traductor y etiquetas e imágenes de contenedor auxiliar

Las imágenes de contenedor de servicios de Azure AI se pueden encontrar en el catálogo del Registro de artefactos Microsoft. En la tabla siguiente se muestra la ubicación de la imagen completa para la traducción de texto y documentos:

Contenedor Ubicación de las imágenes Notas
Traductor: traducción de texto y documentos mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest Puede ver la lista completa de etiquetas de versión de traducción de texto de servicios de Azure AI en MCR.
Text Analytics: idioma mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest Puede ver la lista completa de etiquetas de versión de idioma de Text Analytics de servicios de Azure AI en MCR.
Vision: lectura mcr.microsoft.com/azure-cognitive-services/vision/read:latest Puede ver la lista completa de etiquetas de versión de lectura de Computer Vision de servicios de Azure AIOCR en MCR.

Otros parámetros y comandos

Estos son algunos parámetros y comandos más que puede usar para ejecutar el contenedor:

Registros de uso

Cuando los contenedores de Docker se operan en un entorno sin conexión, el contenedor escribirá los registros de uso en un volumen en el que se recopilan a lo largo del tiempo. También puede llamar a un punto de conexión de API de REST para generar un informe sobre la utilización del servicio.

Argumentos para almacenar registros

Cuando se ejecuta en un entorno desconectado, debe estar disponible un montaje de salida en el contenedor para almacenar los registros de uso. Por ejemplo, podría incluir -v /host/output:{OUTPUT_PATH} y Mounts:Output={OUTPUT_PATH} en el ejemplo siguiente, y reemplazar {OUTPUT_PATH} por la ruta de acceso donde se almacenan los registros:

ejemplo de comando docker run

docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}

Nombres de variables de entorno en las implementaciones de Kubernetes

  • Algunos contenedores de Azure AI, por ejemplo Traductor, requieren que los usuarios pasen nombres de variables de entorno que incluyan dos puntos (:) al ejecutar el contenedor.

  • Kubernetes no acepta dos puntos en los nombres de variables de entorno. Para resolverlo, puede reemplazar dos puntos por dos caracteres de subrayado (__) al implementar en Kubernetes. Consulte el ejemplo siguiente de un formato aceptable para los nombres de variables de entorno:

        env:
        - name: Mounts__License
          value: "/license"
        - name: Mounts__Output
          value: "/output"

Este ejemplo reemplaza el formato predeterminado para los nombres de las variables de entorno Mounts:License y Mounts:Output en el comando docker run.

Obtención de registros de uso mediante los puntos de conexión del contenedor

El contenedor proporciona dos puntos de conexión para devolver registros sobre su uso.

Obtención de todos los registros

El siguiente punto de conexión proporciona un informe que resume todo el uso recopilado en el directorio de registros de facturación montado.

https://<service>/records/usage-logs/

Punto de conexión HTTPS de ejemplo para recuperar todos los registros

http://localhost:5000/records/usage-logs

Obtención de registros de un mes concreto

El siguiente punto de conexión proporciona un informe que resume el uso durante un mes y año específicos:

https://<service>/records/usage-logs/{MONTH}/{YEAR}

Punto de conexión HTTPS de ejemplo para recuperar registros de un mes y año específicos

http://localhost:5000/records/usage-logs/03/2024

El punto de conexión por registros de uso devuelve una respuesta JSON similar al ejemplo siguiente:

Contenedor conectado

Los cargos por utilización se calculan en función del valor de quantity.

{
  "apiType": "string",
"serviceName": "string",
"meters": [
  {
    "name": "string",
    "quantity": 256345435
    }
  ]
}

Resumen

En este artículo ha conocido conceptos y flujos de trabajo para la descarga, instalación y ejecución de contenedores de Traductor de Azure AI:

  • El contenedor de Traductor de Azure AI admite la traducción de texto, la traducción sincrónica de documentos y la transliteración de texto.

  • Las imágenes de contenedor se descargan desde el registro de contenedor y se ejecutan en Docker.

  • La información de facturación debe especificarse al crear una instancia de contenedor.

Pasos siguientes

Más información sobre la configuración de contenedores de Azure AI Más información sobre la compatibilidad con idiomas de los contenedores