次の方法で共有

JavaScript 用 Azure AI Content Safety REST クライアント ライブラリ - バージョン 1.0.1

  • [アーティクル]

azure AI Content Safety は、アプリケーションやサービスでユーザーが生成した有害なコンテンツと AI によって生成されたコンテンツを検出します。 Content Safety には、有害な素材を検出できるテキスト API と画像 API が含まれています。

  • テキスト分析 API: 複数の重大度レベルで、性的なコンテンツ、暴力、ヘイト、自傷行為についてテキストをスキャンします。
  • 画像分析 API: 複数の重大度レベルで、性的コンテンツ、暴力、ヘイト、自傷行為の画像をスキャンします。
  • テキスト ブロックリスト管理 API: 既定の AI 分類子は、ほとんどのコンテンツの安全性のニーズに十分です。ただし、ユース ケースに固有の用語を確認する必要がある場合があります。 Text API で使用する用語のブロックリストを作成できます。

このライブラリを使用するには、REST クライアント ドキュメント に大きく依存してください

主要なリンク:

はじめ

現在サポートされている環境

  • Node.js の LTS バージョン

前提 条件

@azure-rest/ai-content-safety パッケージをインストールする

npmを使用して、JavaScript 用の Azure AI Content Safety REST クライアント REST クライアント ライブラリをインストールします。

npm install @azure-rest/ai-content-safety

ContentSafetyClient を作成して認証する

エンドポイントを取得する

Azure PORTAL または Azure CLI をして、Azure AI Content Safety サービス リソースのエンドポイントを見つけることができます。

# Get the endpoint for the Azure AI Content Safety service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"

AzureKeyCredential を使用して ContentSafetyClient を作成する

  • 手順 1: API キーを取得する

API キーは、Azure Portal で、または次の Azure CLI コマンドを実行して確認できます。

az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"
  • 手順 2: AzureKeyCredential を使用して ContentSafetyClient を作成する

credential パラメーターとして API キーを使用するには、キーを文字列として AzureKeyCredentialのインスタンスに渡します。

import { AzureKeyCredential } from "@azure/core-auth";
import ContentSafetyClient from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const key = "<api_key>";
const credential = new AzureKeyCredential(key);
const client = ContentSafetyClient(endpoint, credential);

Microsoft Entra ID (旧称 Azure Active Directory (AAD)) トークン資格情報を使用して ContentSafetyClient を作成する

  • 手順 1: リソースに対して Microsoft Entra ID を有効にする:Microsoft Entra ID で認証する、この Cognitive Services 認証ドキュメントを参照してください。リソースに対して AAD を有効にする手順について説明します。

    主な手順は次のとおりです。

    • カスタム サブドメインを使用してリソースを作成します。
    • サービス プリンシパルを作成し、それに Cognitive Services ユーザー ロールを割り当てます。

  • 手順 2: AAD アプリケーションのクライアント ID、テナント ID、クライアント シークレットの値を環境変数として設定する:AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET

AAD で認証するには、最初に @azure/identitynpm インストールする必要があります。 セットアップ後、使用する @azure/identity から 資格情報 の種類を選択できます。 たとえば、DefaultAzureCredential 使用してクライアントを認証できます。

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

主な概念

使用可能な機能

このサービスでは、さまざまな種類の分析を使用できます。 次の表では、現在使用可能な API について説明します。

特徴 形容
テキスト分析 API 複数の重大度レベルで、性的なコンテンツ、暴力、嫌悪、自傷行為のテキストをスキャンします。
Image Analysis API 複数の重大度レベルで、性的コンテンツ、暴力、ヘイト、自傷行為の画像をスキャンします。
テキスト ブロックリスト管理 API ほとんどのコンテンツの安全性のニーズには、既定の AI 分類子で十分です。 ただし、ユース ケースに固有の用語を確認する必要がある場合があります。 Text API で使用する用語のブロックリストを作成できます。

損害カテゴリ

