Biblioteca cliente rest de seguridad de contenido de Azure AI para JavaScript: versión 1.0.1

Artículo
02/22/2025

seguridad de contenido de Azure AI detecta contenido generado por el usuario y generado por ia perjudiciales en aplicaciones y servicios. La seguridad del contenido incluye LAS API de texto e imagen que permiten detectar materiales perjudiciales.

Text Analysis API: examina el texto del contenido sexual, la violencia, el odio y el daño propio con niveles de gravedad múltiple.
Image Analysis API: examina imágenes de contenido sexual, violencia, odio y auto-daño con niveles de gravedad múltiple.
API de administración de listas de texto: los clasificadores de IA predeterminados son suficientes para la mayoría de las necesidades de seguridad de contenido; Sin embargo, es posible que tenga que pantallar los términos específicos de su caso de uso. Puede crear listas de bloqueados de términos para usarlas con Text API.

Confíe en gran medida en nuestros documentos de cliente REST de para usar esta biblioteca

Vínculos clave:

código fuente
paquete de (NPM)
documentación de referencia de api de
ejemplos de

Empezar

Entornos admitidos actualmente

Versiones LTS de Node.js

Prerrequisitos

Necesita una suscripción de Azure para usar este paquete.
Un recurso de seguridad de contenido de Azure AI, si no hay ningún recurso existente, podría crear uno nuevo.

Instalación del paquete `@azure-rest/ai-content-safety`

Instale la biblioteca de cliente REST rest de seguridad de contenido de Azure AI para JavaScript con npm:

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

Creación y autenticación de un `ContentSafetyClient`

Obtención del punto de conexión

Puede encontrar el punto de conexión del recurso del servicio Azure AI Content Safety mediante el azure Portal o cli de Azure:

# 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"

Creación de un elemento ContentSafetyClient con AzureKeyCredential

Paso 1: Obtención de la clave de API

La clave de API se puede encontrar en el de Azure Portal o ejecutando el siguiente comando cli de Azure:

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

Paso 2: Creación de un contentSafetyClient con AzureKeyCredential

Para usar una clave de API como parámetro credential, pase la clave como una cadena a una instancia de 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);

Creación de una credencial de token de ContentSafetyClient con el identificador de Microsoft Entra (anteriormente Azure Active Directory (AAD))

Paso 1: Habilitar el identificador de Entra de Microsoft para el recurso Consulte este documento de autenticación de Cognitive Services Autenticar con el identificador de Entra de Microsoft. para conocer los pasos para habilitar AAD para el recurso.

Los pasos principales son:
- Cree un recurso con un subdominio personalizado.
- Cree una entidad de servicio y asígnele el rol de usuario de Cognitive Services.
Paso 2: Establecer los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Para autenticarse con AAD, primero debe npm instalar @azure/identity. Después de la instalación, puede elegir qué tipo de credenciales de de @azure/identity usar. Por ejemplo, DefaultAzureCredential se puede usar para autenticar al cliente.

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

Conceptos clave

Características disponibles

Hay diferentes tipos de análisis disponibles en este servicio. En la tabla siguiente se describen las API disponibles actualmente.

Característica	Descripción
Text Analysis API	Examina el texto del contenido sexual, la violencia, el odio y el daño propio con niveles de gravedad múltiple.
Image Analysis API	Examina imágenes de contenido sexual, violencia, odio y auto-daño con niveles de gravedad múltiple.
API de administración de listas de bloques de texto	Los clasificadores de IA predeterminados son suficientes para la mayoría de las necesidades de seguridad de contenido. Sin embargo, es posible que tenga que pantallar los términos específicos de su caso de uso. Puede crear listas de bloqueados de términos para usarlas con Text API.

Categorías de daños

La seguridad del contenido reconoce cuatro categorías distintas de contenido censurable.

Categoría	Descripción
Odiar	El odio hace referencia a cualquier contenido que ataque o use lenguaje pejorante o discriminatorio en referencia a una persona o grupo de identidad basado en determinados atributos diferenciadores de ese grupo. Esto incluye, entre otros, la raza, la etnia, la nacionalidad, la identidad y la expresión de género, la orientación sexual, la religión, el estado de inmigración, el estado de la capacidad, la apariencia personal y el tamaño del cuerpo.
Sexual	Sexual describe contenido relacionado con órganos anatómicos y genitales, relaciones románticas, actos representados en términos eróticos o cariñosos, embarazo, actos sexuales físicos, incluidos aquellos que se representan como un ataque o un acto sexual forzado violento contra la voluntad de uno— , prostitución, pornografía y abuso.
Violencia	La violencia describe contenido relacionado con acciones físicas destinadas a herir, dañar, dañar o matar a alguien o algo. También incluye armas, armas y entidades relacionadas, como fabricantes, asociaciones, legislación y similares.
Auto-daño	El daño personal describe el contenido relacionado con acciones físicas destinadas a dañar, lesionar o dañar el cuerpo de uno mismo o matarse a propósito.

La clasificación puede tener varias etiquetas. Por ejemplo, cuando un ejemplo de texto pasa por el modelo de moderación de texto, podría clasificarse como contenido sexual y Violencia.

Niveles de gravedad

