How to create custom Text Analytics for health project

Use this article to learn how to set up the requirements for starting with custom text analytics for health and create a project.

Prerequisites

Before you start using custom text analytics for health, you need:

• An Azure subscription - Create one for free.

Create a Language resource

Before you start using custom text analytics for health, you'll need an Azure AI Language resource. It's recommended to create your Language resource and connect a storage account to it in the Azure portal. Creating a resource in the Azure portal lets you create an Azure storage account at the same time, with all of the required permissions preconfigured. You can also read further in the article to learn how to use a pre-existing resource, and configure it to work with custom text analytics for health.

You also will need an Azure storage account where you will upload your .txt documents that will be used to train a model to extract entities.

Note

• You need to have an owner role assigned on the resource group to create a Language resource.
• If you will connect a pre-existing storage account, you should have an owner role assigned to it.

Create Language resource and connect storage account

You can create a resource in the following ways:

• The Azure portal
• Language Studio
• PowerShell

Note

You shouldn't move the storage account to a different resource group or subscription once it's linked with the Language resource.

Create a new resource from the Azure portal

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

2. In the window that appears, select this service from the custom features. Select Continue to create your resource at the bottom of the screen.

   

3. Create a Language resource with following details.

   Name	Description
   Subscription	Your Azure subscription.
   Resource group	A resource group that will contain your resource. You can use an existing one, or create a new one.
   Region	The region for your Language resource. For example, "West US 2".
   Name	A name for your resource.
   Pricing tier	The pricing tier for your Language resource. You can use the Free (F0) tier to try the service.

   Note

   If you get a message saying "your login account is not an owner of the selected storage account's resource group", your account needs to have an owner role assigned on the resource group before you can create a Language resource. Contact your Azure subscription owner for assistance.

4. In this service's section, select an existing storage account or select New storage account. 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
   Storage account name	Any name
   Storage account type	Standard LRS

5. Make sure the Responsible AI Notice is checked. Select Review + create at the bottom of the page, then select Create.

Create a new Language resource from Language Studio

If it's your first time logging in, you'll see a window in Language Studio that will let you choose an existing Language resource or create a new one. You can also create a resource by clicking the settings icon in the top-right corner, selecting Resources, then clicking Create a new resource.

Create a Language resource with following details.

Instance detail	Required value
Azure subscription	Your Azure subscription
Azure resource group	Your Azure resource group
Azure resource name	Your Azure resource name
Location	The region
Pricing tier	The pricing tier of your Language resource.

Important

• Make sure to enable Managed Identity when you create a Language resource.
• Read and confirm Responsible AI notice

To use this service, you'll need to create an Azure storage account if you don't have one already.

Create a new Language resource using PowerShell

You can create a new resource and a storage account using the following CLI template and parameters files, which are hosted on GitHub.

Edit the following values in the parameters file:

Parameter name	Value description
name	Name of your Language resource
location	Region in which your resource is hosted.
sku	The pricing tier of your resource.
storageResourceName	Name of your storage account
storageLocation	Region in which your storage account is hosted.
storageSkuType	SKU of your storage account.
storageResourceGroupName	Resource group of your storage account

