Configure Form Recognizer containers

Important

  • The limit for Form Recognizer container users has been reached. We are not currently accepting new applications for the Form Recognizer container.
  • The Form Recognizer containers currently use version 1.0 of the Form Recognizer API. You can access the latest version of the API by using the managed service instead.

By using Azure Form Recognizer containers, you can build an application architecture that's optimized to take advantage of both robust cloud capabilities and edge locality.

You configure the Form Recognizer container run-time environment by using the docker run command arguments. This container has several required settings and a few optional settings. For a few examples, see the "Example docker run commands" section. The container-specific settings are the billing settings.

Configuration settings

The container has the following configuration settings:

Required Setting Purpose
Yes ApiKey Tracks billing information.
No ApplicationInsights Enables adding Azure Application Insights telemetry support to your container.
Yes Billing Specifies the endpoint URI of the service resource on Azure.
Yes Eula Indicates that you've accepted the license for the container.
No Fluentd Writes log and, optionally, metric data to a Fluentd server.
No HTTP Proxy Configures an HTTP proxy for making outbound requests.
No Logging Provides ASP.NET Core logging support for your container.
No Mounts Reads and writes data from the host computer to the container and from the container back to the host computer.

Important

The ApiKey, Billing, and Eula settings are used together. You must provide valid values for all three settings; otherwise, your container won't start. For more information about using these configuration settings to instantiate a container, see Billing.

ApiKey configuration setting

The ApiKey setting specifies the Azure resource key that's used to track billing information for the container. The value for the ApiKey must be a valid key for the Form Recognizer resource that's specified for Billing in the "Billing configuration setting" section.

You can find this setting in the Azure portal, in Form Recognizer Resource Management, under Keys.

ApplicationInsights setting

The ApplicationInsights setting allows you to add Azure Application Insights telemetry support to your container. Application Insights provides in-depth monitoring of your container. You can easily monitor your container for availability, performance, and usage. You can also quickly identify and diagnose errors in your container.

The following table describes the configuration settings supported under the ApplicationInsights section.

Required Name Data type Description
No InstrumentationKey String The instrumentation key of the Application Insights instance to which telemetry data for the container is sent. For more information, see Application Insights for ASP.NET Core.

Example:
InstrumentationKey=123456789

Billing configuration setting

The Billing setting specifies the endpoint URI of the Form Recognizer resource on Azure that's used to meter billing information for the container. The value for this configuration setting must be a valid endpoint URI for a Form Recognizer resource on Azure. The container reports usage about every 10 to 15 minutes.

You can find this setting in the Azure portal, in Form Recognizer Overview, under Endpoint.

Required Name Data type Description
Yes Billing String Billing endpoint URI. For more information on obtaining the billing URI, see gathering required parameters. For more information and a complete list of regional endpoints, see Custom subdomain names for Cognitive Services.

Eula setting

The Eula setting indicates that you've accepted the license for the container. You must specify a value for this configuration setting, and the value must be set to accept.

Required Name Data type Description
Yes Eula String License acceptance

Example:
Eula=accept

Cognitive Services containers are licensed under your agreement governing your use of Azure. If you do not have an existing agreement governing your use of Azure, you agree that your agreement governing use of Azure is the Microsoft Online Subscription Agreement, which incorporates the Online Services Terms. For previews, you also agree to the Supplemental Terms of Use for Microsoft Azure Previews. By using the container you agree to these terms.

Fluentd settings

Fluentd is an open-source data collector for unified logging. The Fluentd settings manage the container's connection to a Fluentd server. The container includes a Fluentd logging provider, which allows your container to write logs and, optionally, metric data to a Fluentd server.

The following table describes the configuration settings supported under the Fluentd section.

Name Data type Description
Host String The IP address or DNS host name of the Fluentd server.
Port Integer The port of the Fluentd server.
The default value is 24224.
HeartbeatMs Integer The heartbeat interval, in milliseconds. If no event traffic has been sent before this interval expires, a heartbeat is sent to the Fluentd server. The default value is 60000 milliseconds (1 minute).
SendBufferSize Integer The network buffer space, in bytes, allocated for send operations. The default value is 32768 bytes (32 kilobytes).
TlsConnectionEstablishmentTimeoutMs Integer The timeout, in milliseconds, to establish a SSL/TLS connection with the Fluentd server. The default value is 10000 milliseconds (10 seconds).
If UseTLS is set to false, this value is ignored.
UseTLS Boolean Indicates whether the container should use SSL/TLS for communicating with the Fluentd server. The default value is false.

HTTP proxy credentials settings

If you need to configure an HTTP proxy for making outbound requests, use these two arguments:

Name Data type Description
HTTPS_PROXY string The proxy to use, for example, https://proxy:8888
<proxy-url>
HTTPS_PROXY_CREDS string Any credentials needed to authenticate against the proxy, for example, username:password.
<proxy-user> string The user for the proxy.
<proxy-password> string The password associated with <proxy-user> for the proxy.
docker run --rm -it -p 5000:5000 \
--memory 2g --cpus 1 \
--mount type=bind,src=/home/azureuser/output,target=/output \
<registry-location>/<image-name> \
Eula=accept \
Billing=<endpoint> \
ApiKey=<api-key> \
HTTPS_PROXY=<proxy-url> \
HTTPS_PROXY_CREDS=<proxy-user>:<proxy-password> \

Logging settings

