Rychlý start: Vlastní kategorie (standardní režim) (Preview)

Podle tohoto průvodce můžete pomocí vlastní kategorie REST API (Standardní) zabezpečení obsahu Azure AI vytvořit vlastní kategorie obsahu pro váš případ použití a vytrénovat zabezpečení obsahu Azure AI tak, aby je detekoval v novém textovém obsahu.

Další informace o vlastních kategoriích najdete na stránce konceptů vlastních kategorií. Informace o limitech vstupu rozhraní API najdete v části Požadavky na vstup v části Přehled.

Důležité

Tato funkce je dostupná jenom v určitých oblastech Azure. Viz Dostupnost oblastí.

Důležité

Povolit dostatek času pro trénování modelu

Kompletní provádění vlastního trénování kategorií může trvat přibližně pět hodin až deset hodin. Podle toho naplánujte kanál moderování.

Požadavky

• Předplatné Azure – Vytvoření předplatného zdarma
• Jakmile budete mít předplatné Azure, vytvořte na webu Azure Portal prostředek zabezpečení obsahu, abyste získali svůj klíč a koncový bod. Zadejte jedinečný název vašeho prostředku, vyberte předplatné a vyberte skupinu prostředků, podporovanou oblast a podporovanou cenovou úroveň. Pak vyberte Vytvořit.
  • Nasazení prostředku trvá několik minut. Po dokončení vyberte přejít k prostředku. V levém podokně v části Správa prostředků vyberte Klíč předplatného a koncový bod. Zkopírujte koncový bod a jednu z hodnot klíčů do dočasného umístění pro pozdější použití.
• Vytvořte také kontejner úložiště objektů blob v Azure, kde zachováte trénovací soubor poznámek.
• Nainstalujte jednu z následujících instalací:
  • cURL pro volání rozhraní REST API.
  • Nainstalovaný Python 3.x

Příprava trénovacích dat

Pokud chcete vytrénovat vlastní kategorii, potřebujete ukázková textová data představující kategorii, kterou chcete zjistit. V této příručce můžete použít ukázková data. Zadaný soubor poznámek obsahuje textové výzvy týkající se poradenství o přežití v situacích kempování/divočin. Natrénovaný model se naučí rozpoznat tento typ obsahu v nových textových datech.

Tip

Tipy k vytvoření vlastní sady dat najdete v průvodci postupy.

1. Stáhněte si ukázkový textový datový soubor z úložiště GitHub.
2. Nahrajte soubor .jsonl do kontejneru objektů blob účtu Azure Storage. Pak zkopírujte adresu URL objektu blob do dočasného umístění pro pozdější použití.

Důležité

Účet úložiště uživatele je nastavený jako účet hierarchického oboru názvů, který nemůže být podporován vlastními kategoriemi. Zkuste místo toho použít běžný účet úložiště. Například adresu URL objektu blob nelze rozdělit do dvou vrstev, například example/example1/, a měla by obsahovat jenom jednu vrstvu. Další podrobnosti najdete v dokumentaci: Hierarchický obor názvů Azure Data Lake Storage – Azure Storage.

Udělení přístupu k úložišti

V dalším kroku potřebujete udělit vašemu prostředku zabezpečení obsahu přístup ke čtení z prostředku služby Azure Storage. Povolte spravovanou identitu přiřazenou systémem pro instanci Azure AI Content Safety a přiřaďte k identitě roli Přispěvatel dat objektů blob služby Storage nebo Vlastník :

Důležité

Pokračujte pouze přispěvatelem dat v objektech blob služby Storage nebo vlastníkem dat objektů blob služby Storage.

1. Povolte spravovanou identitu pro instanci Zabezpečení obsahu Azure AI.

   

2. Přiřaďte spravované identitě roli Přispěvatel dat objektů blob služby Storage nebo Vlastník . Všechny níže zvýrazněné role by měly fungovat.

   

   

   

Vytvoření a trénování vlastní kategorie

cURL

V následujícím příkazu nahraďte <your_api_key>, <your_endpoint>a další nezbytné parametry vlastními hodnotami. Pak zadejte každý příkaz v okně terminálu a spusťte ho.

Vytvoření nové verze kategorie

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

Tip

Pokaždé, když změníte název kategorie, definici nebo ukázky, se vytvoří nová verze. Číslo verze můžete použít k trasování zpět k předchozím verzím. Nezapomeňte prosím, že toto číslo verze, protože se bude vyžadovat v adrese URL pro další krok – trénování vlastních kategorií.

Požadavek API

Pole	Popis	Příklad hodnoty
categoryName	Název kategorie nebo tématu, ke které požadavek souvisí.	poradenství pro přežití
definition	Stručný popis typu obsahu pro kategorii.	text prompts about survival advice in camping/divočina situace
sampleBlobUrl	Adresa URL pro přístup k ukázkovým souborům JSONL obsahujícím příklady dat pro kategorii	Odkaz

Odpověď rozhraní API

