Quickstart: Custom text classification (preview)

Use this article to get started with creating a custom text classification project where you can train custom models for text classification. A model is an object that's trained to do a certain task. For this system, the models classify text. Models are trained by learning from tagged data.

Custom text classification supports two types of projects:

  • Single label classification - you can assign a single class for each document in your dataset. For example, a movie script could only be classified as "Romance" or "Comedy".
  • Multi label classification - you can assign multiple classes for each document in your dataset. For example, a movie script could be classified as "Comedy" or "Romance" and "Comedy".

In this quickstart you can use the sample datasets provided to build a multi label classification where you can classify movie scripts into one or more categories or you can use single label classification dataset where you can classify abstracts of scientific papers into one of the defined domains.

Prerequisites

Create a new Azure Language resource and Azure storage account

Before you can use custom text classification, you’ll need to create an Azure Language resource, which will give you the credentials that you need to create a project and start training a model. You’ll also need an Azure storage account, where you can upload your dataset that will be used in building your model.

Important

To get started quickly, we recommend creating a new Azure Language resource using the steps provided in this article, which will let you create the Language, and create and/or connect a storage account at the same time, which is easier than doing it later.

If you have a pre-existing resource that you'd like to use, you will need to connect it to storage account.

Create a new resource from the Azure portal

  1. Go to the Azure portal to create a new Azure Language resource.

  2. Click on Create a new resource

  3. In the window that appears, search for Language service

  4. Click Create

  5. In the window that appears, select Custom text classification & custom named entity recognition from the custom features. Click Continue to create your resource.

    A screenshot showing the selection option for custom text classification and custom named entity recognition in Azure portal.

  6. Create a Language resource with following details.

    Instance detail Required value
    Location Learn more about supported regions.
    Pricing tier Learn more about supported pricing tiers.
  7. In the Custom text classification & custom named entity recognition section, select an existing storage account or select Create a new storage account. Note that these values are to help you get started, and not necessarily the storage account values you’ll want to use in production environments. To avoid latency during building your project connect to storage accounts in the same region as your Language resource.

    Storage account value Recommended value
    Name Any name
    Account kind Storage (general purpose v1)
    Performance Standard
    Replication Locally redundant storage (LRS)

Upload sample data to blob container

After you have created an Azure storage account and connected it to your Language resource, you will need to upload the documents from the sample dataset to the root directory of your container. These documents will later be used to train your model.

  1. Download the sample dataset for multi label classification projects.

  2. Open the .zip file, and extract the folder containing the documents.

The provided sample dataset contains about 200 documents, each of which is a summary for a movie. Each document belongs to one or more of the following classes:

  • "Mystery"
  • "Drama"
  • "Thriller"
  • "Comedy"
  • "Action"
  1. In the Azure portal, navigate to the storage account you created, and select it.

  2. In your storage account, select Containers from the left menu, located below Data storage. On the screen that appears, select + Container. Give the container the name example-data and leave the default Public access level.

    A screenshot showing the main page for a storage account.

  3. After your container has been created, select it. Then click Upload button to select the .txt and .json files you downloaded earlier.

    A screenshot showing the button for uploading files to the storage account.

Create a custom text classification project

Once your resource and storage container are configured, create a new custom text classification project. A project is a work area for building your custom ML models based on your data. Your project can only be accessed by you and others who have access to the Language resource being used.

  1. Sign into the Language Studio. A window will appear to let you select your subscription and Language resource. Select your Language resource.

  2. Under the Classify text section of Language Studio, select Custom text classification.

    A screenshot showing the location of custom text classification in the Language Studio landing page.

  3. Select Create new project from the top menu in your projects page. Creating a project will let you label data, train, evaluate, improve, and deploy your models.

    A screenshot of the project creation page.

  4. After you click, Create new project, a screen will appear to let you connect your storage account. If you've already connected a storage account, you will see the storage accounted connected. If not, choose your storage account from the dropdown that appears and click on Connect storage account; this will set the required roles for your storage account. This step will possibly return an error if you are not assigned as owner on the storage account.

    Note

    • You only need to do this step once for each new language resource you use.
    • This process is irreversible, if you connect a storage account to your Language resource you cannot disconnect it later.
    • You can only connect your Language resource to one storage account.

    A screenshot of the storage connection screen for custom classification projects.

  5. Select project type. You can either create a Multi label classification project where each document can belong to one or more classes or Single label classification project where each document can belong to only one class. The selected type can't be changed later. Learn more about project types

    A screenshot of the available custom classification project types.

  6. Enter the project information, including a name, description, and the language of the documents in your project. You won’t be able to change the name of your project later. Click Next.

    Tip

    Your dataset doesn't have to be entirely in the same language. You can have multiple documents, each with different supported languages. If your dataset contains documents of different languages or if you expect text from different languages during runtime, select enable multi-lingual dataset option when you enter the basic information for your project. This option can be enabled later from the Project settings page.

  7. Select the container where you have uploaded your dataset.

    Note

    If you have already labeled your data make sure it follows the supported format and click on Yes, my documents are already labeled and I have formatted JSON labels file and select the labels file from the drop-down menu below. Click Next.

  8. Review the data you entered and select Create Project.

