Usar a API de categorias personalizadas (padrão) (visualização)

A API de categorias personalizadas (padrão) permite criar suas próprias categorias de conteúdo para seu caso de uso e treinar a Segurança de Conteúdo do Azure AI para detetá-las em novos conteúdos.

Importante

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

Atenção

Os dados de exemplo neste guia podem conter conteúdo ofensivo. Aconselha-se a discrição do utilizador.

Pré-requisitos

• Uma assinatura do Azure - Crie uma gratuitamente
• Depois de ter sua assinatura do Azure, crie um recurso de Segurança de Conteúdo no portal do Azure para obter sua chave e ponto de extremidade. Introduza um nome exclusivo para o seu recurso, selecione a sua subscrição e selecione um grupo de recursos, uma região suportada e um escalão de preços suportado. Depois, selecione Criar.
  • O recurso leva alguns minutos para ser implantado. Depois que terminar, selecione ir para recurso. No painel esquerdo, em Gerenciamento de Recursos, selecione Chave de Assinatura e Ponto de Extremidade. Copie o ponto de extremidade e qualquer um dos valores-chave para um local temporário para uso posterior.
• Crie também um contêiner de armazenamento de blob do Azure onde você manterá seu arquivo de anotação de treinamento.
• Um dos seguintes instalados:
  • cURL para chamadas de API REST.
  • Python 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 detetar. Siga estas etapas para preparar seus dados de exemplo:

1. Colete ou escreva seus dados de exemplo:

   • A qualidade dos seus dados de amostra é importante para treinar um modelo eficaz. Procure coletar pelo menos 50 amostras positivas que representem com precisão o conteúdo que você deseja identificar. Estas amostras devem ser claras, variadas e diretamente relacionadas com a definição da categoria.
   • Amostras negativas não são necessárias, mas podem melhorar a capacidade do modelo de distinguir conteúdo relevante de conteúdo irrelevante. Para melhorar o desempenho, procure 50 amostras que não estejam relacionadas com a definição de caso positivo. Estes devem ser variados, mas ainda dentro do contexto do conteúdo que seu modelo encontrará. Escolha cuidadosamente as amostras negativas para garantir que não se sobrepõem inadvertidamente à categoria positiva.
   • Procurar um equilíbrio entre o número de amostras positivas e negativas. Um conjunto de dados desigual pode enviesar o modelo, fazendo com que ele favoreça um tipo de classificação em detrimento de outro, o que pode levar a uma maior taxa de falsos positivos ou negativos.

2. Use um editor de texto para formatar seus dados em um arquivo .jsonl . Abaixo está um exemplo do formato apropriado. Os exemplos de categoria devem ser definidos isPositive como true. Os exemplos negativos são opcionais, mas podem melhorar o desempenho:

   {"text": "This is the 1st sample.", "isPositive": true}
   {"text": "This is the 2nd sample.", "isPositive": true}
   {"text": "This is the 3rd sample (negative).", "isPositive": false}
   

3. Carregue o arquivo .jsonl em um contêiner de blob da conta de Armazenamento do Azure. Copie o URL do blob para um local temporário para uso posterior.

Conceder acesso ao armazenamento

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

Importante

Somente o Contribuidor de Dados de Blob de Armazenamento ou o Proprietário de Dados de Blob de Armazenamento são funções válidas a serem prosseguidas.

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

   

2. Atribua a função de Contribuidor/Proprietário de Dados de Blob de Armazenamento à identidade Gerenciada. Quaisquer funções destacadas abaixo devem funcionar.

   

   

   

Criar e treinar uma categoria personalizada

Importante

Dê tempo suficiente para o treinamento do modelo

A execução de ponta a ponta do treinamento de categoria personalizada pode levar de cerca de cinco horas a dez horas. Planeje seu pipeline de moderação de acordo e aloque tempo para:

• Coletando e preparando seus dados de amostra
• O processo de formação
• Avaliação e ajustes do modelo

cURL

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

Criar nova versão de categoria

curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
        \"categoryName\": \"<your_category_name>\",
        \"definition\": \"<your_category_definition>\",
        \"sampleBlobUrl\": \"https://example.blob.core.windows.net/example-container/sample.jsonl\"
     }"

Inicie o processo de construção da categoria:

Depois de receber a resposta, armazene o ID da operação (referido como id) de forma temporária. Você precisa dessa ID para recuperar o status da compilação usando a API Get status .

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

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-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Analisar texto com uma categoria personalizada

Execute o seguinte comando para analisar o texto com sua categoria personalizada. Substitua <your_category_name> pelo seu próprio valor:

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

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 seus próprios detalhes de recursos 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 nova versão de categoria

Você pode criar uma nova categoria com nome, definição e sample_blob_url da categoria, 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-02-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 = "DrugAbuse"
definition = "This category is related to Drug Abuse."
sample_blob_url = "https://<your-azure-storage-url>/example-container/drugsample.jsonl"

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

Iniciar o processo de construção da categoria

Você pode iniciar o processo de compilação de categoria com o nome da categoria e o número da versão.

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

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

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

Obtenha o status de compilaçã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-02-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-02-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 = "<your_category_name>"
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 por seus valores reais para a chave da API, o ponto de extremidade e o conteúdo específico (nome da categoria, definição e assim por diante). Estes exemplos ajudam-no a gerir as categorias personalizadas na sua conta.

cURL

Obter uma categoria personalizada ou uma versão específica da mesma

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

curl -X GET "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-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 do terminal:

curl -X GET "<endpoint>/contentsafety/text/categories?api-version=2024-02-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 do terminal:

curl -X DELETE "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-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, configure 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'
}

Obter uma categoria personalizada ou uma versão específica da mesma

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-02-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-02-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-02-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údos relacionados

• Conceitos de categorias personalizadas
• Moderar conteúdo com segurança de conteúdo