Použití rozhraní API vlastních kategorií (Standard) (Preview)

Článek
09/02/2024

Rozhraní API vlastních kategorií (standard) umožňuje 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 obsahu.

Důležité

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

Upozornění

Ukázková data v této příručce můžou obsahovat urážlivý obsah. Doporučuje se, aby uživatel rozhodoval.

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. Při přípravě ukázkových dat postupujte takto:

Shromážděte nebo zapište ukázková data:
- Kvalita ukázkových dat je důležitá pro trénování efektivního modelu. Snažte se shromáždit alespoň 50 pozitivních vzorků, které přesně představují obsah, který chcete identifikovat. Tyto ukázky by měly být jasné, různé a přímo související s definicí kategorie.
- Negativní vzorky nejsou povinné, ale můžou zlepšit schopnost modelu odlišit relevantní obsah od irelevantního obsahu. Pokud chcete zvýšit výkon, zaměřte se na 50 vzorků, které nesouvisejí s definicí pozitivního případu. Ty by se měly lišit, ale stále v kontextu obsahu, se kterým se váš model setká. Pečlivě vyberte záporné vzorky, abyste zajistili, že se neúmyslně nepřekrývají s pozitivní kategorií.
- Snažte se o rovnováhu mezi počtem kladných a záporných vzorků. Nerovnoměrná datová sada může model předsunout, což způsobí, že upřednostní jeden typ klasifikace oproti jinému, což může vést k vyšší míře falešně pozitivních nebo negativních výsledků.
K formátování dat v souboru .jsonl použijte textový editor. Níže je uveden příklad odpovídajícího formátu. Příklady kategorií by měly být nastaveny isPositive na truehodnotu . Negativní příklady jsou volitelné, ale můžou zlepšit výkon:
```
{"text": "This is the 1st sample.", "isPositive": true}
{"text": "This is the 2nd sample.", "isPositive": true}
{"text": "This is the 3rd sample (negative).", "isPositive": false}
```
Nahrajte soubor .jsonl do kontejneru objektů blob účtu Azure Storage. Zkopírujte adresu URL objektu blob do dočasného umístění pro pozdější použití.

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.

Povolte spravovanou identitu pro instanci Zabezpečení obsahu Azure AI.
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

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í a přidělte čas pro:

Shromažďování a příprava ukázkových dat
Proces trénování
Vyhodnocení a úpravy modelu

cURL
Python

V následujícíchpříkazch <your_api_key><your_endpoint> 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-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
        \"categoryName\": \"<your_category_name>\",
        \"definition\": \"<your_category_definition>\",
        \"sampleBlobUrl\": \"https://example.blob.core.windows.net/example-container/sample.jsonl\"
     }"

Spusťte proces sestavení kategorie:

Po přijetí odpovědi uložte ID operace (označované jako id) do dočasného. Toto ID potřebujete k načtení stavu sestavení pomocí rozhraní API pro získání stavu .

curl -X POST "<your_endpoint>/contentsafety/text/categories/<your_category_name>:build?api-version=2024-02-15-preview&version={version}" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

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-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

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_category_name> vlastní hodnotou:

curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
        \"text\": \"Example text to analyze\",
        \"categoryName\": \"<your_category_name>\", 
        \"version\": 1
        }"

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é verze 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-02-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 = "DrugAbuse"
definition = "This category is related to Drug Abuse."
sample_blob_url = "https://<your-azure-storage-url>/example-container/drugsample.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.

def trigger_category_build_process(category_name, version):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}:build?api-version=2024-02-15-preview&version={version}"
    response = requests.post(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "<your_category_name>"
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-02-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-02-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 = "<your_category_name>"
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
Python

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-02-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

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-02-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-02-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

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-02-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-02-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-02-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)

Sdílet prostřednictvím

Použití rozhraní API vlastních kategorií (Standard) (Preview)

Požadavky

Příprava trénovacích dat

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

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

Vytvoření nové verze kategorie

Spusťte proces sestavení kategorie:

Získejte stav sestavení kategorie:

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

Vytvoření nové verze kategorie

Zahájení procesu sestavení kategorie

Získejte stav sestavení kategorie:

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

Další operace s vlastními kategoriemi

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

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

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

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

Váš názor

Další materiály

Sdílet prostřednictvím

Použití rozhraní API vlastních kategorií (Standard) (Preview)

Požadavky

Příprava trénovacích dat

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

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

Vytvoření nové verze kategorie

Spusťte proces sestavení kategorie:

Získejte stav sestavení kategorie:

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

Další operace s vlastními kategoriemi

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

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

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

Související obsah

Váš názor

Další materiály