Snabbstart: Anpassade kategorier (standardläge) (förhandsversion)

Följ den här guiden om du vill använda REST API för Azure AI Content Safety Custom-kategorier (standard) för att skapa egna innehållskategorier för ditt användningsfall och träna Azure AI Content Safety att identifiera dem i nytt textinnehåll.

Mer information om anpassade kategorier finns på konceptsidan Anpassade kategorier. För API-indatabegränsningar, se avsnittet Indatakrav i översikten.

Viktigt!

Den här funktionen är endast tillgänglig i vissa Azure-regioner. Se Regiontillgänglighet.

Viktigt!

Ge tillräckligt med tid för modellträning

Körningen av anpassad kategoriträning från slutpunkt till slutpunkt kan ta mellan fem och tio timmar. Planera modereringspipelinen i enlighet med detta.

Förutsättningar

• En Azure-prenumeration – Skapa en kostnadsfritt
• När du har din Azure-prenumeration skapar du en Content Safety-resurs i Azure Portal för att hämta din nyckel och slutpunkt. Ange ett unikt namn för resursen, välj din prenumeration och välj en resursgrupp, region som stöds och prisnivån som stöds. Välj sedan Skapa.
  • Det tar några minuter att distribuera resursen. När den är klar väljer du Gå till resurs. I den vänstra rutan under Resurshantering väljer du Prenumerationsnyckel och Slutpunkt. Kopiera slutpunkten och något av nyckelvärdena till en tillfällig plats för senare användning.
• Skapa också en Azure Blob Storage-container där du behåller din utbildningsanteckningsfil.
• Något av följande installerat:
  • cURL för REST API-anrop.
  • Python 3.x installerat

Förbereda dina träningsdata

För att träna en anpassad kategori behöver du exempeltextdata som representerar den kategori som du vill identifiera. I den här guiden kan du använda exempeldata. Den angivna anteckningsfilen innehåller textuppvisningar om överlevnadsråd i camping-/vildmarkssituationer. Den tränade modellen lär sig att identifiera den här typen av innehåll i nya textdata.

Dricks

Tips om hur du skapar en egen datamängd finns i guiden Instruktioner.

1. Ladda ned exempeltextdatafilen från GitHub-lagringsplatsen.
2. Ladda upp .jsonl-filen till din Azure Storage-kontoblobcontainer. Kopiera sedan blob-URL:en till en tillfällig plats för senare användning.

Viktigt!

Användarens lagringskonto konfigureras som ett hierarkiskt namnområdeskonto, som inte kan stödjas av anpassade kategorier. Prova att använda ett vanligt lagringskonto i stället. Din blob-URL kan till exempel inte delas upp i två lager, till exempel/exempel1/, och bör bara ha ett lager. Mer information finns i dokumentationen: Hierarkiskt namnområde för Azure Data Lake Storage – Azure Storage.

Bevilja lagringsåtkomst

Därefter måste du ge innehållssäkerhetsresursen åtkomst till att läsa från Azure Storage-resursen. Aktivera systemtilldelad hanterad identitet för Azure AI Content Safety-instansen och tilldela rollen storage blobdatadeltagare/ägare till identiteten:

Viktigt!

Endast Storage Blob Data Contributor eller Storage Blob Data Owner är giltiga roller för att fortsätta.

1. Aktivera hanterad identitet för Azure AI Content Safety-instansen.

   

2. Tilldela rollen Storage Blob Data Contributor/Owner till den hanterade identiteten. Alla roller som är markerade nedan bör fungera.

   

   

   

Skapa och träna en anpassad kategori

cURL

I kommandot nedan ersätter <your_api_key>du , <your_endpoint>och andra nödvändiga parametrar med dina egna värden. Ange sedan varje kommando i ett terminalfönster och kör det.

Skapa ny kategoriversion

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

Dricks

Varje gång du ändrar kategorinamn, definition eller exempel skapas en ny version. Du kan använda versionsnumret för att spåra tillbaka till tidigare versioner. Kom ihåg det här versionsnumret eftersom det kommer att krävas i URL:en för nästa steg– anpassade kategorier för träning.

API-begäran

Fält	Beskrivning	Exempelvärde
categoryName	Namnet på kategorin eller ämnet som begäran avser.	överlevnadsråd
definition	En kort beskrivning av innehållstypen för kategorin.	text frågar om överlevnad råd i camping / vildmark situationer
sampleBlobUrl	URL för att komma åt en JSONL-exempelfil som innehåller dataexempel för kategorin.	Länk

API-svar

