適用於 JavaScript 的 Azure 文字分析用戶端連結庫 - 5.1.0 版
Azure TextAnalytics 是雲端式服務，可提供原始文字的進階自然語言處理，並包含六個主要功能：
注意： 此 SDK 以 Azure 文字分析服務 API 3.1.0 版為目標。
- 語言偵測
- 情感分析
- 關鍵片語擷取
- 具名實體辨識
- 辨識個人標識資訊
- 鏈接實體辨識
- 醫療保健分析
- 支援每個檔案的多個動作
使用用戶端連結庫來：
- 偵測寫入的語言輸入文字。
- 分析原始文字以找出正面或負面情感的線索，以判斷客戶對品牌或主題的看法。
- 自動擷取關鍵詞組，以快速識別主要點。
- 將文字中的實體識別並分類為人員、地點、組織、日期/時間、數量、百分比、貨幣、醫療保健特定等等。
- 一次執行上述多項工作。
主要連結：
開始
目前支持的環境
- LTS 版本的 Node.js
- 最新版的 Safari、Chrome、Edge 和 Firefox。
如需詳細資訊，請參閱我們的 支持原則。
先決條件
- 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-text-analytics 套件
使用 npm安裝適用於 JavaScript 的 Azure 文字分析用戶端連結庫：
npm install @azure/ai-text-analytics
建立和驗證 TextAnalyticsClient
若要建立客戶端物件來存取文字分析 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 "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 { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<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 { TextAnalyticsClient } = require("@azure/ai-text-analytics");
const { DefaultAzureCredential } = require("@azure/identity");
const client = new TextAnalyticsClient("<endpoint>", new DefaultAzureCredential());
重要概念
TextAnalyticsClient
TextAnalyticsClient 是開發人員使用文字分析用戶端連結庫的主要介面。 探索此客戶端物件上的方法，以瞭解您可以存取之文字分析服務的不同功能。
輸入
檔 代表文字分析服務中預測模型要分析的單一輸入單位。
TextAnalyticsClient 的作業會採用要分析為批次的輸入集合。 作業方法具有多載，可讓輸入表示為字串，或做為具有附加元數據的物件。
例如，每個檔都可以當做陣列中的字串傳遞，例如
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!" }
];
如需輸入，請參閱 服務限制，包括文件長度限制、批次大小上限和支援的文字編碼。
傳回值
對應至單一檔的傳回值是成功的結果或錯誤物件。 每個 TextAnalyticsClient 方法都會傳回一個異質性陣列，這些結果和錯誤會依索引對應至輸入。 文字輸入及其結果在輸入和結果集合中會有相同的索引。 集合也可以選擇性地包含輸入批次的相關信息，以及該批次在 [statistics] 字段中的處理方式。
結果，例如 AnalyzeSentimentResult，是文字分析作業的結果，其中包含單一文字輸入的預測或預測。 作業的結果類型也可以選擇性地包含輸入文件的相關信息及其處理方式。
錯誤 物件 TextAnalyticsErrorResult，表示服務處理檔時發生錯誤，並包含錯誤的相關信息。
檔案錯誤處理
在作業傳回的集合中，如果發生錯誤，則錯誤會因 error 屬性的存在而區分錯誤，其中包含內部 TextAnalyticsError 物件。 對於成功的結果物件，此屬性 一律undefined。
例如，若要篩選掉所有錯誤，您可以使用下列 filter：
const results = await client.analyzeSentiment(documents);
const onlySuccessful = results.filter((result) => result.error === undefined);
附注：如果 compilerOptions.strictNullChecks 設定為 tsconfig.json 組態中的 true，TypeScript 使用者可以從更好的結果和錯誤對象類型檢查中獲益。 例如：
const [result] = await client.analyzeSentiment(["Hello world!"]);
if (result.error !== undefined) {
// In this if block, TypeScript will be sure that the type of `result` is
// `TextAnalyticsError` if compilerOptions.strictNullChecks is enabled in
// the tsconfig.json
console.log(result.error);
}
這項功能是在 TypeScript 3.2 中引進的，因此 TypeScript 3.1 的使用者必須將結果值轉換成其對應的成功變體，如下所示：
const [result] = await client.detectLanguage(["Hello world!"]);
if (result.error === undefined) {
const { primaryLanguage } = result as DetectLanguageSuccessResult;
}
例子
分析情感
分析文字的情感，以判斷其是否為正面、負面、中性或混合，包括每一句子情感分析和信賴分數。
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"I did not like the restaurant. The food was too spicy.",
"The restaurant was decorated beautifully. The atmosphere was unlike any other restaurant I've been to.",
"The food was yummy. :)"
];
async function main() {
const results = await client.analyzeSentiment(documents);
for (const result of results) {
if (result.error === undefined) {
console.log("Overall sentiment:", result.sentiment);
console.log("Scores:", result.confidenceScores);
} else {
console.error("Encountered an error:", result.error);
}
}
}
main();
若要取得與產品/服務層面相關意見的更細微資訊，也稱為自然語言處理中的以層面為基礎的情感分析（NLP），請參閱這裡
辨識實體
將文字中的實體辨識並分類為人員、地點、組織、日期/時間、數量、貨幣等。
language 參數是選擇性的。 如果未指定，則會使用預設英文模型。
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"Microsoft was founded by Bill Gates and Paul Allen.",
"Redmond is a city in King County, Washington, United States, located 15 miles east of Seattle.",
"Jeff bought three dozen eggs because there was a 50% discount."
];
async function main() {
const results = await client.recognizeEntities(documents, "en");
for (const result of results) {
if (result.error === undefined) {
console.log(" -- Recognized entities for input", result.id, "--");
for (const entity of result.entities) {
console.log(entity.text, ":", entity.category, "(Score:", entity.confidenceScore, ")");
}
} else {
console.error("Encountered an error:", result.error);
}
}
}
main();
辨識 PII 實體
在社會安全號碼、銀行帳戶資訊、信用卡號碼等文字中，有個別的端點和作業可辨識個人標識資訊（PII）。其使用方式與上述標準實體辨識非常類似：
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"The employee's SSN is 555-55-5555.",
"The employee's phone number is (555) 555-5555."
];
async function main() {
const results = await client.recognizePiiEntities(documents, "en");
for (const result of results) {
if (result.error === undefined) {
console.log(" -- Recognized PII entities for input", result.id, "--");
for (const entity of result.entities) {
console.log(entity.text, ":", entity.category, "(Score:", entity.confidenceScore, ")");
}
} else {
console.error("Encountered an error:", result.error);
}
}
}
main();
辨識連結實體
「鏈接」實體是知識庫中存在的實體（例如維琪百科）。
recognizeLinkedEntities 作業可以藉由判斷他們可能參考的知識庫中的專案來釐清實體（例如，在一段文字中，“火星”一詞是指地球，或羅馬戰爭之神）。 鏈接的實體包含提供實體定義之知識庫的相關聯 URL。
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"Microsoft was founded by Bill Gates and Paul Allen.",
"Easter Island, a Chilean territory, is a remote volcanic island in Polynesia.",
"I use Azure Functions to develop my product."
];
async function main() {
const results = await client.recognizeLinkedEntities(documents, "en");
for (const result of results) {
if (result.error === undefined) {
console.log(" -- Recognized linked entities for input", result.id, "--");
for (const entity of result.entities) {
console.log(entity.name, "(URL:", entity.url, ", Source:", entity.dataSource, ")");
for (const match of entity.matches) {
console.log(
" Occurrence:",
'"' + match.text + '"',
"(Score:",
match.confidenceScore,
")"
);
}
}
} else {
console.error("Encountered an error:", result.error);
}
}
}
main();
擷取關鍵詞組
關鍵片語擷取會識別檔中的主要交談點。 例如，假設輸入文字「食物很美味，而且有精彩的員工」，服務會傳回「食物」和「美妙的員工」。
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"Redmond is a city in King County, Washington, United States, located 15 miles east of Seattle.",
"I need to take my cat to the veterinarian.",
"I will travel to South America in the summer."
];
async function main() {
const results = await client.extractKeyPhrases(documents, "en");
for (const result of results) {
if (result.error === undefined) {
console.log(" -- Extracted key phrases for input", result.id, "--");
console.log(result.keyPhrases);
} else {
console.error("Encountered an error:", result.error);
}
}
}
main();
偵測語言
判斷一段文字的語言。
countryHint 參數是選擇性的，但如果已知來源國家/地區，可協助服務提供正確的輸出。 如果提供，它應該設定為 ISO-3166 Alpha-2 雙字母國家/地區代碼（例如美國為 “us” 或 “jp” for Japan），或設定為值 "none"。 如果未提供 參數，則會使用預設 "us" （美國） 模型。 如果您不知道檔的原點國家/地區，則應該使用參數 "none"，而文字分析服務會套用已針對未知來源國家/地區進行調整的模型。
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"This is written in English.",
"Il documento scritto in italiano.",
"Dies ist in deutscher Sprache verfasst."
];
async function main() {
const results = await client.detectLanguage(documents, "none");
for (const result of results) {
if (result.error === undefined) {
const { primaryLanguage } = result;
console.log(
"Input #",
result.id,
"identified as",
primaryLanguage.name,
"( ISO6391:",
primaryLanguage.iso6391Name,
", Score:",
primaryLanguage.confidenceScore,
")"
);
} else {
console.error("Encountered an error:", result.error);
}
}
}
main();
分析醫療保健實體
醫療保健分析會識別醫療保健實體。 例如，假設輸入文字 「Prescribed 100mg ibuprofen， 每日服用兩次」 服務會傳回 「100mg」 分類為劑量，“ibuprofen” 分類為 MedicationName，而 “兩次每日”則傳回 Frequency。
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"Prescribed 100mg ibuprofen, taken twice daily.",
"Patient does not suffer from high blood pressure."
];
async function main() {
const poller = await client.beginAnalyzeHealthcareEntities(documents);
const results = await poller.pollUntilDone();
for await (const result of results) {
console.log(`- Document ${result.id}`);
if (!result.error) {
console.log("\tRecognized Entities:");
for (const entity of result.entities) {
console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
}
} else console.error("\tError:", result.error);
}
}
main();
分析動作
分析動作可讓您一次應用多個分析（具名動作）。
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
"Microsoft was founded by Bill Gates and Paul Allen.",
"The employee's SSN is 555-55-5555.",
"Easter Island, a Chilean territory, is a remote volcanic island in Polynesia.",
"I use Azure Functions to develop my product."
];
async function main() {
const actions = {
recognizeEntitiesActions: [{ modelVersion: "latest" }],
recognizePiiEntitiesActions: [{ modelVersion: "latest" }],
extractKeyPhrasesActions: [{ modelVersion: "latest" }]
};
const poller = await client.beginAnalyzeActions(documents, actions);
const resultPages = await poller.pollUntilDone();
for await (const page of resultPages) {
const keyPhrasesAction = page.extractKeyPhrasesResults[0];
if (!keyPhrasesAction.error) {
for (const doc of keyPhrasesAction.results) {
console.log(`- Document ${doc.id}`);
if (!doc.error) {
console.log("\tKey phrases:");
for (const phrase of doc.keyPhrases) {
console.log(`\t- ${phrase}`);
}
} else {
console.error("\tError:", doc.error);
}
}
}
const entitiesAction = page.recognizeEntitiesResults[0];
if (!entitiesAction.error) {
for (const doc of entitiesAction.results) {
console.log(`- Document ${doc.id}`);
if (!doc.error) {
console.log("\tEntities:");
for (const entity of doc.entities) {
console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
}
} else {
console.error("\tError:", doc.error);
}
}
}
const piiEntitiesAction = page.recognizePiiEntitiesResults[0];
if (!piiEntitiesAction.error) {
for (const doc of piiEntitiesAction.results) {
console.log(`- Document ${doc.id}`);
if (!doc.error) {
console.log("\tPii Entities:");
for (const entity of doc.entities) {
console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
}
} else {
console.error("\tError:", doc.error);
}
}
}
}
}
main();
故障排除
伐木
啟用記錄可能有助於找出有關失敗的實用資訊。 若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在運行時間啟用記錄，方法是在 @azure/logger中呼叫 setLogLevel：
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
如需如何啟用記錄的詳細指示，請參閱
後續步驟
如需如何使用此連結庫的詳細範例，請參閱 範例 目錄。
貢獻
如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。
相關專案
