Szybki start: kategorie niestandardowe (tryb standardowy) (wersja zapoznawcza)

Postępuj zgodnie z tym przewodnikiem, aby użyć interfejsu API REST niestandardowych kategorii bezpieczeństwa zawartości usługi Azure AI (standard), aby utworzyć własne kategorie zawartości dla przypadku użycia i wytrenować bezpieczeństwo zawartości usługi Azure AI w celu wykrycia ich w nowej zawartości tekstowej.

Aby uzyskać więcej informacji na temat kategorii niestandardowych, zobacz stronę pojęcia Kategorie niestandardowe. Aby uzyskać informacje o limitach danych wejściowych interfejsu API, zobacz sekcję Wymagania dotyczące danych wejściowych w sekcji Przegląd.

Ważne

Ta funkcja jest dostępna tylko w niektórych regionach świadczenia usługi Azure. Zobacz Dostępność regionów.

Ważne

Zezwalaj na wystarczająco dużo czasu na trenowanie modelu

Kompleksowe wykonywanie trenowania kategorii niestandardowych może potrwać od około pięciu godzin do dziesięciu godzin. Zaplanuj odpowiednio potok moderowania.

Wymagania wstępne

• Subskrypcja platformy Azure — utwórz bezpłatnie
• Po utworzeniu subskrypcji platformy Azure utwórz zasób Bezpieczeństwo zawartości w witrynie Azure Portal, aby uzyskać klucz i punkt końcowy. Wprowadź unikatową nazwę zasobu, wybierz subskrypcję i wybierz grupę zasobów, obsługiwany region i obsługiwaną warstwę cenową. Następnie wybierz Utwórz.
  • Wdrożenie zasobu trwa kilka minut. Po zakończeniu wybierz pozycję Przejdź do zasobu. W okienku po lewej stronie w obszarze Zarządzanie zasobami wybierz pozycję Klucz subskrypcji i punkt końcowy. Skopiuj punkt końcowy i jedną z wartości klucza do lokalizacji tymczasowej do późniejszego użycia.
• Utwórz również kontener usługi Azure Blob Storage, w którym będziesz przechowywać plik adnotacji szkoleniowych.
• Zainstalowano jedną z następujących opcji:
  • cURL dla wywołań interfejsu API REST.
  • Zainstalowany język Python 3.x

Przygotowywanie danych treningowych

Aby wytrenować kategorię niestandardową, potrzebujesz przykładowych danych tekstowych reprezentujących kategorię, którą chcesz wykryć. W tym przewodniku możesz użyć przykładowych danych. Podany plik adnotacji zawiera tekstowe monity o porady dotyczące przetrwania w sytuacjach kempingowych/dzikiej przyrody. Wytrenowany model nauczy się wykrywać ten typ zawartości w nowych danych tekstowych.

Napiwek

Aby uzyskać porady dotyczące tworzenia własnego zestawu danych, zobacz Przewodnik z instrukcjami.

1. Pobierz przykładowy plik danych tekstowych z repozytorium GitHub.
2. Przekaż plik jsonl do kontenera obiektów blob konta usługi Azure Storage. Następnie skopiuj adres URL obiektu blob do lokalizacji tymczasowej do późniejszego użycia.

Ważne

Konto magazynu użytkownika jest skonfigurowane jako konto hierarchicznej przestrzeni nazw, które nie może być obsługiwane przez kategorie niestandardowe. Spróbuj zamiast tego użyć zwykłego konta magazynu. Na przykład adres URL obiektu blob nie może być podzielony na dwie warstwy, takie jak example/example1/, i powinien mieć tylko jedną warstwę. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją: Hierarchiczna przestrzeń nazw usługi Azure Data Lake Storage — Azure Storage.

Udzielanie dostępu do magazynu

Następnie należy przyznać dostęp do zasobu Bezpieczeństwo zawartości w celu odczytu z zasobu usługi Azure Storage. Włącz tożsamość zarządzaną przypisaną przez system dla wystąpienia bezpieczeństwa zawartości usługi Azure AI i przypisz rolę Współautor/Właściciel danych obiektu blob usługi Storage do tożsamości:

