Compartir a través de

Instalación del contenedor OCR de Lectura de Visión de Azure AI 3.2 de disponibilidad general

  • Artículo

Los contenedores le permiten ejecutar las API de Azure AI Vision en su propio entorno y pueden ayudarle a cumplir requisitos específicos de seguridad y gobernanza de datos. En este artículo aprenderá a descargar, instalar y ejecutar el contenedor de Azure AI Vision Read (OCR).

El contenedor Read permite extraer texto impreso y manuscrito de imágenes y documentos en formatos de archivo JPEG, PNG, BMP, PDF y TIFF. Para obtener más información sobre el servicio Read, consulte la Guía de procedimientos de Read API.

Novedades

La versión de disponibilidad general 3.2-model-2022-04-30 del contenedor de Read está disponible con compatibilidad con 164 idiomas y otras mejoras. Si es un cliente existente, siga las instrucciones de descarga para empezar.

El contenedor Read 3.2 de OCR es el modelo más reciente con disponibilidad general y proporciona:

  • Nuevos modelos para una mejor precisión.
  • Compatibilidad con varios idiomas en el mismo documento.
  • Compatibilidad con un total de 164 idiomas. Consulte la lista completa de idiomas admitidos por OCR.
  • Una única operación para documentos e imágenes.
  • Compatibilidad con imágenes y documentos de mayor tamaño.
  • Puntuaciones de confianza.
  • Compatibilidad con documentos con texto impreso y manuscrito.
  • Capacidad de extraer texto solo de páginas seleccionadas en un documento.
  • Elija el orden de salida de la línea de texto, desde un orden predeterminado a un orden de lectura más natural para los idiomas procedentes del latín.
  • Clasificación de línea de texto como estilo manuscrito o no solo para idiomas latinos.

Si actualmente usa el contenedor Read 2.0, consulte la guía de migración para obtener información sobre los cambios en las nuevas versiones.

Requisitos previos

Debe cumplir los siguientes requisitos previos para poder usar los contenedores:

Obligatorio Propósito
Motor de Docker Necesita que el motor de Docker esté instalado en un equipo host. Docker dispone de paquetes que configuran el entorno de Docker en macOS, Windows y Linux. Para conocer los principios básicos de Docker y de los contenedores, consulte Introducción a Docker.

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.
Conocimientos sobre 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.
Recurso de Computer Vision Para poder usar el contenedor, debe tener:

Un recurso de Computer Vision y la clave de API asociada con el URI del punto de conexión. Ambos valores están disponibles en las páginas de introducción y claves del recurso y son necesarios para iniciar el contenedor.

{API_KEY} : una de las dos claves de recurso disponibles en la página Claves

{ENDPOINT_URI} : el punto de conexión tal como se proporciona en la página de Información general.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

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.

Captura de pantalla que muestra la recopilación del URI de punto de conexión para su uso posterior.

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.

Captura de pantalla que muestra la obtención de una de las dos claves para su uso posterior.

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.

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:

Compatibilidad con la extensión avanzada de vector

El equipo host es el equipo que ejecuta el contenedor de Docker. El host debe ser compatible con las extensiones avanzadas de vector (AVX2). Puede comprobar la compatibilidad con AVX2 en los hosts de Linux con el comando siguiente:

grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected

Advertencia

El equipo host es necesario para admitir AVX2. El contenedor no funcionará correctamente sin compatibilidad con AVX2.

Recomendaciones y requisitos del contenedor

Nota

Los requisitos y las recomendaciones se basan en pruebas comparativas con una única solicitud por segundo, con una imagen de 523 kB de una carta comercial escaneada que contiene 29 líneas y 803 caracteres en total. La configuración recomendada dio como resultado una respuesta aproximadamente dos veces más rápida en comparación con la configuración mínima.

En la tabla siguiente se describe la asignación mínima y recomendada de recursos para cada contenedor OCR de Read.