The Logging settings manage ASP.NET Core logging support for your container. You can use the same configuration settings and values for your container that you use for an ASP.NET Core application.

The following logging providers are supported by the container:

Provider Purpose
Console The ASP.NET Core Console logging provider. All of the ASP.NET Core configuration settings and default values for this logging provider are supported.
Debug The ASP.NET Core Debug logging provider. All of the ASP.NET Core configuration settings and default values for this logging provider are supported.
Disk The JSON logging provider. This logging provider writes log data to the output mount.

This container command stores logging information in the JSON format to the output mount:

docker run --rm -it -p 5000:5000 \
--memory 2g --cpus 1 \
--mount type=bind,src=/home/azureuser/output,target=/output \
<registry-location>/<image-name> \
Eula=accept \
Billing=<endpoint> \
ApiKey=<api-key> \
Logging:Disk:Format=json

This container command shows debugging information, prefixed with dbug, while the container is running:

docker run --rm -it -p 5000:5000 \
--memory 2g --cpus 1 \
<registry-location>/<image-name> \
Eula=accept \
Billing=<endpoint> \
ApiKey=<api-key> \
Logging:Console:LogLevel:Default=Debug

Disk logging

The Disk logging provider supports the following configuration settings:

Name Data type Description
Format String The output format for log files.
Note: This value must be set to json to enable the logging provider. If this value is specified without also specifying an output mount while instantiating a container, an error occurs.
MaxFileSize Integer The maximum size, in megabytes (MB), of a log file. When the size of the current log file meets or exceeds this value, a new log file is started by the logging provider. If -1 is specified, the size of the log file is limited only by the maximum file size, if any, for the output mount. The default value is 1.

For more information about configuring ASP.NET Core logging support, see Settings file configuration.

Mount settings

Use bind mounts to read and write data to and from the container. You can specify an input mount or an output mount by specifying the --mount option in the docker run command.

The Form Recognizer container requires an input mount and an output mount. The input mount can be read-only, and it's required for access to the data that's used for training and scoring. The output mount has to be writable, and you use it to store the models and temporary data.

The exact syntax of the host mount location varies depending on the host operating system. Additionally, the mount location of the host computer might not be accessible because of a conflict between the Docker service account permissions and the host mount location permissions.

Optional Name Data type Description
Required Input String The target of the input mount. The default value is /input.

Example:
--mount type=bind,src=c:\input,target=/input
Required Output String The target of the output mount. The default value is /output.

Example:
--mount type=bind,src=c:\output,target=/output

Example docker run commands

The following examples use the configuration settings to illustrate how to write and use docker run commands. When it's running, the container continues to run until you stop it.

  • Line-continuation character: The Docker commands in the following sections use a back slash (\) as a line continuation character. Replace or remove this character, depending on your host operating system's requirements.
  • Argument order: Don't change the order of the arguments unless you're familiar with Docker containers.

Replace {argument_name} in the following table with your own values:

Placeholder Value
{FORM_RECOGNIZER_API_KEY} The key that's used to start the container. It's available on the Azure portal Form Recognizer Keys page.
{FORM_RECOGNIZER_ENDPOINT_URI} The billing endpoint URI value is available on the Azure portal Form Recognizer Overview page.
{COMPUTER_VISION_API_KEY} The key is available on the Azure portal Computer Vision API Keys page.
{COMPUTER_VISION_ENDPOINT_URI} The billing endpoint. If you're using a cloud-based Computer Vision resource, the URI value is available on the Azure portal Computer Vision API Overview page. If you're using a cognitive-services-recognize-text container, use the billing endpoint URL that's passed to the container in the docker run command.

See gathering required parameters for details on how to obtain these values.

Note

New resources created after July 1, 2019, will use custom subdomain names. For more information and a complete list of regional endpoints, see Custom subdomain names for Cognitive Services.

Important

To run the container, specify the Eula, Billing, and ApiKey options; otherwise, the container won't start. For more information, see Billing.

Form Recognizer container Docker examples

The following Docker examples are for the Form Recognizer container.

Basic example for Form Recognizer

docker run --rm -it -p 5000:5000 --memory 8g --cpus 2 \
--mount type=bind,source=c:\input,target=/input  \
--mount type=bind,source=c:\output,target=/output \
containerpreview.azurecr.io/microsoft/cognitive-services-form-recognizer \
Eula=accept \
Billing={FORM_RECOGNIZER_ENDPOINT_URI} \
ApiKey={FORM_RECOGNIZER_API_KEY} \
FormRecognizer:ComputerVisionApiKey={COMPUTER_VISION_API_KEY} \
FormRecognizer:ComputerVisionEndpointUri={COMPUTER_VISION_ENDPOINT_URI}

Logging example for Form Recognizer

docker run --rm -it -p 5000:5000 --memory 8g --cpus 2 \
--mount type=bind,source=c:\input,target=/input  \
--mount type=bind,source=c:\output,target=/output \
containerpreview.azurecr.io/microsoft/cognitive-services-form-recognizer \
Eula=accept \
Billing={FORM_RECOGNIZER_ENDPOINT_URI} \
ApiKey={FORM_RECOGNIZER_API_KEY} \
FormRecognizer:ComputerVisionApiKey={COMPUTER_VISION_API_KEY} \
FormRecognizer:ComputerVisionEndpointUri={COMPUTER_VISION_ENDPOINT_URI}
Logging:Console:LogLevel:Default=Information

Next steps