Use the following PowerShell command to deploy the Azure Resource Manager (ARM) template with the files you edited.

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile <path-to-arm-template> `
  -TemplateParameterFile <path-to-parameters-file>

See the ARM template documentation for information on deploying templates and parameter files.

Note

• The process of connecting a storage account to your Language resource is irreversible, it cannot be disconnected later.
• You can only connect your language resource to one storage account.

Using a pre-existing Language resource

You can use an existing Language resource to get started with custom NER as long as this resource meets the below requirements:

Requirement	Description
Regions	Make sure your existing resource is provisioned in one of the supported regions. If not, you will need to create a new resource in one of these regions.
Pricing tier	The pricing tier for your resource.
Managed identity	Make sure that the resource's managed identity setting is enabled. Otherwise, read the next section.

To use custom text analytics for health, you'll need to create an Azure storage account if you don't have one already.

Enable identity management for your resource

Azure portal

Your Language resource must have identity management. To enable it using the Azure portal:

1. Go to your Language resource
2. From left hand menu, under Resource Management section, select Identity
3. From System assigned tab, make sure to set Status to On

Language Studio

Your Language resource must have identity management, to enable it using Language Studio:

1. Select the settings icon in the top right corner of the screen
2. Select Resources
3. Select the check box Managed Identity for your Azure AI Language resource.

Enable custom text analytics for health

Make sure to enable Custom text classification / Custom Named Entity Recognition / Custom text analytics for health feature from Azure portal.

1. Go to your Language resource in the Azure portal.
2. From the left side menu, under Resource Management section, select Features
3. Enable the Custom text classification / Custom Named Entity Recognition / Custom text analytics feature
4. Connect your storage account
5. Select Apply

Important

• Make sure that your Language resource has storage blob data contributor role assigned on the storage account you are connecting.

Add required roles

Use the following steps to set the required roles for your Language resource and storage account.

Roles for your Azure AI Language resource

1. Go to your storage account or Language resource in the Azure portal.

2. Select Access Control (IAM) in the left navigation menu.

3. Select Add to Add Role Assignments, and choose the appropriate role for your account.

   You should have the owner or contributor role assigned on your Language resource.

4. Within Assign access to, select User, group, or service principal

5. Select Select members

6. Select your user name. You can search for user names in the Select field. Repeat this for all roles.

7. Repeat these steps for all the user accounts that need access to this resource.

Roles for your storage account

1. Go to your storage account page in the Azure portal.
2. Select Access Control (IAM) in the left navigation menu.
3. Select Add to Add Role Assignments, and choose the Storage blob data contributor role on the storage account.
4. Within Assign access to, select Managed identity.
5. Select Select members
6. Select your subscription, and Language as the managed identity. You can search for user names in the Select field.

Important

If you have a virtual network or private endpoint, be sure to select Allow Azure services on the trusted services list to access this storage account in the Azure portal.

Enable CORS for your storage account

Make sure to allow (GET, PUT, DELETE) methods when enabling Cross-Origin Resource Sharing (CORS). Set allowed origins field to https://language.cognitive.azure.com. Allow all header by adding * to the allowed header values, and set the maximum age to 500.

Create a custom Text Analytics for health project

Once your resource and storage container are configured, create a new custom text analytics for health project. A project is a work area for building your custom AI models based on your data. Your project can only be accessed by you and others who have access to the Azure resource being used. If you have labeled data, you can use it to get started by importing a project.

Language Studio

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

2. Under the Extract information section of Language Studio, select Custom Text Analytics for health.

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

   

4. Enter the project information, including a name, description, and the language of the files in your project. If you're using the example dataset, select English. You can't change the name of your project later. Select 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.

5. After you select Create new project, a window 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 select 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 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.

   

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

7. If you have already labeled data make sure it follows the supported format and select Yes, my files are already labeled and I have formatted JSON labels file and select the labels file from the drop-down menu. Select Next. If you are using the dataset from the QuickStart, there is no need to review the formatting of the JSON labels file.

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

REST APIs

To start creating a custom Text Analytics for health model, you need to create a project. Creating a project will let you label data, train, evaluate, improve, and deploy your models.

Note

The project name is case-sensitive for all operations.

Create a PATCH request using the following URL, headers, and JSON body to create your project.

Request URL

Use the following URL to create a project. Replace the placeholder values below with your own values.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?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. See Model lifecycle to learn more about other available API versions.	2022-05-01

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.

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "CustomHealthcare",
  "description": "Project description",
  "multilingual": "True",
  "storageInputContainerName": "{CONTAINER-NAME}"
}

Key	Placeholder	Value	Example
projectName	{PROJECT-NAME}	The name of your project. This value is case-sensitive.	myProject
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 supported language codes.	en-us
projectKind	CustomHealthcare	Your project kind.	CustomHealthcare
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 ones 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

This request will return a 201 response, which means that the project is created.

This request will return an error if:

• The selected resource doesn't have proper permission for the storage account.

Import project

If you have already labeled data, you can use it to get started with the service. Make sure that your labeled data follows the accepted data formats.

Language Studio

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 Extract information section of Language Studio, select Custom text analytics for health.

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

4. After you select Create new project, a screen will appear to let you connect your storage account. If you can’t find your storage account, make sure you created a resource using the recommended steps. If you've already connected a storage account to your Language resource, you will see your storage account connected.

   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.

   

5. Enter the project information, including a name, description, and the language of the files in your project. You won’t be able to change the name of your project later. Select 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.

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

7. Select Yes, my files are already labeled and I have formatted JSON labels file and select the labels file from the drop-down menu below to import your JSON labels file. Make sure it follows the supported format.

8. Select Next.

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

REST APIs

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.

If a project with the same name already exists, the data of that project is replaced.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/: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. See Model lifecycle to learn more about other available API versions.	2022-05-01

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.

{
	"projectFileVersion": "{API-VERSION}",
	"stringIndexType": "Utf16CodeUnit",
	"metadata": {
		"projectName": "{PROJECT-NAME}",
		"projectKind": "CustomHealthcare",
		"description": "Trying out custom Text Analytics for health",
		"language": "{LANGUAGE-CODE}",
		"multilingual": true,
		"storageInputContainerName": "{CONTAINER-NAME}",
		"settings": {}
	},
	"assets": {
		"projectKind": "CustomHealthcare",
		"entities": [
			{
				"category": "Entity1",
				"compositionSetting": "{COMPOSITION-SETTING}",
				"list": {
					"sublists": [
						{
							"listKey": "One",
							"synonyms": [
								{
									"language": "en",
									"values": [
										"EntityNumberOne",
										"FirstEntity"
									]
								}
							]
						}
					]
				}
			},
			{
				"category": "Entity2"
			},
			{
				"category": "MedicationName",
				"list": {
					"sublists": [
						{
							"listKey": "research drugs",
							"synonyms": [
								{
									"language": "en",
									"values": [
										"rdrug a",
										"rdrug b"
									]
								}
							]

						}
					]
				}
				"prebuilts": "MedicationName"
			}
		],
		"documents": [
			{
				"location": "{DOCUMENT-NAME}",
				"language": "{LANGUAGE-CODE}",
				"dataset": "{DATASET}",
				"entities": [
					{
						"regionOffset": 0,
						"regionLength": 500,
						"labels": [
							{
								"category": "Entity1",
								"offset": 25,
								"length": 10
							},
							{
								"category": "Entity2",
								"offset": 120,
								"length": 8
							}
						]
					}
				]
			},
			{
				"location": "{DOCUMENT-NAME}",
				"language": "{LANGUAGE-CODE}",
				"dataset": "{DATASET}",
				"entities": [
					{
						"regionOffset": 0,
						"regionLength": 100,
						"labels": [
							{
								"category": "Entity2",
								"offset": 20,
								"length": 5
							}
						]
					}
				]
			}
		]
	}
}

Key	Placeholder	Value	Example
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
projectName	{PROJECT-NAME}	Project name	myproject
storageInputContainerName	{CONTAINER-NAME}	Container name	mycontainer
entities		Array containing all the entity types you have in the project. These are the entity types that will be extracted from your documents into.
category		The name of the entity type, which can be user defined for new entity definitions, or predefined for prebuilt entities.
compositionSetting	{COMPOSITION-SETTING}	Rule that defines how to manage multiple components in your entity. Options are combineComponents or separateComponents.	combineComponents
list		Array containing all the sublists you have in the project for a specific entity. Lists can be added to prebuilt entities or new entities with learned components.
sublists	[]	Array containing sublists. Each sublist is a key and its associated values.	[]
listKey	One	A normalized value for the list of synonyms to map back to in prediction.	One
synonyms	[]	Array containing all the synonyms	synonym
language	{LANGUAGE-CODE}	A string specifying the language code for the synonym in your sublist. If your project is a multilingual project and you want to support your list of synonyms for all the languages in your project, you have to explicitly add your synonyms to each language. See Language support for more information about supported language codes.	en
values	"EntityNumberone", "FirstEntity"	A list of comma separated strings that will be matched exactly for extraction and map to the list key.	"EntityNumberone", "FirstEntity"
prebuilts	MedicationName	The name of the prebuilt component populating the prebuilt entity. Prebuilt entities are automatically loaded into your project by default but you can extend them with list components in your labels file.	MedicationName
documents		Array containing all the documents in your project and list of the entities labeled within each 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 file will go to when split before training. Possible values for this field are Train and Test.	Train
regionOffset		The inclusive character position of the start of the text.	0
regionLength		The length of the bounding box in terms of UTF16 characters. Training only considers the data in this region.	500
category		The type of entity associated with the span of text specified.	Entity1
offset		The start position for the entity text.	25
length		The length of the entity in terms of UTF16 characters.	20
language	{LANGUAGE-CODE}	A string specifying the language code for the document used in your project. If your project is a multilingual project, choose the language code of the majority of the documents. See Language support for more information about supported language codes.	en

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 operation-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 project details

Language Studio

1. Go to your project settings page in Language Studio.

2. You can see project details.

3. In this page you can update project description and enable/disable Multi-lingual dataset in project settings.

4. You can also view the connected storage account and container to your Language resource.

5. You can also retrieve your primary resource key from this page.

   

REST APIs

Use the following GET request to get your project details. Replace the placeholder values below 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. See Model lifecycle to learn more about other available API versions.	2022-05-01

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

    {
        "createdDateTime": "2021-10-19T23:24:41.572Z",
        "lastModifiedDateTime": "2021-10-19T23:24:41.572Z",
        "lastTrainedDateTime": "2021-10-19T23:24:41.572Z",
        "lastDeployedDateTime": "2021-10-19T23:24:41.572Z",
        "projectKind": "CustomHealthcare",
        "storageInputContainerName": "{CONTAINER-NAME}",
        "projectName": "{PROJECT-NAME}",
        "multilingual": false,
        "description": "Project description",
        "language": "{LANGUAGE-CODE}"
    }

Value	Placeholder	Description	Example
projectKind	CustomHealthcare	Your project kind.	CustomHealthcare
storageInputContainerName	{CONTAINER-NAME}	The name of your Azure storage container where you have uploaded your documents.	myContainer
projectName	{PROJECT-NAME}	The name of your project. This value is case-sensitive.	myProject
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 ones included in your training documents). For more information about multilingual support, see Language support.	true
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.	en

Once you send your API request, you will receive a 200 response indicating success and JSON response body with your project details.

Delete project

Language Studio

When you don't need your project anymore, you can delete your project using Language Studio.

1. Select the Language service feature you're using at the top of the page, s
2. Select the project you want to delete
3. Select Delete from the top menu.

REST APIs

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/{projectName}?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. See Model lifecycle to learn more about other available API versions.	2022-05-01

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. A successful call results with an Operation-Location header used to check the status of the job.

Next steps

• You should have an idea of the project schema you will use to label your data.

• After you define your schema, you can start labeling your data, which will be used for model training, evaluation, and finally making predictions.