適用於 JavaScript 的 Azure 文字分析用戶端連結庫 - 1.1.0 版

  • 發行項

Azure Cognitive Service for Language 是雲端式服務，可提供原始文字的進階自然語言處理，並包含下列主要功能：

注意： 此 SDK 以 Azure 認知服務為語言 API 版本 2023-04-01 為目標。

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

使用用戶端連結庫來：

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

主要連結：

從 諮詢移轉 ️

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

新功能

開始

目前支持的環境

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

先決條件

  • Azure 訂用帳戶。
  • 現有的 認知服務 或語言資源。 如果您需要建立資源，您可以使用 Azure 入口網站 或 Azure CLI 遵循本文件中的步驟 。

如果您使用 Azure CLI，請使用您自己的唯一名稱取代 <your-resource-group-name> 和 <your-resource-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_ID、AZURE_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 或 language/countryHint，則可以根據作業指定為 TextDocumentInput 或 DetectLanguageInput 清單：

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，是語言作業的結果，其中包含單一文字輸入的預測或預測。 作業的結果類型也可以選擇性地包含輸入文件的相關信息及其處理方式。

錯誤 物件 TextAnalysisErrorResult，表示服務處理檔時發生錯誤，並包含錯誤的相關信息。

檔案錯誤處理

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

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

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

附注：如果 compilerOptions.strictNullChecks 設定為 tsconfig.json 組態中的 true，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/記錄器套件檔。

後續步驟

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

貢獻

如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。

印象