Skip to content

Commit 92dd781

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #224332 from laujan/59400-move-disconnected-container-to-fr
move-disconnected-container-to-fr
2 parents 5668a28 + 96fb2cd commit 92dd781

File tree

3 files changed

+270
-0
lines changed

3 files changed

+270
-0
lines changed

‎articles/applied-ai-services/form-recognizer/containers/form-recognizer-disconnected-containers.md

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
---
2+
title: Use For containers in disconnected environments
3+
titleSuffix: Azure Applied AI Services
4+
description: Learn how to run Azure Cognitive Services Docker containers disconnected from the internet.
5+
ms.service: applied-ai-services
6+
ms.subservice: forms-recognizer
7+
author: laujan
8+
manager: nitinme
9+
ms.topic: reference
10+
ms.date: 01/18/2023
11+
ms.author: lajanuar
12+
---
13+
14+
# Use Form Recognizer containers in disconnected environments
15+
16+
<!-- markdownlint-disable MD036 -->
17+
<!-- markdownlint-disable MD001 -->
18+
19+
Azure Cognitive Services Form Recognizer containers allow you to use Form Recognizer APIs with the benefits of containerization. Disconnected containers are offered through commitment tier pricing offered at a discounted rate compared to pay-as-you-go pricing. With commitment tier pricing, you can commit to using Form Recognizer features for a fixed fee, at a predictable total cost, based on the needs of your workload.
20+
21+
## Get started
22+
23+
Before attempting to run a Docker container in an offline environment, make sure you're familiar with the following requirements to successfully download and use the container:
24+
25+
* Host computer requirements and recommendations.
26+
* The Docker `pull` command you'll use to download the container.
27+
* How to validate that a container is running.
28+
* How to send queries to the container's endpoint, once it's running.
29+
30+
## Request access to use containers in disconnected environments
31+
32+
Complete and submit the [request form](https://aka.ms/csdisconnectedcontainers) to request access to the containers disconnected from the Internet.
33+
34+
[!INCLUDE [Request access to public preview](../../../../includes/cognitive-services-containers-request-access.md)]
35+
36+
Access is limited to customers that meet the following requirements:
37+
38+
* Your organization should be identified as strategic customer or partner with Microsoft.
39+
* Disconnected containers are expected to run fully offline, hence your use cases must meet one of the following or similar requirements:
40+
* Environment or device(s) with zero connectivity to internet.
41+
* Remote location that occasionally has internet access.
42+
* Organization under strict regulation of not sending any kind of data back to cloud.
43+
* Application completed as instructed - Pay close attention to guidance provided throughout the application to ensure you provide all the necessary information required for approval.
44+
45+
## Create a new resource and purchase a commitment plan
46+
47+
1. Create a new [Form Recognizer resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer) in the Azure portal.
48+
49+
1. Enter the applicable information to create your resource. Be sure to select **Commitment tier disconnected containers** as your pricing tier.
50+
51+
> [!NOTE]
52+
>
53+
> * You will only see the option to purchase a commitment tier if you have been approved by Microsoft.
54+
55+
:::image type="content" source="../media/create-resource-offline-container.png" alt-text="A screenshot showing resource creation on the Azure portal.":::
56+
57+
1. Select **Review + Create** at the bottom of the page. Review the information, and select **Create**.
58+
59+
## Gather required parameters
60+
61+
There are three required parameters for all Cognitive Services' containers:
62+
63+
* The end-user license agreement (EULA) must be present with a value of *accept*.
64+
* The endpoint URL for your resource from the Azure portal.
65+
* The API key for your resource from the Azure portal.
66+
67+
Both the endpoint URL and API key are needed when you first run the container to configure it for disconnected usage. You can find the key and endpoint on the **Key and endpoint** page for your resource in the Azure portal:
68+
69+
:::image type="content" source="../media/containers/keys-and-endpoint.png" alt-text="Screenshot: Azure portal keys and endpoint page.":::
70+
71+
> [!IMPORTANT]
72+
> You will only use your key and endpoint to configure the container to run in a disconnected environment. After you configure the container, you won't need the key and endpoint values to send API requests. Store them securely, for example, using Azure Key Vault. Only one key is necessary for this process.
73+
74+
## Download a Docker container with `docker pull`
75+
76+
Download the Docker container that has been approved to run in a disconnected environment. For example:
77+
78+
|Docker pull command | Value |Format|
79+
|----------|-------|------|
80+
|&bullet; **`docker pull [image]`**</br>&bullet; **`docker pull [image]:latest`**|The latest container image.|&bullet; mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout</br> </br>&bullet; mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice: latest |
81+
|||
82+
|&bullet; **`docker pull [image]:[version]`** | A specific container image |dockers pull mcr.microsoft.com/azure-cognitive-services/form-recognizer/receipt:2.1-preview |
83+
84+
**Example Docker pull command**
85+
86+
```docker
87+
docker pull mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice:latest
88+
```
89+
90+
## Configure the container to be run in a disconnected environment
91+
92+
Now that you've downloaded your container, you'll need to execute the `docker run` command with the following parameter:
93+
94+
* **`DownloadLicense=True`**. This parameter will download a license file that will enable your Docker container to run when it isn't connected to the internet. It also contains an expiration date, after which the license file will be invalid to run the container. You can only use the license file in corresponding approved container.
95+
96+
> [!IMPORTANT]
97+
>The `docker run` command will generate a template that you can use to run the container. The template contains parameters you'll need for the downloaded models and configuration file. Make sure you save this template.
98+
99+
The following example shows the formatting for the `docker run` command you'll use, with placeholder values. Replace these placeholder values with your own values.
100+
101+
| Placeholder | Value | Format or example |
102+
|-------------|-------|---|
103+
| `{IMAGE}` | The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice` |
104+
| `{LICENSE_MOUNT}` | The path where the license will be downloaded, and mounted. | `/host/license:/path/to/license/directory` |
105+
| `{ENDPOINT_URI}` | The endpoint for authenticating your service request. You can find it on your resource's **Key and endpoint** page, on the Azure portal. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
106+
| `{API_KEY}` | The key for your Text Analytics resource. You can find it on your resource's **Key and endpoint** page, on the Azure portal. |`{string}`|
107+
| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |
108+
109+
**Example `docker run` command**
110+
111+
```docker
112+
113+
docker run --rm -it -p 5000:5000 \
114+
115+
-v {LICENSE_MOUNT} \
116+
117+
{IMAGE} \
118+
119+
eula=accept \
120+
121+
billing={ENDPOINT_URI} \
122+
123+
apikey={API_KEY} \
124+
125+
DownloadLicense=True \
126+
127+
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
128+
```
129+
130+
After you've configured the container, use the next section to run the container in your environment with the license, and appropriate memory and CPU allocations.
131+
132+
## Form Recognizer container models and configuration
133+
134+
> [!IMPORTANT]
135+
> If you're using the Translator, Neural text-to-speech, or Speech-to-text containers, read the **Additional parameters** section for information on commands or additional parameters you will need to use.
136+
137+
After you've [configured the container](#configure-the-container-to-be-run-in-a-disconnected-environment), the values for the downloaded translation models and container configuration will be generated and displayed in the container output:
138+
139+
```bash
140+
-e MODELS= /path/to/model1/, /path/to/model2/
141+
-e TRANSLATORSYSTEMCONFIG=/path/to/model/config/translatorsystemconfig.json
142+
```
143+
144+
## Run the container in a disconnected environment
145+
146+
Once the license file has been downloaded, you can run the container in a disconnected environment with your license, appropriate memory, and suitable CPU allocations. The following example shows the formatting of the `docker run` command with placeholder values. Replace these placeholders values with your own values.
147+
148+
Whenever the container is run, the license file must be mounted to the container and the location of the license folder on the container's local filesystem must be specified with `Mounts:License=`. In addition, an output mount must be specified so that billing usage records can be written.
149+
150+
Placeholder | Value | Format or example |
151+
|-------------|-------|---|
152+
| `{IMAGE}` | The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice` |
153+
`{MEMORY_SIZE}` | The appropriate size of memory to allocate for your container. | `4g` |
154+
| `{NUMBER_CPUS}` | The appropriate number of CPUs to allocate for your container. | `4` |
155+
| `{LICENSE_MOUNT}` | The path where the license will be located and mounted. | `/host/license:/path/to/license/directory` |
156+
| `{OUTPUT_PATH}` | The output path for logging [usage records](#usage-records). | `/host/output:/path/to/output/directory` |
157+
| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |
158+
| `{CONTAINER_OUTPUT_DIRECTORY}` | Location of the output folder on the container's local filesystem. | `/path/to/output/directory` |
159+
160+
**Example `docker run` command**
161+
162+
```docker
163+
docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \
164+
165+
-v {LICENSE_MOUNT} \
166+
167+
-v {OUTPUT_PATH} \
168+
169+
{IMAGE} \
170+
171+
eula=accept \
172+
173+
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
174+
175+
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}
176+
```
177+
178+
## Other parameters and commands
179+
180+
Here are a few more parameters and commands you may need to run the container.
181+
182+
#### Usage records
183+
184+
When operating Docker containers in a disconnected environment, the container will write usage records to a volume where they're collected over time. You can also call a REST API endpoint to generate a report about service usage.
185+
186+
#### Arguments for storing logs
187+
188+
When run in a disconnected environment, an output mount must be available to the container to store usage logs. For example, you would include `-v /host/output:{OUTPUT_PATH}` and `Mounts:Output={OUTPUT_PATH}` in the following example, replacing `{OUTPUT_PATH}` with the path where the logs will be stored:
189+
190+
```Docker
191+
docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}
192+
```
193+
194+
#### Get records using the container endpoints
195+
196+
The container provides two endpoints for returning records about its usage.
197+
198+
#### Get all records
199+
200+
The following endpoint will provide a report summarizing all of the usage collected in the mounted billing record directory.
201+
202+
```http
203+
https://<service>/records/usage-logs/
204+
```
205+
206+
**Example HTTPS endpoint**
207+
208+
`http://localhost:5000/records/usage-logs`
209+
210+
The usage-log endpoint will return a JSON response similar to the following example:
211+
212+
```json
213+
{
214+
"apiType": "string",
215+
"serviceName": "string",
216+
"meters": [
217+
{
218+
"name": "string",
219+
"quantity": 256345435
220+
}
221+
]
222+
}
223+
```
224+
225+
#### Get records for a specific month
226+
227+
The following endpoint will provide a report summarizing usage over a specific month and year.
228+
229+
```HTTP
230+
https://<service>/records/usage-logs/{MONTH}/{YEAR}
231+
```
232+
233+
This usage-logs endpoint will return a JSON response similar to the following example:
234+
235+
```json
236+
{
237+
"apiType": "string",
238+
"serviceName": "string",
239+
"meters": [
240+
{
241+
"name": "string",
242+
"quantity": 56097
243+
}
244+
]
245+
}
246+
```
247+
248+
### Purchase a different commitment plan for disconnected containers
249+
250+
Commitment plans for disconnected containers have a calendar year commitment period. When you purchase a plan, you'll be charged the full price immediately. During the commitment period, you can't change your commitment plan, however you can purchase more unit(s) at a pro-rated price for the remaining days in the year. You have until midnight (UTC) on the last day of your commitment, to end a commitment plan.
251+
252+
You can choose a different commitment plan in the **Commitment tier pricing** settings of your resource under the **Resource Management** section.
253+
254+
### End a commitment plan
255+
256+
If you decide that you don't want to continue purchasing a commitment plan, you can set your resource's auto-renewal to **Do not auto-renew**. Your commitment plan will expire on the displayed commitment end date. After this date, you won't be charged for the commitment plan. You'll be able to continue using the Azure resource to make API calls, charged at pay-as-you-go pricing. You have until midnight (UTC) on the last day of the year to end a commitment plan for disconnected containers. If you cancel at or before that time, you won't be charged for the following year.
257+
258+
## Troubleshooting
259+
260+
Run the container with an output mount and logging enabled. These settings will enable the container generates log files that are helpful for troubleshooting issues that occur while starting or running the container.
261+
262+
> [!TIP]
263+
> For more troubleshooting information and guidance, see [Disconnected containers Frequently asked questions (FAQ)](../../../cognitive-services/containers/disconnected-container-faq.yml).
264+
265+
## Next steps
266+
267+
[Deploy the Sample Labeling tool to an Azure Container Instance (ACI)](../deploy-label-tool.md#deploy-with-azure-container-instances-aci)

‎articles/applied-ai-services/form-recognizer/media/create-resource-offline-container.png

26.8 KB
Loading

‎articles/applied-ai-services/form-recognizer/toc.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,9 @@ items:
8787
- name: Container image tags
8888
displayName: registry, mcr
8989
href: containers/form-recognizer-container-image-tags.md
90+
- name: Disconnected containers
91+
displayName: docker, commitment, plan, environment, usage
92+
href: containers/form-recognizer-disconnected-containers.md
9093
- name: Configure secure communications
9194
items:
9295
- name: Set up Virtual Networks

0 commit comments

Comments
 (0)