Menggunakan API kategori kustom (standar) (pratinjau)

API kategori kustom (standar) memungkinkan Anda membuat kategori konten Anda sendiri untuk kasus penggunaan Anda dan melatih Azure AI Content Safety untuk mendeteksinya dalam konten baru.

Penting

Fitur ini hanya tersedia di wilayah Azure tertentu. Lihat Ketersediaan wilayah.

Perhatian

Data sampel dalam panduan ini mungkin berisi konten yang menyinggung. Kebijaksanaan pengguna disarankan.

Prasyarat

• Langganan Azure - buat langganan gratis
• Setelah Anda memiliki langganan Azure, buat sumber daya Content Safety di portal Azure untuk mendapatkan kunci dan titik akhir Anda. Masukkan nama unik untuk sumber daya Anda, pilih langganan Anda, dan pilih grup sumber daya, wilayah yang didukung, dan tingkat harga yang didukung. Lalu pilih Buat.
  • Sumber daya membutuhkan waktu beberapa menit untuk disebarkan. Setelah selesai, Pilih buka sumber daya. Di panel kiri, di bawah Manajemen Sumber Daya, pilih Kunci Langganan dan Titik Akhir. Salin titik akhir dan salah satu nilai kunci ke lokasi sementara untuk digunakan nanti.
• Buat juga kontainer penyimpanan blob Azure tempat Anda akan menyimpan file anotasi pelatihan.
• Salah satu hal berikut ini terinstal:
  • cURL untuk panggilan REST API.
  • Python 3.x terinstal

Menyiapkan data pelatihan Anda

Untuk melatih kategori kustom, Anda memerlukan contoh data teks yang mewakili kategori yang ingin Anda deteksi. Ikuti langkah-langkah berikut untuk menyiapkan data sampel Anda:

1. Kumpulkan atau tulis data sampel Anda:

   • Kualitas data sampel Anda penting untuk melatih model yang efektif. Bertujuan untuk mengumpulkan setidaknya 50 sampel positif yang secara akurat mewakili konten yang ingin Anda identifikasi. Sampel ini harus jelas, bervariasi, dan terkait langsung dengan definisi kategori.
   • Sampel negatif tidak diperlukan, tetapi dapat meningkatkan kemampuan model untuk membedakan konten yang relevan dari konten yang tidak relevan. Untuk meningkatkan performa, arahkan untuk 50 sampel yang tidak terkait dengan definisi kasus positif. Ini harus bervariasi tetapi masih dalam konteks konten yang akan ditemui model Anda. Pilih sampel negatif dengan hati-hati untuk memastikan tidak tumpang tindih secara tidak sengaja dengan kategori positif.
   • Berusahalah untuk keseimbangan antara jumlah sampel positif dan negatif. Himpunan data yang tidak merata dapat membuat model bias, menyebabkannya mendukung satu jenis klasifikasi daripada yang lain, yang dapat menyebabkan tingkat positif palsu atau negatif yang lebih tinggi.

2. Gunakan editor teks untuk memformat data Anda dalam file .jsonl . Di bawah ini adalah contoh format yang sesuai. Contoh kategori harus diatur isPositive ke true. Contoh negatif bersifat opsional tetapi dapat meningkatkan performa:

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

3. Unggah file .jsonl ke kontainer blob akun Azure Storage. Salin URL blob ke lokasi sementara untuk digunakan nanti.

Memberikan akses penyimpanan

Selanjutnya, Anda perlu memberikan akses sumber daya Content Safety anda untuk membaca dari sumber daya Azure Storage. Aktifkan identitas Terkelola yang ditetapkan sistem untuk instans Azure AI Content Safety dan tetapkan peran Kontributor/Pemilik Data Blob Penyimpanan ke identitas:

Penting

Hanya Kontributor Data Blob Penyimpanan atau Pemilik Data Blob Penyimpanan yang merupakan peran yang valid untuk melanjutkan.

1. Aktifkan identitas terkelola untuk instans Azure AI Content Safety.

   

2. Tetapkan peran Kontributor/Pemilik Data Blob Penyimpanan ke identitas Terkelola. Peran apa pun yang disorot di bawah ini harus berfungsi.

   

   

   

