安裝和執行關鍵片語擷取容器

發行項
12/19/2023

容器可讓您在自己的基礎結構上裝載關鍵片語擷取 API。如果您的安全性或資料治理需求無法藉由從遠端呼叫關鍵片語擷取來滿足，容器可能是不錯的選擇。

注意

免費帳戶僅限每月 5000 個文字記錄，且只有免費和標準定價層可使用容器。如需交易要求費率的更多資訊，請參閱資料與服務限制。

容器可讓您在自己的環境中執行關鍵片語擷取 API，而且能夠配合您的特定安全性和資料控管需求。關鍵片語擷取容器針對原始的文字提供進階的自然語言處理，同時包含三種主要功能：情緒分析、關鍵片語擷取以及語言偵測。

必要條件

如果您沒有 Azure 訂用帳戶，請建立免費帳戶。
主機電腦上已安裝了 Docker。 Docker 必須設定為允許容器與 Azure 連線，以及傳送帳單資料至 Azure。
- 在 Windows 上，也必須將 Docker 設定為支援 Linux 容器。
- 您應該對 Docker 概念有基本的了解。
以免費 (F0) 或標準 (S) 定價層語言資源。

收集必要參數

所有 Azure AI 容器都需要三個主要參數。 Microsoft 軟體授權條款必須具有接受值。也需要端點 URI 和 API 金鑰。

端點 URI

{ENDPOINT_URI} 值可在相對應 Azure AI 服務資源的 Azure 入口網站 [概觀] 頁面上取得。移至 [概觀] 頁面，將滑鼠停留在端點上，然後會出現 [複製到剪貼簿] 圖示。複製端點並用在需要之處。

顯示收集供稍後使用的端點 URI 的螢幕擷取畫面。

索引鍵

{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/ 存放庫內，並命名為 keyphrase。完整的容器映像名稱為 mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase。

若要使用最新版本的容器，您可以使用 latest 標記。您也可以在 MCR 上找到標籤的完整清單。

使用 docker pull \(英文\) 命令從 Microsoft Container Registry 下載容器映像。

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase: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 選項以執行容器，否則容器將不會啟動。如需詳細資訊，請參閱帳單。
情感分析和語言偵測容器使用的是 v3 版本的 API，並已正式推出。關鍵片語擷取容器使用的是 v2 版本的 API，且目前為預覽版。

若要執行關鍵片語擷取容器，請執行下列 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/keyphrase \
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 中執行。
您可以使用 REST API 或 SDK，藉由指定容器的主機 URI 來呼叫關鍵片語擷取容器中的作業。
將容器具現化時，您必須指定帳單資訊。

重要

Azure AI 容器若未連線至用於計量的 Azure，即無法獲得執行的授權。客戶必須啟用容器以持續與計量服務進行帳單資訊的通訊。 Azure AI 容器不會將客戶資料 (例如正在分析的文字) 傳送給 Microsoft。

下一步

請參閱設定容器以了解組態設定。