빠른 시작: 사용자 지정 범주(표준 모드)(미리 보기)

이 가이드에 따라 Azure AI 콘텐츠 보안 사용자 지정 범주(표준) REST API를 사용하여 사용 사례에 대한 자체 콘텐츠 범주를 만들고 Azure AI 콘텐츠 보안을 학습하여 새 텍스트 콘텐츠에서 이를 검색합니다.

사용자 지정 범주에 대한 자세한 내용은 사용자 지정 범주 개념 페이지를 참조하세요. API 입력 제한에 대해서는 개요의 입력 요구 사항 섹션을 참조하세요.

Important

이 기능은 특정 Azure 지역에서만 사용할 수 있습니다. 지역 가용성을 참조하세요.

Important

모델 학습에 충분한 시간 허용

사용자 지정 범주 학습의 전체 실행에는 약 5시간에서 10시간이 걸릴 수 있습니다. 이에 따라 조정 파이프라인을 계획합니다.

필수 조건

• Azure 구독 - 체험 구독 만들기
• Azure 구독이 있으면 Azure Portal에서 콘텐츠 안전 리소스를 생성하여 키와 엔드포인트를 가져옵니다. 리소스의 고유한 이름을 입력하고, 구독을 선택하고, 리소스 그룹과 지원되는 지역, 지원되는 가격 책정 계층을 선택합니다. 다음으로 만들기를 선택합니다.
  • 리소스를 배포하는 데 몇 분 정도 걸립니다. 완료되면 리소스로 이동을 선택합니다. 왼쪽 창의 리소스 관리에서 구독 키 및 엔드포인트를 선택합니다. 나중에 사용할 수 있도록 엔드포인트와 키 값 중 하나를 임시 위치에 복사합니다.
• 또한 학습 주석 파일을 보관할 Azure Blob Storage 컨테이너를 만듭니다.
• 다음 중 하나가 설치되었습니다.
  • REST API 호출을 위한 cURL.
  • Python 3.x가 설치되었습니다.

학습 데이터 준비

사용자 지정 범주를 학습하려면 검색하려는 범주를 나타내는 예 텍스트 데이터가 필요합니다. 이 가이드에서는 샘플 데이터를 사용할 수 있습니다. 제공된 주석 파일에는 캠핑/야생 상황에서의 생존 조언에 대한 텍스트 프롬프트가 포함되어 있습니다. 학습된 모델은 새로운 텍스트 데이터에서 이러한 형식의 콘텐츠를 검색하는 방법을 학습합니다.

팁

고유의 데이터 세트를 만드는 방법에 대한 도움말은 방법 가이드를 참조하세요.

1. GitHub 리포지토리에서 샘플 텍스트 데이터 파일을 다운로드합니다.
2. Azure Storage 계정 Blob 컨테이너에 .jsonl 파일을 업로드합니다. 그런 다음 나중에 사용할 수 있도록 Blob URL을 임시 위치에 복사합니다.

Important

사용자의 스토리지 계정은 사용자 지정 범주에서 지원될 수 없는 계층 구조 네임스페이스 계정으로 설정됩니다. 대신 일반 스토리지 계정을 사용해 보세요. 예를 들어 Blob URL은 example/example1/과 같은 두 계층으로 분할할 수 없으며 계층이 하나만 있어야 합니다. 자세한 내용은 Azure Data Lake Storage 계층 구조 네임스페이스 - Azure Storage 설명서를 참조하세요.

스토리지 액세스 권한 부여

그 후에 Azure Storage 리소스에서 읽을 수 있는 콘텐츠 안전 리소스 액세스 권한을 부여해야 합니다. Azure AI Content Safety 인스턴스에 시스템 할당 관리 ID를 사용하도록 설정하고 스토리지 Blob 데이터 기여자/소유자의 역할을 ID에 할당합니다.

Important

Storage Blob 데이터 기여자 또는 스토리지 Blob 데이터 소유자만 유효한 역할을 진행합니다.

1. Azure AI 콘텐츠 안전 인스턴스에 관리 ID를 사용하도록 설정합니다.

   

2. 관리 ID에 Storage 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	범주에 대한 데이터 예제를 포함하는 샘플 JSONL 파일에 액세스하기 위한 URL입니다.	링크

API 응답

필드	설명	값 예
categoryName	응답과 관련된 범주 또는 토픽의 이름입니다.	생존 조언
definition	범주의 콘텐츠 형식에 대한 간략한 설명입니다.	캠핑 / 광야 상황에서 생존 조언에 대한 텍스트 프롬프트
sampleBlobUrl	범주에 대한 데이터 예제를 포함하는 샘플 JSONL 파일에 액세스하기 위한 URL입니다.	링크
sampleBlobSnapshotUrl	데이터의 특정 버전에 대한 액세스를 제공하는 샘플 JSONL 파일의 스냅샷 URL입니다.	스냅샷 URL
version	범주 데이터의 버전 번호입니다.	1
createdTime	범주 데이터가 만들어진 타임스탬프입니다.	2024-10-28T22:06:59.4626988Z
status	범주 데이터 처리의 현재 상태입니다.	성공함

범주 빌드 프로세스 시작:

<your_api_key> 및 <your_endpoint> 고유한 값으로 바꾸고 마지막 단계에서 얻은 URL에 버전 번호도 추가합니다. 모델 학습에 충분한 시간 허용: 사용자 지정 범주 학습의 엔드 투 엔드 실행은 약 5시간에서 10시간 정도 걸릴 수 있습니다. 이에 따라 조정 파이프라인을 계획합니다. 응답을 받은 후 작업 ID(id라고 함)를 임시 위치에 저장합니다. 이 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-xxxxxxxxxxxx
status	요청의 현재 상태	성공함

범주 빌드 상태를 가져오기:

상태를 검색하려면 이전 API 응답에서 가져오는 id를 활용하여 아래 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-xxxxxxxxxxxx
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 요청

필드	설명
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)

범주 빌드 프로세스 시작

범주 이름과 버전 번호를 사용하여 범주 빌드 프로세스를 시작할 수 있습니다. 모델 학습에 충분한 시간을 허용합니다. 사용자 지정 범주 학습의 전체 실행에는 약 5시간에서 10시간이 걸릴 수 있습니다. 이에 따라 조정 파이프라인을 계획합니다. 응답을 받은 후 작업 ID(id라고 함)를 Notebook과 같은 곳에 저장했는지 확인합니다. 이 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

그런 다음 자체 AI 리소스 세부 정보로 필요한 구성을 설정합니다.

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)

관련 콘텐츠

• 사용자 지정 범주 개념
• 콘텐츠 보안을 고려한 콘텐츠 검토