Contenedores en entornos desconectados (sin conexión)

Este contenido se aplica a: v3.0 (GA) v3.1 (GA)

¿Qué son los contenedores desconectados?

Los contenedores de Azure AI ofrecen la flexibilidad de ejecutar algunos servicios de Documento de inteligencia localmente en contenedores. Los contenedores conectados se ejecutan localmente en el entorno y envían información de uso a la nube para la facturación. Los contenedores desconectados están diseñados para escenarios en los que no se necesita conectividad con la nube para que se ejecuten los contenedores.

Los contenedores de Documento de inteligencia de Azure AI permiten usar las API de Documento de inteligencia con las ventajas de la contenedorización. Se ofrecen contenedores desconectados mediante precios del nivel de compromiso, con una tarifa con descuento en comparación con los precios de pago por uso. Con los precios del nivel de compromiso puede confirmar el uso de las características de Documento de inteligencia con una tarifa fija, con un costo total predecible, en función de las necesidades de la carga de trabajo.

Introducción

Antes de intentar ejecutar un contenedor Docker en un entorno sin conexión, asegúrese que le son familiares los siguientes requisitos para descargar y usar correctamente el contenedor:

• Recomendaciones y requisitos del equipo host.
• El comando pull de Docker para descargar el contenedor.
• Validación de que un contenedor está en ejecución.
• Envío de consultas al punto de conexión del contenedor, una vez que se está ejecutando.

Solicitud de acceso para usar contenedores en entornos desconectados

Para poder usar contenedores de Documento de inteligencia en entornos desconectados, primero debe rellenar y enviar un formulario de solicitud y comprar un plan de compromiso.

Crear un nuevo recurso en Azure Portal

Empiece por aprovisionar un nuevo recurso en el portal.

• Asegúrese de seleccionar la opción Commitment tier disconnected containers DC0 del plan de tarifa

• Seleccione el plan de tarifa adecuado de al menos uno de los niveles de compromiso personalizados, leídos o creados previamente.

  

Contenedor	Mínima	Recomendado	Plan de compromiso
Read	8 núcleos, 10 GB de memoria	8 núcleos, 24 GB de memoria	OCR (Leer)
Layout	8 núcleos, 16 GB de memoria	8 núcleos, 24 GB de memoria	Creada previamente
Business Card	8 núcleos, 16 GB de memoria	8 núcleos, 24 GB de memoria	Creada previamente
General Document	8 núcleos, 12 GB de memoria	8 núcleos, 24 GB de memoria	Creada previamente
ID Document	8 núcleos, 8 GB de memoria	8 núcleos, 24 GB de memoria	Creada previamente
Invoice	8 núcleos, 16 GB de memoria	8 núcleos, 24 GB de memoria	Creada previamente
Receipt	8 núcleos, 11 GB de memoria	8 núcleos, 24 GB de memoria	Creada previamente
Custom Template	8 núcleos, 16 GB de memoria	8 núcleos, 24 GB de memoria	API personalizado

Recopilación de todos los parámetros obligatorios

Se requieren tres parámetros para todos los contenedores de servicios de Azure AI:

• El contrato de licencia para el usuario final (CLUF) se debe haber aceptado.
• La dirección URL del punto de conexión para el recurso desde el Azure Portal.
• La clave de API para el recurso desde el Azure Portal.

La primera vez que se ejecuta el contenedor se necesitan la dirección URL del punto de conexión y la clave de API, con el fin de configurarlo para que se pueda usar sin conexión. Tanto la clave como el punto de conexión se pueden encontrar en la página Clave y punto de conexión para el recurso en el Azure Portal:

Importante

La clave y el punto de conexión solo se usarán para configurar el contenedor para que se ejecute en un entorno desconectado. Después de configurar el contenedor no los necesitará para enviar solicitudes de API. Almacénelas de forma segura, por ejemplo, con Azure Key Vault. Solo se necesita una clave para este proceso.

Descarga de un contenedor de Docker con docker pull

Descargue el contenedor Docker aprobado para ejecutarse en un entorno desconectado. Por ejemplo:

Comando docker pull	Value	Formato
● ● ● docker pull [image] docker pull [image]latest	La imagen de contenedor más reciente.	● ● ● mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice-3.0:latest

ejemplo de comando docker pull

docker pull mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice:latest

Configuración del contenedor para que se ejecute en un entorno desconectado

Las imágenes de contenedor desconectados son las mismas que los contenedores conectados. La diferencia clave es que los contenedores desconectados requieren un archivo de licencia. Este archivo de licencia se descarga iniciando el contenedor en un modo conectado con el parámetro downloadLicense establecido en true.

Ahora que el contenedor se ha descargado, debe ejecutar el comando docker run con el siguiente parámetro:

• DownloadLicense=True. Este parámetro descarga un archivo de licencia que permite que el contenedor de Docker se ejecute sin tener conexión a Internet. También contiene una fecha de expiración, tras la cual el archivo de licencia no es válido para ejecutar el contenedor. Solo puede usar el archivo de licencia en el contenedor aprobado correspondiente.

Importante

El comando docker run generará una plantilla que puede usar para ejecutar el contenedor. La plantilla contiene parámetros que necesitará para los modelos descargados y el archivo de configuración. Asegúrese de guardar esta plantilla.

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.

