安裝和執行 Azure AI 翻譯工具 容器
容器可讓您在自己的基礎結構上裝載 Azure AI 翻譯工具 API。 容器映像包含在任何私人、公用或個人運算環境中一致執行應用程式所需的所有連結庫、工具和相依性。 如果您的安全性或數據控管需求無法透過遠端呼叫 Azure AI 翻譯工具 API 來完成，容器是不錯的選擇。
在本文中，瞭解如何使用 Docker API 在在線安裝和執行 翻譯工具 容器。 Azure AI 翻譯工具 容器支援下列作業：
文字翻譯。 將文字或片語的內容意義，從支援的
source文字或片語即時翻譯為支持target的語言。 如需詳細資訊，請參閱容器：翻譯文字。🆕 文字音譯。 將文字從一個語言文本或寫入系統轉換成另一個語言腳本，或即時寫入系統。 如需詳細資訊， 請參閱容器：音譯文字。
🆕 檔翻譯（預覽）。 以同步方式翻譯檔，同時即時保留結構和格式。 如需詳細資訊， 請參閱Container：translate 檔。
必要條件
若要開始使用，您需要下列資源、閘道存取核准和工具：
Azure 資源
有效的 Azure 訂閱。 如果您沒有帳戶，您可以 建立免費的 12 個月帳戶。
在核准的訂用帳戶標識符下建立的 Azure AI 翻譯工具 資源（而非多服務 Azure AI 服務資源）。 您需要與資源相關聯的 API 金鑰和端點 URI。 這兩個值都需要啟動容器，而且可以在 Azure 入口網站的資源概觀頁面上找到。
針對 翻譯工具 連線的容器，選取
S1定價層。
針對已中斷連線的容器 翻譯工具，請選取
Commitment tier disconnected containers作為您的定價層。 如果您已核准已中斷連線的容器存取要求，則只會看到購買承諾層的選項。
Docker 工具
您應具備對 Docker 概念 (例如登錄、存放庫、容器和容器映像等) 的基本了解，以及基本docker術語與命令的知識。 如需 Docker 和容器基本概念的入門，請參閱 Docker 概觀 \(英文\)。
提示
請考慮將 Docker Desktop 新增至計算環境。 Docker Desktop 是圖形使用者介面 （GUI），可讓您直接從桌面建置、執行及共用容器化應用程式。
DockerDesktop 包含 Docker 引擎、Docker CLI 用戶端、Docker Compose，並提供針對您慣用操作系統設定 Docker 的套件：
| 工具 | 描述 | 條件 |
|---|---|---|
| Docker 引擎 | Docker 引擎是 Docker 容器化平臺的核心元件。 它必須安裝在 主計算機上 ，才能讓您建置、執行及管理容器。 | 所有作業都需要 。 |
| Docker Compose (英文) | Docker Compose 工具可用來定義及執行多容器應用程式。 | 支援容器的必要專案。 |
| Docker CLI | Docker 命令行介面可讓您與 Docker 引擎互動，並直接從本機電腦管理 Docker 容器。 | 建議需求 |
主機電腦需求
主機是執行 Docker 容器的 x64 型電腦。 它可以是內部部署的電腦，或 Azure 中的其中一個 Docker 主控服務：
- Azure Kubernetes Service。
- Azure 容器執行個體。
- 部署至 Azure Stack 的 Kubernetes \(英文\) 叢集。 如需詳細資訊，請參閱將 Kubernetes 部署至 Azure Stack。
| 作業系統 | 系統需求 |
|---|---|
| Windows | • 已安裝 Windows 10 或 Windows 11 • 64 位處理器 • 至少 4 GB 的 RAM • Windows Hyper-V 和容器功能，以及 BIOS 層級的硬體虛擬化 • 如需詳細資訊， 請參閱在 Windows 上安裝 Docker Desktop |
| Mac： | • 2010 計算機型號或更新版本 • OS 10.13 或更新版本 • 至少 4 GB 的 RAM • 如需詳細資訊， 請參閱在 Mac 上安裝 Docker Desktop |
| Linux | • 64 位版本的 Ubuntu（最新 LTS（長期支援）版本或目前的非 LTS 版本）、Debian 12、Fedora 38 或 Fedora 39 • 虛擬化的CPU支援 • 至少 4 GB 的 RAM • 如需詳細資訊， 請參閱在Linux上安裝Docker Desktop |
建議的 CPU 核心數和記憶體
注意
最低和建議的規格是以 Docker 限制，而不是主機機器資源為基礎。
下表說明每個容器的最小和建議規格，以及允許的每秒交易數（TPS）。
| 函式 | 建議的最小值 | 備註 |
|---|---|---|
| 文字翻譯 | 4 核心、4 GB 記憶體 | |
| 文字音譯 | 4 核心，2 GB 記憶體 | |
| 文件翻譯 | 4 核心，6 GB 記憶體 | 可以同時使用下列公式計算可同時處理的檔數目：[最小值（n-2）、（m-6)/4）]。 • n 是 CPU 核心的數目。• m 是 GB 的記憶體。• 範例：8 核心，32 GB 記憶體可以處理六（6）個並行檔 [最小值（ 8-2）， (36-6)/4)]。 |
每個核心必須至少 2.6 GHz 或更快。
針對每個語言組，建議使用 2 GB 的記憶體。
除了基準需求之外，每個並行文件處理都有 4 GB 的記憶體。
提示
您可以使用 docker images \(英文\) 命令來列出已下載的容器映像。 例如，下列命令會列出每個已下載之容器映像的識別碼、存放庫和標籤，並將它格式化為表格：
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" IMAGE ID REPOSITORY TAG <image-id> <repository-path/name> <tag-name>
必要輸入
所有 Azure AI 容器都需要下列輸入值：
EULA 接受設定。 您必須將使用者許可協定 （EULA） 設定為 的值
Eula=accept。API 金鑰和端點 URL。 API 金鑰可用來啟動容器。 您可以流覽至 Azure AI 翻譯工具 資源金鑰和端點頁面，然後選取
Copy to clipboard圖示，以擷取 API 金鑰和端點 URL 值。如果您要翻譯檔，請務必使用文件翻譯端點。
重要
金鑰可用來存取您的 Azure AI 資源。 請勿共用您的金鑰， 安全地加以儲存，例如使用 Azure Key Vault。
我們也建議定期重新產生這些金鑰。 呼叫 API 只需一把金鑰。 當您重新產生第一把金鑰時，可以使用第二把金鑰繼續存取服務。
計費
對容器的查詢會以 API
Key所使用的 Azure 資源定價層計費。您必須針對每個用來處理文件和影像的容器執行個體支付費用。
docker run 命令會從 Microsoft 成品登錄 下載映像，並在下列三個選項都提供有效值時啟動容器：
| 選項 | 描述 |
|---|---|
ApiKey |
用來追蹤計費資訊的 Azure AI 服務資源密鑰。 此選項的值必須設定為 中 Billing指定之已布建資源的索引鍵。 |
Billing |
用來追蹤計費資訊的 Azure AI 服務資源的端點。 此選項的值必須設定為已佈建 Azure 資源的端點 URI。 |
Eula |
表示您接受容器的授權。 此選項的值必須設定為接受。 |
連線到 Azure
容器計費自變數值可讓容器連線到計費端點並執行。
容器會每隔 10 到 15 分鐘回報使用量。 如果容器未在允許的時間範圍內連線到 Azure，容器會繼續執行，但在還原計費端點之前不會提供查詢。
在 10 到 15 分鐘的相同時間間隔內，嘗試連接 10 次。 如果無法在 10 次嘗試內連線到計費端點，容器會停止處理要求。 請參閱 Azure AI 容器常見問題，以獲得需傳送哪些資訊給 Microsoft 以供計費的範例。
容器映像和標籤
您可以在 Microsoft 成品登錄 目錄中找到 Azure AI 服務容器映像。 Azure AI 翻譯工具 容器位於 azure-cognitive-services/translator 存放庫內，並命名為 text-translation。 完整的容器映像名稱為 mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest。
若要使用最新版本的容器，請使用最新的標籤。 您可以在 MCR 上檢視 Azure AI 服務文字翻譯版本標籤的完整清單。
使用容器
選取索引標籤以選擇 Azure AI 翻譯工具 容器環境：
Azure AI 翻譯工具 容器可讓您在自己的環境中執行 Azure AI 翻譯工具 服務on-premise。 連線 容器會在本機執行，並將使用量資訊傳送至雲端以進行計費。
下載並執行容器映像
docker run 命令會從 Microsoft 成品登錄 下載映像，並啟動容器。
重要
- 以下幾節的 Docker 命令會使用反斜線
\作為行接續字元。 請根據您主機作業系統的需求加以替換或移除。 - 必須指定
EULA、Billing及ApiKey選項以執行容器，否則容器將不會啟動。 - 如果您要翻譯檔，請務必使用文件翻譯端點。
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
上述命令：
- 從下載的容器映像建立執行中 翻譯工具 容器。
- 配置 12 GB 的記憶體和四個 CPU 核心。
- 公開傳輸控制通訊協定 （TCP） 埠 5000，併為容器配置虛擬 TTY。 現在，位址
localhost會指向容器本身，而不是您的主計算機。 - 接受用戶合約 （EULA）。
- 設定計費端點。
- 下載英文、法文、西班牙文、阿拉伯文和俄文語言的翻譯模型。
- 在容器結束之後自動將其移除。 容器映像仍可在主機電腦上使用。
提示
其他 Docker 命令：
docker ps列出執行中的容器。docker pause {your-container name}暫停執行中的容器。docker unpause {your-container-name}取消暫停的容器。docker restart {your-container-name}會重新啟動執行中的容器。docker exec可讓您在執行中的容器中執行命令 lto 卸離 或 設定環境變數 。
如需詳細資訊， 請參閱docker CLI 參考。
在相同主機上執行多個容器
如果您打算使用公開的連接埠執行多個容器，請務必使用不同的公開連接埠來執行每個容器。 例如，在連接埠 5000 上執行第一個容器，以及在連接埠 5001 上執行第二個容器。
您可以讓此容器和不同的 Azure AI 容器在主機上一起執行。 您也可以針對相同的 Azure AI 容器執行多個容器。
查詢 翻譯工具 容器端點
容器會提供 REST 型翻譯工具端點 API。 以下是指定來源語言 （from=en） 的範例要求：
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?'}]"
注意
來源語言偵測需要額外的容器。 如需詳細資訊， 請參閱支援容器
如果 cURL POST 要求傳
Service is temporarily unavailable回回應，則容器尚未就緒。 請稍候幾分鐘，然後再試一次。
驗證容器正在執行
有數種方式可驗證容器正在執行：
容器會提供一個首頁
/做為容器正在執行的視覺驗證。您可以開啟您喜愛的網頁瀏覽器並瀏覽至有問題容器的「外部 IP」位址和公開的連接埠。 使用下列的要求 URL 來驗證容器是否正在執行。 列出的範例要求 URL 指向
http://localhost:5000，但您的特定容器可能會有所不同。 請記住，您將會瀏覽至容器的外部 IP 位址和公開的連接埠。
| 要求 URL | 目的 |
|---|---|
http://localhost:5000/ |
容器會提供首頁。 |
http://localhost:5000/ready |
以 GET 提出要求。 將會確認容器是否已準備好接受對模型的查詢。 此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。 |
http://localhost:5000/status |
以 GET 提出要求。 會在不需進行端點查詢的同時，確認用來啟動容器的 API 金鑰是否有效。 此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。 |
http://localhost:5000/swagger |
容器會為端點提供一組完整的文件和立即試用功能。 使用此功能，您可以將自己的設定輸入至以 Web 為基礎的 HTML 表單並進行查詢，而無須撰寫任何程式碼。 查詢傳回之後，會提供範例 CURL 命令來示範必要的 HTTP 標頭和本文格式。 |
如果您在執行 Azure AI 服務容器時遇到問題，可以嘗試使用 Microsoft 診斷容器。 您可以使用此容器來診斷部署環境中的常見錯誤，這些錯誤可能會導致 Azure AI 容器無法如預期般運作。
若要取得容器，請使用下列 docker pull 命令：
docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic
接著執行該容器。 將 {ENDPOINT_URI} 取代為您的端點，並將 {API_KEY} 取代為您資源的金鑰：
docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
容器會測試與計費端點的網路連線能力。
停止容器
若要關閉容器，請在容器執行所在的命令列環境中，選取 [Ctrl+C]。
支援容器的使用案例
某些 翻譯工具 查詢需要支援容器才能順利完成作業。 如果您使用 Office 檔，而且不需要來源語言偵測，只需要 翻譯工具 容器。 不過，如果需要來源語言偵測，或您使用掃描的 PDF 檔，則需要支援容器：
下表列出文字和文件翻譯作業所需的支援容器。 翻譯工具 容器會透過 Azure 帳戶上的 Azure AI 翻譯工具 資源，將帳單資訊傳送至 Azure。
| 作業 | 要求查詢 | Document type | 支援容器 |
|---|---|---|---|
| •文本翻譯 • 檔案翻譯 |
from 指定。 |
Office 檔 | 無 |
| •文本翻譯 • 檔案翻譯 |
from 未指定。 需要自動語言偵測，才能判斷來源語言。 |
Office 檔 | 文字分析：語言容器 ✔️ |
| •文本翻譯 • 檔案翻譯 |
from 指定。 |
掃描的 PDF 檔 | Vision：read 容器 ✔️ |
| •文本翻譯 • 檔案翻譯 |
from 未指定需要自動語言偵測來判斷來源語言。 |
掃描的 PDF 檔 | 文字分析：語言容器 ✔️ Vision：read 容器 ✔️ |
使用操作支援的容器 docker compose
Docker compose 是一種工具，可讓您使用一 compose.yaml個名為 的單一 YAML 檔案來設定多容器應用程式。 docker compose up使用 命令來啟動容器應用程式，以及docker compose down停止和移除容器的命令。
如果您已安裝 Docker Desktop CLI，它包含 Docker compose 及其必要條件。 如果您沒有 Docker Desktop，請參閱 安裝 Docker Compose 概觀。
建立您的應用程式
使用您慣用的編輯器或 IDE，為您的應用程式建立名為
container-environment的新目錄或您選擇的名稱。建立名為
compose.yaml的新 YAML 檔案。 .yml或 .yaml 擴展名都可用於compose檔案。將下列 YAML 程式代碼範例複製並貼到您的
compose.yaml檔案中。 將和{TRANSLATOR_ENDPOINT_URI}取代{TRANSLATOR_KEY}為您 Azure 入口網站 翻譯工具 實例中的金鑰和端點值。 如果您要翻譯檔案，請務必使用document translation endpoint。最上層名稱 （
azure-ai-translator、azure-ai-languageazure-ai-read、 ） 是您指定的參數。container_name是選擇性參數，可在容器執行時設定名稱，而不是讓docker compose產生名稱。services: azure-ai-translator: container_name: azure-ai-translator image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest environment: - EULA=accept - billing={TRANSLATOR_ENDPOINT_URI} - apiKey={TRANSLATOR_KEY} - AzureAiLanguageHost=http://azure-ai-language:5000 - AzureAiReadHost=http://azure-ai-read:5000 ports: - "5000:5000" azure-ai-language: container_name: azure-ai-language image: mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest environment: - EULA=accept - billing={TRANSLATOR_ENDPOINT_URI} - apiKey={TRANSLATOR_KEY} azure-ai-read: container_name: azure-ai-read image: mcr.microsoft.com/azure-cognitive-services/vision/read:latest environment: - EULA=accept - billing={TRANSLATOR_ENDPOINT_URI} - apiKey={TRANSLATOR_KEY}開啟終端機瀏覽至
container-environment資料夾，並使用下列docker-compose命令啟動容器：docker compose up若要停止容器，請使用下列命令：
docker compose down提示
實用的 Docker 命令：
docker compose pause暫停執行中的容器。docker compose unpause {your-container-name}取消暫停的容器。docker compose restart會重新啟動所有已停止且執行中的容器，且所有先前的變更都保持不變。 如果您對組compose.yaml態進行變更，則不會使用docker compose restart命令來更新這些變更。 您必須使用docker compose up命令來反映檔案中的compose.yaml更新和變更。docker compose ps -a列出所有容器，包括已停止的容器。docker compose exec可讓您執行命令，以 中斷連結 或 設定執行中容器中的環境變數 。
如需詳細資訊， 請參閱docker CLI 參考。
翻譯工具並支援容器映像和標籤
您可以在 Microsoft 成品登錄 目錄中找到 Azure AI 服務容器映像。 下表列出文字和文件翻譯的完整影像位置：
| 容器 | 映像位置 | 備註 |
|---|---|---|
| 翻譯工具：文字和文件翻譯 | mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest |
您可以在 MCR 上檢視 Azure AI 服務文字翻譯版本標籤的完整清單。 |
| 文字分析：語言 | mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest |
您可以在 MCR 上檢視 Azure AI 服務的完整清單 文字分析 語言版本標籤。 |
| 視覺：讀取 | mcr.microsoft.com/azure-cognitive-services/vision/read:latest |
您可以在 MCR 上檢視 Azure AI 服務的完整清單，電腦視覺 讀取OCR版本標籤。 |
其他參數和命令
以下是您可以用來執行容器的幾個參數和命令：
使用量記錄
在中斷聯機的環境中操作 Docker 容器時，容器會將使用量記錄寫入一段時間收集的磁碟區。 您也可以呼叫 REST API 端點，以產生有關服務使用量的報告。
用於儲存記錄的自變數
在中斷連線的環境中執行時，容器必須可使用輸出掛接來儲存使用量記錄。 例如，您會在下列範例中包含 -v /host/output:{OUTPUT_PATH} 和 Mounts:Output={OUTPUT_PATH}，將 {OUTPUT_PATH} 取代為儲存記錄的路徑：
範例 docker run 命令
docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}
Kubernetes 部署中的環境變數名稱
一些 Azure AI 容器，例如翻譯工具，要求使用者在執行容器時傳遞包含冒號 (
:) 的環境變數名稱。Kubernetes 不接受環境變數名稱中的冒號。 若要解決，您可以在部署至 Kubernetes 時，以兩個底線字元 （
__） 取代冒號。 請參閱以下環境變數名稱的可接受格式範例：
env:
- name: Mounts__License
value: "/license"
- name: Mounts__Output
value: "/output"
此範例取代 docker run 命令中 Mounts:License 和 Mounts:Output 環境變數名稱的預設格式。
使用容器端點取得使用量記錄
容器提供了兩個端點，用於傳回有關其使用量的記錄。
取得所有記錄
下列端點提供一份報告，彙總在裝載的帳單記錄目錄中收集到的所有使用量。
https://<service>/records/usage-logs/
擷取所有記錄的 HTTPS 端點範例
http://localhost:5000/records/usage-logs
取得特定月份的記錄
下列端點提供一份報告，彙總特定月份和年份的使用量報告：
https://<service>/records/usage-logs/{MONTH}/{YEAR}
擷取特定月份和年份記錄的 HTTPS 端點範例
http://localhost:5000/records/usage-logs/03/2024
使用量記錄端點會傳回類似下列範例的 JSON 回應：
連線容器
使用量費用是根據 值計算 quantity 。
{
"apiType": "string",
"serviceName": "string",
"meters": [
{
"name": "string",
"quantity": 256345435
}
]
}
摘要
在本文中，您已瞭解下載、安裝及執行 Azure AI 翻譯工具 容器的概念和工作流程：
Azure AI 翻譯工具 容器支援文字翻譯、同步文件翻譯和文字音譯。
容器映像是從容器登錄下載，並在 Docker 中執行。
當您具現化容器時，必須指定計費資訊。