Share via


適用于 JavaScript 的 Azure 文字分析用戶端程式庫 - 6.0.0-Beta.1 版

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

注意: 此 SDK 以適用于語言 API 2022-04-01-preview 的 Azure 認知服務為目標。

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

使用用戶端程式庫可以:

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

重要連結:

開始使用

目前支援的環境

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

必要條件

如果您使用 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-text-analytics 套件

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

npm install @azure/ai-text-analytics

建立和驗證 TextAnalysisClient

若要建立用戶端物件來存取語言 API,您需要 endpoint Language 資源的 和 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-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_ID 、、 AZURE_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!",
];

或者,如果您想要傳入每個專案的檔 idlanguagecountryHint/ ,則可以根據作業來提供 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 設定 truetsconfig.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);
}

範例

情感分析

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

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 可以藉由判斷知識庫中哪些專案可能參考 (來厘清實體,例如,在一段文字中,「Mars」 一詞是指行星,或判斷) 的羅馬戰法。 連結實體包含提供實體定義之知識庫的相關 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();

關鍵片語擷取

關鍵字組擷取可識別檔中的主要交談點。 例如,假設輸入文字為「The food was delicious and there were wonderful staff」,服務會傳回「food」和「wonderful staff」。

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」) 或值 "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();

醫療保健分析

醫療保健分析會識別醫療保健實體。 例如,假設輸入文字 「指定 100mg ibuprofen,每天採用兩次」,服務會傳回分類為「100mg」、「ibuprofen」分類為「檔案名稱」,而「每天兩次」則傳回為 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/logger 套件文件

下一步

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

參與

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

曝光數