Início Rápido: Categorias personalizadas (modo padrão) (visualização)

Siga este guia para usar a API REST de categorias personalizadas (padrão) da Segurança de Conteúdo de IA do Azure para criar suas próprias categorias de conteúdo para seu caso de uso e treinar a Segurança de Conteúdo de IA do Azure para detectá-las em novos conteúdos de texto.

Para obter mais informações sobre categorias Personalizadas, confira a página Conceito de categorias personalizadas. Para obter os limites de entrada de dados de APIs, confira a seção Requisitos de entrada de dados em Visão Geral.

Importante

Esse recurso só está disponível em determinadas regiões do Azure. Confira a Disponibilidade de região.

Importante

Reserve tempo suficiente para o treinamento do modelo

A execução de ponta a ponta do treinamento de categoria personalizada pode levar cerca de cinco a dez horas. Planeje o pipeline de moderação de acordo.

Pré-requisitos

• Uma assinatura do Azure – crie uma gratuitamente
• Depois de ter uma assinatura do Azure, crie um recurso de Segurança do Conteúdo no portal do Azure para obter uma chave e um ponto de extremidade. Insira um nome exclusivo para o recurso, selecione sua assinatura e selecione um grupo de recursos, região com suporte e tipo de preço com suporte. Em seguida, selecione Criar.
  • O recurso demora alguns minutos para implantar. Após a conclusão, selecione ir para o recurso. No painel à esquerda, em Gerenciamento de Recursos, selecione Chave de Assinatura e Ponto de Extremidade. Copie o ponto de extremidade e qualquer um dos valores de chave para um local temporário para uso posterior.
• Além disso, crie um contêiner de armazenamento de blobs do Azure onde você manterá seu arquivo de anotação de treinamento.
• Um dos seguintes instalados:
  • cURL para chamadas à API REST.
  • Python 3.x 3.x instalado

Prepare seus dados de treinamento

Para treinar uma categoria personalizada, você precisa de dados de texto de exemplo que representem a categoria que você deseja detectar. Neste guia, você pode usar dados de exemplo. O arquivo de anotação fornecido contém avisos de texto sobre recomendações de sobrevivência em situações de acampamento/selva. O modelo treinado aprenderá a detectar esse tipo de conteúdo em novos dados de texto.

Dica

Para obter dicas sobre como criar seu conjunto de dados, confira o Guia de instruções.

1. Baixe o arquivo de dados de texto de exemplo do repositório GitHub.
2. Carregue o arquivo .jsonl no contêiner de blobs da conta do Armazenamento do Azure. Em seguida, copie a URL do blob para um local temporário para uso posterior.

Importante

A conta de armazenamento do usuário é configurada como uma conta de namespace hierárquica, que não pode ser suportada por Categorias Personalizadas. Tente usar uma conta de armazenamento regular. Por exemplo, a URL do blob não pode ser dividida em duas camadas, como exemplo/exemplo1/, e deve ter apenas uma camada. Para obter mais detalhes, consulte a documentação: Namespace hierárquico do Azure Data Lake Storage – Armazenamento do Azure.

Conceder acesso ao armazenamento

Em seguida, você precisa fornecer acesso ao recurso de Content Security para ler do recurso de Armazenamento do Azure. Habilite a identidade gerenciada atribuída pelo sistema para a instância de Segurança de Conteúdo de IA do Azure e atribua a função de Colaborador/Proprietário de Dados de Blobs de Armazenamento à identidade:

Importante

Somente o Colaborador de Dados de Blobs de Armazenamento ou o Proprietário de Dados de Blobs de Armazenamento são funções válidas para continuar.

1. Habilite a identidade gerenciada para a instância de Segurança de Conteúdo de IA do Azure.

   

2. Atribua a função de Colaborador/Proprietário de Dados do Blob de Armazenamento à identidade gerenciada. Todas as funções realçadas abaixo devem funcionar.

   

   

   

Criar e treinar uma categoria personalizada

Curl

No comando abaixo, substitua <your_api_key>, <your_endpoint> e outros parâmetros necessários por valores próprios. Em seguida, insira cada comando em uma janela do terminal e execute-o.

Criar nova versão da categoria

curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
            \"categoryName\": \"survival-advice\",
            \"definition\": \"text prompts about survival advice in camping/wilderness situations\",
            \"sampleBlobUrl\": \"https://<your-azure-storage-url>/example-container/survival-advice.jsonl\"
        }"

Dica

