JavaScript için Azure AI Content Safety REST istemci kitaplığı - sürüm 1.0.1

Azure AI content Safety, uygulama ve hizmetlerde kullanıcı tarafından oluşturulan ve yapay zeka tarafından oluşturulan zararlı içerikleri algılar. İçerik Güvenliği, zararlı malzemeleri algılamanıza olanak sağlayan metin ve görüntü API'leri içerir.

Metin Analizi API'si: Metni cinsel içerik, şiddet, nefret ve kendine zarar verecek şekilde çok önem düzeyiyle tarar.
Görüntü Analizi API'si: Çok önem düzeyine sahip cinsel içerik, şiddet, nefret ve kendine zarar verecek görüntüleri tarar.
Metin Blok Listesi Yönetim API'leri: Varsayılan yapay zeka sınıflandırıcıları çoğu içerik güvenliği gereksinimi için yeterlidir; ancak, kullanım örneğiniz için özel terimleri denetlemeniz gerekebilir. Metin API'siyle kullanmak üzere engelleyici terim listeleri oluşturabilirsiniz.

Bu kitaplığı kullanmak için REST istemci belgelerimize

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

Node.js LTS sürümleri

Önkoşullar

Bu paketi kullanmak için bir Azure aboneliği gerekir.
Bir Azure AI Content Safety kaynağı varsa, yeni bir kaynakoluşturabilirsiniz.

`@azure-rest/ai-content-safety` paketini yükleme

npmile JavaScript için Azure AI Content Safety REST istemcisi REST istemci kitaplığını yükleyin:

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

`ContentSafetyClient` oluşturma ve kimlik doğrulaması

Uç noktayı alma

Azure Portal veya Azure CLI kullanarak Azure AI İçerik Güvenliği hizmeti kaynağınızın uç noktasını bulabilirsiniz:

# 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 ile ContentSafetyClient oluşturma

1. Adım: API anahtarını alma

API anahtarı Azure Portal veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:

az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"

2. Adım: AzureKeyCredential ile ContentSafetyClient oluşturma

credential parametresi olarak bir API anahtarı kullanmak için anahtarı AzureKeyCredentialörneğine dize olarak geçirin.

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 (eski adıyla Azure Active Directory (AAD)) belirteci kimlik bilgileriyle ContentSafetyClient oluşturma

1. Adım: Kaynağınız için Microsoft Entra Id'yi etkinleştirme Microsoft Entra Id ile kimlik doğrulamasıbu Bilişsel Hizmetler kimlik doğrulama belgesine bakın. AAD'yi kaynağınız için etkinleştirme adımları için.

Ana adımlar şunlardır:
- Özel bir alt etki alanıyla kaynak oluşturun.
- Hizmet Sorumlusu oluşturun ve Bilişsel Hizmetler Kullanıcı rolü atayın.
2. Adım: AAD uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

AAD ile kimlik doğrulaması yapmak için önce @azure/identityyüklemeniz npm gerekir. Kurulumdan sonra, @azure/identity hangi tür kimlik bilgisi kullanılacağını seçebilirsiniz. Örneğin, istemcinin kimliğini doğrulamak için DefaultAzureCredential kullanılabilir.

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

Temel kavramlar

Kullanılabilir özellikler

Bu hizmetten farklı analiz türleri kullanılabilir. Aşağıdaki tabloda şu anda kullanılabilen API'ler açıklanmaktadır.

Özellik	Açıklama
Metin Analizi API'si	Metni cinsel içerik, şiddet, nefret ve kendine zarar verecek şekilde çok önem dereceleriyle tarar.
Görüntü Analizi API'si	Çok önem düzeyiyle cinsel içerik, şiddet, nefret ve kendine zarar verme görüntülerini tarar.
Metin Blok Listesi Yönetim API'leri	Varsayılan yapay zeka sınıflandırıcıları çoğu içerik güvenliği gereksinimi için yeterlidir. Ancak, kullanım örneğiniz için özel terimleri denetlemeniz gerekebilir. Metin API'siyle kullanmak üzere engelleyici terim listeleri oluşturabilirsiniz.

Zarar kategorileri

İçerik Güvenliği dört farklı uygunsuz içerik kategorisi tanır.