Train your model

Typically after you create a project, you go ahead and start labeling the documents you have in the container connected to your project. For this quickstart, you have imported a sample labeled dataset and initialized your project with the sample JSON labels file.

To start training your model from within the Language Studio:

  1. Select Training jobs from the left side menu.

  2. Select Start a training job from the top menu.

  3. Select Train a new model and type in the model name in the text box. You can also overwrite an existing model by selecting this option and choosing the model you want to overwrite from the dropdown menu. Overwriting a trained model is irreversible, but it won't affect your deployed models until you deploy the new model.

    Create a new training job

  4. Select data splitting method. You can choose Automatically splitting the testing set from training data where the system will split your labeled data between the training and testing sets, according to the specified percentages. Or you can Use a manual split of training and testing data, this option is only enabled if you have added documents to your testing set during data labeling. See How to train a model for more information on data splitting.

  5. Click on the Train button.

  6. If you click on the training job ID from the list, a side pane will appear where you can check the Training progress, Job status, and other details for this job.

    Note

    • Only successfully completed training jobs will generate models.
    • Training can take some time between a couple of minutes and several hours based on the size of your labeled data.
    • You can only have one training job running at a time. You can't start other training job within the same project until the running job is completed.

Deploy your model

Generally after training a model you would review it's evaluation details and make improvements if necessary. In this quickstart, you will just deploy your model, and make it available for you to try in the Language studio, or you can call the prediction API.

To deploy your model from within the Language Studio:

  1. Select Deploying a model from the left side menu.

  2. Click on Add deployment to start a new deployment job.

    A screenshot showing the deployment button

  3. Select Create new deployment to create a new deployment and assign a trained model from the dropdown below. You can also Overwrite an existing deployment by selecting this option and select the trained model you want to assign to it from the dropdown below.

    Note

    Overwriting an existing deployment doesn't require changes to your Prediction API call but the results you get will be based on the newly assigned model.

    A screenshot showing the deployment screen

  4. click on Submit to start deployment job.

  5. After deployment is successful, an expiration date will appear next to it. Deployment expiration is when your deployed model will be unavailable to be used for prediction, which typically happens twelve months after a training configuration expires.

Test your model

After your model is deployed, you can start using it to classify your text via Prediction API. For this quickstart, you will use the Language Studio to submit the custom text classification task and visualize the results. In the sample dataset you downloaded earlier you can find some test documents that you can use in this step.

To test your deployed models within Language Studio:

  1. Select Testing deployments from the menu on the left side of the screen.

  2. Select the model you want to test. You can only test models that are assigned to deployments.

  3. For multilingual projects, select the language of the text you're testing using the language dropdown.

  4. Select the deployment you want to query/test from the dropdown.

  5. Enter the text you want to submit in the request, or upload a .txt document to use.

  6. Click on Run the test from the top menu.

  7. In the Result tab, you can see the predicted classes for your text. You can also view the JSON response under the JSON tab. The following example is for a multi label classification project. A single label classification project will only return one class in the result.

    A screenshot showing model test results for a multi label classification project. The example is from CMU Movie Summary, CC BY-SA 3.0, modified by Microsoft

Clean up projects

