Краткое руководство. Пользовательские категории (стандартный режим) (предварительная версия)

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

Дополнительные сведения о пользовательских категориях см. на странице концепции пользовательских категорий. Сведения о ограничениях ввода API см. в разделе "Требования к входным данным" в разделе "Обзор".

Внимание

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

Внимание

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

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

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

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

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

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

Совет

Советы по созданию собственного набора данных см. в руководстве по созданию собственного набора данных.

1. Скачайте пример текстового файла данных из репозитория GitHub.
2. Отправьте JSONL-файл в контейнер BLOB-объектов служба хранилища Azure учетной записи. Затем скопируйте URL-адрес большого двоичного объекта в временное расположение для последующего использования.

Внимание

Учетная запись хранения пользователя настраивается как иерархическая учетная запись пространства имен, которая не может поддерживаться пользовательскими категориями. Попробуйте использовать обычную учетную запись хранения. Например, URL-адрес большого двоичного объекта не может быть разделен на два уровня, например example/example1/, и должен иметь только один слой. Дополнительные сведения см. в документации: иерархическое пространство имен Azure Data Lake Storage — служба хранилища Azure.

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

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

Внимание

Продолжить можно только участником данных BLOB-объектов хранилища или владельцем данных BLOB-объектов хранилища.

1. Включите управляемое удостоверение для экземпляра безопасности содержимого ИИ Azure.

   

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

   

   

   

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

cURL

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

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

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

Совет

Каждый раз, когда вы изменяете имя категории, определение или примеры, будет создана новая версия. Номер версии можно использовать для трассировки до предыдущих версий. Запомните этот номер версии, так как он будет необходим в URL-адресе для следующих этапов обучения пользовательских категорий.

API-запрос

Поле	Описание	Пример значения
categoryName	Имя категории или раздела, к к который относится запрос.	советы по выживанию
definition	Краткое описание типа контента для категории.	текст запрашивает советы по выживанию в ситуациях кемпинга и дикой природы
sampleBlobUrl	URL-адрес для доступа к образцу JSONL-файла, содержащего примеры данных для категории.	Ссылка

Ответ API

Поле	Описание	Пример значения
categoryName	Имя категории или раздела, к который относится ответ.	советы по выживанию
definition	Краткое описание типа контента для категории.	текст запрашивает советы по выживанию в ситуациях кемпинга и дикой природы
sampleBlobUrl	URL-адрес для доступа к образцу JSONL-файла, содержащего примеры данных для категории.	Ссылка
sampleBlobSnapshotUrl	URL-адрес моментального снимка примера JSONL-файла, который предоставляет доступ к определенной версии данных.	URL-адрес моментального снимка
version	Номер версии данных категории.	1
createdTime	Метка времени при создании данных категории.	2024-10-28T22:06:59.462698Z
status	Текущее состояние обработки данных категории.	Выполнено

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

Замените <your_api_key и <your_endpoint>> собственными значениями, а также добавьте номер версии в URL-адрес, полученный на последнем шаге. Разрешить достаточно времени для обучения модели: сквозное выполнение обучения пользовательских категорий может занять от пяти часов до десяти часов. Запланируйте конвейер модерации соответствующим образом. После получения ответа сохраните идентификатор операции (который называется id) во временном расположении. Этот идентификатор будет необходим для получения состояния сборки с помощью API получения состояния в следующем разделе.

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"

Ответ API

Поле	Описание	Пример значения
operation id	Уникальный идентификатор для получения состояния сборки	b6c69dc1-2338-484e-85a5b-xxxx
status	Текущее состояние запроса	Выполнено

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

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

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"

Ответ API

Поле	Описание	Пример значения
operation id	Уникальный идентификатор для получения состояния сборки	b6c69dc1-2338-484e-855b-xxxxx
status	Текущее состояние запроса	Выполнено

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

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

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

API-запрос

Поле	Description
text	Текстовое содержимое или сообщение, предназначенное для обнаружения категорий
categoryName	Имя категории, в которой должен быть обнаружен текст
version	Номер версии категории

Ответ API

Поле	Описание	Пример значения
customCategoryAnalysis	Объект, содержащий результат анализа для категории.	—
detected	Указывает, обнаружена ли указанная категория.	false

Python

Сначала необходимо установить необходимую библиотеку 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-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)

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

Вы можете запустить процесс сборки категории с именем категории и номером версии. Разрешить достаточно времени для обучения модели: сквозное выполнение обучения пользовательских категорий может занять от пяти часов до десяти часов. Запланируйте конвейер модерации соответствующим образом. После получения ответа убедитесь, что вы храните идентификатор операции (называемый id) где-то, как записная книжка. Этот идентификатор будет необходим для получения состояния сборки с помощью функции "get_build_status" в следующем разделе.

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)

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

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

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)

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

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

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)

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

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

cURL

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

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

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"

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

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

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"

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

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

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

Сначала убедитесь, что вы установили необходимую библиотеку 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-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)

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

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)

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

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

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

• Основные понятия пользовательских категорий
• Умеренное содержимое с помощью безопасности содержимого