Fält	Beskrivning	Exempelvärde
categoryName	Namnet på kategorin eller ämnet som svaret relaterar till.	överlevnadsråd
definition	En kort beskrivning av innehållstypen för kategorin.	text frågar om överlevnad råd i camping / vildmark situationer
sampleBlobUrl	URL för att komma åt en JSONL-exempelfil som innehåller dataexempel för kategorin.	Länk
sampleBlobSnapshotUrl	Url för ögonblicksbild av JSONL-exempelfilen, som ger åtkomst till en specifik version av data.	URL för ögonblicksbild
version	Versionsnumret för kategoridata.	1
createdTime	Tidsstämpel när kategoridata skapades.	2024-10-28T22:06:59.4626988Z
status	Aktuell status för kategoridatabearbetningen.	Klart

Starta kategorigenereringsprocessen:

Ersätt <your_api_key> och <your_endpoint> med dina egna värden och lägg även till versionsnumret i url:en som du hämtade från det senaste steget. Tillåt tillräckligt med tid för modellträning: körningen från slutpunkt till slutpunkt för anpassad kategoriträning kan ta mellan fem och tio timmar. Planera modereringspipelinen i enlighet med detta. När du har fått svaret lagrar du åtgärds-ID:t (kallas id) på en tillfällig plats. Det här ID:t krävs för att hämta byggstatusen med hjälp av API:et Hämta status i nästa avsnitt.

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-svar

Fält	Beskrivning	Exempelvärde
operation id	Unik identifierare för att hämta byggstatusen	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
status	Aktuell status för begäran	Klart

Hämta status för kategoriversion:

Om du vill hämta statusen använder du det id som hämtades från det tidigare API-svaret och placerar det i sökvägen till API:et nedan.

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-svar

Fält	Beskrivning	Exempelvärde
operation id	Unik identifierare för att hämta byggstatusen	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
status	Aktuell status för begäran	Klart

Analysera text med en anpassad kategori

Kör följande kommando för att analysera text med din anpassade kategori. Ersätt <your_api_key> och <your_endpoint> med dina egna värden.

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-begäran

Fält	beskrivning
text	Textinnehållet eller meddelandet som är avsett för kategoriidentifiering
categoryName	Namnet på kategorin som texten syftar till att identifieras under
version	Versionsnummer för kategorin

API-svar

Fält	Beskrivning	Exempelvärde
customCategoryAnalysis	Objekt som innehåller analysresultatet för kategorin.	—
detected	Anger om den angivna kategorin har identifierats.	falskt

Python

Först måste du installera det nödvändiga Python-biblioteket:

pip install requests

Öppna sedan ett nytt Python-skript och definiera de nödvändiga variablerna med din egen Azure-resursinformation:

import requests

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

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

Skapa en ny kategori

Du kan skapa en ny kategori med kategorinamn, definition och sample_blob_url, och du får det automatiskt genererade versionsnumret för den här kategorin.

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)

Starta kategorigenereringsprocessen

Du kan starta kategorigenereringsprocessen med kategorinamnet och versionsnumret. Tillåt tillräckligt med tid för modellträning: körningen från slutpunkt till slutpunkt för anpassad kategoriträning kan ta mellan fem och tio timmar. Planera modereringspipelinen i enlighet med detta. När du har fått svaret ser du till idatt du lagrar åtgärds-ID:t (kallas ) någonstans som din notebook-fil. Det här ID:t krävs för att hämta versionsstatusen med hjälp av funktionen "get_build_status" i nästa avsnitt.

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)

Hämta status för kategoriversion:

Om du vill hämta statusen använder du det id som hämtades från föregående svar.

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)

Analysera text med en anpassad kategori

Du måste ange kategorinamnet och versionsnumret (valfritt; tjänsten använder det senaste som standard) under slutsatsdragningen. Du kan ange flera kategorier om de redan har definierats.

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)

Andra åtgärder för anpassade kategorier

Kom ihåg att ersätta platshållarna nedan med dina faktiska värden för API-nyckeln, slutpunkten och specifikt innehåll (kategorinamn, definition och så vidare). De här exemplen hjälper dig att hantera de anpassade kategorierna i ditt konto.

cURL

Hämta en anpassad kategori eller en specifik version av den

Ersätt platshållarna med dina egna värden och kör följande kommando i ett terminalfönster:

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"

Lista kategorier för de senaste versionerna

Ersätt platshållarna med dina egna värden och kör följande kommando i ett terminalfönster:

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"

Ta bort en anpassad kategori eller en specifik version av den

Ersätt platshållarna med dina egna värden och kör följande kommando i ett terminalfönster:

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

Kontrollera först att du har installerat det nödvändiga Python-biblioteket:

pip install requests

Konfigurera sedan nödvändiga konfigurationer med din egen AI-resursinformation:

import requests

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

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

Hämta en anpassad kategori eller en specifik version av den

Ersätt platshållarna med dina egna värden och kör följande kod i Python-skriptet:

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)

Lista kategorier för de senaste versionerna

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)

Ta bort en anpassad kategori eller en specifik version av den

Ersätt platshållarna med dina egna värden och kör följande kod i Python-skriptet:

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)

Relaterat innehåll

• Begrepp för anpassade kategorier
• Moderera innehåll med content safety