共用方式為

安裝和執行 Azure AI 翻譯工具容器

  • 發行項

容器可讓您將 Azure AI 翻譯工具 API 裝載在自己的基礎結構上。 容器映像包含在任何私人、公用或個人運算環境中一致執行應用程式所需的所有程式庫、工具和相依性。 如果您的安全性或資料控管需求無法透過遠端呼叫 Azure AI 翻譯工具 API 來完成，容器是不錯的選擇。

在本文中，了解如何使用 Docker API 在線上安裝和執行翻譯工具容器。 Azure AI 翻譯工具容器支援下列作業：

  • 文字翻譯。 從支援的 source 翻譯文字或詞組的內容意義，即時翻譯為支援的 target 語言。 如需詳細資訊，請參閱容器：翻譯文字。

  • 🆕 文字轉換。 將文字從一個語言文本或寫入系統轉換成另一個語言指令碼，或即時寫入系統。 如需詳細資訊，請參閱 容器：轉換文字。

  • 🆕 文件翻譯。 以同步方式翻譯文件，同時即時保留結構和格式。 如需詳細資訊，請參閱容器：翻譯文件。

必要條件

若要開始使用，您需要下列資源、閘道存取核准和工具：

Azure 資源

重要

您的翻譯工具資源必須符合下列需求：

  • 您的翻譯工具實例必須是 翻譯工具 資源（而非 多服務 Azure AI 服務資源）。

  • 您的翻譯工具實例必須是 可用 Azure 地理區域內的區域 資源（而非 全域 Azure AI Translator 資源）。 如需詳細資訊， 請參閱 Azure AI Translator 區域定價選項。

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：

作業系統 系統需求
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

注意

最低和建議的規格是以 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

Docker 命令：

  • 從已下載的容器映象建立執行翻譯容器。
  • 配置 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 AI 翻譯工具，使用您 Azure 帳戶上的資源來將帳單資訊傳送至 Azure。

作業 要求查詢 Document type 支援容器
• 文字翻譯
• 文件翻譯		 from 已指定。 Office 文件 無
• 文字翻譯
• 文件翻譯		 from 未指定。 需要自動語言偵測，才能判斷來源語言。 Office 文件 ✔️ 文字分析：語言容器
• 文字翻譯
• 文件翻譯		 from 已指定。 掃描的 PDF 文件 ✔️ 視覺：讀取容器
• 文字翻譯
• 文件翻譯		 from 為指定，需要自動語言偵測，才能判斷來源語言。 掃描的 PDF 文件 ✔️ 文字分析：語言容器

✔️ 視覺：讀取容器

使用 docker compose 操作支援容器

Docker Compose 是一種工具，可讓您使用通常名為 compose.yaml 的單一 YAML 檔案來設定多容器應用程式。 使用 docker compose up 命令來啟動容器應用程式和 docker compose down 命令來停止和移除您的容器。

如果您已安裝 Docker Desktop CLI，包含 Docker Compose 及其必要條件。 如果您沒有 Docker Desktop，請參閱安裝 Docker Compose 概觀。

建立您的應用程式

  1. 使用您慣用的編輯器或 IDE，為名為 container-environment 的應用程式建立或所選名稱新目錄。

  2. 建立名為 compose.yaml 的新 YAML 檔案。 .yml 或 .yaml 延伸檔案都可用於 compose 檔案。

  3. 將下列 YAML 程式碼範例複製並貼到 compose.yaml 檔案中。 請使用 Azure 入口網站翻譯工具執行個體中的金鑰和端點取代 {TRANSLATOR_KEY} 和 {TRANSLATOR_ENDPOINT_URI}。 如果您要翻譯文件，請務必使用 document translation endpoint。

  4. 最上層名稱 (azure-ai-translator、azure-ai-language、azure-ai-read) 是您指定的參數。

  5. container_name 是選擇性參數，可在容器執行時設定名稱，而不是讓 docker compose 產生名稱。

    services:
  azure-ai-translator:
    container_name: azure-ai-translator
    image: mcr.microsoft.com/azure-cognitive-services/translator/text-translation::latest
    environment:
        - EULA=accept
        - billing={TRANSLATOR_ENDPOINT_URI}
        - apiKey={TRANSLATOR_KEY}
        - ladurl=http://azure-ai-language:5000
        - VISIONURL=http://azure-ai-read:5000
    ports:
          - "5000:5000"
    volumes:
          - {your local folder}:/usr/local/models
    azure-ai-language:
      container_name: azure-ai-language
      image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
      environment:
          - EULA=accept
          - billing={LANGUAGE_RESOURCE_ENDPOINT_URI}
          - apiKey={LANGUAGE_RESOURCE_KEY}
          - Languages=en,es
          - LADINCLUSTER=true
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={COMPUTER_VISION_ENDPOINT_URI}
          - apiKey={COMPUTER_VISION_KEY}

  6. 開啟終端機瀏覽至 container-environment 資料夾，並使用下列 docker-compose 命令啟動容器：

    docker compose up

  7. 若要停止容器，請使用下列命令：

    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 可讓您執行命令 lto 中斷連結，或在執行中的容器中設定環境變數。

    如需詳細資訊，請參閱 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 中執行。

  • 當您具現化容器時，必須指定計費資訊。

下一步

深入了解 Azure AI 容器組態，深入了解容器語言支援。