Skip to content

Commit ef31414

Browse files
jinruishaojinruishao
authored
Update quickstart-custom-categories.md
1 parent f827811 commit ef31414

File tree

1 file changed

+171
-23
lines changed

1 file changed

+171
-23
lines changed

‎articles/ai-services/content-safety/quickstart-custom-categories.md

Lines changed: 171 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,6 @@ For more information on Custom categories, see the [Custom categories concept pa
2626
>
2727
> The end-to-end execution of custom category training can take from around five hours to ten hours. Plan your moderation pipeline accordingly.
2828
29-
30-
## Custom categories (standard mode) (preview) User Flow
31-
32-
![image](https://github.com/user-attachments/assets/2a510f8c-9f88-461e-9082-64d5e05ce13a)
33-
34-
35-
3629
## Prerequisites
3730

3831
* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services/)
@@ -67,7 +60,7 @@ In the command below, replace `<your_api_key>`, `<your_endpoint>`, and other nec
6760
### Create new category version
6861

6962
```bash
70-
curl -X PUT "<your_endpoint>/contentsafety/text/categories/survival-advice?api-version=2024-09-15-preview" \
63+
curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview" \
7164
-H "Ocp-Apim-Subscription-Key: <your_api_key>" \
7265
-H "Content-Type: application/json" \
7366
-d "{
@@ -77,29 +70,56 @@ curl -X PUT "<your_endpoint>/contentsafety/text/categories/survival-advice?api-v
7770
}"
7871
```
7972
> [!TIP]
80-
> Every time you change your category name, definition or samples, a new version will be created. You can use the version number to trace back to previous versions. Please remember this version number, as it will be required in the URL for the next step- training custom categories.
81-
### Get new category version
73+
> Every time you change your category name, definition or samples,a new version will be created. You can use the version number to trace back to previous versions. Please remember this version number, as it will be required in the URL for the next step- training custom categories.
74+
75+
76+
77+
#### API Request
78+
79+
80+
| Field | Description | Example Value |
81+
|------------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
82+
| `categoryName` | The name of the category or topic the request relates to. | survival-advice |
83+
| `definition` | A brief description of the content type for the category. | text prompts about survival advice in camping/wilderness situations |
84+
| `sampleBlobUrl` | URL to access a sample JSONL file containing data examples for the category. | Link |
85+
86+
87+
88+
89+
#### API Response
90+
91+
| Field | Description | Example Value |
92+
|------------------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
93+
| `categoryName` | The name of the category or topic the response relates to. | survival-advice |
94+
| `definition` | A brief description of the content type for the category. | text prompts about survival advice in camping/wilderness situations |
95+
| `sampleBlobUrl` | URL to access a sample JSONL file containing data examples for the category. | Link |
96+
| `sampleBlobSnapshotUrl`| Snapshot URL of the sample JSONL file, which provides access to a specific version of the data. | Snapshot URL |
97+
| `version` | The version number of the category data. | 1 |
98+
| `createdTime` | Timestamp when the category data was created. | 2024-10-28T22:06:59.4626988Z |
99+
| `status` | Current status of the category data processing. | Succeeded |
100+
101+
102+
82103

83-
```bash
84-
curl -X PUT "<your_endpoint>/contentsafety/text/categories/survival-advice?api-version=2024-09-15-preview" \
85-
-H "Ocp-Apim-Subscription-Key: <your_api_key>" \
86-
-H "Content-Type: application/json" \
87-
-d "{
88-
\"categoryName\": \"survival-advice\",
89-
\"definition\": \"text prompts about survival advice in camping/wilderness situations\",
90-
\"sampleBlobUrl\": \"https://<your-azure-storage-url>/example-container/survival-advice.jsonl\"
91-
}"
92-
```
93104

94105
### Start the category build process:
95106

96-
Replace <your_api_key> and <your_endpoint> with your own values, and also **append the version number you obtained from the last step.** Allow enough time for model training: the end-to-end execution of custom category training can take from around five hours to ten hours. Plan your moderation pipeline accordingly. After you receive the response, store the operation ID (referred to as `id`) in a temporary location. This ID will be necessary for retrieving the build status using the **Get status** API in the next section.
107+
Replace <your_api_key> and <your_endpoint> with your own values, and also **append the version number in the url you obtained from the last step.** Allow enough time for model training: the end-to-end execution of custom category training can take from around five hours to ten hours. Plan your moderation pipeline accordingly. After you receive the response, store the operation ID (referred to as `id`) in a temporary location. This ID will be necessary for retrieving the build status using the **Get status** API in the next section.
97108

98109
```bash
99110
curl -X POST "<your_endpoint>/contentsafety/text/categories/survival-advice:build?api-version=2024-09-15-preview&version={version}" \
100111
-H "Ocp-Apim-Subscription-Key: <your_api_key>" \
101112
-H "Content-Type: application/json"
102113
```
114+
115+
#### API Response
116+
117+
| Field | Description | Example Value |
118+
|------------|-----------------------------------------------|-----------------------------------------------|
119+
| `operation id` | Unique identifier for retrieving the build statuse | b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx |
120+
| `status` | Current status of the request | Succeeded |
121+
122+
103123
### Get the category build status:
104124

105125
To retrieve the status, utilize the `id` obtained from the previous API response and place it in the path of the API below.
@@ -109,6 +129,12 @@ curl -X GET "<your_endpoint>/contentsafety/text/categories/operations/<id>?api-v
109129
-H "Ocp-Apim-Subscription-Key: <your_api_key>" \
110130
-H "Content-Type: application/json"
111131
```
132+
#### API Response
133+
134+
| Field | Description | Example Value |
135+
|------------|-----------------------------------------------|-----------------------------------------------|
136+
| `operation id` | Unique identifier for retrieving the build statuse | b6c69dc1-2338-484e-855b-xxxxxxxxxxxx |
137+
| `status` | Current status of the request | Succeeded |
112138

113139
## Analyze text with a customized category
114140

@@ -124,6 +150,17 @@ curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-versi
124150
\"version\": 1
125151
}"
126152
```
153+
#### API Request
154+
| Field | Description |
155+
|----------------|---------------------------------------------------------|
156+
| `text` | The text content or message intended for category detection |
157+
| `categoryName` | The name of the category the text aims to be detected under |
158+
| `version` | Version number of the category |
159+
#### API Response
160+
| Field | Description | Example Value |
161+
|--------------------------|---------------------------------------------------------|---------------|
162+
| `customCategoryAnalysis` | Object containing the analysis result for the category. | — |
163+
| `detected` | Indicates whether the specified category was detected. | false |
127164

128165

129166
#### [Python](#tab/python)
@@ -231,11 +268,122 @@ version = 1
231268
result = analyze_text_with_customized_category(text, category_name, version)
232269
print(result)
233270
```
271+
---
272+
273+
## Other custom categories operations
274+
275+
Remember to replace the placeholders below with your actual values for the API key, endpoint, and specific content (category name, definition, and so on). These examples help you to manage the customized categories in your account.
276+
277+
#### [cURL](#tab/curl)
278+
279+
### Get a customized category or a specific version of it
280+
281+
Replace the placeholders with your own values and run the following command in a terminal window:
282+
283+
```bash
284+
curl -X GET "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
285+
-H "Ocp-Apim-Subscription-Key: <your_api_key>" \
286+
-H "Content-Type: application/json"
287+
```
288+
289+
### List categories of their latest versions
290+
291+
Replace the placeholders with your own values and run the following command in a terminal window:
292+
293+
```bash
294+
curl -X GET "<endpoint>/contentsafety/text/categories?api-version=2024-09-15-preview" \
295+
-H "Ocp-Apim-Subscription-Key: <your_api_key>" \
296+
-H "Content-Type: application/json"
297+
```
298+
299+
### Delete a customized category or a specific version of it
300+
301+
Replace the placeholders with your own values and run the following command in a terminal window:
302+
303+
```bash
304+
curl -X DELETE "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
305+
-H "Ocp-Apim-Subscription-Key: <your_api_key>" \
306+
-H "Content-Type: application/json"
307+
```
308+
309+
#### [Python](#tab/python)
310+
311+
First, make sure you've installed the required Python library:
312+
313+
```bash
314+
pip install requests
315+
```
316+
317+
Then, set up the necessary configurations with your own AI resource details:
318+
319+
```python
320+
import requests
321+
322+
API_KEY = '<your_api_key>'
323+
ENDPOINT = '<your_endpoint>'
324+
325+
headers = {
326+
'Ocp-Apim-Subscription-Key': API_KEY,
327+
'Content-Type': 'application/json'
328+
}
329+
```
330+
331+
### Get a customized category or a specific version of it
332+
333+
Replace the placeholders with your own values and run the following code in your Python script:
334+
335+
```python
336+
def get_customized_category(category_name, version=None):
337+
url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
338+
if version:
339+
url += f"&version={version}"
340+
341+
response = requests.get(url, headers=headers)
342+
return response.json()
343+
344+
# Replace the parameters with your own values
345+
category_name = "DrugAbuse"
346+
version = 1
347+
348+
result = get_customized_category(category_name, version)
349+
print(result)
350+
```
351+
352+
### List categories of their latest versions
353+
354+
```python
355+
def list_categories_latest_versions():
356+
url = f"{ENDPOINT}/contentsafety/text/categories?api-version=2024-09-15-preview"
357+
response = requests.get(url, headers=headers)
358+
return response.json()
359+
360+
result = list_categories_latest_versions()
361+
print(result)
362+
```
363+
364+
### Delete a customized category or a specific version of it
365+
366+
Replace the placeholders with your own values and run the following code in your Python script:
367+
368+
```python
369+
def delete_customized_category(category_name, version=None):
370+
url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
371+
if version:
372+
url += f"&version={version}"
373+
374+
response = requests.delete(url, headers=headers)
375+
return response.status_code
376+
377+
# Replace the parameters with your own values
378+
category_name = "<your_category_name>"
379+
version = 1
380+
381+
result = delete_customized_category(category_name, version)
382+
print(result)
383+
```
234384

235385
---
236386

237387
## Related content
238-
239-
* For information on other Custom categories operations, see the [How-to guide](./how-to/custom-categories.md).
240388
* [Custom categories concepts](./concepts/custom-categories.md)
241389
* [Moderate content with Content Safety](./quickstart-text.md)

0 commit comments

Comments
 (0)