When you don't need your project anymore, you can delete your project using Language Studio. Select Custom text classification in the top, then select the project you want to delete. Click on Delete from the top menu to delete the project.

Prerequisites

Create a new Azure Language resource and Azure storage account

Before you can use custom text classification, you’ll need to create an Azure Language resource, which will give you the credentials that you need to create a project and start training a model. You’ll also need an Azure storage account, where you can upload your dataset that will be used in building your model.

Important

To get started quickly, we recommend creating a new Azure Language resource using the steps provided in this article, which will let you create the Language, and create and/or connect a storage account at the same time, which is easier than doing it later.

If you have a pre-existing resource that you'd like to use, you will need to connect it to storage account.

Create a new resource from the Azure portal

  1. Go to the Azure portal to create a new Azure Language resource.

  2. Click on Create a new resource

  3. In the window that appears, search for Language service

  4. Click Create

  5. In the window that appears, select Custom text classification & custom named entity recognition from the custom features. Click Continue to create your resource.

    A screenshot showing the selection option for custom text classification and custom named entity recognition in Azure portal.

  6. Create a Language resource with following details.

    Instance detail Required value
    Location Learn more about supported regions.
    Pricing tier Learn more about supported pricing tiers.
  7. In the Custom text classification & custom named entity recognition section, select an existing storage account or select Create a new storage account. Note that these values are to help you get started, and not necessarily the storage account values you’ll want to use in production environments. To avoid latency during building your project connect to storage accounts in the same region as your Language resource.

    Storage account value Recommended value
    Name Any name
    Account kind Storage (general purpose v1)
    Performance Standard
    Replication Locally redundant storage (LRS)

Upload sample data to blob container

After you have created an Azure storage account and connected it to your Language resource, you will need to upload the documents from the sample dataset to the root directory of your container. These documents will later be used to train your model.

  1. Download the sample dataset for multi label classification projects.

  2. Open the .zip file, and extract the folder containing the documents.

The provided sample dataset contains about 200 documents, each of which is a summary for a movie. Each document belongs to one or more of the following classes:

  • "Mystery"
  • "Drama"
  • "Thriller"
  • "Comedy"
  • "Action"
  1. In the Azure portal, navigate to the storage account you created, and select it.

  2. In your storage account, select Containers from the left menu, located below Data storage. On the screen that appears, select + Container. Give the container the name example-data and leave the default Public access level.

    A screenshot showing the main page for a storage account.

  3. After your container has been created, select it. Then click Upload button to select the .txt and .json files you downloaded earlier.

    A screenshot showing the button for uploading files to the storage account.

Get your resource keys and endpoint

  • Go to your resource overview page in the Azure portal

  • From the menu on the left side, select Keys and Endpoint. You will use the endpoint and key for the API requests

A screenshot showing the key and endpoint page in the Azure portal.

Create a custom text classification project

Once your resource and storage container are configured, create a new custom text classification project. A project is a work area for building your custom ML models based on your data. Your project can only be accessed by you and others who have access to the Language resource being used.

Trigger import project job

Submit a POST request using the following URL, headers, and JSON body to import your labels file. Make sure that your labels file follow the accepted format.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}
Placeholder Value Example
{ENDPOINT} The endpoint for authenticating your API request. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} The name for your project. This value is case-sensitive. myProject
{API-VERSION} The version of the API you are calling. The value referenced here is for the latest version released. Learn more about other available API versions 2022-03-01-preview

Headers

Use the following header to authenticate your request.

Key Value
Ocp-Apim-Subscription-Key The key to your resource. Used for authenticating your API requests.

Body

Use the following JSON in your request. Replace the placeholder values below with your own values.

{
  "api-version": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "projectKind": "customMultiLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "storageInputContainerName": "{CONTAINER-NAME}",
    "settings": {}
  },
  "assets": {
    "classes": [
      {
        "category": "Class1"
      },
      {
        "category": "Class2"
      }
    ],
    "documents": [
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class1"
          },
          {
            "category": "Class2"
          }
        ]
      },
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class2"
          }
        ]
      }
    ]
  }
}