Kategori	Açıklama
Nefret	Nefret, bir kişinin veya kimlik grubunun belirli ayırt edici özniteliklerine dayalı olarak pejoratif veya ayrımcı bir dile saldıran veya kullanan içeriği ifade eder. Buna ırk, etnik köken, milliyet, cinsiyet kimliği ve ifadesi, cinsel yönelim, din, göçmenlik durumu, yetenek durumu, kişisel görünüm ve beden boyutu dahildir ancak bunlarla sınırlı değildir.
Seksüel	Cinsel, anatomik organlar ve cinsel organlar, romantik ilişkiler ile ilgili içeriği tanımlar, erotik veya sevgi dolu terimlerle tasvir edilen eylemler, hamilelik, fiziksel cinsel eylemler ( saldırı olarak gösterilen eylemler veya kişinin isteklerine karşı zorlamalı cinsel şiddet eylemleri dahil),, pornografi ve istismar.
Şiddet	Şiddet, birini veya başka bir şeyi yaralayan, yaralayan, zarar verecek veya öldürmeye yönelik fiziksel eylemlerle ilgili içeriği tanımlar. Ayrıca silahlar, silahlar ve üreticiler, dernekler, mevzuat ve benzeri ilgili varlıkları da içeriyor.
Kendine zarar verme	Kendine zarar verme, kişinin vücuduna bilerek zarar verme, yaralanma veya zarar verme ya da kendini öldürme amaçlı fiziksel eylemlerle ilgili içeriği tanımlar.

Sınıflandırma çok etiketli olabilir. Örneğin, bir metin örneği metin denetleme modelinden geçtiğinde, hem Cinsel içerik hem de Şiddet olarak sınıflandırılabilir.

Önem derecesi düzeyleri

Hizmetin uyguladığı her zarar kategorisi de önem derecesiyle birlikte gelir. Önem derecesi düzeyi, bayrak eklenmiş içeriği göstermenin sonuçlarının önem derecesini belirtmek için tasarlanır.

Metin: Metin modelinin geçerli sürümü, tam 0-7 önem derecesi ölçeğinidestekler. Varsayılan olarak, yanıt 4 değeri verir: 0, 2, 4 ve 6. Her iki bitişik düzey tek bir düzeye eşlenir. Kullanıcılar istekte "outputType" kullanabilir ve çıkışta 8 değer elde etmek için bunu "EightSeverityLevels" olarak ayarlayabilir: 0,1,2,3,4,5,6,7. Ayrıntılar için metin içeriği önem düzeyi tanımlarına başvurabilirsiniz.

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

Görüntü: Görüntü modelinin geçerli sürümü, tam 0-7 önem derecesi ölçeğinin kırpılmışsürümünü destekler. Sınıflandırıcı yalnızca 0, 2, 4 ve 6 önem derecelerini döndürür; her iki bitişik düzey tek bir düzeye eşlenir. Ayrıntılar için görüntü içeriği önem düzeyi tanımlarına başvurabilirsiniz.

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

Metin blok listesi yönetimi

Metin blok listenizi yönetmek için aşağıdaki işlemler desteklenir:

Blok listesi oluşturma veya değiştirme
Tüm blok listelerini listeleme
blocklistName ile blok listesi alma
Blok listesine blockItems ekleme
Blok listesinden blockItems kaldırma
BlocklistName tarafından bir blok listesindeki tüm blockItem'leri listeleme
blockItemId ve blocklistName ile blok listesinde blockItem alma
Blok listesini ve tüm blockItem'lerini silme

Metni analiz ederken kullanmak istediğiniz blok listelerini ayarlayabilir ve ardından döndürülen yanıttan blok listesi eşleşme sonucunu alabilirsiniz.

Örnekler

Aşağıdaki bölümde, hem TypeScript hem de JavaScript en yaygın Content Safety hizmet görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

metin analiz
görüntü analiz
Metin blok listesini yönetme

Metni analiz etme

Blok listeleri olmadan metinleri analiz etme

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

Blok listeleriyle metni analiz etme

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

Görüntüyü analiz etme

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

Metin blok listesini yönetme

Metin blok listesi oluşturma veya güncelleştirme

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

Metin blok listelerini listeleme

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

Metin blok listesi alma

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

Metin blok listesini silme

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 ekleme

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 listele

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 alma

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 öğesini kaldırma

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

Sorun giderme

Günlük tutmak

Günlüğe kaydetmeyi etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, @azure/loggersetLogLevel çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki adımlar

Ek belgeler

Azure Content Safety hakkında daha kapsamlı belgeler için bkz. learn.microsoft.com üzerinde Azure AI content Safety .

Katkıda

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-02-20