安裝和執行適用於語音服務 API 的 Docker 容器
藉由使用容器，您可以在自己的環境中執行一些 Azure 認知服務語音服務 API。 容器非常適合用於特定的安全性和資料控管需求。 在本文中，您將了解如何下載、安裝及執行語音容器。
透過語音容器，您將可建置最能同時善用健全雲端功能和邊緣位置的語音應用程式架構。 有數個容器可供使用，採用與雲端式 Azure 語音服務相同的定價。
可用的語音容器
重要事項
我們已於 2021 年 8月 31 日淘汰標準語音合成語音和文字轉換語音容器。 請考慮移轉您的應用程式，改用類神經文字轉換語音容器。 如需更新應用程式的詳細資訊，請參閱從標準語音移轉至預建神經語音。
| 容器 | 特性 | 支援的版本和地區設定 |
|---|---|---|
| 語音轉文字 | 使用中繼結果分析情感和轉譯連續即時語音或批次音訊錄製內容。 | 最新：3.12.0 如需所有支援的版本和地區設定，請參閱 Microsoft Container Registry (MCR) 和 JSON 標籤。 |
| 自訂語音轉換文字 | 從自訂語音入口網站使用自訂模型，搭配中繼結果將連續即時語音或批次音訊錄製內容轉譯為文字。 | 最新：3.12.0 如需所有支援的版本和地區設定，請參閱 Microsoft Container Registry (MCR) 和 JSON 標籤。 |
| 語音語言識別 | 偵測音訊檔案中所說的語言。 | 最新：1.11.01 如需所有支援的版本和地區設定，請參閱 Microsoft Container Registry (MCR) 和 JSON 標籤。 |
| 類神經文字轉換語音 | 使用深度神經網路技術將文字轉換成自然發音語音，使語音合成更自然。 | 最新：2.11.0 如需所有支援的版本和地區設定，請參閱 Microsoft Container Registry (MCR) 和 JSON 標籤。 |
1 容器可在公開預覽中取得。 預覽中的容器仍在開發中，且不符合 Microsoft 的穩定性和支援需求。
必要條件
重要
若要使用語音容器，您必須提交線上要求並使其獲得核准。 如需詳細資訊，請參閱「要求核准以執行容器」一節。
在使用語音服務容器之前，您必須符合下列必要條件。 如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。 您需要：
- 主機電腦上已安裝了 Docker。 Docker 必須設定為允許容器與 Azure 連線，以及傳送帳單資料至 Azure。
- 在 Windows 上，也必須將 Docker 設定為支援 Linux 容器。
- 您應該對 Docker 概念有基本的了解。
- 以免費 (F0) 或標準 (S) 定價層語音服務資源。
收集必要參數
所有認知服務容器都需要三個主要參數。 Microsoft 軟體授權條款必須具有接受值。 也需要端點 URI 和 API 金鑰。
端點 URI
{ENDPOINT_URI} 值可在相對應認知服務資源的 Azure 入口網站 [概觀] 頁面上取得。 移至 [概觀] 頁面，將滑鼠停留在端點上，然後會出現 [複製到剪貼簿] 圖示。 複製端點並用在需要之處。
索引鍵
此 {API_KEY} 值可用來啟動容器，並可在相對應認知服務資源的 Azure 入口網站 [金鑰] 頁面上取得。 移至 [金鑰] 頁面，然後選取 [複製到剪貼簿] 圖示。
重要事項
這些訂用帳戶金鑰可用來存取認知服務 API。 請勿共用您的金鑰。 安全地儲存金鑰。 例如，使用 Azure Key Vault。 我們也建議您定期重新產生這些金鑰。 進行 API 呼叫時，只需要一個金鑰。 重新產生第一個金鑰時，您可以使用第二個金鑰繼續存取服務。
主機電腦的需求和建議
主機是執行 Docker 容器的 x64 型電腦。 它可以是您內部部署的電腦，或是在 Azure 中裝載服務的 Docker，例如：
- Azure Kubernetes Service。
- Azure 容器執行個體。
- 部署至 Azure Stack 的 Kubernetes \(英文\) 叢集。 如需詳細資訊，請參閱將 Kubernetes 部署至 Azure Stack。
容器的需求和建議
下表說明每個語音容器的資源適用的最低和建議配置：
| 容器 | 最小值 | 建議 | 語音模型 |
|---|---|---|---|
| 語音轉文字 | 4 核心，4 GB 記憶體 | 8 核心、8 GB 記憶體 | +4 到 8 GB 記憶體 |
| 自訂語音轉換文字 | 4 核心，4 GB 記憶體 | 8 核心、8 GB 記憶體 | +4 到 8 GB 記憶體 |
| 語音語言識別 | 1 核心，1 GB 記憶體 | 1 核心，1 GB 記憶體 | n/a |
| 類神經文字轉換語音 | 6 核心，12 GB 記憶體 | 8 核心，16 GB 記憶體 | n/a |
每個核心必須至少 2.6 GHz 或更快。
核心和記憶體會對應至 --cpus 和 --memory 設定，用來作為 docker run 命令的一部分。
注意
最低和建議的配置以 Docker 限制 (而非主機電腦資源) 為基礎。 例如，大型語言模型的語音轉換文字容器記憶體對應部分。 我們建議您將整個檔案放入記憶體中。 您必須新增額外的 4 到 8 GB 以載入語音模式l (請參閱上表) 。 此外，任一個容器的第一次執行可能需要較長的時間，因為模型會分頁至記憶體中。
進階向量擴充功能支援
主機是執行 Docker 容器的電腦。 主機必須支援進階向量擴充功能 (AVX2)。 您可以使用下列命令，在 Linux 主機上檢查 AVX2 支援：
grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected
警告
需要主機電腦才能支援 AVX2。 若沒有 AVX2 支援，容器將無法正確運作。
要求核准以執行容器
填寫並提交要求表單，以要求容器的存取權。
該表格需要有關您本身、您的公司，以及您將會使用該容器之使用者情節的資訊。 提交表單之後，Azure 認知服務小組會在 10 個工作天內進行審核，並以電子郵件將做出的決定傳送給您。
重要
- 在表單上，您必須使用與 Azure 訂用帳戶識別碼相關聯的電子郵件地址。
- 您用來執行容器的 Azure 資源，必須使用已核准的 Azure 訂用帳戶識別碼來建立。
- 檢查您的電子郵件 (收件匣和垃圾郵件資料夾)，以從 Microsoft 取得您應用程式狀態的更新。
經過核准之後，您將能在從 Microsoft Container Registry (MCR) 下載容器之後執行容器，稍後將在本文中加以說明。
如果您的 Azure 訂用帳戶尚未核准，您將無法執行容器。
語音容器映射
您可以在 mcr.microsoft.com 容器登錄聯盟上找到語音轉換文字容器映像。 其位於 azure-cognitive-services/speechservices/ 存放庫內，並命名為 speech-to-text。 完整的容器映像名稱為 mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text。 您可以在 MCR 上找到標籤的完整清單。
| 容器 | Repository |
|---|---|
| 語音轉文字 | mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text:latest |
提示
您可以使用 docker images \(英文\) 命令來列出已下載的容器映像。 例如，下列命令會列出每個已下載之容器映像的識別碼、存放庫和標籤，並將它格式化為表格：
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
<image-id> <repository-path/name> <tag-name>
使用 docker pull 取得容器映像
適用於語音轉換文字容器的 docker pull
使用 docker pull 命令，從 Microsoft Container Registry下載容器映像：
docker pull mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text:latest
重要
latest 標籤會提取 en-US 地區設定。 如需其他地區設定，請參閱語音轉換文字地區設定。
語音轉換文字地區設定
除了 latest 以外的所有標籤都採用下列格式，而且會區分大小寫：
<major>.<minor>.<patch>-<platform>-<locale>-<prerelease>
下列標籤是格式的範例：
2.6.0-amd64-en-us
如需語音轉換文字容器支援的所有地區設定，請參閱語音轉換文字映像標籤。
使用該容器
容器位於主機電腦上之後，請透過下列程序來使用容器。
使用 docker run 執行容器
將 docker run 命令執行容器。 如需如何取得 {Endpoint_URI} 和 {API_Key} 值的詳細資訊，請參閱收集必要參數。 docker run 命令也有相關範例可供參考。
注意
如需一般容器需求，請參閱容器需求與建議。
若要執行標準語音轉換文字容器，請執行下列 docker run 命令：
docker run --rm -it -p 5000:5000 --memory 8g --cpus 4 \
mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
此命令：
- 從容器映像執行語音轉換文字容器。
- 配置 4 個 CPU 核心和 8 GB 的記憶體。
- 公開 TCP 通訊埠 5000，並為容器配置虛擬 TTY。
- 在容器結束之後自動將其移除。 容器映像仍可在主機電腦上使用。
注意
容器支援使用 GStreamer 為語音 SDK 提供壓縮音訊輸入。 若要在容器中安裝 GStreamer，請遵循搭配語音 SDK 使用轉碼器壓縮的音訊輸入中適用於 GStreamer 的 Linux 指示。
語音轉換文字輸出上的自動分段標記
預設會啟用自動分段標記。 若要在您的回應中取得自動分段標記，請使用 diarize_speech_config.set_service_property。
將片語輸出格式設定為
Detailed。設定自動分段標記的模式。 支援的模式為
Identity和Anonymous。diarize_speech_config.set_service_property( name='speechcontext-PhraseOutput.Format', value='Detailed', channel=speechsdk.ServicePropertyChannel.UriQueryParameter ) diarize_speech_config.set_service_property( name='speechcontext-phraseDetection.speakerDiarization.mode', value='Identity', channel=speechsdk.ServicePropertyChannel.UriQueryParameter )注意
「身分識別」模式會傳回
"SpeakerId": "Customer"或"SpeakerId": "Agent"。 「匿名」模式會傳回"SpeakerId": "Speaker 1"或"SpeakerId": "Speaker 2"。
分析語音轉換文字輸出上的情感
從語音轉文字容器的 v2.6.0 開始，您應該使用語言服務 3.0 API 端點，而不是預覽端點。 例如：
https://eastus.api.cognitive.microsoft.com/text/analytics/v3.0/sentimenthttps://localhost:5000/text/analytics/v3.0/sentiment
注意
語言服務 v3.0 API 不具備對 v3.0-preview.1 的回溯相容性。 若要取得最新的情感功能支援，請使用語音轉換文字容器映像的 v2.6.0 和語言服務 v3.0。
從語音轉換文字容器的 v2.2.0 開始，您可以在輸出上呼叫情感分析 v3 API。 若要呼叫情感分析，您將需要語言服務 API 資源端點。 例如：
https://eastus.api.cognitive.microsoft.com/text/analytics/v3.0-preview.1/sentimenthttps://localhost:5000/text/analytics/v3.0-preview.1/sentiment
如果您要存取雲端中的語言服務端點，將需要金鑰。 如果您是在本機執行語言服務功能，可能不需要提供此金鑰。
金鑰和端點會以引數的形式傳遞至語音容器，如下列範例所示：
docker run -it --rm -p 5000:5000 \
mcr.microsoft.com/azure-cognitive-services/speechservices/speech-to-text:latest \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY} \
CloudAI:SentimentAnalysisSettings:TextAnalyticsHost={TEXT_ANALYTICS_HOST} \
CloudAI:SentimentAnalysisSettings:SentimentAnalysisApiKey={SENTIMENT_APIKEY}
此命令：
- 執行與前述命令相同的步驟。
- 儲存語言服務 API 端點和金鑰，以傳送情感分析要求。
語音轉換文字輸出上的 Phraselist v2
從語音轉文字容器的 v2.6.0 開始，您可以使用自己的片語取得輸出 (整個句子或中間的片語)。 例如，下列句子中的 the tall man：
- "This is a sentence the tall man this is another sentence."
若要設定片語清單，您必須在進行呼叫時新增自己的片語。 例如：
phrase="the tall man"
recognizer = speechsdk.SpeechRecognizer(
speech_config=dict_speech_config,
audio_config=audio_config)
phrase_list_grammer = speechsdk.PhraseListGrammar.from_recognizer(recognizer)
phrase_list_grammer.addPhrase(phrase)
dict_speech_config.set_service_property(
name='setflight',
value='xonlineinterp',
channel=speechsdk.ServicePropertyChannel.UriQueryParameter
)
如果您有多個要新增的片語，請為每個片語呼叫 .addPhrase()，以將其新增至片語清單。
重要事項
必須指定 Eula、Billing 及 ApiKey 選項以執行容器。 否則，容器將不會啟動。 如需詳細資訊，請參閱帳單。
在已中斷連線的環境中執行容器
您必須要求存取權，才能使用中斷網際網路連線的容器。 如需詳細資訊，請參閱要求可在已中斷連線環境中使用容器的存取權。
如需語音服務容器設定，請參閱 中斷連線的容器。
查詢容器的預測端點
注意
如果您正在執行多個容器，請使用唯一的連接埠號碼。
| 容器 | SDK 主機 URL | 通訊協定 |
|---|---|---|
| 標準語音轉換文字和自訂語音轉換文字 | ws://localhost:5000 |
WS |
| 類神經文字轉換語音，語音語言識別 | http://localhost:5000 |
HTTP |
如需使用 WSS 和 HTTPS 通訊協定的詳細資訊，請參閱容器安全性。
語音轉換文字 (標準和自訂)
容器會提供 Websocket 型查詢端點 API，可透過語音 SDK 來存取。 根據預設，語音 SDK 會使用線上語音服務。 若要使用容器，您必須變更初始化方法。
提示
搭配使用語音 SDK 與容器時，您不需要提供 Azure 語音資源訂用帳戶金鑰或驗證持有人權杖。
請參閱以下範例。
從使用此 Azure 雲端初始化呼叫變更：
var config = SpeechConfig.FromSubscription("YourSubscriptionKey", "YourServiceRegion");
若要搭配容器主機使用此呼叫：
var config = SpeechConfig.FromHost(
new Uri("ws://localhost:5000"));
分析情感
如果已將語言服務 API 認證提供給容器，您可以搭配情感分析使用語音 SDK 來傳送語音辨識要求。 您可以將 API 回應設定為使用「簡單」或「詳細」格式。
注意
語音服務 Python SDK 的 v1.13 具有情感分析的識別問題。 如果您是在語音服務 Python SDK 中使用情感分析，請使用 v1.12.x 或更早版本。
若要將語音用戶端設定為使用簡單格式，請將 "Sentiment" 新增為 Simple.Extensions 的值。 如果您想要選擇特定的語言服務模型版本，請取代 speechcontext-phraseDetection.sentimentAnalysis.modelversion 屬性設定中的 'latest'。
speech_config.set_service_property(
name='speechcontext-PhraseOutput.Simple.Extensions',
value='["Sentiment"]',
channel=speechsdk.ServicePropertyChannel.UriQueryParameter
)
speech_config.set_service_property(
name='speechcontext-phraseDetection.sentimentAnalysis.modelversion',
value='latest',
channel=speechsdk.ServicePropertyChannel.UriQueryParameter
)
Simple.Extensions 會在回應的根層中傳回情感結果。
{
"DisplayText":"What's the weather like?",
"Duration":13000000,
"Id":"6098574b79434bd4849fee7e0a50f22e",
"Offset":4700000,
"RecognitionStatus":"Success",
"Sentiment":{
"Negative":0.03,
"Neutral":0.79,
"Positive":0.18
}
}
如果您想要完全停用情感分析，請將 false 值新增至 sentimentanalysis.enabled。
speech_config.set_service_property(
name='speechcontext-phraseDetection.sentimentanalysis.enabled',
value='false',
channel=speechsdk.ServicePropertyChannel.UriQueryParameter
)
類神經文字轉換語音
容器會提供 REST 型端點 API。 平台、架構和語言變化有許多適用的範例原始程式碼專案。
使用類神經文字轉換語音容器時，您應依賴所下載之映像標籤的地區設定和語音。 例如，如果您已下載 latest 標籤，則預設地區設定為 en-US 和 AriaNeural 語音。 然後，{VOICE_NAME} 引數將是 en-US-AriaNeural。 請參閱下列範例 SSML：
<speak version="1.0" xml:lang="en-US">
<voice name="en-US-AriaNeural">
This text will get converted into synthesized speech.
</voice>
</speak>
在相同主機上執行多個容器
如果您打算使用公開的連接埠執行多個容器，請務必使用不同的公開連接埠來執行每個容器。 例如，在連接埠 5000 上執行第一個容器，以及在連接埠 5001 上執行第二個容器。
您可以讓此容器和不同的認知服務容器在主機上一起執行。 您也可以針對相同的認知服務容器執行多個容器。
驗證容器正在執行
有數種方式可驗證容器正在執行。 找出有問題容器的外部 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]。
疑難排解
當您啟動或執行容器時，可能會遇到問題。 請使用輸出裝載並啟用記錄。 這樣做可讓容器產生記錄檔，在您排解問題時派上用場。
提示
如需更多疑難排解資訊和指引，請參閱認知服務容器常見問題集 (FAQ)。
如果您在執行認知服務容器時遇到問題，則可以嘗試使用 Microsoft 診斷容器。 您可以使用此容器來診斷部署環境中的常見錯誤，這些錯誤可能會導致認知服務容器無法如預期般運作。
若要取得容器，請使用下列 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}
容器會測試帳單端點的網路連線能力。
計費
語音容器會使用您 Azure 帳戶上的「語音」資源，將計費資訊傳送至 Azure。
容器查詢按 ApiKey 參數所使用的 Azure 資源定價層計費。
Azure 認知服務容器在未連線至計量或計費端點的情況下，將無法獲得執行的授權。 您必須讓容器隨時都能與計量端點進行帳單資訊的通訊。 認知服務容器不會將客戶資料 (例如正在分析的影像或文字) 傳送至 Microsoft。
連線到 Azure
容器需要計費引數值才能執行。 這些值讓容器能夠連線到計費端點。 容器會每隔 10 到 15 分鐘回報使用量。 如果容器未在允許的時間範圍內連線到 Azure，容器會繼續執行，但在還原計費端點之前不會提供查詢。 以 10 到 15 分鐘的相同時間間隔嘗試連線 10 次。 如果無法在 10 次嘗試內連線到計費端點，則容器會停止回應要求。 請參閱認知服務容器常見問題，獲得需傳送哪些資訊給 Microsoft 以供計費的範例。
計費引數
當下列三個選項都填入了有效值時，docker run 命令將會啟動容器：
| 選項 | Description |
|---|---|
ApiKey |
用以追蹤計費資訊的認知服務資源 API 金鑰。 此選項值必須設定為已佈建 Billing 指定資源的 API 金鑰。 |
Billing |
用來追蹤計費資訊的認知服務資源端點。 此選項的值必須設定為已佈建 Azure 資源的端點 URI。 |
Eula |
表示您接受容器的授權。 此選項的值必須設定為接受。 |
如需這些選項的詳細資訊，請參閱設定容器。
總結
在本文中，您已了解如何下載、安裝及執行語音容器的概念和工作流程。 摘要說明：
- 語音提供四個適用於 Docker 的 Linux 容器，分別具備不同的功能：
- 語音轉文字
- 自訂語音轉換文字
- 類神經文字轉換語音
- 語音語言識別
- 容器映像是從 Azure 中的容器登錄下載。
- 容器映像是在 Docker 中執行。
- 無論您使用 REST API (僅文字轉換語音) 還是 SDK (語音轉換文字或文字轉換語音)，都要指定容器的主機 URI。
- 將容器具現化時，您必須提供計費資訊。
重要事項
認知服務容器在未連線至 Azure 進行計量的情況下，則不會獲得執行的授權。 客戶必須啟用容器以持續與計量服務進行帳單資訊的通訊。 認知服務容器不會將客戶資料 (例如正在分析的影像或文字) 傳送至 Microsoft。
後續步驟
- 檢閱設定容器以了解組態設定。
- 了解如何搭配 Kubernetes 和 Helm 使用語音服務容器。
- 使用更多認知服務容器。