Membuat dan melatih kategori kustom

Penting

Izinkan cukup waktu untuk pelatihan model

Eksekusi menyeluruh pelatihan kategori kustom dapat memakan waktu sekitar lima jam hingga sepuluh jam. Rencanakan alur moderasi Anda sesuai dan alokasikan waktu untuk:

• Mengumpulkan dan menyiapkan data sampel Anda
• Proses pelatihan
• Evaluasi dan penyesuaian model

cURL

Dalam perintah di bawah ini, ganti <your_api_key>, <your_endpoint>, dan parameter lain yang diperlukan dengan nilai Anda sendiri. Kemudian masukkan setiap perintah di jendela terminal dan jalankan.

Membuat versi kategori baru

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

Mulai proses build kategori:

Setelah Anda menerima respons, simpan ID operasi (disebut sebagai id) dalam sementara. Anda memerlukan ID ini untuk mengambil status build menggunakan GET status API.

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"

Dapatkan status build kategori:

Untuk mengambil status, gunakan yang id diperoleh dari respons API sebelumnya dan letakkan di jalur API di bawah ini.

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"

Menganalisis teks dengan kategori yang dikustomisasi

Jalankan perintah berikut untuk menganalisis teks dengan kategori yang dikustomisasi. Ganti <your_category_name> dengan nilai Anda sendiri:

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

Python

Pertama, Anda perlu menginstal pustaka Python yang diperlukan:

pip install requests

Kemudian, buka skrip Python baru dan tentukan variabel yang diperlukan dengan detail sumber daya Azure Anda sendiri:

import requests

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

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

Membuat versi kategori baru

Anda dapat membuat kategori baru dengan nama kategori, definisi, dan sample_blob_url, dan Anda akan mendapatkan nomor versi yang dibuat secara otomatis dari kategori ini.

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)

Memulai proses build kategori

Anda dapat memulai proses build kategori dengan nama kategori dan nomor versi.

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)

Dapatkan status build kategori:

Untuk mengambil status, gunakan yang id diperoleh dari respons sebelumnya.

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)

Menganalisis teks dengan kategori yang dikustomisasi

Anda perlu menentukan nama kategori dan nomor versi (opsional; layanan menggunakan yang terbaru secara default) selama inferensi. Anda dapat menentukan beberapa kategori jika sudah ditentukan.

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)

Operasi kategori kustom lainnya

Ingatlah untuk mengganti tempat penampung di bawah ini dengan nilai aktual Anda untuk kunci API, titik akhir, dan konten tertentu (nama kategori, definisi, dan sebagainya). Contoh-contoh ini membantu Anda mengelola kategori yang disesuaikan di akun Anda.

cURL

Mendapatkan kategori yang dikustomisasi atau versi tertentu dari kategori tersebut

Ganti tempat penampung dengan nilai Anda sendiri dan jalankan perintah berikut di jendela terminal:

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"

Mencantumkan kategori versi terbarunya

Ganti tempat penampung dengan nilai Anda sendiri dan jalankan perintah berikut di jendela terminal:

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"

Menghapus kategori yang dikustomisasi atau versi tertentu dari kategori tersebut

Ganti tempat penampung dengan nilai Anda sendiri dan jalankan perintah berikut di jendela terminal:

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"

Python

Pertama, pastikan Anda telah menginstal pustaka Python yang diperlukan:

pip install requests

Kemudian, siapkan konfigurasi yang diperlukan dengan detail sumber daya AI Anda sendiri:

import requests

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

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

Mendapatkan kategori yang dikustomisasi atau versi tertentu dari kategori tersebut

Ganti tempat penampung dengan nilai Anda sendiri dan jalankan kode berikut di skrip Python Anda:

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)

Mencantumkan kategori versi terbarunya

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)

Menghapus kategori yang dikustomisasi atau versi tertentu dari kategori tersebut

Ganti tempat penampung dengan nilai Anda sendiri dan jalankan kode berikut di skrip Python Anda:

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)

Konten terkait

• Konsep kategori kustom
• Memoderasi konten dengan Keamanan Konten