Sempre que você alterar o nome da categoria, a definição ou os exemplos, uma nova versão será criada. Você pode usar o número de versão para rastrear de volta para versões anteriores. Lembre-se desse número de versão, pois ele será necessário na URL para as próximas categorias personalizadas de treinamento.

Solicitação API

Campo	Descrição	Valor de Exemplo
categoryName	O nome da categoria ou tópico ao qual a solicitação está relacionada.	dicas de sobrevivência
definition	Uma breve descrição do tipo de conteúdo para a categoria.	prompts de texto sobre dicas de sobrevivência em situações de acampamento/na natureza
sampleBlobUrl	URL para acessar um arquivo JSONL de exemplo que contém exemplos de dados para a categoria.	Link

Resposta da API

Campo	Descrição	Valor de Exemplo
categoryName	O nome da categoria ou tópico ao qual a resposta está relacionada.	dicas de sobrevivência
definition	Uma breve descrição do tipo de conteúdo para a categoria.	prompts de texto sobre dicas de sobrevivência em situações de acampamento/na natureza
sampleBlobUrl	URL para acessar um arquivo JSONL de exemplo que contém exemplos de dados para a categoria.	Link
sampleBlobSnapshotUrl	URL de instantâneo do arquivo JSONL de exemplo, que fornece acesso a uma versão específica dos dados.	URL do instantâneo
version	O número de versão dos dados da categoria.	1
createdTime	Carimbo de data/hora de quando os dados da categoria foram criados.	2024-10-28T22:06:59.4626988Z
status	Status atual do processamento de dados da categoria.	Com sucesso

Inicie o processo de criação da categoria:

Substitua <your_api_key> e <your_endpoint> por seus próprios valores e também acrescente o número de versão na URL obtido da última etapa. Permita tempo suficiente para o treinamento de modelo: a execução de ponta a ponta do treinamento de categoria personalizada pode levar cerca de cinco a dez horas. Planeje o pipeline de moderação de acordo. Depois de receber a resposta, armazene a ID da operação (conhecida como id) em um local temporário. Essa ID será necessária para recuperar o status de criação usando a API Obter status na próxima seção.

curl -X POST "<your_endpoint>/contentsafety/text/categories/survival-advice:build?api-version=2024-09-15-preview&version={version}" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Resposta da API

Campo	Descrição	Valor de Exemplo
operation id	Identificador exclusivo para recuperar o status de compilação	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
status	Status atual da solicitação	Com sucesso

Obtenha o status de compilação da categoria:

Para recuperar o status, utilize o id obtido da resposta anterior da API e coloque-o no caminho da API abaixo.

curl -X GET "<your_endpoint>/contentsafety/text/categories/operations/<id>?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Resposta da API

Campo	Descrição	Valor de Exemplo
operation id	Identificador exclusivo para recuperar o status de compilação	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
status	Status atual da solicitação	Com sucesso

Analisar texto com uma categoria personalizada

Execute o comando a seguir para analisar o texto com a categoria personalizada. Substitua <your_api_key> e <your_endpoint> pelos seus próprios valores.

curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
            \"text\": \"<Example text to analyze>\",
            \"categoryName\": \"survival-advice\", 
            \"version\": 1
        }"

Solicitação API

Campo	Descrição
text	O conteúdo de texto ou a mensagem destinada à detecção de categoria
categoryName	O nome da categoria pelo qual o texto pretende ser detectado
version	Número de versão da categoria

Resposta da API

Campo	Descrição	Valor de Exemplo
customCategoryAnalysis	Objeto que contém o resultado da análise para a categoria.	—
detected	Indica se a categoria especificada foi detectada.	false

Python

Primeiro, você precisa instalar a biblioteca Python necessária:

pip install requests

Em seguida, abra um novo script Python e defina as variáveis necessárias com os detalhes do seu recurso do Azure:

import requests

API_KEY = '<your_api_key>'
ENDPOINT = '<your_endpoint>'

headers = {
    'Ocp-Apim-Subscription-Key': API_KEY,
    'Content-Type': 'application/json'
}

Criar uma categoria

Você pode criar uma categoria com nome da categoria, definição e sample_blob_url e obterá o número de versão gerado automaticamente dessa categoria.

def create_new_category_version(category_name, definition, sample_blob_url):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    data = {
        "categoryName": category_name,
        "definition": definition,
        "sampleBlobUrl": sample_blob_url
    }
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# Replace the parameters with your own values
category_name = "survival-advice"
definition = "text prompts about survival advice in camping/wilderness situations"
sample_blob_url = "https://<your-azure-storage-url>/example-container/survival-advice.jsonl"