Key Placeholder Value Example
api-version {API-VERSION} The version of the API you are calling. The version used here must be the same API version in the URL. Learn more about other available API versions 2022-03-01-preview
projectName {PROJECT-NAME} The name of your project. This value is case-sensitive. myProject
projectKind customMultiLabelClassification Your project kind. customMultiLabelClassification
language {LANGUAGE-CODE} A string specifying the language code for the documents used in your project. If your project is a multilingual project, choose the language code of the majority of the documents. See language support to learn more about multilingual support. en-us
multilingual true A boolean value that enables you to have documents in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents. See language support to learn more about multilingual support. true
storageInputContainerName {CONTAINER-NAME} The name of your Azure storage container where you have uploaded your documents. myContainer
classes [] Array containing all the classes you have in the project. These are the classes you want to classify your documents into. []
documents [] Array containing all the documents in your project and what the classes labeled for this document. []
location {DOCUMENT-NAME} The location of the documents in the storage container. Since all the documents are in the root of the container this should be the document name. doc1.txt
dataset {DATASET} The test set to which this document will go to when split before training. See How to train a model for more information on data splitting. Possible values for this field are Train and Test. Train

Once you send your API request, you’ll receive a 202 response indicating that the job was submitted correctly. In the response headers, extract the location value. It will be formatted like this:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} is used to identify your request, since this operation is asynchronous. You’ll use this URL to get the import job status.

Possible error scenarios for this request:

  • The selected resource doesn't have proper permissions for the storage account.
  • The storageInputContainerName specified doesn't exist.
  • Invalid language code is used, or if the language code type isn't string.
  • multilingual value is a string and not a boolean.

Get import job Status

Use the following GET request to get the status of your importing your project. Replace the placeholder values below with your own values.

Request URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
Placeholder Value Example
{ENDPOINT} The endpoint for authenticating your API request. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} The name of your project. This value is case-sensitive. myProject
{JOB-ID} The ID for locating your model's training status. This value is in the location header value you received in the previous step. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} The version of the API you are calling. The value referenced here is for the latest version released. Learn more about other available API versions 2022-03-01-preview

Headers

Use the following header to authenticate your request.

Key Value
Ocp-Apim-Subscription-Key The key to your resource. Used for authenticating your API requests.

Train your model

Typically after you create a project, you go ahead and start tagging the documents you have in the container connected to your project. For this quickstart, you have imported a sample tagged dataset and initialized your project with the sample JSON tags file.

Start training your model

After your project has been imported, you can start training your model.

Submit a POST request using the following URL, headers, and JSON body to submit a training job. Replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
Placeholder Value Example
{ENDPOINT} The endpoint for authenticating your API request. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} The name of your project. This value is case-sensitive. myProject
{API-VERSION} The version of the API you are calling. The value referenced here is for the latest version released. Learn more about other available API versions 2022-03-01-preview

Headers

Use the following header to authenticate your request.

Key Value
Ocp-Apim-Subscription-Key The key to your resource. Used for authenticating your API requests.

Request body

Use the following JSON in your request body. The model will be given the {MODEL-NAME} once training is complete. Only successful training jobs will produce models.

{
  "modelLabel": "{MODEL-NAME}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage", 
    "trainingSplitPercentage": 80,
    "testingSplitPercentage": 20
}
Key Placeholder Value Example
modelLabel {MODEL-NAME} The model name that will be assigned to your model once trained successfully. myModel
trainingConfigVersion {CONFIG-VERSION} This is the model version that will be used to train the model. 2022-05-01
evaluationOptions Option to split your data across training and testing sets. {}
kind percentage Split methods. Possible values are percentage or manual. See How to train a model for more information. percentage
trainingSplitPercentage 80 Percentage of your tagged data to be included in the training set. Recommended value is 80. 80
testingSplitPercentage 20 Percentage of your tagged data to be included in the testing set. Recommended value is 20. 20

Note

The trainingSplitPercentage and testingSplitPercentage are only required if Kind is set to percentage and the sum of both percentages should be equal to 100.

Once you send your API request, you’ll receive a 202 response indicating that the job was submitted correctly. In the response headers, extract the location value. It will be formatted like this:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} is used to identify your request, since this operation is asynchronous. You can use this URL to get the training status.

Get training job status

Training could take sometime between 10 and 30 minutes. You can use the following request to keep polling the status of the training job until it's successfully completed.

