安裝並執行自訂具名實體辨識容器
容器讓您可使用自己的定型模型，在自己的基礎結構上裝載自訂具名實體辨識 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)。
| 最低主機規格 | 建議的主機規格 | 最小 TPS | 最大 TPS | |
|---|---|---|---|---|
| 自訂具名實體辨識 | 1 核心，2 GB 記憶體 | 1 核心，4 GB 記憶體 | 15 | 30 |
CPU 核心和記憶體會對應至 --cpus 和 --memory 設定，以作為 docker run 命令的一部分使用。
匯出自訂具名實體辨識模型
繼續執行 Docker 映像之前，您必須匯出自己的定型模型，以將其公開至您的容器。 使用下列命令擷取模型，並以您自己的值取代下列預留位置：
| 預留位置 | 值 | 格式或範例 |
|---|---|---|
| {API_KEY} | 自訂具名實體辨識資源的金鑰。 在 Azure 入口網站上，您可以在資源的 [金鑰和端點] 頁面上找到金鑰。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| {ENDPOINT_URI} | 用於存取自訂具名實體辨識 API 的端點。 在 Azure 入口網站上，您可以在資源的 [金鑰和端點] 頁面上找到金鑰。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
| {PROJECT_NAME} | 包含您要匯出之模型的專案名稱。 您可以在 Language Studio 入口網站的 [專案] 索引標籤上找到它。 | myProject |
| {TRAINED_MODEL_NAME} | 您想要匯出的定型模型名稱。 您可以在 Language Studio 入口網站的 [專案] 底下的 [模型評估] 索引標籤上找到定型模型。 | myTrainedModel |
curl --location --request PUT '{ENDPOINT_URI}/language/authoring/analyze-text/projects/{PROJECT_NAME}/exported-models/{TRAINED_MODEL_NAME}?api-version=2023-04-15-preview' \
--header 'Ocp-Apim-Subscription-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"TrainedmodelLabel": "{TRAINED_MODEL_NAME}"
}'
使用 docker pull 取得容器映像
您可以在 mcr.microsoft.com 容器登錄聯盟上找到自訂具名實體辨識容器映像。 其位於 azure-cognitive-services/textanalytics/ 存放庫內，並命名為 customner。 完整的容器映像名稱為 mcr.microsoft.com/azure-cognitive-services/textanalytics/customner。
若要使用最新版本的容器，您可以使用 latest 標記。 您也可以在 MCR 上找到標籤的完整清單。
使用 docker pull \(英文\) 命令從 Microsoft Container Registry 下載容器映像。
docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/customner: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 |
| {PROJECT_NAME} | 包含您要匯出之模型的專案名稱。 您可以在 Language Studio 入口網站的 [專案] 索引標籤上找到它。 | myProject |
| {LOCAL_PATH} | 會下載上一個步驟中匯出模型的路徑。 您可以選擇您喜好的任何路徑。 | C:/custom-ner-model |
| {TRAINED_MODEL_NAME} | 您想要匯出的定型模型名稱。 您可以在 Language Studio 入口網站的 [專案] 底下的 [模型評估] 索引標籤上找到定型模型。 | myTrainedModel |
docker run --rm -it -p5000:5000 --memory 4g --cpus 1 \
-v {LOCAL_PATH}:/modelPath \
mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest \
EULA=accept \
BILLING={ENDPOINT_URI} \
APIKEY={API_KEY} \
projectName={PROJECT_NAME}
exportedModelName={TRAINED_MODEL_NAME}
此命令：
- 執行自訂具名實體辨識容器，並將匯出的模型下載到指定的本機路徑。
- 配置一個 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 標頭和本文格式。 |
停止容器
若要關閉容器，請在容器執行所在的命令列環境中，選取 [Ctrl+C]。
疑難排解
如果您在啟用輸出掛接和記錄的情況下執行容器，容器將會產生記錄檔，有助於排解在啟動或執行容器時所發生的問題。
提示
如需疑難排解的詳細資訊和指導，請參閱 Azure AI 容器常見問題集 (FAQ)。
計費
自訂具名實體辨識容器會使用 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。
下一步
- 請參閱設定容器以了解組態設定。