result = create_new_category_version(category_name, definition, sample_blob_url)
print(result)

Iniciar o processo de criação da categoria

Você pode iniciar o processo de criação de categoria com o nome da categoria e número de versão. Permita tempo suficiente para o treinamento de modelo: a execução de ponta a ponta do treinamento de categoria personalizada pode levar cerca de cinco a dez horas. Planeje o pipeline de moderação de acordo. Depois de receber a resposta, lembre-se de armazenar a ID da operação (conhecida como id) em algum lugar como o Bloco de anotações. Essa ID será necessária para recuperar o status de criação usando a função ‘get_build_status’ na próxima seção.

def trigger_category_build_process(category_name, version):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}:build?api-version=2024-09-15-preview&version={version}"
    response = requests.post(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "survival-advice"
version = 1

result = trigger_category_build_process(category_name, version)
print(result)

Obtenha o status de criação da categoria:

Para recuperar o status, utilize o id obtido da resposta anterior.

def get_build_status(id):
    url = f"{ENDPOINT}/contentsafety/text/categories/operations/{id}?api-version=2024-09-15-preview"
    response = requests.get(url, headers=headers)
    return response.status_code

# Replace the parameter with your own value
id = "your-operation-id"

result = get_build_status(id)
print(result)

Analisar texto com uma categoria personalizada

Você precisa especificar o nome da categoria e o número da versão (opcional; o serviço usa o mais recente por padrão) durante a inferência. Você pode especificar várias categorias se elas já estiverem definidas.

def analyze_text_with_customized_category(text, category_name, version):
    url = f"{ENDPOINT}/contentsafety/text:analyzeCustomCategory?api-version=2024-09-15-preview"
    data = {
        "text": text,
        "categoryName": category_name,
        "version": version
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Replace the parameters with your own values
text = "<Example text to analyze>"
category_name = "survival-advice"
version = 1

result = analyze_text_with_customized_category(text, category_name, version)
print(result)

Outras operações de categorias personalizadas

Lembre-se de substituir os espaços reservados abaixo pelos valores reais da chave de API, do endpoint e do conteúdo específico (nome da categoria, definição e assim por diante). Esses exemplos ajudam você a gerenciar as categorias personalizadas em sua conta.

Curl

Obtenha uma categoria personalizada ou uma versão específica dela

Substitua os espaços reservados por seus próprios valores e execute o seguinte comando em uma janela de terminal:

curl -X GET "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Listar categorias de suas versões mais recentes

Substitua os espaços reservados por seus próprios valores e execute o seguinte comando em uma janela de terminal:

curl -X GET "<endpoint>/contentsafety/text/categories?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Excluir uma categoria personalizada ou uma versão específica dela

Substitua os espaços reservados por seus próprios valores e execute o seguinte comando em uma janela de terminal:

curl -X DELETE "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Python

Primeiro, certifique-se de ter instalado a biblioteca Python necessária:

pip install requests

Em seguida, defina as configurações necessárias com seus próprios detalhes de recursos de IA:

import requests

API_KEY = '<your_api_key>'
ENDPOINT = '<your_endpoint>'

headers = {
    'Ocp-Apim-Subscription-Key': API_KEY,
    'Content-Type': 'application/json'
}

Obtenha uma categoria personalizada ou uma versão específica dela

Substitua os espaços reservados por seus próprios valores e execute o seguinte código em seu script Python:

def get_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.get(url, headers=headers)
    return response.json()

# Replace the parameters with your own values
category_name = "DrugAbuse"
version = 1

result = get_customized_category(category_name, version)
print(result)

Listar categorias de suas versões mais recentes

def list_categories_latest_versions():
    url = f"{ENDPOINT}/contentsafety/text/categories?api-version=2024-09-15-preview"
    response = requests.get(url, headers=headers)
    return response.json()

result = list_categories_latest_versions()
print(result)

Excluir uma categoria personalizada ou uma versão específica dela

Substitua os espaços reservados por seus próprios valores e execute o seguinte código em seu script Python:

def delete_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.delete(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "<your_category_name>"
version = 1

result = delete_customized_category(category_name, version)
print(result)

Conteúdo relacionado

• Conceitos de categorias personalizadas
• Modere o conteúdo com a Segurança do Conteúdo