Marcador de posición	Value	Formato o ejemplo
{IMAGE}	Imagen de contenedor que desea usar.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{LICENSE_MOUNT}	La ruta de acceso donde se descarga y monta la licencia.	/host/license:/path/to/license/directory
{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 Documento de inteligencia. Puede encontrarla en la página Clave y punto de conexión del recurso en Azure Portal.	{string}
{CONTAINER_LICENSE_DIRECTORY}	Ubicación de la carpeta de licencias en el sistema de archivos local del contenedor.	/path/to/license/directory

ejemplo de comando docker run

docker run --rm -it -p 5000:5050 \

-v {LICENSE_MOUNT} \

{IMAGE} \

eula=accept \

billing={ENDPOINT_URI} \

apikey={API_KEY} \

DownloadLicense=True \

Mounts:License={CONTAINER_LICENSE_DIRECTORY}

En el siguiente comando, reemplace los marcadores de posición de la ruta de acceso de la carpeta, el punto de conexión de facturación y la clave de API para descargar un archivo de licencia para el contenedor de diseño.

docker run -v {folder path}:/license --env Mounts:License=/license --env DownloadLicense=True --env Eula=accept --env Billing={billing endpoint} --env ApiKey={api key} mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest

Una vez configurado el contenedor, use la siguiente sección para ejecutar el contenedor en su entorno con la licencia y las asignaciones de memoria y CPU adecuadas.

Configuración y modelos de contenedor de Documento de inteligencia

Después de configurar el contenedor, los valores de los modelos de Documento de inteligencia descargados y la configuración del contenedor se generarán y mostrarán en la salida del contenedor.

Ejecución del contenedor en un entorno sin conexión

Una vez haya descargado el archivo de licencia, puede ejecutar el contenedor en un entorno desconectado con la licencia, la memoria adecuada y las asignaciones de CPU adecuadas. En el ejemplo siguiente se muestra el formato del comando docker run con valores de marcador de posición. Reemplace estos valores por los suyos.

Cada vez que se ejecute el contenedor, el archivo de licencia debe estar montado 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=. Además, se debe especificar un montaje de salida para que se puedan escribir registros de utilización de facturación.

Marcador de posición	Value	Formato o ejemplo
{IMAGE}	Imagen de contenedor que desea usar.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{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}	La ruta de acceso donde se encuentra y se monta la licencia.	/host/license:/path/to/license/directory
{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

ejemplo de comando docker run

docker run --rm -it -p 5000:5050 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \

-v {LICENSE_MOUNT} \

-v {OUTPUT_PATH} \

{IMAGE} \

eula=accept \

Mounts:License={CONTAINER_LICENSE_DIRECTORY}

Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

Iniciar un contenedor desconectado es similar a iniciar un contenedor conectado. Los contenedores desconectados requieren un parámetro de licencia agregado. Este es un archivo docker-compose.yml de ejemplo para iniciar un contenedor personalizado en modo desconectado. Agregue la variable de entorno CUSTOM_LICENSE_MOUNT_PATH con un valor establecido en la carpeta que contiene el archivo de licencia descargado, y la variable de entorno OUTPUT_MOUNT_PATH con un valor establecido en la carpeta que contiene los registros de uso.

version: '3.3'
services:
 nginx:
  image: nginx:alpine
  container_name: reverseproxy
  volumes:
    - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
  ports:
    - "5000:5050"
 layout:
  container_name: azure-cognitive-service-layout
  image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest
  environment:
    eula: accept
    apikey: ${FORM_RECOGNIZER_KEY}
    billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
    Logging:Console:LogLevel:Default: Information
    SharedRootFolder: /shared
    Mounts:Shared: /shared
    Mounts:Output: /logs
    Mounts:License: /license
  volumes:
    - type: bind
      source: ${SHARED_MOUNT_PATH}
      target: /shared
    - type: bind
      source: ${OUTPUT_MOUNT_PATH}
      target: /logs
    - type: bind
      source: ${LAYOUT_LICENSE_MOUNT_PATH}
      target: /license
  expose:
    - "5000"

 custom-template:
  container_name: azure-cognitive-service-custom-template
  image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.0:latest
  restart: always
  depends_on:
    - layout
  environment:
    AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
    eula: accept
    apikey: ${FORM_RECOGNIZER_KEY}
    billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
    Logging:Console:LogLevel:Default: Information
    SharedRootFolder: /shared
    Mounts:Shared: /shared
    Mounts:Output: /logs
    Mounts:License: /license
  volumes:
    - type: bind
      source: ${SHARED_MOUNT_PATH}
      target: /shared
    - type: bind
      source: ${OUTPUT_MOUNT_PATH}
      target: /logs
    - type: bind
      source: ${CUSTOM_LICENSE_MOUNT_PATH}
      target: /license
  expose:
    - "5000"

 studio:
  container_name: form-recognizer-studio
  image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.0
  environment:
    ONPREM_LOCALFILE_BASEPATH: /onprem_folder
    STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
  volumes:
    - type: bind
      source: ${FILE_MOUNT_PATH} # path to your local folder
      target: /onprem_folder
    - type: bind
      source: ${DB_MOUNT_PATH} # path to your local folder
      target: /onprem_db
  ports:
    - "5001:5001"
  user: "1000:1000" # echo $(id -u):$(id -g)

Otros parámetros y comandos

Estos son algunos parámetros y comandos más que debe 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:

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

Obtención de registros 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

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

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

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

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}

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

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

Solución de problemas

Ejecute el contenedor con un montaje de salida y un registro habilitados. Esta configuración habilita al contenedor para generar archivos de registro que son útiles para solucionar problemas que se producen al iniciar o ejecutar el contenedor.

Sugerencia

Para más información e instrucciones para la solución de problemas, consulte Preguntas frecuentes sobre los contenedores sin conexión.

Pasos siguientes

• Implementar la herramienta de etiquetado de ejemplo en una instancia de Azure Container Instances (ACI)
• Cambio o finalización de un plan de compromiso