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

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

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

중요

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

중요

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

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

필수 구성 요소

• Azure 계정. GitHub 계정이 없는 경우 무료로 만들 수 있습니다.
• Azure AI 리소스

설치 프로그램

콘텐츠 안전 사용해 보기 페이지를 사용하려면 다음 단계를 수행합니다.

1. Azure AI 파운드리로 이동한 다음 프로젝트/허브로 이동합니다. 그런 다음 왼쪽 탐색에서 Guardrails + 컨트롤 탭을 선택하고 사용해 보기 탭을 선택합니다.
2. 사용해 보기 페이지에서 조정 가능한 임계값을 사용하여 부적절하거나 유해한 콘텐츠를 필터링하여 텍스트 및 이미지 콘텐츠와 같은 다양한 Guardrails 및 컨트롤 기능을 실험할 수 있습니다.

사용자 지정 범주 사용

이 기능을 사용하면 사용자 고유의 사용자 지정 콘텐츠 범주를 만들고 학습시키고 텍스트 일치 항목을 검사할 수 있습니다.

1. 사용자 지정 범주 패널을 선택합니다.
2. 새 범주 추가를 선택하여 대화 상자를 엽니다. 범주 이름과 텍스트 설명을 입력하고 Blob Storage 컨테이너를 텍스트 학습 데이터와 연결합니다. 만들기 및 학습을 선택합니다.
3. 범주를 하나 선택한 뒤 샘플 입력 텍스트를 입력하고 테스트 실행을 선택합니다. 서비스는 사용자 지정 범주 결과를 반환합니다.

자세한 내용은 사용자 지정 범주 개념 가이드를 참조하세요.

필수 구성 요소

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

학습 데이터 준비

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

팁

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

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

중요

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

스토리지 액세스 권한 부여

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

중요

진행 가능한 적절한 역할은 Storage Blob 데이터 기여자나 Storage 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	지정된 범주가 검색되었는지 여부를 나타냅니다.	거짓

파이썬

먼저, 필수 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 키, 엔드포인트 및 특정 콘텐츠(범주 이름, 정의 등)에 대한 실제 값으로 바꿔야 합니다. 이 예는 계정에서 사용자 지정된 범주를 관리하는 데 도움이 됩니다.

중요

주의해서 API 키를 사용합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요. API 키를 사용하는 경우 Azure Key Vault에 안전하게 저장합니다. 앱에서 API 키를 안전하게 사용하는 방법에 대한 자세한 내용은 Azure Key Vault를 사용하여 API 키를 참조하세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

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 라이브러리를 설치했는지 확인합니다.

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)

관련 콘텐츠

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