Cada categoría de daño que el servicio aplica también incluye una clasificación de nivel de gravedad. El nivel de gravedad está diseñado para indicar la gravedad de las consecuencias de mostrar el contenido marcado.

Text: la versión actual del modelo de texto admite el escala de gravedad completa de 0 a 7. De forma predeterminada, la respuesta generará 4 valores: 0, 2, 4 y 6. Cada dos niveles adyacentes se asignan a un único nivel. Los usuarios podrían usar "outputType" en la solicitud y establecerlo como "EightSeverityLevels" para obtener 8 valores en la salida: 0,1,2,3,4,5,6,7. Puede consultar definiciones de niveles de gravedad de contenido de texto para obtener más información.

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

Image: la versión actual del modelo de imagen admite la versión recortada de la escala de gravedad completa de 0 a 7. El clasificador solo devuelve gravedades 0, 2, 4 y 6; cada dos niveles adyacentes se asignan a un único nivel. Puede consultar definiciones de niveles de gravedad de contenido de imagen para obtener más información.

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

Administración de listas de bloqueados de texto

Se admiten las siguientes operaciones para administrar la lista de bloqueados de texto:

Crear o modificar una lista de bloqueados
Enumerar todas las listas de bloqueados
Obtener una lista de bloqueados por blocklistName
Agregar blockItems a una lista de bloques
Eliminación de blockItems de una lista de bloques
Enumerar todos los blockItems de una lista de bloques por blocklistName
Obtener un blockItem en una lista de bloques por blockItemId y blocklistName
Eliminar una lista de bloques y todos sus blockItems

Puede establecer las listas de bloqueo que desea usar al analizar texto y, a continuación, obtener el resultado de coincidencia de lista de bloqueos de la respuesta devuelta.

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes del servicio seguridad de contenido en typeScript y javaScript, entre las que se incluyen:

Analizar de texto
analizar de imágenes
administrar de la lista de bloqueados de texto

Análisis de texto

Análisis de texto sin listas de bloqueo

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

Análisis de texto con listas de bloques

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

Analizar imagen

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

Administrar lista de bloqueados de texto

Creación o actualización de la lista de bloqueos de texto

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

Enumerar listas de bloqueados de texto

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

Obtener lista de bloqueados de texto

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

Eliminar lista de bloqueados de texto

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

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

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

Obtener blockItem

Mecanografiado

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

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

Solución de problemas

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Pasos siguientes

Documentación adicional

Para más información sobre la seguridad de contenido de Azure, consulte el de seguridad de contenido de Azure AI en learn.microsoft.com.

Contribuyendo

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.

Compartir a través de

Biblioteca cliente rest de seguridad de contenido de Azure AI para JavaScript: versión 1.0.1

Empezar

Entornos admitidos actualmente

Prerrequisitos

Instalación del paquete `@azure-rest/ai-content-safety`

Creación y autenticación de un `ContentSafetyClient`

Obtención del punto de conexión

Creación de un elemento ContentSafetyClient con AzureKeyCredential

Creación de una credencial de token de ContentSafetyClient con el identificador de Microsoft Entra (anteriormente Azure Active Directory (AAD))

Conceptos clave

Características disponibles

Categorías de daños

Niveles de gravedad

Administración de listas de bloqueados de texto

Ejemplos

Análisis de texto

Análisis de texto sin listas de bloqueo

Análisis de texto con listas de bloques

Analizar imagen

Administrar lista de bloqueados de texto

Creación o actualización de la lista de bloqueos de texto

Enumerar listas de bloqueados de texto

Obtener lista de bloqueados de texto

Eliminar lista de bloqueados de texto

Agregar blockItems

Enumerar blockItems

Obtener blockItem

Quitar blockItems

Solución de problemas

Registro

Pasos siguientes

Documentación adicional

Contribuyendo

Recursos adicionales

Compartir a través de

Biblioteca cliente rest de seguridad de contenido de Azure AI para JavaScript: versión 1.0.1

Empezar

Entornos admitidos actualmente

Prerrequisitos

Instalación del paquete @azure-rest/ai-content-safety

Creación y autenticación de un ContentSafetyClient

Obtención del punto de conexión

Creación de un elemento ContentSafetyClient con AzureKeyCredential

Creación de una credencial de token de ContentSafetyClient con el identificador de Microsoft Entra (anteriormente Azure Active Directory (AAD))

Conceptos clave

Características disponibles

Categorías de daños

Niveles de gravedad

Administración de listas de bloqueados de texto

Ejemplos

Análisis de texto

Análisis de texto sin listas de bloqueo

Análisis de texto con listas de bloques

Analizar imagen

Administrar lista de bloqueados de texto

Creación o actualización de la lista de bloqueos de texto

Enumerar listas de bloqueados de texto

Obtener lista de bloqueados de texto

Eliminar lista de bloqueados de texto

Agregar blockItems

Enumerar blockItems

Obtener blockItem

Quitar blockItems

Solución de problemas

Registro

Pasos siguientes

Documentación adicional

Contribuyendo

Recursos adicionales

Instalación del paquete `@azure-rest/ai-content-safety`

Creación y autenticación de un `ContentSafetyClient`