Use the following GET request to get the status of your model's training progress. Replace the placeholder values below with your own values.

Request URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
Placeholder Value Example
{ENDPOINT} The endpoint for authenticating your API request. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} The name of your project. This value is case-sensitive. myProject
{JOB-ID} The ID for locating your model's training status. This value is in the location header value you received in the previous step. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} The version of the API you are calling. The value referenced here is for the latest version released. Learn more about other available API versions 2022-03-01-preview

Headers

Use the following header to authenticate your request.

Key Value
Ocp-Apim-Subscription-Key The key to your resource. Used for authenticating your API requests.

Response Body

Once you send the request, you’ll get the following response.

{
  "jobs": [
    {
      "result": {
        "trainedModelLabel": "{MODEL-NAME}",
        "trainingConfigVersion": "string",
        "trainStatus": {
          "percentComplete": 0,
          "elapsedTime": "string"
        },
        "evaluationStatus": {
          "percentComplete": 0,
          "elapsedTime": "string"
        }
      },
      "jobId": "string",
      "createdDateTime": "2022-04-12T12:13:28.771Z",
      "lastUpdatedDateTime": "2022-04-12T12:13:28.771Z",
      "expirationDateTime": "2022-04-12T12:13:28.771Z",
      "status": "unknown",
      "warnings": [
        {
          "code": "unknown",
          "message": "string"
        }
      ],
      "errors": [
        {
          "code": "unknown",
          "message": "string"
        }
      ]
    }
  ]
}

Deploy your model

Generally after training a model you would review it's evaluation details and make improvements if necessary. In this quickstart, you will just deploy your model, and make it available for you to try in the Language studio, or you can call the prediction API.

Submit deployment job

Submit a PUT request using the following URL, headers, and JSON body to submit a deployment job. Replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}
Placeholder Value Example
{ENDPOINT} The endpoint for authenticating your API request. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} The name of your project. This value is case-sensitive. myProject
{DEPLOYMENT-NAME} The name of your deployment. This value is case-sensitive. staging
{API-VERSION} The version of the API you are calling. The value referenced here is for the latest version released. Learn more about other available API versions 2022-03-01-preview

Headers

Use the following header to authenticate your request.

Key Value
Ocp-Apim-Subscription-Key The key to your resource. Used for authenticating your API requests.

Request body

Use the following JSON in the body of your request. Use the name of the model you to assign to the deployment.

{
  "trainedModelLabel": "{MODEL-NAME}",
}
Key Placeholder Value Example
trainedModelLabel {MODEL-NAME} The model name that will be assigned to your deployment. You can only assign successfully trained models. This value is case-sensitive. myModel

Once you send your API request, you’ll receive a 202 response indicating that the job was submitted correctly. In the response headers, extract the location value. It will be formatted like this:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} is used to identify your request, since this operation is asynchronous. You can use this URL to get the deployment status.

Get deployment job status

Use the following GET request to query the status of the deployment job. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
Placeholder Value Example
{ENDPOINT} The endpoint for authenticating your API request. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} The name of your project. This value is case-sensitive. myProject
{DEPLOYMENT-NAME} The name of your deployment. This value is case-sensitive. staging
{JOB-ID} The ID for locating your model's training status. This is in the location header value you received in the previous step. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} The version of the API you are calling. The value referenced here is for the latest version released. Learn more about other available API versions 2022-03-01-preview

Headers

Use the following header to authenticate your request.

Key Value
Ocp-Apim-Subscription-Key The key to your resource. Used for authenticating your API requests.

Response Body

Once you send the request, you will get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Classify text

After your model is deployed successfully, you can start using it to classify your text via Prediction API. In the sample dataset you downloaded earlier you can find some test documents that you can use in this step.

Submit a custom text classification task

Use this POST request to start a text classification task.

{ENDPOINT}/text/analytics/v3.2-preview.2/analyze

Headers

Key Value
Ocp-Apim-Subscription-Key Your subscription key that provides access to this API.

Body