Ważne

Tylko współautor danych obiektu blob usługi Storage lub właściciel danych obiektu blob usługi Storage są prawidłowe, aby kontynuować.

1. Włącz tożsamość zarządzaną dla wystąpienia bezpieczeństwa zawartości usługi Azure AI.

   

2. Przypisz rolę Współautor/Właściciel danych obiektu blob usługi Storage do tożsamości zarządzanej. Wszystkie role wyróżnione poniżej powinny działać.

   

   

   

Tworzenie i trenowanie kategorii niestandardowej

cURL

W poniższym poleceniu zastąp <your_api_key>wartości , <your_endpoint>i innymi wymaganymi parametrami własnymi wartościami. Następnie wprowadź każde polecenie w oknie terminalu i uruchom je.

Tworzenie nowej wersji kategorii

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

Napiwek

Za każdym razem, gdy zmienisz nazwę kategorii, definicję lub przykłady, zostanie utworzona nowa wersja. Możesz użyć numeru wersji do śledzenia z powrotem do poprzednich wersji. Pamiętaj ten numer wersji, ponieważ będzie on wymagany w adresie URL dla następnych kategorii niestandardowych trenowania.

Żądanie procesora API

Pole	Opis	Przykładowa wartość
categoryName	Nazwa kategorii lub tematu, do którego odnosi się żądanie.	porady dotyczące przetrwania
definition	Krótki opis typu zawartości dla kategorii.	tekst monituje o porady dotyczące przetrwania w sytuacjach kempingowych/dzikiej przyrody
sampleBlobUrl	Adres URL umożliwiający uzyskanie dostępu do przykładowego pliku JSONL zawierającego przykłady danych dla kategorii.	Link

Odpowiedź interfejsu API

Pole	Opis	Przykładowa wartość
categoryName	Nazwa kategorii lub tematu, z którego odnosi się odpowiedź.	porady dotyczące przetrwania
definition	Krótki opis typu zawartości dla kategorii.	tekst monituje o porady dotyczące przetrwania w sytuacjach kempingowych/dzikiej przyrody
sampleBlobUrl	Adres URL umożliwiający uzyskanie dostępu do przykładowego pliku JSONL zawierającego przykłady danych dla kategorii.	Link
sampleBlobSnapshotUrl	Adres URL migawki przykładowego pliku JSONL, który zapewnia dostęp do określonej wersji danych.	Adres URL migawki
version	Numer wersji danych kategorii.	1
createdTime	Sygnatura czasowa utworzenia danych kategorii.	2024-10-28T22:06:59.4626988Z
status	Bieżący stan przetwarzania danych kategorii.	Powodzenie

Uruchom proces kompilacji kategorii:

Zastąp <your_api_key> i <your_endpoint> własnymi wartościami, a także dołącz numer wersji w adresie URL uzyskanym w ostatnim kroku. Zezwalaj na wystarczająco dużo czasu na trenowanie modelu: kompleksowe wykonywanie trenowania kategorii niestandardowej może potrwać od około pięciu godzin do dziesięciu godzin. Zaplanuj odpowiednio potok moderowania. Po otrzymaniu odpowiedzi zapisz identyfikator operacji (określany jako id) w lokalizacji tymczasowej. Ten identyfikator będzie niezbędny do pobierania stanu kompilacji przy użyciu interfejsu API Pobierania stanu w następnej sekcji.

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"

Odpowiedź interfejsu API

Pole	Opis	Przykładowa wartość
operation id	Unikatowy identyfikator pobierania stanu kompilacji	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
status	Bieżący stan żądania	Powodzenie

Pobierz stan kompilacji kategorii:

Aby pobrać stan, skorzystaj z uzyskanej id z poprzedniej odpowiedzi interfejsu API i umieść ją w ścieżce poniższego interfejsu 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"

Odpowiedź interfejsu API

Pole	Opis	Przykładowa wartość
operation id	Unikatowy identyfikator pobierania stanu kompilacji	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
status	Bieżący stan żądania	Powodzenie

