適用于 JavaScript 的 Azure 文字分析用戶端程式庫 - 1.1.0 版

  • 發行項

適用于語言的 Azure 認知服務 是雲端式服務，可提供原始文字的進階自然語言處理，並包含下列主要功能：

注意： 此 SDK 的目標是適用于語言 API 2023-04-01 的 Azure 認知服務。

  • 語言偵測
  • 情感分析
  • 關鍵片語擷取
  • 具名實體辨識
  • 辨識個人識別資訊
  • 實體連結
  • 醫療保健分析
  • 擷取摘要
  • 抽象摘要
  • 自訂實體辨識
  • 自訂檔分類
  • 支援每份檔的多個動作

使用用戶端程式庫可以：

  • 偵測寫入的語言輸入文字。
  • 藉由分析原始文字以取得正面或負面情感的線索，來判斷客戶對品牌或主題的想法。
  • 自動擷取關鍵片語，以快速識別重點。
  • 將文字中的實體識別並分類為人員、地點、組織、日期/時間、數量、百分比、貨幣、醫療保健特定等等。
  • 一次執行多個上述工作。

重要連結：

從 @azure/ai-text-analytics 諮詢⚠ 移轉 ️

如需如何將 AI 文字分析 用戶端程式庫 5.x 版的應用程式程式碼更新至新的 AI 語言文字用戶端程式庫的詳細指示，請參閱移轉指南。

新功能

開始使用

目前支援的環境

如需詳細資訊，請參閱我們的支援原則。

必要條件

如果您使用 Azure CLI，請將 和 <your-resource-name> 取代 <your-resource-group-name> 為您自己的唯一名稱：

az cognitiveservices account create --kind TextAnalytics --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

安裝 @azure/ai-language-text 套件

使用 npm 安裝適用于 JavaScript 的 Azure 文字分析用戶端程式庫：

npm install @azure/ai-language-text

建立和驗證 TextAnalysisClient

若要建立用戶端物件來存取語言 API，您需要 endpoint 語言資源和 credential 的 。 文字分析用戶端可以使用 Azure Active Directory 認證或 API 金鑰認證來進行驗證。

您可以在 Azure 入口網站或 使用下列 Azure CLI 程式碼片段，找到語言資源的端點：

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "properties.endpoint"

使用 API 金鑰

使用 Azure 入口網站 流覽至您的語言資源並擷取 API 金鑰，或使用下列 Azure CLI 程式碼片段：

注意： 有時候 API 金鑰稱為「訂用帳戶金鑰」或「訂用帳戶 API 金鑰」。

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

擁有 API 金鑰和端點之後，您可以使用 AzureKeyCredential 類別來驗證用戶端，如下所示：

const { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-language-text");

const client = new TextAnalysisClient("<endpoint>", new AzureKeyCredential("<API key>"));

使用 Azure Active Directory 認證

用戶端 API 金鑰驗證用於大部分的範例中，但您也可以使用 Azure 身分識別程式庫向 Azure Active Directory 進行驗證。 若要使用如下所示的 DefaultAzureCredential 提供者，或其他 Azure SDK 提供的認證提供者，請安裝 @azure/identity 套件：

npm install @azure/identity

您也需要 註冊新的 AAD 應用程式 ，並將角色指派 "Cognitive Services User" 給服務主體來授與語言的存取權 (附注..其他角色，例如 "Owner" 不會授與必要的許可權，只會 "Cognitive Services User" 足以執行範例和範例程式碼) 。

將 AAD 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數： AZURE_CLIENT_ID 、、 AZURE_TENANT_IDAZURE_CLIENT_SECRET 。

const { TextAnalysisClient } = require("@azure/ai-language-text");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new TextAnalysisClient("<endpoint>", new DefaultAzureCredential());

重要概念

TextAnalysisClient

TextAnalysisClient 是開發人員使用文字分析用戶端程式庫的主要介面。 探索此用戶端物件上的方法，以瞭解您可以存取之語言服務的不同功能。

輸入

檔代表語言服務預測模型要分析的單一輸入單位。 上的 TextAnalysisClient 作業會接受要分析為批次的輸入集合。 作業方法具有多載，可讓輸入以字串表示，或做為具有附加中繼資料的物件。

例如，每個檔都可以當做陣列中的字串傳遞，例如

const documents = [
  "I hated the movie. It was so slow!",
  "The movie made it into my top ten favorites.",
  "What a great movie!",
];

或者，如果您想要傳入個別專案的檔 id 或 languagecountryHint/ ，則可以根據作業提供或 DetectLanguageInput 清單; TextDocumentInput

const textDocumentInputs = [
  { id: "1", language: "en", text: "I hated the movie. It was so slow!" },
  { id: "2", language: "en", text: "The movie made it into my top ten favorites." },
  { id: "3", language: "en", text: "What a great movie!" },
];

請參閱輸入 的服務限制 ，包括檔長度限制、批次大小上限和支援的文字編碼。

傳回值

對應至單一檔的傳回值是成功的結果或錯誤物件。 每個 TextAnalysisClient 方法都會傳回依索引對應至輸入的結果和錯誤的異質陣列。 文字輸入及其結果在輸入和結果集合中會有相同的索引。

例如SentimentAnalysisResult 的結果是語言作業的結果，其中包含單一文字輸入的預測或預測。 作業的結果類型也可以選擇性地包含輸入檔的相關資訊及其處理方式。

error物件 TextAnalysisErrorResult 表示服務在處理檔時發生錯誤，並包含錯誤的相關資訊。

檔錯誤處理

在作業傳回的集合中，如果發生錯誤，錯誤會與屬性是否存在 error 而區分為成功的回應，其中包含內部 TextAnalysisError 物件。 對於成功的結果物件，這個屬性一律undefined 為 。

例如，若要篩選掉所有錯誤，您可以使用下列 filter 專案：

const results = await client.analyze("SentimentAnalysis", documents);
const onlySuccessful = results.filter((result) => result.error === undefined);

注意：如果 compilerOptions.strictNullCheckstrue 設定為 tsconfig.json ，TypeScript 使用者可以受益于更妥善地檢查結果和錯誤物件。 例如：

const [result] = await client.analyze("SentimentAnalysis", ["Hello world!"]);

if (result.error !== undefined) {
  // In this if block, TypeScript will be sure that the type of `result` is
  // `TextAnalysisError` if compilerOptions.strictNullChecks is enabled in
  // the tsconfig.json

  console.log(result.error);
}

範例

用戶端使用方式

預先建置的工作

自訂工作

疑難排解

記錄

啟用記錄有助於找出失敗的相關實用資訊。 若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

下一步

如需如何使用此程式庫的詳細範例，請參閱 範例 目錄。

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數