Pole	Popis	Příklad hodnoty
categoryName	Název kategorie nebo tématu, ke které odpověď souvisí.	poradenství pro přežití
definition	Stručný popis typu obsahu pro kategorii.	text prompts about survival advice in camping/divočina situace
sampleBlobUrl	Adresa URL pro přístup k ukázkovým souborům JSONL obsahujícím příklady dat pro kategorii	Odkaz
sampleBlobSnapshotUrl	Adresa URL snímku ukázkového souboru JSONL, která poskytuje přístup ke konkrétní verzi dat.	Adresa URL snímku
version	Číslo verze dat kategorií.	0
createdTime	Časové razítko při vytvoření dat kategorií	2024-10-28T22:06:59.4626988Z
status	Aktuální stav zpracování dat kategorií	Úspěšný

Spusťte proces sestavení kategorie:

Nahraďte <your_api_key> a <your_endpoint> vlastními hodnotami a připojte také číslo verze v adrese URL, kterou jste získali z posledního kroku. Počkejte dostatek času na trénování modelu: Kompletní spuštění vlastního trénování kategorií může trvat přibližně pět hodin až deset hodin. Podle toho naplánujte kanál moderování. Po přijetí odpovědi uložte ID operace (označované jako id) do dočasného umístění. Toto ID bude nutné k načtení stavu sestavení pomocí rozhraní API pro získání stavu v další části.

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"

Odpověď rozhraní API

Pole	Popis	Příklad hodnoty
operation id	Jedinečný identifikátor pro načtení stavu sestavení	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
status	Aktuální stav žádosti	Úspěšný

Získejte stav sestavení kategorie:

Pokud chcete načíst stav, použijte id získané z předchozí odpovědi rozhraní API a umístěte ho do cesty níže uvedeného rozhraní 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"

Odpověď rozhraní API

Pole	Popis	Příklad hodnoty
operation id	Jedinečný identifikátor pro načtení stavu sestavení	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
status	Aktuální stav žádosti	Úspěšný

Analýza textu s přizpůsobenou kategorií

Spuštěním následujícího příkazu analyzujte text s přizpůsobenou kategorií. Nahraďte <your_api_key> a <your_endpoint> nahraďte vlastními hodnotami.

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

Požadavek API

Pole	Popis
text	Textový obsah nebo zpráva určená k detekci kategorií
categoryName	Název kategorie, pro které má být text zjištěn
version	Číslo verze kategorie

Odpověď rozhraní API

Pole	Popis	Příklad hodnoty
customCategoryAnalysis	Objekt obsahující výsledek analýzy pro kategorii.	—
detected	Určuje, zda byla zjištěna zadaná kategorie.	false (nepravda)

Python

Nejprve je potřeba nainstalovat požadovanou knihovnu Pythonu:

pip install requests

Pak otevřete nový skript Pythonu a definujte potřebné proměnné s vlastními podrobnostmi o prostředcích Azure:

import requests

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

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

Vytvoření nové kategorie

Můžete vytvořit novou kategorii s názvem kategorie, definicí a sample_blob_url a získáte automaticky vygenerované číslo verze této kategorie.

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)

Zahájení procesu sestavení kategorie

Proces sestavení kategorie můžete zahájit s názvem kategorie a číslem verze. Počkejte dostatek času na trénování modelu: Kompletní spuštění vlastního trénování kategorií může trvat přibližně pět hodin až deset hodin. Podle toho naplánujte kanál moderování. Po přijetí odpovědi se ujistěte, že uložíte ID operace (označované jako id) někde jako váš poznámkový blok. Toto ID bude nutné k načtení stavu sestavení pomocí funkce get_build_status v další části.

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)

Získejte stav sestavení kategorie:

Pokud chcete načíst stav, využijte id získané z předchozí odpovědi.

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)

Analýza textu s přizpůsobenou kategorií

Při odvozování je potřeba zadat název kategorie a číslo verze (volitelné, služba ve výchozím nastavení používá nejnovější verzi). Pokud už jsou definované, můžete zadat více kategorií.

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)

Další operace s vlastními kategoriemi

Nezapomeňte nahradit níže uvedené zástupné symboly skutečnými hodnotami klíče rozhraní API, koncového bodu a konkrétního obsahu (název kategorie, definice atd.). Tyto příklady vám pomůžou spravovat přizpůsobené kategorie ve vašem účtu.

cURL

Získání přizpůsobené kategorie nebo konkrétní verze

Zástupné symboly nahraďte vlastními hodnotami a v okně terminálu spusťte následující příkaz:

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"

Seznam kategorií jejich nejnovějších verzí

Zástupné symboly nahraďte vlastními hodnotami a v okně terminálu spusťte následující příkaz:

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"

Odstranění přizpůsobené kategorie nebo konkrétní verze

Zástupné symboly nahraďte vlastními hodnotami a v okně terminálu spusťte následující příkaz:

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

Nejprve se ujistěte, že jste nainstalovali požadovanou knihovnu Pythonu:

pip install requests

Pak nastavte potřebné konfigurace s vlastními podrobnostmi o prostředku AI:

import requests

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

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

Získání přizpůsobené kategorie nebo konkrétní verze

Zástupné symboly nahraďte vlastními hodnotami a spusťte následující kód ve skriptu Pythonu:

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)

Seznam kategorií jejich nejnovějších verzí

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)

Odstranění přizpůsobené kategorie nebo konkrétní verze

Zástupné symboly nahraďte vlastními hodnotami a spusťte následující kód ve skriptu Pythonu:

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)

Související obsah

• Koncepty vlastních kategorií
• Moderování obsahu s bezpečností obsahu