Analizowanie tekstu przy użyciu dostosowanej kategorii

Uruchom następujące polecenie, aby przeanalizować tekst przy użyciu dostosowanej kategorii. Zastąp <your_api_key> wartości i <your_endpoint> własnymi wartościami.

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

Żądanie procesora API

Pole	opis
text	Zawartość tekstowa lub wiadomość przeznaczona do wykrywania kategorii
categoryName	Nazwa kategorii, w której ma zostać wykryty tekst
version	Numer wersji kategorii

Odpowiedź interfejsu API

Pole	Opis	Przykładowa wartość
customCategoryAnalysis	Obiekt zawierający wynik analizy dla kategorii.	—
detected	Wskazuje, czy określona kategoria została wykryta.	fałsz

Python

Najpierw należy zainstalować wymaganą bibliotekę języka Python:

pip install requests

Następnie otwórz nowy skrypt języka Python i zdefiniuj niezbędne zmienne przy użyciu własnych szczegółów zasobu platformy Azure:

import requests

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

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

Tworzenie nowej kategorii

Możesz utworzyć nową kategorię z nazwą kategorii, definicją i sample_blob_url, a następnie uzyskasz automatycznie wygenerowany numer wersji tej kategorii.

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)

Uruchamianie procesu kompilacji kategorii

Proces kompilacji kategorii można rozpocząć z nazwą kategorii i numerem wersji. Zezwalaj na wystarczająco dużo czasu na trenowanie modelu: kompleksowe wykonywanie trenowania kategorii niestandardowej może potrwać od około pięciu godzin do dziesięciu godzin. Zaplanuj odpowiednio potok moderowania. Po otrzymaniu odpowiedzi upewnij się, że identyfikator operacji (określany jako ) jest przechowywany w dowolnym miejscu, takim jak idnotes. Ten identyfikator będzie niezbędny do pobrania stanu kompilacji przy użyciu funkcji "get_build_status" w następnej sekcji.

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)

Pobierz stan kompilacji kategorii:

Aby pobrać stan, skorzystaj z uzyskanej id z poprzedniej odpowiedzi.

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)

Analizowanie tekstu przy użyciu dostosowanej kategorii

Podczas wnioskowania należy określić nazwę kategorii i numer wersji (opcjonalnie; usługa używa najnowszej domyślnie). Możesz określić wiele kategorii, jeśli zostały już zdefiniowane.

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)

Inne operacje kategorii niestandardowych

Pamiętaj, aby zastąpić symbole zastępcze poniżej rzeczywistymi wartościami klucza interfejsu API, punktu końcowego i określonej zawartości (nazwa kategorii, definicja itd.). Te przykłady ułatwiają zarządzanie dostosowanymi kategoriami na koncie.

cURL

Pobieranie dostosowanej kategorii lub określonej wersji

Zastąp symbole zastępcze własnymi wartościami i uruchom następujące polecenie w oknie terminalu:

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"

Wyświetlanie listy kategorii najnowszych wersji

Zastąp symbole zastępcze własnymi wartościami i uruchom następujące polecenie w oknie terminalu:

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"

Usuwanie dostosowanej kategorii lub określonej wersji

Zastąp symbole zastępcze własnymi wartościami i uruchom następujące polecenie w oknie terminalu:

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

Najpierw upewnij się, że zainstalowano wymaganą bibliotekę języka Python:

pip install requests

Następnie skonfiguruj niezbędne konfiguracje przy użyciu własnych szczegółów zasobów sztucznej inteligencji:

import requests

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

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

Pobieranie dostosowanej kategorii lub określonej wersji

Zastąp symbole zastępcze własnymi wartościami i uruchom następujący kod w skrypcie języka 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)

Wyświetlanie listy kategorii najnowszych wersji

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)

Usuwanie dostosowanej kategorii lub określonej wersji

Zastąp symbole zastępcze własnymi wartościami i uruchom następujący kod w skrypcie języka 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)

Powiązana zawartość

• Pojęcia dotyczące kategorii niestandardowych
• Moderowanie zawartości przy użyciu bezpieczeństwa zawartości