共用方式為


適用於 JavaScript 的 Azure 文字分析用戶端連結庫 - 6.0.0-beta.1 版

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

注意: 此 SDK 以 Azure 認知服務為語言 API 版本 2022-04-01-preview。

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

使用用戶端連結庫來:

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

主要連結:

開始

目前支持的環境

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

先決條件

如果您使用 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

建立和驗證 TextAnalysisClient

若要建立客戶端物件以存取語言 API,您需要語言資源的 endpointcredential。 文字分析用戶端可以使用 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-text-analytics");

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_IDAZURE_TENANT_IDAZURE_CLIENT_SECRET

const { TextAnalysisClient } = require("@azure/ai-text-analytics");
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!",
];

或者,如果您想要傳入個別項目檔 idlanguage/countryHint,則可以根據作業指定為 TextDocumentInputDetectLanguageInput 清單:

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);
}

例子

情感分析

分析文字的情感,以判斷其是否為正面、負面、中性或混合,包括每一句子情感分析和信賴分數。

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

const client = new TextAnalysisClient("<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.analyze("SentimentAnalysis", 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 { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalysisClient("<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.analyze("EntityRecognition", 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 { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalysisClient("<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.analyze("PiiEntityRecognition", 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();

實體連結

「鏈接」實體是知識庫中存在的實體(例如維琪百科)。 EntityLinking 動作可以藉由判斷他們可能參考的知識庫中的專案來釐清實體(例如,在一段文字中,“火星”一詞是指行星或羅馬戰爭之神)。 鏈接的實體包含提供實體定義之知識庫的相關聯 URL。

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

const client = new TextAnalysisClient("<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.analyze("EntityLinking", 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 { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalysisClient("<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.analyze("KeyPhraseExtraction", 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 { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalysisClient("<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.analyze("LanguageDetection", 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 {
  AnalyzeBatchAction,
  AzureKeyCredential,
  TextAnalysisClient,
} = require("@azure/ai-text-analytics");

const client = new TextAnalysisClient("<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 actions: AnalyzeBatchAction[] = [
    {
      kind: "Healthcare",
    },
  ];
  const poller = await client.beginAnalyzeBatch(actions, documents, "en");
  const results = await poller.pollUntilDone();
  for await (const actionResult of results) {
    if (actionResult.kind !== "Healthcare") {
      throw new Error(`Expected a healthcare results but got: ${actionResult.kind}`);
    }
    if (actionResult.error) {
      const { code, message } = actionResult.error;
      throw new Error(`Unexpected error (${code}): ${message}`);
    }
    for (const result of actionResult.results) {
      console.log(`- Document ${result.id}`);
      if (result.error) {
        const { code, message } = result.error;
        throw new Error(`Unexpected error (${code}): ${message}`);
      }
      console.log("\tRecognized Entities:");
      for (const entity of result.entities) {
        console.log(`\t- Entity "${entity.text}" of type ${entity.category}`);
        if (entity.dataSources.length > 0) {
          console.log("\t and it can be referenced in the following data sources:");
          for (const ds of entity.dataSources) {
            console.log(`\t\t- ${ds.name} with Entity ID: ${ds.entityId}`);
          }
        }
      }
    }
  }
}

main();

擷取摘要

擷取摘要會識別摘要所屬文章的句子。

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

const client = new TextAnalysisClient("<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 actions: AnalyzeBatchAction[] = [
    {
      kind: "ExtractiveSummarization",
      maxSentenceCount: 2,
    },
  ];
  const poller = await client.beginAnalyzeBatch(actions, documents, "en");
  const results = await poller.pollUntilDone();

  for await (const actionResult of results) {
    if (actionResult.kind !== "ExtractiveSummarization") {
      throw new Error(`Expected extractive summarization results but got: ${actionResult.kind}`);
    }
    if (actionResult.error) {
      const { code, message } = actionResult.error;
      throw new Error(`Unexpected error (${code}): ${message}`);
    }
    for (const result of actionResult.results) {
      console.log(`- Document ${result.id}`);
      if (result.error) {
        const { code, message } = result.error;
        throw new Error(`Unexpected error (${code}): ${message}`);
      }
      console.log("Summary:");
      console.log(result.sentences.map((sentence) => sentence.text).join("\n"));
    }
  }
}

main();

自定義實體辨識

使用使用 azure Language Studio 建置的自定義實體偵測模型,將文字中的實體辨識並分類為實體。

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

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

const documents = [
  "We love this trail and make the trip every year. The views are breathtaking and well worth the hike! Yesterday was foggy though, so we missed the spectacular views. We tried again today and it was amazing. Everyone in my family liked the trail although it was too challenging for the less athletic among us.",
  "Last week we stayed at Hotel Foo to celebrate our anniversary. The staff knew about our anniversary so they helped me organize a little surprise for my partner. The room was clean and with the decoration I requested. It was perfect!",
];

async function main() {
  const actions: AnalyzeBatchAction[] = [
    {
      kind: "CustomEntityRecognition",
      deploymentName,
      projectName,
    },
  ];
  const poller = await client.beginAnalyzeBatch(actions, documents, "en");
  for await (const actionResult of results) {
    if (actionResult.kind !== "CustomEntityRecognition") {
      throw new Error(`Expected a CustomEntityRecognition results but got: ${actionResult.kind}`);
    }
    if (actionResult.error) {
      const { code, message } = actionResult.error;
      throw new Error(`Unexpected error (${code}): ${message}`);
    }
    for (const result of actionResult.results) {
      console.log(`- Document ${result.id}`);
      if (result.error) {
        const { code, message } = result.error;
        throw new Error(`Unexpected error (${code}): ${message}`);
      }
      console.log("\tRecognized Entities:");
      for (const entity of result.entities) {
        console.log(`\t- Entity "${entity.text}" of type ${entity.category}`);
      }
    }
  }
}

main();

自定義單一標籤分類

使用使用 azure Language Studio 建置的自定義單一標籤模型來分類檔,

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

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

const documents = [
  "The plot begins with a large group of characters where everyone thinks that the two main ones should be together but foolish things keep them apart. Misunderstandings, miscommunication, and confusion cause a series of humorous situations.",
];

async function main() {
  const actions: AnalyzeBatchAction[] = [
    {
      kind: "CustomSingleLabelClassification",
      deploymentName,
      projectName,
    },
  ];
  const poller = await client.beginAnalyzeBatch(actions, documents, "en");
  const results = await poller.pollUntilDone();

  for await (const actionResult of results) {
    if (actionResult.kind !== "CustomSingleLabelClassification") {
      throw new Error(
        `Expected a CustomSingleLabelClassification results but got: ${actionResult.kind}`
      );
    }
    if (actionResult.error) {
      const { code, message } = actionResult.error;
      throw new Error(`Unexpected error (${code}): ${message}`);
    }
    for (const result of actionResult.results) {
      console.log(`- Document ${result.id}`);
      if (result.error) {
        const { code, message } = result.error;
        throw new Error(`Unexpected error (${code}): ${message}`);
      }
      console.log(`\tClassification: ${result.classification.category}`);
    }
  }
}

main();

自定義多重標籤分類

使用使用 azure Language Studio 建置的自定義多重標籤模型來分類檔,

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

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

const documents = [
  "The plot begins with a large group of characters where everyone thinks that the two main ones should be together but foolish things keep them apart. Misunderstandings, miscommunication, and confusion cause a series of humorous situations.",
];

async function main() {
  const actions: AnalyzeBatchAction[] = [
    {
      kind: "CustomMultiLabelClassification",
      deploymentName,
      projectName,
    },
  ];
  const poller = await client.beginAnalyzeBatch(actions, documents, "en");
  const results = await poller.pollUntilDone();

  for await (const actionResult of results) {
    if (actionResult.kind !== "CustomMultiLabelClassification") {
      throw new Error(
        `Expected a CustomMultiLabelClassification results but got: ${actionResult.kind}`
      );
    }
    if (actionResult.error) {
      const { code, message } = actionResult.error;
      throw new Error(`Unexpected error (${code}): ${message}`);
    }
    for (const result of actionResult.results) {
      console.log(`- Document ${result.id}`);
      if (result.error) {
        const { code, message } = result.error;
        throw new Error(`Unexpected error (${code}): ${message}`);
      }
      console.log(`\tClassification:`);
      for (const classification of result.classifications) {
        console.log(`\t\t-category: ${classification.category}`);
      }
    }
  }
}

main();

動作批處理

在一個服務要求中的每個輸入檔上套用多個動作。

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

const client = new TextAnalysisClient("<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: AnalyzeBatchAction[] = [
    {
      kind: "EntityRecognition",
      modelVersion: "latest",
    },
    {
      kind: "PiiEntityRecognition",
      modelVersion: "latest",
    },
    {
      kind: "KeyPhraseExtraction",
      modelVersion: "latest",
    },
  ];
  const poller = await client.beginAnalyzeBatch(actions, documents, "en");
  const actionResults = await poller.pollUntilDone();
  for await (const actionResult of actionResults) {
    if (actionResult.error) {
      const { code, message } = actionResult.error;
      throw new Error(`Unexpected error (${code}): ${message}`);
    }
    switch (actionResult.kind) {
      case "KeyPhraseExtraction": {
        for (const doc of actionResult.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);
          }
        }
        break;
      }
      case "EntityRecognition": {
        for (const doc of actionResult.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);
          }
        }
        break;
      }
      case "PiiEntityRecognition": {
        for (const doc of actionResult.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);
          }
        }
        break;
      }
      default: {
        throw new Error(`Unexpected action results: ${actionResult.kind}`);
      }
    }
  }
}

main();

故障排除

伐木

啟用記錄可能有助於找出有關失敗的實用資訊。 若要查看 HTTP 要求和回應的記錄,請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者,您可以在運行時間啟用記錄,方法是在 @azure/logger中呼叫 setLogLevel

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

如需如何啟用記錄的詳細指示,請參閱@azure/記錄器套件檔。

後續步驟

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

貢獻

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

印象