{
    "displayName": "{JOB-NAME}",
    "analysisInput": {
        "documents": [
            {
                "id": "{DOC-ID}",
                "language": "{LANGUAGE-CODE}",
                "text": "{DOC-TEXT}"
            },
            {
                "id": "{DOC-ID}",
                "language": "{LANGUAGE-CODE}",
                "text": "{DOC-TEXT}"
            }
        ]
    },
    "tasks": {
        "customMultiLabelClassificationTasks": [
            {
                "parameters": {
                    "project-name": "{PROJECT-NAME}",
                    "deployment-name": "{DEPLOYMENT-NAME}"
                }
            }
        ]
    }
}
Key Placeholder Value Example
displayName {JOB-NAME} Your job name. MyJobName
documents [{},{}] List of documents to run tasks on. [{},{}]
id {DOC-ID} Document name or ID. doc1
language {LANGUAGE-CODE} A string specifying the language code for the document. If this key isn't specified, the service will assume the default language of the project that was selected during project creation. See language support for a list of supported language codes. en-us
text {DOC-TEXT} Document task to run the tasks on. Lorem ipsum dolor sit amet
tasks List of tasks we want to perform. []
customMultiLabelClassificationTasks Task identifier for task we want to perform.
parameters List of parameters to pass to the task.
project-name {PROJECT-NAME} The name for your project. This value is case-sensitive. myProject
deployment-name {DEPLOYMENT-NAME} The name of your deployment. This value is case-sensitive. prod

Response

You will receive a 202 response indicating success. In the response headers, extract operation-location. operation-location is formatted like this:

{YOUR-ENDPOINT}/text/analytics/v3.2-preview.2/analyze/jobs/<jobId>

You can use this URL to query the task completion status and get the results when task is completed.

Get task results

Use the following GET request to query the status/results of the custom classification task. You can use the endpoint you received from the previous step.

{ENDPOINT}/text/analytics/v3.2-preview.2/analyze/jobs/<jobId>.

Headers

Key Value
Ocp-Apim-Subscription-Key Your Subscription key that provides access to this API.

Response body

The response will be a JSON document with the following parameters.

{
    "createdDateTime": "2021-05-19T14:32:25.578Z",
    "displayName": "{JOB-NAME}",
    "expirationDateTime": "2021-05-19T14:32:25.578Z",
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
    "status": "completed",
    "errors": [],
    "tasks": {
        "details": {
            "name": "{JOB-NAME}",
            "lastUpdateDateTime": "2021-03-29T19:50:23Z",
            "status": "completed"
        },
        "completed": 1,
        "failed": 0,
        "inProgress": 0,
        "total": 1,
        "tasks": {
    "customMultiClassificationTasks": [
        {
            "lastUpdateDateTime": "2021-05-19T14:32:25.579Z",
            "name": "{JOB-NAME}",
            "status": "completed",
            "results": {
                "documents": [
                    {
                        "id": "{DOC-ID}",
                        "classes": [
                            {
                                "category": "Class_1",
                                "confidenceScore": 0.0551877357
                            }
                        ],
                        "warnings": []
                    },
                    {
                        "id": "{DOC-ID}",
                        "classes": [
                            {
                                "category": "Class_1",
                                "confidenceScore": 0.0551877357
                            },
                                                        {
                                "category": "Class_2",
                                "confidenceScore": 0.0551877357
                            }
                        ],
                        "warnings": []
                    }
                ],
                "errors": [],
                "statistics": {
                    "documentsCount":0,
                    "erroneousDocumentsCount":0,
                    "transactionsCount":0
                }
                    }
                }
            ]
        }
    }

Clean up resources

When you no longer need your project, you can delete it with the following DELETE request. Replace the placeholder values with your own values.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}?api-version={API-VERSION}
Placeholder Value Example
{ENDPOINT} The endpoint for authenticating your API request. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} The name for your project. This value is case-sensitive. myProject
{API-VERSION} The version of the API you are calling. The value referenced here is for the latest version released. Learn more about other available API versions 2022-03-01-preview

Headers

Use the following header to authenticate your request.

Key Value
Ocp-Apim-Subscription-Key The key to your resource. Used for authenticating your API requests.

Once you send your API request, you will receive a 202 response indicating success, which means your project has been deleted.

Next steps

After you've created a custom text classification model, you can:

When you start to create your own custom text classification projects, use the how-to articles to learn more about developing your model in greater detail: