這很重要
- Azure AI 語言公開預覽版本提供了正在開發期間之功能的早期存取權。
- 根據使用者意見反應，在正式運作之前，功能、方法和程式可能會變更。
Azure AI 語言是一項雲端式服務，它將自然語言處理 (NLP) 功能應用於文字型資料。 文件摘要會使用自然語言處理來產生文件的擷取 (主要句子擷取) 或抽象 (內容文字擷取) 摘要。
AbstractiveSummarization 和 ExtractiveSummarization API 皆支援原生文件處理。 原生文件是指用來建立原始文件的檔案格式，例如 Microsoft Word (docx) 或可攜式文件檔案 (pdf)。 原生文件支援代表在使用 Azure AI 語言資源功能之前，不再需要進行文字前置處理。 原生文件支援功能可讓您非同步傳送 API 要求，使用 HTTP POST 要求本文傳送資料並使用 HTTP GET 要求查詢字串來擷取狀態結果。 已處理的文件位於您的 Azure Blob 儲存體目標容器中。
支援的文件格式
應用程式會使用原生檔案格式來建立、儲存或開啟原生文件。 目前 PII 和文件摘要功能支援下列原生文件格式：
| 檔案類型 | 副檔名 | 描述 |
|---|---|---|
| 文字 | .txt |
未格式化的文字文件。 |
| Adobe PDF | .pdf |
可攜式文件檔案格式的文件。 |
| Microsoft Word | .docx |
Microsoft Word 文件檔案。 |
輸入指導方針
支援的檔案格式
| 類型 | 支援和限制 |
|---|---|
| 不支援完整掃描的 PDF。 | |
| 影像中的文字 | 不支援內嵌文字的數位影像。 |
| 數位資料表 | 不支援掃描文件中的資料表。 |
文件大小
| 屬性 | 輸入限制 |
|---|---|
| 每個要求的文件總數 | 不超過 20 個 |
| 每個要求的內容大小總計 | ≤ 10 MB |
使用 HTTP 要求包含原生文件
現在就開始吧：
在此專案中，我們使用 cURL 命令列工具來進行 REST API 呼叫。
備註
cURL 套件已預安裝於大部分的 Windows 10 和 Windows 11 和大部分 macOS 和 Linux 發行版上。 您可以使用下列命令來檢查套件版本：Windows：
curl.exe -VmacOScurl -VLinux：curl --version如果未安裝 cURL，則以下是適用於您的平台的安裝連結：
Azure Blob 儲存帳戶。 您也必須在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器：
- 來源容器。 可會在此容器中上傳要分析的原生檔案 (必要)。
- 目標容器。 此容器是分析的檔案所將儲存之處 (必要)。
單一服務語言資源（不是多服務 Azure AI Foundry 資源）：
完成語言資源專案和執行個體詳細資料欄位，如下所示：
訂用帳戶。 選取您可用的一個 Azure 訂用帳戶。
資源群組。 您可以建立新的資源群組，或將資源新增至共用相同生命週期、許可權和原則的預先存在資源群組。
資源區域。 除非您的業務或應用程式需要特定區域，否則請選擇 [全域]。 如果您打算使用系統指派的受控識別 進行驗證，請選擇地理區域，例如美國西部。
名稱. 輸入您為資源選擇的名稱。 您所選擇的名稱在 Azure 中必須是唯一的。
定價層。 您可以使用免費定價層 (
Free F0) 來試用服務，之後可升級至付費層以用於實際執行環境。按一下 檢閱 + 建立。
檢閱服務條款，然後選取 [建立] 以部署資源。
成功部署資源之後，請選取 [移至資源]。
擷取金鑰和語言服務端點
對語言服務的要求需要唯讀金鑰和自訂端點，才能驗證存取權。
當您建立新資源後，部署完成後，請選取 前往資源。 如果您擁有現有的語言服務資源，請直接瀏覽至您的資源頁面。
在左側滑軌中，於 [資源管理] 下選取 [金鑰和端點]。
您可以複製
key和language service instance endpoint並將其貼到程式碼範例中，以驗證您對語言服務的要求。 呼叫 API 只需一把金鑰。
建立 Azure Blob 儲存體容器
在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器。
- 來源容器。 可會在此容器中上傳要分析的原生檔案 (必要)。
- 目標容器。 此容器是分析的檔案所將儲存之處 (必要)。
驗證
您的語言資源需要授與對儲存體帳戶的存取權，才能建立、讀取或刪除 Blob。 有兩個主要方法可用來授與儲存體資料的存取權：
共用存取簽章 (SAS) 權杖。 會使用 Microsoft Entra 認證來保護使用者委派 SAS 權杖。 SAS 權杖會對您 Azure 儲存體帳戶中的資源提供安全的委派存取權。
受控識別角色型存取控制 (RBAC)。 適用於 Azure 資源的受控識別是一種服務主體，其會建立 Microsoft Entra 身分識別和 Azure 受控資源的特定權限。
在此專案中，我們會使用附加為查詢字串的共用存取簽章 (SAS) 權杖，驗證對 source location 和 target location URL 的存取權。 每個權杖都會指派給特定的 Blob (檔案)。
- 您的來源容器或 Blob 必須具有指定的讀取和列出存取權。
- 您的目標容器或 Blob 必須具有指定的寫入和列出存取權。
擷取式摘要 API 會使用自然語言處理技術來尋找非結構化文字文件中的主要句子。 這些句子會共同傳達文件的主要概念。
擷取式摘要會傳回排名分數做為系統回應的一部分，以及在原始文件中擷取的句子和其位置。 排名分數是判斷句子相關程度以及與文件主要概念相關程度的指標。 此模型會針對每個句子提供 0 到 1 (含) 之間的分數，並傳回每個要求的最高評分句子。 例如，如果您要求三個句子的摘要，則服務會傳回三個最高評分的句子。
Azure AI 語言中有另一項功能 (關鍵片語擷取)，可擷取重要資訊。 若要決定關鍵詞組擷取和擷取摘要，以下是實用的考慮：
- 關鍵片語擷取會在擷取式摘要傳回句子時傳回片語。
- 擷取式摘要會連同排名分數一起傳回句子，而且每個要求都會傳回排名最高的句子。
- 擷取式摘要也傳回下列位置資訊：
- 位移：每個所擷取句子的開始位置。
- 長度：每個所擷取句子的長度。
決定如何處理資料 (選擇性)
提交資料
您會以文字字串形式將文件提交至 API。 分析會在接收要求時執行。 因為 API 為非同步，所以傳送 API 要求與接收結果之間可能會有延遲。
當您使用這項功能時，API 結果可從要求內嵌的時間起 24 小時內提供使用，且會在回應中指出。 在這段時間之後，結果將會予以清除，且無法再供擷取。
取得文字摘要結果
在取得語言偵測的結果後，您可以將結果串流至應用程式，或將輸出儲存到本機系統上的檔案。
以下是一個您可能會提交的摘要內容範例，摘自 Microsoft 部落格文章 整合 AI 的全貌呈現。 本文只是一個範例。 API 可以接受較長的輸入文字。 如需詳細資訊， 請參閱數據和服務限制。
「在 Microsoft，我們不斷學習和了解更全面、以人為中心的方法，追求讓 AI 超越現有的技術。 身為 Azure AI 服務的技術長，我一直致力於與優秀的科學家和工程師合作，將這項追求轉變成現實。 在我的角色中，我熱衷於觀察人類認知的三個屬性 (單一語言文字 (X)、音訊或視覺效果感應式信號 (Y) 和多語系 (Z)) 之間的關係，並擁有獨特的觀點。 在這三者之間的交集中，存在著一種我們稱為 XYZ 代碼的魔法，如[圖 1]所示，這是一種聯合表示法，可以創造出更強大的 AI，能更好地說話、聆聽、觀察和理解人類。 我們相信 XYZ 程式碼可讓我們達成長期願景: 跨網域傳輸學習、跨形式和語言。 其目標是要具備預先定型模型，這些模型可共同學習標記法，以支援各式各樣的下游 AI 工作，幾乎像是如今人類所為一樣。 過去五年來，我們已在交談式語音辨識、機器翻譯、交談式問題解答、電腦閱讀理解和影像字幕方面達成了人類的效能評定表現。 這五項突破強烈預示著我們的雄心壯志將引發 AI 功能大躍進，實現多重感官和多語系學習，更接近人類學習和理解的方式。 我相信共同 XYZ 程式碼是這個志向的基石 (如果與下游 AI 工作中的外部知識來源搭配使用)。
文字摘要 API 要求會在收到要求時，透過建立 API 後端的作業來處理。 如果作業成功，則會傳回 API 的輸出。 輸出將可供擷取 24 小時。 在這段時間之後，就會清除輸出。 由於多語系和表情符號的支援，回應可能會包含文字位移。 如需詳細資訊， 請參閱如何處理位移。
當您使用上述範例時，API 可能會傳回這些摘要句子：
擷取式摘要：
- 「在 Microsoft，我們不斷學習和了解更全面、以人為中心的方法，追求讓 AI 超越現有的技術。」
- 「我們相信 XYZ 程式碼可讓我們達成長期願景: 跨網域傳輸學習、跨形式和語言。」
- 「其目標是要具備預先定型模型，這些模型可共同學習標記法，以支援各式各樣的下游 AI 工作，幾乎像是如今人類所為一樣。」
抽象式摘要：
- 「Microsoft 正在對學習和理解採用更全面、以人為中心的方法。 我們相信 XYZ 程式碼可讓我們達成長期願景: 跨網域傳輸學習、跨形式和語言。 在過去五年，我們已在基準測試方面達成人為表現。」
嘗試文字擷取摘要
您可以使用文字擷取式摘要來取得文章、論文或文件的摘要。 若要查看範例，請參閱快速入門文章。
您可以使用 sentenceCount 參數來指定傳回的句子數目，預設值為 3。 範圍是從 1 到 20。
您也可以使用 sortby 參數來指定要傳回已擷取句子的順序，也就是 Offset 或 Rank，預設值為 Offset。
| 參數值 | 描述 |
|---|---|
| 順位 | 根據服務所決定的輸入文件相關性來排序句子。 |
| 位移 | 保留句子在輸入文件中出現的原始順序。 |
文字抽象式摘要
下列範例會讓您開始使用文字抽象摘要:
- 將下列 命令複製到文字編輯器。 BASH 範例會使用
\行接續字元。 如果您的主控台或終端使用不同的行接續字元，請改為使用該字元。
curl -i -X POST https://<your-language-resource-endpoint>/language/analyze-text/jobs?api-version=2023-04-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
'
{
"displayName": "Text Abstractive Summarization Task Example",
"analysisInput": {
"documents": [
{
"id": "1",
"language": "en",
"text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Azure AI services, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
}
]
},
"tasks": [
{
"kind": "AbstractiveSummarization",
"taskName": "Text Abstractive Summarization Task 1",
}
]
}
'
視需要在命令中進行下列變更：
- 將
your-language-resource-key值取代為您的金鑰。 - 將要求 URL
your-language-resource-endpoint的第一個部分取代為您的端點 URL。
- 將
開啟命令提示字元視窗 (例如：BASH)。
將文字編輯器中的命令貼到命令提示字元視窗中，然後執行該命令。
從回應標頭取得
operation-location。 值看起來會類似下列 URL：
https://<your-language-resource-endpoint>/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-10-01-preview
- 若要取得要求的結果，請使用下列 cURL 命令。 請務必將
<my-job-id>取代為您從先前的operation-location回應標頭收到的數字識別碼數值：
curl -X GET https://<your-language-resource-endpoint>/language/analyze-text/jobs/<my-job-id>?api-version=2022-10-01-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>"
抽象式文字摘要範例 JSON 回應
{
"jobId": "cd6418fe-db86-4350-aec1-f0d7c91442a6",
"lastUpdateDateTime": "2022-09-08T16:45:14Z",
"createdDateTime": "2022-09-08T16:44:53Z",
"expirationDateTime": "2022-09-09T16:44:53Z",
"status": "succeeded",
"errors": [],
"displayName": "Text Abstractive Summarization Task Example",
"tasks": {
"completed": 1,
"failed": 0,
"inProgress": 0,
"total": 1,
"items": [
{
"kind": "AbstractiveSummarizationLROResults",
"taskName": "Text Abstractive Summarization Task 1",
"lastUpdateDateTime": "2022-09-08T16:45:14.0717206Z",
"status": "succeeded",
"results": {
"documents": [
{
"summaries": [
{
"text": "Microsoft is taking a more holistic, human-centric approach to AI. We've developed a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We've achieved human performance on benchmarks in conversational speech recognition, machine translation, ...... and image captions.",
"contexts": [
{
"offset": 0,
"length": 247
}
]
}
],
"id": "1"
}
],
"errors": [],
"modelVersion": "latest"
}
}
]
}
}
| 參數 | 描述 |
|---|---|
-X POST <endpoint> |
指定用於存取 API 的語言資源端點。 |
--header Content-Type: application/json |
用於傳送 JSON 資料的內容類型。 |
--header "Ocp-Apim-Subscription-Key:<key> |
指定用於存取 API 的語言資源金鑰。 |
-data |
包含您想要隨要求傳遞之資料的 JSON 檔案。 |
下列 cURL 命令是從 BASH 殼層執行。 使用您自己的資源名稱、資源金鑰和 JSON 值來編輯這些命令。 透過選取 Personally Identifiable Information (PII) 或 Document Summarization 範例程式碼專案，嘗試分析原生文件：
摘要範例文件
針對此專案，您需要上傳至來源容器的來源文件。 您可以為此快速入門下載 Microsoft Word 範例文件或 Adobe PDF。 來源語言為英文。
建置 POST 要求
使用您慣用的編輯器或 IDE，為名為
native-document的應用程式建立新目錄。在您的原生文件目錄中，建立名為 document-summarization.json 的新 JSON 檔案。
複製文件摘要要求範例並貼入
document-summarization.json檔案。 使用 Azure 入口網站儲存體帳戶容器執行個體的值取代{your-source-container-SAS-URL}和{your-target-container-SAS-URL}：
要求範例
{
"tasks": [
{
"kind": "ExtractiveSummarization",
"parameters": {
"sentenceCount": 6
}
}
],
"analysisInput": {
"documents": [
{
"source": {
"location": "{your-source-blob-SAS-URL}"
},
"targets": {
"location": "{your-target-container-SAS-URL}"
}
}
]
}
}
執行 POST 要求
執行 POST 要求之前，請使用 Azure 入口網站語言資源執行個體的端點值取代 {your-language-resource-endpoint} 和 {your-key}。
這很重要
完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性。
PowerShell
cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"
命令提示字元/終端機
curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"
回應範例：
HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2024-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT
POST 回應 (jobId)
您收到 202 (Success) 回應，其中包含唯讀 Operation-Location 標頭。 此標頭的值包含 jobId，可透過查詢以取得非同步作業的狀態，並且可使用 GET 要求來擷取結果：
取得分析結果 (GET 要求)
成功完成 POST 要求之後，請輪詢 POST 要求中傳回的 operation-location 標頭，以檢視已處理的資料。
以下是 GET 要求的結構：
GET {cognitive-service-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview執行命令之前，請進行下列變更：
將 {jobId} 取代為 POST 回應中的 Operation-Location 標頭。
將 {your-language-resource-endpoint} 和 {your-key} 取代為 Azure 入口網站中語言服務執行個體的值。
取得要求
cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"
curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"
檢視回應
您收到 200 (Success) 回應及 JSON 輸出。 狀態欄位會指出作業的結果。 如果作業未完成，狀態的值將會是 "running" 或 "notStarted"，此時您應該以手動方式或透過指令碼再次呼叫 API。 我們建議您在每次呼叫之間間隔一秒或更長的時間。
範例回應
{
"jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
"lastUpdatedDateTime": "2024-01-24T13:17:58Z",
"createdDateTime": "2024-01-24T13:17:47Z",
"expirationDateTime": "2024-01-25T13:17:47Z",
"status": "succeeded",
"errors": [],
"tasks": {
"completed": 1,
"failed": 0,
"inProgress": 0,
"total": 1,
"items": [
{
"kind": "ExtractiveSummarizationLROResults",
"lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
"status": "succeeded",
"results": {
"documents": [
{
"id": "doc_0",
"source": {
"kind": "AzureBlob",
"location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
},
"targets": [
{
"kind": "AzureBlob",
"location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/ExtractiveSummarization-0001/input.result.json"
}
],
"warnings": []
}
],
"errors": [],
"modelVersion": "2023-02-01-preview"
}
}
]
}
}
成功完成時：
- 已分析的文件可在您的目標容器中找到。
- 成功的 POST 方法會傳回
202 Accepted回應碼，指出服務已建立批次要求。 - POST 要求也會傳回回應標頭，包括提供後續 GET 要求中使用的值的
Operation-Location。
清理資源
如果您想要清除和移除 Azure AI 服務訂用帳戶，則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。