Использование API пользовательских категорий (стандартный)

Статья
09/02/2024

API пользовательских категорий (стандартный) позволяет создавать собственные категории контента для вашего варианта использования и обучать безопасность содержимого ИИ Azure, чтобы обнаружить их в новом содержимом.

Внимание

Эта функция доступна только в определенных регионах Azure. См . сведения о доступности региона.

Внимание

Примеры данных в этом руководстве могут содержать оскорбительные материалы. Рекомендуется использовать усмотрение пользователя.

Необходимые компоненты

подписка Azure — создайте бесплатную учетную запись.
После получения подписки Azure создайте ресурс безопасности содержимого в портал Azure, чтобы получить ключ и конечную точку. Введите уникальное имя ресурса, выберите подписку и выберите группу ресурсов, поддерживаемый регион и поддерживаемую ценовую категорию. Затем выберите Создать.
- Развертывание ресурса занимает несколько минут. После завершения выберите ресурс. В области слева в разделе "Управление ресурсами" выберите "Ключ подписки" и "Конечная точка". Скопируйте конечную точку и любой из ключевых значений в временное расположение для последующего использования.
Также создайте контейнер хранилища BLOB-объектов Azure, где вы будете хранить файл заметки для обучения.
Одна из следующих установленных:
- cURL для вызовов REST API.
- Установлен Python 3.x

Подготовка обучающих данных

Чтобы обучить пользовательскую категорию, вам потребуется пример текстовых данных, представляющих категорию, которую вы хотите обнаружить. Выполните следующие действия, чтобы подготовить примеры данных:

Сбор или запись примеров данных:
- Качество примеров данных важно для обучения эффективной модели. Стремится собрать по крайней мере 50 положительных выборок, которые точно представляют содержимое, которое вы хотите определить. Эти примеры должны быть четкими, разнообразными и напрямую связаны с определением категории.
- Отрицательные примеры не требуются, но они могут улучшить способность модели различать релевантный контент от неуместного содержимого. Чтобы повысить производительность, нацелуйтесь на 50 примеров, которые не связаны с положительным определением регистра. Они должны быть разнообразными, но по-прежнему в контексте содержимого, с которым будет сталкиваться ваша модель. Тщательно выбирайте отрицательные выборки, чтобы убедиться, что они непреднамеренно перекрываются с положительной категорией.
- Стремиться к балансу между количеством положительных и отрицательных выборок. Неровный набор данных может предвзять модель, что приводит к тому, что она предпочитает один тип классификации по сравнению с другим, что может привести к более высокой скорости ложных срабатываний или отрицательных значений.
Используйте текстовый редактор для форматирования данных в JSONL-файле . Ниже приведен пример соответствующего формата. Примеры категорий должны иметь значение isPositive true. Отрицательные примеры являются необязательными, но могут повысить производительность:
```
{"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}
```
Отправьте JSONL-файл в контейнер BLOB-объектов служба хранилища Azure учетной записи. Скопируйте URL-адрес большого двоичного объекта в временное расположение для последующего использования.

Предоставление доступа к хранилищу

Затем необходимо предоставить ресурс безопасности содержимого для чтения из ресурса служба хранилища Azure. Включите управляемое удостоверение, назначаемое системой для экземпляра Безопасности содержимого ИИ Azure, и назначьте роль участника данных BLOB-объектов хранилища, владельца или читателя удостоверения:

Включите управляемое удостоверение для экземпляра безопасности содержимого ИИ Azure.
Назначьте роль участника или владельца данных BLOB-объектов хранилища управляемому удостоверению. Все роли, выделенные ниже, должны работать.

Создание и обучение пользовательской категории

Внимание

Разрешить достаточно времени для обучения модели

Сквозное выполнение обучения пользовательских категорий может занять от пяти часов до десяти часов. Запланируйте конвейер модерации соответствующим образом и выделите время:

Сбор и подготовка примеров данных
Учебный процесс
Оценка и корректировка модели

cURL
Python

В приведенных ниже командах замените <your_api_key>и <your_endpoint>другие необходимые параметры собственными значениями. Затем введите каждую команду в окне терминала и запустите ее.

Создание новой версии категории

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\"
     }"

Запустите процесс сборки категории:

После получения ответа сохраните идентификатор операции (который называется id) временным. Этот идентификатор необходим для получения состояния сборки с помощью API получения состояния get.

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"

Получите состояние сборки категории:

Чтобы получить состояние, используйте id полученный из предыдущего ответа API и поместите его в путь к API ниже.

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"

Анализ текста с помощью настраиваемой категории

Выполните следующую команду, чтобы проанализировать текст с помощью настраиваемой категории. Замените <your_category_name> собственным значением:

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:

pip install requests

Затем откройте новый скрипт Python и определите необходимые переменные с собственными сведениями о ресурсе Azure:

import requests

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

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

Создание новой версии категории

Вы можете создать новую категорию с именем категории, определением и sample_blob_url, и вы получите автоматически созданный номер версии этой категории.

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)

Запуск процесса сборки категории

Вы можете запустить процесс сборки категории с именем категории и номером версии.

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)

Получите состояние сборки категории:

Чтобы получить состояние, используйте id полученный из предыдущего ответа.

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)

Анализ текста с помощью настраиваемой категории

Необходимо указать имя категории и номер версии (необязательно; служба использует последнюю по умолчанию) во время вывода. Можно указать несколько категорий, если они уже определены.

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)

Другие пользовательские операции категории

Не забудьте заменить заполнители ниже фактическими значениями ключа API, конечной точки и определенного содержимого (имя категории, определение и т. д.). Эти примеры помогают управлять настраиваемыми категориями в вашей учетной записи.

cURL
Python

Получение настраиваемой категории или определенной версии ее

Замените заполнители собственными значениями и выполните следующую команду в окне терминала:

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"

Замените заполнители собственными значениями и выполните следующую команду в окне терминала:

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"

Удаление настраиваемой категории или определенной версии ее

Замените заполнители собственными значениями и выполните следующую команду в окне терминала:

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:

pip install requests

Затем настройте необходимые конфигурации с помощью собственных сведений о ресурсе ИИ:

import requests

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

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

Получение настраиваемой категории или определенной версии ее

Замените заполнители собственными значениями и запустите следующий код в скрипте 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)

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)

Удаление настраиваемой категории или определенной версии ее

Замените заполнители собственными значениями и запустите следующий код в скрипте 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)

Поделиться через

Использование API пользовательских категорий (стандартный)

Необходимые компоненты

Подготовка обучающих данных

Предоставление доступа к хранилищу

Создание и обучение пользовательской категории

Создание новой версии категории

Запустите процесс сборки категории:

Получите состояние сборки категории:

Анализ текста с помощью настраиваемой категории

Создание новой версии категории

Запуск процесса сборки категории

Получите состояние сборки категории:

Анализ текста с помощью настраиваемой категории

Другие пользовательские операции категории

Получение настраиваемой категории или определенной версии ее

Удаление настраиваемой категории или определенной версии ее

Получение настраиваемой категории или определенной версии ее

Удаление настраиваемой категории или определенной версии ее

Обратная связь

Дополнительные ресурсы

Поделиться через

Использование API пользовательских категорий (стандартный)

Необходимые компоненты

Подготовка обучающих данных

Предоставление доступа к хранилищу

Создание и обучение пользовательской категории

Создание новой версии категории

Запустите процесс сборки категории:

Получите состояние сборки категории:

Анализ текста с помощью настраиваемой категории

Другие пользовательские операции категории

Получение настраиваемой категории или определенной версии ее

Список категорий последних версий

Удаление настраиваемой категории или определенной версии ее

Связанный контент

Обратная связь

Дополнительные ресурсы