使用內部部署的語言偵測 Docker 容器
容器可讓您將語言偵測 API 裝載在自己的基礎結構上。 如果從遠端呼叫語言偵測無法達到安全性或資料治理需求，則容器可能是不錯的選擇。
必要條件
- 如果您沒有 Azure 訂用帳戶，請建立免費帳戶。
- 主機電腦上已安裝了 Docker。 Docker 必須設定為允許容器與 Azure 連線，以及傳送帳單資料至 Azure。
- 在 Windows 上，也必須將 Docker 設定為支援 Linux 容器。
- 您應該對 Docker 概念有基本的了解。
- 以免費 (F0) 或標準 (S) 定價層語言資源 。
收集必要參數
所有 Azure AI 容器都需要三個主要參數。 Microsoft 軟體授權條款必須具有接受值。 也需要端點 URI 和 API 金鑰。
端點 URI
{ENDPOINT_URI} 值可在相對應 Azure AI 服務資源的 Azure 入口網站 [概觀] 頁面上取得。 移至 [概觀] 頁面，將滑鼠停留在端點上，然後會出現 [複製到剪貼簿] 圖示。 複製端點並用在需要之處。
索引鍵
{API_KEY} 值可用來啟動容器，並可在相對應 Azure AI 服務資源的 Azure 入口網站 [金鑰] 頁面上取得。 移至 [金鑰] 頁面，然後選取 [複製到剪貼簿] 圖示。
重要事項
這些訂用帳戶金鑰可用於存取 Azure AI 服務 API。 請勿共用您的金鑰。 安全地儲存金鑰。 例如，使用 Azure Key Vault。 我們也建議您定期重新產生這些金鑰。 進行 API 呼叫時，只需要一個金鑰。 重新產生第一個金鑰時，您可以使用第二個金鑰繼續存取服務。
主機電腦的需求和建議
主機是執行 Docker 容器的 x64 型電腦。 它可以是您內部部署的電腦，或是在 Azure 中裝載服務的 Docker，例如：
- Azure Kubernetes Service。
- Azure 容器執行個體。
- 部署至 Azure Stack 的 Kubernetes \(英文\) 叢集。 如需詳細資訊，請參閱將 Kubernetes 部署至 Azure Stack。
下表描述語言偵測容器的最低和建議規格。 每個 CPU 核心必須至少 2.6 GHz 或更快。 也會列出允許的每秒交易數 (TPS)。
| 最低主機規格 | 建議的主機規格 | 最小 TP | 最大 TPS | |
|---|---|---|---|---|
| 語言偵測 | 1 核心、2 GB 記憶體 | 1 核心、4 GB 記憶體 | 15 | 30 |
CPU 核心和記憶體會對應至 --cpus 和 --memory 設定，用來做為 docker run 命令的一部分。
使用 docker pull 取得容器映像
您可以在 mcr.microsoft.com 容器登錄聯盟上找到語言偵測容器映像。 其位於 azure-cognitive-services/textanalytics/ 存放庫內，並命名為 language。 完整的容器映像名稱為 mcr.microsoft.com/azure-cognitive-services/textanalytics/language
若要使用最新版本的容器，您可以使用 latest 標記。 您也可以在 MCR 上找到標籤的完整清單。
使用 docker pull 命令從 Microsoft Container Registry 下載容器映像。
docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
提示
您可以使用 docker images \(英文\) 命令來列出已下載的容器映像。 例如，下列命令會列出每個已下載之容器映像的識別碼、存放庫和標籤，並將它格式化為表格：
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
<image-id> <repository-path/name> <tag-name>
透過 docker run 執行容器
一旦容器位於主機電腦後，請使用 docker run 命令來執行容器。 容器將會繼續執行，直到您將其停止為止。
重要
- 以下幾節的 Docker 命令會使用反斜線
\作為行接續字元。 請根據您主機作業系統的需求加以替換或移除。 - 必須指定
Eula、Billing及ApiKey選項以執行容器，否則容器將不會啟動。 如需詳細資訊，請參閱帳單。
若要執行「語言偵測」容器，請執行下列 docker run 命令。 將下列預留位置取代為您自己的值：
| 預留位置 | 值 | 格式或範例 |
|---|---|---|
| {API_KEY} | 語言資源的金鑰。 在 Azure 入口網站上，您可以在資源的 [金鑰和端點] 頁面上找到金鑰。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| {ENDPOINT_URI} | 存取語言偵測 API 的端點。 在 Azure 入口網站上，您可以在資源的 [金鑰和端點] 頁面上找到金鑰。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/textanalytics/language \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
此命令：
- 從容器映像執行「語言偵測」容器
- 配置一個 CPU 核心和 4 GB 的記憶體
- 公開 TCP 連接埠 5000，並為容器配置虛擬 TTY
- 在容器結束之後自動將其移除。 容器映像仍可在主機電腦上使用。
在相同主機上執行多個容器
如果您打算使用公開的連接埠執行多個容器，請務必使用不同的公開連接埠來執行每個容器。 例如，在連接埠 5000 上執行第一個容器，以及在連接埠 5001 上執行第二個容器。
您可以讓此容器和不同的 Azure AI 服務容器在主機上一起執行。 您也可以針對相同的 Azure AI 服務容器執行多個容器。
查詢容器的預測端點
容器會提供以 REST 為基礎的查詢預測端點 API。
請對容器 API 使用主機 http://localhost:5000。
驗證容器正在執行
有數種方式可驗證容器正在執行。 找出有問題容器的外部 IP 位址和公開的連接埠，然後開啟您最愛的網頁瀏覽器。 使用下列各種要求 URL 來驗證容器是否正在執行。 此處列出的範例要求 URL 為 http://localhost:5000，但您的特定容器可能會有所不同。 請確保您將會依賴容器的外部 IP 位址和公開的連接埠。
| 要求 URL | 用途 |
|---|---|
http://localhost:5000/ |
容器會提供首頁。 |
http://localhost:5000/ready |
以 GET 提出要求，此 URL 將會驗證容器是否已準備好接受對模型的查詢。 此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。 |
http://localhost:5000/status |
也會以 GET 提出要求，此 URL 會在不需進行端點查詢的同時，確認用來啟動容器的 API 金鑰是否有效。 此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。 |
http://localhost:5000/swagger |
容器會為端點提供一組完整的文件和 [立即試用] 功能。 使用此功能，您可以將自己的設定輸入至以 Web 為基礎的 HTML 表單並進行查詢，而無須撰寫任何程式碼。 當查詢傳回時，會提供範例 CURL 命令來示範所需的 HTTP 標頭和本文格式。 |
執行與網際網路中斷連線的容器
若要使用此與網際網路中斷連線的容器，您必須先填寫申請表並購買承諾用量方案來要求存取權。 如需詳細資訊，請參閱「在中斷連線環境中使用 Docker 容器」。
如果您已獲核准執行與網際網路中斷連線的容器，請使用下列範例顯示您會使用之 docker run 命令的格式設定以及預留位置值。 以您自己的值取代這些預留位置值。
您 docker run 命令中的 DownloadLicense=True 參數會下載授權檔案，讓您的 Docker 容器可在未連線至網際網路時執行。 其也包含到期日，在此日期之後，授權檔案將無效，以致無法執行容器。 您只能搭配已獲核准的適當容器使用授權檔案。 例如，您無法將語音轉換文字容器的授權檔案和文件智慧容器搭配使用。
| 預留位置 | 值 | 格式或範例 |
|---|---|---|
{IMAGE} |
您想要使用的容器映像。 | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{LICENSE_MOUNT} |
將下載並掛接授權的路徑。 | /host/license:/path/to/license/directory |
{ENDPOINT_URI} |
用於驗證服務要求的端點。 在 Azure 入口網站上，您可以在資源的 [金鑰和端點] 頁面上找到金鑰。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{API_KEY} |
文字分析資源的索引鍵。 在 Azure 入口網站上，您可以在資源的 [金鑰和端點] 頁面上找到金鑰。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
{CONTAINER_LICENSE_DIRECTORY} |
容器本機檔案系統上的授權資料夾位置。 | /path/to/license/directory |
docker run --rm -it -p 5000:5000 \
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
一旦下載了授權檔案，您就可以在已中斷連線的環境中執行容器。 下列範例會顯示您將使用的 docker run 命令格式，以及預留位置值。 以您自己的值取代這些預留位置值。
無論在何處執行容器，授權檔案都必須掛接到該容器，而且授權資料夾在該容器本機檔案系統上的位置必須是使用 Mounts:License= 指定的。 也須指定輸出掛接，才能寫入帳單使用記錄。
| 預留位置 | 值 | 格式或範例 |
|---|---|---|
{IMAGE} |
您想要使用的容器映像。 | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{MEMORY_SIZE} |
要為您容器配置的適當記憶體大小。 | 4g |
{NUMBER_CPUS} |
要為您容器配置的適當 CPU 數目。 | 4 |
{LICENSE_MOUNT} |
將尋找並掛接授權的路徑。 | /host/license:/path/to/license/directory |
{OUTPUT_PATH} |
用於記錄使用量記錄的輸出路徑。 | /host/output:/path/to/output/directory |
{CONTAINER_LICENSE_DIRECTORY} |
容器本機檔案系統上的授權資料夾位置。 | /path/to/license/directory |
{CONTAINER_OUTPUT_DIRECTORY} |
容器本機檔案系統上的輸出資料夾位置。 | /path/to/output/directory |
docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \
-v {LICENSE_MOUNT} \
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}
停止容器
若要關閉容器，請在容器執行所在的命令列環境中，選取 [Ctrl+C]。
疑難排解
如果您在啟用輸出掛接和記錄的情況下執行容器，容器將會產生記錄檔，有助於排解在啟動或執行容器時所發生的問題。
提示
如需疑難排解資訊和指引，請參閱 azure AI 容器常見問題 (常見問題) 。
計費
語言偵測容器會使用您 Azure 帳戶上的「語言」資源將計費資訊傳送到 Azure。
容器查詢按 ApiKey 參數所使用的 Azure 資源定價層計費。
Azure AI 服務容器若未連線至計量或計費端點，即無法獲得執行的授權。 您必須讓容器隨時都能與計量端點進行帳單資訊的通訊。 Azure AI 服務容器不會將客戶資料 (例如正在分析的影像或文字) 傳送給 Microsoft。
連線到 Azure
容器需要計費引數值才能執行。 這些值讓容器能夠連線到計費端點。 容器會每隔 10 到 15 分鐘回報使用量。 如果容器未在允許的時間範圍內連線到 Azure，容器會繼續執行，但在還原計費端點之前不會提供查詢。 以 10 到 15 分鐘的相同時間間隔嘗試連線 10 次。 如果無法在 10 次嘗試內連線到計費端點，則容器會停止回應要求。 請參閱「Azure AI 服務容器常見問題集」，以獲得需傳送哪些資訊給 Microsoft 以供計費的範例。
計費引數
當下列三個選項都填入了有效值時，docker run 命令將會啟動容器：
| 選項 | 描述 |
|---|---|
ApiKey |
Azure AI 服務資源的 API 金鑰，用於追蹤計費資訊。 此選項值必須設定為已佈建 Billing 指定資源的 API 金鑰。 |
Billing |
Azure AI 服務資源的端點，用於追蹤計費資訊。 此選項的值必須設定為已佈建 Azure 資源的端點 URI。 |
Eula |
表示您接受容器的授權。 此選項的值必須設定為接受。 |
如需這些選項的詳細資訊，請參閱設定容器。
總結
在本文中，您已了解下載、安裝及執行語言偵測容器的概念和工作流程。 摘要說明：
- 語言偵測提供適用於 Docker 的 Linux 容器
- 容器映像可從 Microsoft Container Registry (MCR) 下載取得。
- 容器映像是在 Docker 中執行。
- 將容器具現化時，您必須指定帳單資訊。
重要
此容器在未連線至 Azure 進行計量的情況下，將無權執行。 客戶必須啟用容器以持續與計量服務進行帳單資訊的通訊。 Azure AI 容器不會將客戶資料 (例如正在分析的文字) 傳送給 Microsoft。
下一步
- 請參閱設定容器以了解組態設定。