Install and run Translator containers
Containers enable you to run several features of the Translator service in your own environment. Containers are great for specific security and data governance requirements. In this article you learn how to download, install, and run a Translator container.
Translator container enables you to build a translator application architecture that is optimized for both robust cloud capabilities and edge locality.
See the list of languages supported when using Translator containers.
Important
- To use the Translator container, you must submit an online request and have it approved. For more information, see Request approval to run container.
- Translator container supports limited features compared to the cloud offerings. For more information, see Container translate methods.
Prerequisites
To get started, you need an active Azure account. If you don't have one, you can create a free account.
You also need:
Required | Purpose |
---|---|
Familiarity with Docker |
|
Docker Engine |
|
Translator resource |
|
Optional | Purpose |
---|---|
Azure CLI (command-line interface) |
|
Required elements
All Azure AI containers require three primary elements:
EULA accept setting. An end-user license agreement (EULA) set with a value of
Eula=accept
.API key and Endpoint URL. The API key is used to start the container. You can retrieve the API key and Endpoint URL values by navigating to the Translator resource Keys and Endpoint page and selecting the
Copy to clipboard
icon.
Important
- Keys are used to access your Azure AI resource. Do not share your keys. Store them securely, for example, using Azure Key Vault. We also recommend regenerating these keys regularly. Only one key is necessary to make an API call. When regenerating the first key, you can use the second key for continued access to the service.
Host computer
The host is an x64-based computer that runs the Docker container. It can be a computer on your premises or a Docker hosting service in Azure, such as:
- Azure Kubernetes Service.
- Azure Container Instances.
- A Kubernetes cluster deployed to Azure Stack. For more information, see Deploy Kubernetes to Azure Stack.
Container requirements and recommendations
The following table describes the minimum and recommended CPU cores and memory to allocate for the Translator container.
Container | Minimum | Recommended | Language Pair |
---|---|---|---|
Translator | 2 cores, 2-GB memory |
4 cores, 8-GB memory |
4 |
Each core must be at least 2.6 gigahertz (GHz) or faster.
For every language pair, it's recommended to have 2 GB of memory. By default, the Translator offline container has four language pairs.
The core and memory correspond to the
--cpus
and--memory
settings, which are used as part of thedocker run
command.
Note
CPU core and memory correspond to the
--cpus
and--memory
settings, which are used as part of the docker run command.The minimum and recommended specifications are based on Docker limits, not host machine resources.
Request approval to run container
Complete and submit the Azure AI services Application for Gated Services to request access to the container.
The form requests information about you, your company, and the user scenario for which you'll use the container. After you submit the form, the Azure AI services team reviews it and emails you with a decision within 10 business days.
Important
- On the form, you must use an email address associated with an Azure subscription ID.
- The Azure resource you use to run the container must have been created with the approved Azure subscription ID.
- Check your email (both inbox and junk folders) for updates on the status of your application from Microsoft.
After you're approved, you'll be able to run the container after you download it from the Microsoft Container Registry (MCR), described later in the article.
You won't be able to run the container if your Azure subscription hasn't been approved.
Translator container image
The Translator container image can be found on the mcr.microsoft.com
container registry syndicate. It resides within the azure-cognitive-services/translator
repository and is named text-translation
. The fully qualified container image name is mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest
.
To use the latest version of the container, you can use the latest
tag. You can find a full list of tags on the MCR.
Get container images with docker commands
Important
- The docker commands in the following sections use the back slash,
\
, as a line continuation character. Replace or remove this based on your host operating system's requirements. - The
EULA
,Billing
, andApiKey
options must be specified to run the container; otherwise, the container won't start.
Use the docker run command to download a container image from Microsoft Container registry and run it.
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
The above command:
- Downloads and runs a Translator container from the container image.
- Allocates 12 gigabytes (GB) of memory and four CPU core.
- Exposes TCP port 5000 and allocates a pseudo-TTY for the container
- Accepts the end-user agreement (EULA)
- Configures billing endpoint
- Downloads translation models for languages English, French, Spanish, Arabic, and Russian
- Automatically removes the container after it exits. The container image is still available on the host computer.
Run multiple containers on the same host
If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. For example, run the first container on port 5000 and the second container on port 5001.
You can have this container and a different Azure AI container running on the HOST together. You also can have multiple containers of the same Azure AI container running.
Query the container's Translator endpoint
The container provides a REST-based Translator endpoint API. Here's an example request:
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?'}]"
Note
If you attempt the cURL POST request before the container is ready, you'll end up getting a Service is temporarily unavailable response. Wait until the container is ready, then try again.
Stop the container
To shut down the container, in the command-line environment where the container is running, select Ctrl+C.
Troubleshoot
Validate that a container is running
There are several ways to validate that the container is running:
The container provides a homepage at
/
as a visual validation that the container is running.You can open your favorite web browser and navigate to the external IP address and exposed port of the container in question. Use the following request URLs to validate the container is running. The example request URLs listed point to
http://localhost:5000
, but your specific container may vary. Keep in mind that you're navigating to your container's External IP address and exposed port.
Request URL | Purpose |
---|---|
http://localhost:5000/ |
The container provides a home page. |
http://localhost:5000/ready |
Requested with GET. Provides a verification that the container is ready to accept a query against the model. This request can be used for Kubernetes liveness and readiness probes. |
http://localhost:5000/status |
Requested with GET. Verifies if the api-key used to start the container is valid without causing an endpoint query. This request can be used for Kubernetes liveness and readiness probes. |
http://localhost:5000/swagger |
The container provides a full set of documentation for the endpoints and a Try it out feature. With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. After the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format that's required. |
If you're having trouble running an Azure AI services container, you can try using the Microsoft diagnostics container. Use this container to diagnose common errors in your deployment environment that might prevent Azure AI containers from functioning as expected.
To get the container, use the following docker pull
command:
docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic
Then run the container. Replace {ENDPOINT_URI}
with your endpoint, and replace {API_KEY}
with your key to your resource:
docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
The container will test for network connectivity to the billing endpoint.
Text translation code samples
Translate text with swagger
English ↔ German
Navigate to the swagger page: http://localhost:5000/swagger/index.html
- Select POST /translate
- Select Try it out
- Enter the From parameter as
en
- Enter the To parameter as
de
- Enter the api-version parameter as
3.0
- Under texts, replace
string
with the following JSON
[
{
"text": "hello, how are you"
}
]
Select Execute, the resulting translations are output in the Response Body. You should expect something similar to the following response:
"translations": [
{
"text": "hallo, wie geht es dir",
"to": "de"
}
]
Translate text with Python
import requests, json
url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]
request = requests.post(url, headers=headers, json=body)
response = request.json()
print(json.dumps(
response,
sort_keys=True,
indent=4,
ensure_ascii=False,
separators=(',', ': ')))
Translate text with C#/.NET console app
Launch Visual Studio, and create a new console application. Edit the *.csproj
file to add the <LangVersion>7.1</LangVersion>
node—specifies C# 7.1. Add the Newtoonsoft.Json NuGet package, version 11.0.2.
In the Program.cs
replace all the existing code with the following script:
using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
namespace TranslateContainer
{
class Program
{
const string ApiHostEndpoint = "http://localhost:5000";
const string TranslateApi = "/translate?api-version=3.0&from=en&to=de";
static async Task Main(string[] args)
{
var textToTranslate = "Sunny day in Seattle";
var result = await TranslateTextAsync(textToTranslate);
Console.WriteLine(result);
Console.ReadLine();
}
static async Task<string> TranslateTextAsync(string textToTranslate)
{
var body = new object[] { new { Text = textToTranslate } };
var requestBody = JsonConvert.SerializeObject(body);
var client = new HttpClient();
using (var request =
new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
})
{
// Send the request and await a response.
var response = await client.SendAsync(request);
return await response.Content.ReadAsStringAsync();
}
}
}
}
Summary
In this article, you learned concepts and workflows for downloading, installing, and running Translator container. Now you know:
- Translator provides Linux containers for Docker.
- Container images are downloaded from the container registry and run in Docker.
- You can use the REST API to call 'translate' operation in Translator container by specifying the container's host URI.
Next steps
Feedback
Submit and view feedback for