Content Safety は、不快なコンテンツの 4 つの異なるカテゴリを認識します。

カテゴリ 形容
憎む ヘイトとは、そのグループの特定の差別化属性に基づいて、個人または ID グループを参照して、悲観的または差別的な言語を攻撃または使用するコンテンツを指します。 これには、人種、民族、国籍、性同一性と表現、性的指向、宗教、移民ステータス、能力ステータス、個人的な外観、体の大きさが含まれますが、これらに限定されません。
性的 性的表現は、解剖学的な臓器や性器、ロマンチックな関係、性的または愛情的な言葉で描かれた行為、妊娠、物理的な性的行為(自分の意志に反する暴行や強制的な性的暴力行為、売春、ポルノ、虐待など)に関連するコンテンツを記述します。
暴力 暴力とは、人を傷つけたり、傷つけたり、損害を与えたり、人を殺したりすることを意図した物理的な行動に関連するコンテンツを表します。 また、武器、銃、メーカー、協会、法律などの関連エンティティも含まれます。
自傷行為 自傷行為とは、意図的に身体を傷つけたり、傷つけたり、体を傷つけたり、自分を殺したりすることを目的とした物理的な行為に関連するコンテンツを表します。

分類には複数のラベルを付けることができます。 たとえば、テキスト サンプルがテキスト モデレーション モデルを通過すると、性的コンテンツと暴力の両方として分類される可能性があります。

重大度レベル

サービスが適用されるすべての損害カテゴリには、重大度レベルの評価も含まれています。 重大度レベルは、フラグ付きコンテンツを表示した結果の重大度を示します。

テキスト: 現在のバージョンのテキスト モデルでは、完全な 0 から 7 の重大度スケールがサポートされています。 既定では、応答は 0、2、4、6 の 4 つの値を出力します。 隣接する 2 つの各レベルは、1 つのレベルにマップされます。 ユーザーは要求で "outputType" を使用し、それを "EightSeverityLevels" として設定して、出力で 0,1,2,2,3,4,5,6,7 の 8 つの値を取得できます。 詳細については、テキスト コンテンツの重大度レベルの定義 を参照してください。

  • [0,1] -> 0
  • [2,3] -> 2
  • [4,5] -> 4
  • [6,7] -> 6

イメージ: イメージ モデルの現在のバージョンでは、完全な 0 から 7 の重大度スケール のトリミング バージョンがサポートされています。 分類子は重大度 0、2、4、および 6 のみを返します。各 2 つの隣接するレベルは、1 つのレベルにマップされます。 詳細については、イメージ コンテンツの重大度レベルの定義 を参照してください。

  • [0,1] -> 0
  • [2,3] -> 2
  • [4,5] -> 4
  • [6,7] -> 6

テキスト ブロックリストの管理

テキスト ブロックリストを管理するには、次の操作がサポートされています。

  • ブロックリストを作成または変更する
  • すべてのブロックリストを一覧表示する
  • blocklistName でブロックリストを取得する
  • ブロックリストに blockItems を追加する
  • ブロックリストから blockItems を削除する
  • ブロックリスト内のすべての blockItem を blocklistName で一覧表示する
  • blockItemId と blocklistName によってブロックリスト内の blockItem を取得する
  • ブロックリストとそのすべての blockItems を削除する

テキストを分析するときに使用するブロックリストを設定すると、返された応答からブロックリストの一致結果を取得できます。

例

次のセクションでは、TypeScript と JavaScriptの両方で最も一般的な Content Safety Service タスクの一部を説明するいくつかのコード スニペットを示します。

テキストの分析

ブロックリストなしでテキストを分析する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const text = "This is a sample text";
const analyzeTextOption = { text: text };
const analyzeTextParameters = { body: analyzeTextOption };

const result = await client.path("/text:analyze").post(analyzeTextParameters);

if (isUnexpected(result)) {
  throw result;
}