Contenedor Mínima Recomendado
Read 3.2 2022-04-30 4 núcleos, 8 GB de memoria 8 núcleos, 16 GB de memoria
Read 3.2 2021-04-12 4 núcleos, 16 GB de memoria 8 núcleos, 24 GB de memoria
  • Cada núcleo debe ser de 2,6 gigahercios (GHz) como mínimo.

El núcleo y la memoria se corresponden con los valores de --cpus y --memory que se usan como parte del comando docker run.

Obtener la imagen de contenedor

La imagen de contenedor de Lectura OCR de Visión de Azure AI se puede encontrar en la distribución del registro de contenedor de mcr.microsoft.com. Reside en el repositorio azure-cognitive-services y se denomina read. El nombre completo de la imagen de contenedor es mcr.microsoft.com/azure-cognitive-services/vision/read.

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.

Las siguientes imágenes de contenedor están disponibles para lectura.

Contenedor Container Registry/Repositorio/Nombre de imagen Etiquetas
Disponibilidad general de Read 3.2 mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 latest, 3.2, 3.2-model-2022-04-30

Use el comando docker pull para descargar una imagen de contenedor.

docker pull mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

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>

Uso del contenedor

Una vez que el contenedor esté en el equipo host, utilice el siguiente proceso para trabajar con el contenedor.

  1. Ejecute el contenedor con la configuración de facturación requerida. Hay más ejemplos del comando docker run disponibles.
  2. Consulta del punto de conexión de predicción del contenedor.

Ejecución del contenedor

Utilice el comando docker run para ejecutar el contenedor. Consulte Recopilación de los parámetros obligatorios para más información sobre cómo obtener los valores de {ENDPOINT_URI} y {API_KEY}.

Hay disponibles ejemplos del comando docker run.

docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

El comando anterior:

  • Ejecuta el contenedor de disponibilidad general más reciente de OCR de Read desde la imagen de contenedor.
  • Asigna un núcleo de 8 CPU y 16 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.

También puede ejecutar el contenedor mediante variables de entorno:

docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
--env Eula=accept \
--env Billing={ENDPOINT_URI} \
--env ApiKey={API_KEY} \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

Hay más ejemplos del comando docker run disponibles.

Importante

Para poder ejecutar el contenedor, las opciones Eula, Billing y ApiKey deben estar especificadas; de lo contrario, el contenedor no se iniciará. Para obtener más información, vea Facturación.

Si usa Azure Storage para almacenar imágenes del procesamiento, puede crear una cadena de conexión que se use al llamar al contenedor.

Para buscar la cadena de conexión:

  1. Navegue a Cuentas de almacenamiento en Azure Portal y busque su cuenta.
  2. Seleccione Claves de acceso en la lista de navegación izquierda.
  3. La cadena de conexión se encontrará debajo de Cadena de conexión

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.

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.

Página principal del contenedor

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. Puede ver la ruta de acceso de Swagger en http://localhost:5000/swagger/.

Lectura asincrónica

Puede usar las operaciones POST /vision/v3.2/read/analyze y GET /vision/v3.2/read/operations/{operationId} conjuntamente para leer una imagen asincrónicamente, de manera similar a cómo el servicio Visión de Azure AI usa las operaciones de REST correspondientes. El método POST asincrónico devolverá un valor operationId que se usa como identificador de la solicitud HTTP GET.

En la interfaz de usuario de Swagger, seleccione Analyze para expandirlo en el explorador. A continuación, seleccione Probarlo>Elegir archivo. En este ejemplo, usaremos la imagen siguiente:

pestañas o espacios

Una vez ejecutado correctamente el método POST, devuelve un código de estado HTTP 202. Como parte de la respuesta, hay un encabezado operation-location que contiene el punto de conexión del resultado de la solicitud.

 content-length: 0
 date: Fri, 04 Sep 2020 16:23:01 GMT
 operation-location: http://localhost:5000/vision/v3.2/read/operations/a527d445-8a74-4482-8cb3-c98a65ec7ef9
 server: Kestrel

El elemento operation-location es la dirección URL completa y se obtiene acceso a ella a través de HTTP GET. Esta es la respuesta JSON a la ejecución de la dirección URL operation-location desde la imagen anterior:

{
  "status": "succeeded",
  "createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
  "lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
  "analyzeResult": {
    "version": "3.2.0",
    "readResults": [
      {
        "page": 1,
        "angle": 2.1243,
        "width": 502,
        "height": 252,
        "unit": "pixel",
        "lines": [
          {
            "boundingBox": [
              58,
              42,
              314,
              59,
              311,
              123,
              56,
              121
            ],
            "text": "Tabs vs",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.96
              }
            },
            "words": [
              {
                "boundingBox": [
                  68,
                  44,
                  225,
                  59,
                  224,
                  122,
                  66,
                  123
                ],
                "text": "Tabs",
                "confidence": 0.933
              },
              {
                "boundingBox": [
                  241,
                  61,
                  314,
                  72,
                  314,
                  123,
                  239,
                  122
                ],
                "text": "vs",
                "confidence": 0.977
              }
            ]
          },
          {
            "boundingBox": [
              286,
              171,
              415,
              165,
              417,
              197,
              287,
              201
            ],
            "text": "paces",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.746
              }
            },
            "words": [
              {
                "boundingBox": [
                  286,
                  179,
                  404,
                  166,
                  405,
                  198,
                  290,
                  201
                ],
                "text": "paces",
                "confidence": 0.938
              }
            ]
          }
        ]
      }
    ]
  }
}

Importante

Si implementa varios contenedores OCR de lectura detrás de un equilibrador de carga en, por ejemplo, Docker Compose o Kubernetes, debe tener una caché externa. Dado que el contenedor de procesamiento y el contenedor de la solicitud GET podrían no ser los mismos, una caché externa almacena los resultados y los comparte entre contenedores. Para más información sobre la configuración de caché, consulte Configuración de contenedores de Docker de Visión de Azure AI.

Lectura sincrónica

Puede usar la siguiente operación para leer sincrónicamente una imagen.

POST /vision/v3.2/read/syncAnalyze

Una vez leída la imagen en su totalidad, entonces, y solo entonces, devuelve la API una respuesta JSON. La única excepción a este comportamiento es un escenario de error. Cuando se produce un error, se devuelve el siguiente código JSON:

{
    "status": "Failed"
}

El objeto de respuesta JSON tiene el mismo gráfico de objetos que la versión asincrónica. Si es usuario de JavaScript y quiere seguridad de tipos, considere la posibilidad de usar TypeScript para convertir la respuesta JSON.

Para ver un caso de uso de ejemplo, consulte el espacio aislado de TypeScript aquí y seleccione Ejecutar para visualizar su facilidad de uso.

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 Inteligencia de Documentos.

Marcador Value Formato o ejemplo
{IMAGE} Imagen de contenedor que desea usar. mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{LICENSE_MOUNT} Ruta de acceso en que se descargará y montará 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 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} \
{IMAGE} \
eula=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/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} Ruta de acceso en la que se encontrará y montará 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 
docker run --rm -it -p 5000:5000 --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}

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.

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.

Facturación

Los contenedores de Azure AI envían información de facturación a Azure mediante el recurso correspondiente de la cuenta de 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 la descarga, la instalación y la ejecución de contenedores de Visión de Azure AI. En resumen:

  • Visión de Azure AI proporciona un contenedor de Linux para Docker que incluye Lectura.
  • Para ejecutar la imagen del contenedor de Read se necesita una aplicación.
  • Las imágenes de contenedor se ejecutan en Docker.
  • Puede usar la API de REST o el SDK para llamar a operaciones en contenedores de OCR de lectura mediante la especificación del URI del host del contenedor.
  • Debe especificar la información de facturación al crear una instancia de un contenedor.

Importante

Los contenedores de Azure AI no tienen licencia para ejecutarse sin estar conectados 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, la imagen o el texto que se está analizando) a Microsoft.

Pasos siguientes