for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
  const textCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
  console.log(
    textCategoriesAnalysisOutput.category,
    " severity: ",
    textCategoriesAnalysisOutput.severity,
  );
}

ブロックリストを使用してテキストを分析する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, {
  CreateOrUpdateTextBlocklistParameters,
  isUnexpected,
} from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

async function createOrUpdateTextBlocklist() {
  const blocklistName = "TestBlocklist";
  const blocklistDescription = "Test blocklist management.";
  const createOrUpdateTextBlocklistParameters: CreateOrUpdateTextBlocklistParameters = {
    contentType: "application/merge-patch+json",
    body: {
      description: blocklistDescription,
    },
  };

  const result = await client
    .path("/text/blocklists/{blocklistName}", blocklistName)
    .patch(createOrUpdateTextBlocklistParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log(
    "Blocklist created or updated: Name",
    result.body.blocklistName,
    ", Description: ",
    result.body.description,
  );
}

async function addBlockItems() {
  const blocklistName = "TestBlocklist";
  const blockItemText1 = "sample";
  const blockItemText2 = "text";
  const addOrUpdateBlocklistItemsParameters = {
    body: {
      blocklistItems: [
        {
          description: "Test block item 1",
          text: blockItemText1,
        },
        {
          description: "Test block item 2",
          text: blockItemText2,
        },
      ],
    },
  };

  const result = await client
    .path("/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems", blocklistName)
    .post(addOrUpdateBlocklistItemsParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log("Block items added: ");
  if (result.body.blocklistItems) {
    for (const blockItem of result.body.blocklistItems) {
      console.log(
        "BlockItemId: ",
        blockItem.blocklistItemId,
        ", Text: ",
        blockItem.text,
        ", Description: ",
        blockItem.description,
      );
    }
  }
}

async function analyzeTextWithBlocklists() {
  const blocklistName = "TestBlocklist";
  const inputText = "This is a sample to test text with blocklist.";
  const analyzeTextParameters = {
    body: {
      text: inputText,
      blocklistNames: [blocklistName],
      haltOnBlocklistHit: false,
    },
  };

  const result = await client.path("/text:analyze").post(analyzeTextParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log("Blocklist match results: ");
  if (result.body.blocklistsMatch) {
    for (const blocklistMatchResult of result.body.blocklistsMatch) {
      console.log(
        "BlocklistName: ",
        blocklistMatchResult.blocklistName,
        ", BlockItemId: ",
        blocklistMatchResult.blocklistItemId,
        ", BlockItemText: ",
        blocklistMatchResult.blocklistItemText,
      );
    }
  }
}

try {
  await createOrUpdateTextBlocklist();
  await addBlockItems();
  await analyzeTextWithBlocklists();
} catch (err) {
  console.error("The sample encountered an error:", err);
}

画像の分析

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";
import { readFileSync } from "node:fs";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const image_path = "./samples-dev/example-data/image.png";

const imageBuffer = readFileSync(image_path);
const base64Image = imageBuffer.toString("base64");
const analyzeImageOption = { image: { content: base64Image } };
const analyzeImageParameters = { body: analyzeImageOption };

const result = await client.path("/image:analyze").post(analyzeImageParameters);

if (isUnexpected(result)) {
  throw result;
}

for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
  const imageCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
  console.log(
    imageCategoriesAnalysisOutput.category,
    " severity: ",
    imageCategoriesAnalysisOutput.severity,
  );
}

テキスト ブロックリストの管理

テキスト ブロックリストを作成または更新する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, {
  CreateOrUpdateTextBlocklistParameters,
  isUnexpected,
} from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";
const blocklistDescription = "Test blocklist management.";
const createOrUpdateTextBlocklistParameters: CreateOrUpdateTextBlocklistParameters = {
  contentType: "application/merge-patch+json",
  body: {
    description: blocklistDescription,
  },
};

const result = await client
  .path("/text/blocklists/{blocklistName}", blocklistName)
  .patch(createOrUpdateTextBlocklistParameters);

if (isUnexpected(result)) {
  throw result;
}

console.log(
  "Blocklist created or updated: Name",
  result.body.blocklistName,
  ", Description: ",
  result.body.description,
);

テキスト ブロックリストを一覧表示する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const result = await client.path("/text/blocklists").get();

if (isUnexpected(result)) {
  throw result;
}

console.log("List blocklists: ");
if (result.body.value) {
  for (const blocklist of result.body.value) {
    console.log(
      "BlocklistName: ",
      blocklist.blocklistName,
      ", Description: ",
      blocklist.description,
    );
  }
}

テキスト ブロックリストを取得する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client.path("/text/blocklists/{blocklistName}", blocklistName).get();

if (isUnexpected(result)) {
  throw result;
}

console.log("Get blocklist: ");
console.log("Name: ", result.body.blocklistName, ", Description: ", result.body.description);

テキスト ブロックリストを削除する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client.path("/text/blocklists/{blocklistName}", blocklistName).delete();

if (isUnexpected(result)) {
  throw result;
}

console.log("Deleted blocklist: ", blocklistName);

blockItems を追加する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";
const blockItemText1 = "sample";
const blockItemText2 = "text";
const addOrUpdateBlocklistItemsParameters = {
  body: {
    blocklistItems: [
      {
        description: "Test block item 1",
        text: blockItemText1,
      },
      {
        description: "Test block item 2",
        text: blockItemText2,
      },
    ],
  },
};

const result = await client
  .path("/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems", blocklistName)
  .post(addOrUpdateBlocklistItemsParameters);

if (isUnexpected(result)) {
  throw result;
}

console.log("Block items added: ");
if (result.body.blocklistItems) {
  for (const blockItem of result.body.blocklistItems) {
    console.log(
      "BlockItemId: ",
      blockItem.blocklistItemId,
      ", Text: ",
      blockItem.text,
      ", Description: ",
      blockItem.description,
    );
  }
}

blockItems を一覧表示する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client
  .path("/text/blocklists/{blocklistName}/blocklistItems", blocklistName)
  .get();

if (isUnexpected(result)) {
  throw result;
}

console.log("List block items: ");
if (result.body.value) {
  for (const blockItem of result.body.value) {
    console.log(
      "BlockItemId: ",
      blockItem.blocklistItemId,
      ", Text: ",
      blockItem.text,
      ", Description: ",
      blockItem.description,
    );
  }
}

blockItem を取得する

TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blockItemId = "<blockItemId>";
const blocklistName = "TestBlocklist";

const blockItem = await client
  .path(
    "/text/blocklists/{blocklistName}/blocklistItems/{blocklistItemId}",
    blocklistName,
    blockItemId,
  )
  .get();

if (isUnexpected(blockItem)) {
  throw blockItem;
}

console.log("Get blockitem: ");
console.log(
  "BlockItemId: ",
  blockItem.body.blocklistItemId,
  ", Text: ",
  blockItem.body.text,
  ", Description: ",
  blockItem.body.description,
);

blockItems を削除する

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blockItemId = "<blockItemId>";
const blocklistName = "TestBlocklist";
const blockItemText = "sample";

const removeBlocklistItemsParameters = {
  body: {
    blocklistItemIds: [blockItemId],
  },
};
const removeBlockItem = await client
  .path("/text/blocklists/{blocklistName}:removeBlocklistItems", blocklistName)
  .post(removeBlocklistItemsParameters);

if (isUnexpected(removeBlockItem)) {
  throw removeBlockItem;
}

console.log("Removed blockItem: ", blockItemText);

トラブルシューティング

伐採

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。 または、@azure/loggerで setLogLevel を呼び出すことによって、実行時にログを有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細な手順については、@azure/logger パッケージのドキュメントを参照してください。

次の手順

その他のドキュメント

Azure Content Safety に関するより広範なドキュメントについては、learn.microsoft.com の Azure AI Content Safety を参照してください。

貢献

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイド を参照してください。