Merge pull request #234564 from aahill/ta4h-how-to-4

how to files, fixes

Author: American-Dipper

articles/cognitive-services/language-service/custom-text-analytics-for-health/how-to/deploy-model.md

@@ -0,0 +1,106 @@
+---
+title: Deploy a custom Text Analytics for health model
+titleSuffix: Azure Cognitive Services
+description: Learn about deploying a model for custom Text Analytics for health.
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: how-to
+ms.date: 10/12/2022
+ms.author: aahi
+ms.custom: language-service-custom-ta4h
+---
+
+# Deploy a custom text analytics for health model
+
+Once you're satisfied with how your model performs, it's ready to be deployed and used to recognize entities in text. Deploying a model makes it available for use through the [prediction API](https://aka.ms/ct-runtime-swagger).
+
+## Prerequisites
+
+* A successfully [created project](create-project.md) with a configured Azure storage account.
+* Text data that has [been uploaded](design-schema.md#data-preparation) to your storage account.
+* [Labeled data](label-data.md) and a successfully [trained model](train-model.md).
+* Reviewed the [model evaluation details](view-model-evaluation.md) to determine how your model is performing.
+
+For more information, see [project development lifecycle](../overview.md#project-development-lifecycle).
+
+## Deploy model
+
+After you've reviewed your model's performance and decided it can be used in your environment, you need to assign it to a deployment. Assigning the model to a deployment makes it available for use through the [prediction API](https://aka.ms/ct-runtime-swagger). It is recommended to create a deployment named *production* to which you assign the best model you have built so far and use it in your system. You can create another deployment called *staging* to which you can assign the model you're currently working on to be able to test it. You can have a maximum of 10 deployments in your project. 
+
+# [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Deploy a model using Language Studio](../includes/language-studio/deploy-model.md)]
+   
+# [REST APIs](#tab/rest-api)
+
+### Submit deployment job
+
+[!INCLUDE [deploy model](../includes/rest-api/deploy-model.md)]
+
+### Get deployment job status
+
+[!INCLUDE [get deployment status](../includes/rest-api/get-deployment-status.md)]
+
+---
+
+## Swap deployments
+
+After you are done testing a model assigned to one deployment and you want to assign this model to another deployment you can swap these two deployments. Swapping deployments involves taking the model assigned to the first deployment, and assigning it to the second deployment. Then taking the model assigned to second deployment, and assigning it to the first deployment. You can use this process to swap your *production* and *staging* deployments when you want to take the model assigned to *staging* and assign it to *production*. 
+
+# [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Swap deployments](../includes/language-studio/swap-deployment.md)]
+
+# [REST APIs](#tab/rest-api)
+
+[!INCLUDE [Swap deployments](../includes/rest-api/swap-deployment.md)]
+
+---
+
+
+## Delete deployment
+
+# [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Delete deployment](../includes/language-studio/delete-deployment.md)]
+
+# [REST APIs](#tab/rest-api)
+
+[!INCLUDE [Delete deployment](../includes/rest-api/delete-deployment.md)]
+
+---
+
+## Assign deployment resources
+
+You can [deploy your project to multiple regions](../../concepts/custom-features/multi-region-deployment.md) by assigning different Language resources that exist in different regions.
+
+# [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Assign resource](../../conversational-language-understanding/includes/language-studio/assign-resources.md)]
+
+# [REST APIs](#tab/rest-api)
+
+[!INCLUDE [Assign resource](../../custom-text-classification/includes/rest-api/assign-resources.md)]
+
+---
+
+## Unassign deployment resources
+
+When unassigning or removing a deployment resource from a project, you will also delete all the deployments that have been deployed to that resource's region.
+
+# [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Unassign resource](../../conversational-language-understanding/includes/language-studio/unassign-resources.md)]
+
+# [REST APIs](#tab/rest-api)
+
+[!INCLUDE [Unassign resource](../../custom-text-classification/includes/rest-api/unassign-resources.md)]
+
+---
+
+## Next steps
+
+After you have a deployment, you can use it to [extract entities](call-api.md) from text.

articles/cognitive-services/language-service/custom-text-analytics-for-health/how-to/fail-over.md

@@ -0,0 +1,141 @@
+---
+title: Back up and recover your custom Text Analytics for health models
+titleSuffix: Azure Cognitive Services
+description: Learn how to save and recover your custom Text Analytics for health models.
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: conceptual
+ms.date: 04/25/2022
+ms.author: aahi
+ms.custom: language-service-custom-ta4h
+---
+
+# Back up and recover your custom Text Analytics for health models
+
+When you create a Language resource, you specify a region for it to be created in. From then on, your resource and all of the operations related to it take place in the specified Azure server region. It's rare, but not impossible, to encounter a network issue that affects an entire region. If your solution needs to always be available, then you should design it to fail over into another region. This requires two Azure Language resources in different regions and synchronizing custom models across them. 
+
+If your app or business depends on the use of a custom Text Analytics for health model, we recommend that you create a replica of your project in an additional supported region. If a regional outage occurs, you can then access your model in the other fail-over region where you replicated your project.
+
+Replicating a project means that you export your project metadata and assets, and import them into a new project. This only makes a copy of your project settings and tagged data. You still need to [train](./train-model.md) and [deploy](./deploy-model.md) the models to be available for use with [prediction APIs](https://aka.ms/ct-runtime-swagger).
+
+In this article, you will learn to how to use the export and import APIs to replicate your project from one resource to another existing in different supported geographical regions, guidance on keeping your projects in sync and changes needed to your runtime consumption.
+
+##  Prerequisites
+
+* Two Azure Language resources in different Azure regions. [Create your resources](./create-project.md#create-a-language-resource) and connect them to an Azure storage account. It's recommended that you connect each of your Language resources to different storage accounts. Each storage account should be located in the same respective regions that your separate Language resources are in. You can follow the [quickstart](../quickstart.md?pivots=rest-api#create-a-new-azure-language-resource-and-azure-storage-account) to create an additional Language resource and storage account.
+
+
+## Get your resource keys endpoint
+
+Use the following steps to get the keys and endpoint of your primary and secondary resources. These will be used in the following steps.
+
+[!INCLUDE [Get keys and endpoint Azure Portal](../includes/get-keys-endpoint-azure.md)]
+
+> [!TIP]
+> Keep a note of keys and endpoints for both primary and secondary resources as well as the primary and secondary container names. Use these values to replace the following placeholders:
+`{PRIMARY-ENDPOINT}`, `{PRIMARY-RESOURCE-KEY}`, `{PRIMARY-CONTAINER-NAME}`, `{SECONDARY-ENDPOINT}`, `{SECONDARY-RESOURCE-KEY}`, and `{SECONDARY-CONTAINER-NAME}`.
+> Also take note of your project name, your model name and your deployment name. Use these values to replace the following placeholders:  `{PROJECT-NAME}`, `{MODEL-NAME}` and `{DEPLOYMENT-NAME}`.
+
+## Export your primary project assets
+
+Start by exporting the project assets from the project in your primary resource.
+
+### Submit export job
+
+Replace the placeholders in the following request with your `{PRIMARY-ENDPOINT}` and `{PRIMARY-RESOURCE-KEY}` that you obtained in the first step.
+
+[!INCLUDE [Export project assets using the REST API](../includes/rest-api/export-project.md)]
+
+### Get export job status
+
+Replace the placeholders in the following request with your `{PRIMARY-ENDPOINT}` and `{PRIMARY-RESOURCE-KEY}` that you obtained in the first step.
+
+[!INCLUDE [Export project assets using the REST API](../includes/rest-api/get-export-status.md)]
+
+
+Copy the response body as you will use it as the body for the next import job.
+
+## Import to a new project 
+
+Now go ahead and import the exported project assets in your new project in the secondary region so you can replicate it.
+
+### Submit import job
+
+Replace the placeholders in the following request with your `{SECONDARY-ENDPOINT}`, `{SECONDARY-RESOURCE-KEY}`, and `{SECONDARY-CONTAINER-NAME}` that you obtained in the first step.
+
+[!INCLUDE [Import project using the REST API](../includes/rest-api/import-project.md)]
+
+### Get import job status
+
+Replace the placeholders in the following request with your `{SECONDARY-ENDPOINT}` and `{SECONDARY-RESOURCE-KEY}` that you obtained in the first step.
+
+[!INCLUDE [Import project using the REST API](../includes/rest-api/get-import-status.md)]
+
+
+## Train your model
+
+After importing your project, you only have copied the project's assets and metadata and assets. You still need to train your model, which will incur usage on your account. 
+
+### Submit training job
+
+Replace the placeholders in the following request with your `{SECONDARY-ENDPOINT}` and `{SECONDARY-RESOURCE-KEY}` that you obtained in the first step.
+
+[!INCLUDE [train model](../includes/rest-api/train-model.md)]
+
+
+### Get training status
+
+Replace the placeholders in the following request with your `{SECONDARY-ENDPOINT}` and `{SECONDARY-RESOURCE-KEY}` that you obtained in the first step.
+
+[!INCLUDE [get training model status](../includes/rest-api/get-training-status.md)]
+
+## Deploy your model
+
+This is the step where you make your trained model available form consumption via the [runtime prediction API](https://aka.ms/ct-runtime-swagger). 
+
+> [!TIP]
+> Use the same deployment name as your primary project for easier maintenance and minimal changes to your system to handle redirecting your traffic.
+
+### Submit deployment job 
+
+Replace the placeholders in the following request with your `{SECONDARY-ENDPOINT}` and `{SECONDARY-RESOURCE-KEY}` that you obtained in the first step.
+
+[!INCLUDE [deploy model](../includes/rest-api/deploy-model.md)]
+
+### Get the deployment status
+
+Replace the placeholders in the following request with your `{SECONDARY-ENDPOINT}` and `{SECONDARY-RESOURCE-KEY}` that you obtained in the first step.
+
+[!INCLUDE [get deploy status](../includes/rest-api/get-deployment-status.md)]
+
+## Changes in calling the runtime
+
+Within your system, at the step where you call [runtime prediction API](https://aka.ms/ct-runtime-swagger) check for the response code returned from the submit task API. If you observe a **consistent** failure in submitting the request, this could indicate an outage in your primary region. Failure once doesn't mean an outage, it may be transient issue. Retry submitting the job through the secondary resource you have created. For the second request use your `{SECONDARY-ENDPOINT}` and `{SECONDARY-RESOURCE-KEY}`, if you have followed the steps above, `{PROJECT-NAME}` and `{DEPLOYMENT-NAME}` would be the same so no changes are required to the request body. 
+
+In case you revert to using your secondary resource you will observe slight increase in latency because of the difference in regions where your model is deployed. 
+
+## Check if your projects are out of sync
+
+Maintaining the freshness of both projects is an important part of the process. You need to frequently check if any updates were made to your primary project so that you move them over to your secondary project. This way if your primary region fails and you move into the secondary region you should expect similar model performance since it already contains the latest updates. Setting the frequency of checking if your projects are in sync is an important choice. We recommend that you do this check daily in order to guarantee the freshness of data in your secondary model.
+
+### Get project details
+
+Use the following url to get your project details, one of the keys returned in the body indicates the last modified date of the project. 
+Repeat the following step twice, one for your primary project and another for your secondary project and compare the timestamp returned for both of them to check if they are out of sync.
+
+  [!INCLUDE [get project details](../includes/rest-api/get-project-details.md)]
+
+
+Repeat the same steps for your replicated project using `{SECONDARY-ENDPOINT}` and `{SECONDARY-RESOURCE-KEY}`. Compare the returned `lastModifiedDateTime` from both projects. If your primary project was modified sooner than your secondary one, you need to repeat the steps of [exporting](#export-your-primary-project-assets), [importing](#import-to-a-new-project), [training](#train-your-model) and [deploying](#deploy-your-model).
+
+
+## Next steps
+
+In this article, you have learned how to use the export and import APIs to replicate your project to a secondary Language resource in other region. Next, explore the API reference docs to see what else you can do with authoring APIs.
+
+* [Authoring REST API reference](https://aka.ms/ct-authoring-swagger)
+
+* [Runtime prediction REST API reference](https://aka.ms/ct-runtime-swagger)

articles/cognitive-services/language-service/custom-text-analytics-for-health/how-to/train-model.md

@@ -0,0 +1,83 @@
+---
+title: How to train your custom Text Analytics for health model
+titleSuffix: Azure Cognitive Services
+description: Learn about how to train your model for custom Text Analytics for health.
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: how-to
+ms.date: 05/06/2022
+ms.author: aahi
+ms.custom: language-service-custom-ta4h
+---
+
+# Train your custom Text Analytics for health model
+
+Training is the process where the model learns from your [labeled data](label-data.md). After training is completed, you'll be able to view the [model's performance](view-model-evaluation.md) to determine if you need to improve your model.
+
+To train a model, you start a training job and only successfully completed jobs create a model. Training jobs expire after seven days, which means you won't be able to retrieve the job details after this time. If your training job completed successfully and a model was created, the model won't be affected. You can only have one training job running at a time, and you can't start other jobs in the same project. 
+
+The training times can be anywhere from a few minutes when dealing with few documents, up to several hours depending on the dataset size and the complexity of your schema.
+
+
+## Prerequisites
+
+* A successfully [created project](create-project.md) with a configured Azure blob storage account
+* Text data that [has been uploaded](design-schema.md#data-preparation) to your storage account.
+* [Labeled data](label-data.md)
+
+See the [project development lifecycle](../overview.md#project-development-lifecycle) for more information.
+
+## Data splitting
+
+Before you start the training process, labeled documents in your project are divided into a training set and a testing set. Each one of them serves a different function.
+The **training set** is used in training the model, this is the set from which the model learns the labeled entities and what spans of text are to be extracted as entities. 
+The **testing set** is a blind set that is not introduced to the model during training but only during evaluation. 
+After model training is completed successfully, the model is used to make predictions from the documents in the testing and based on these predictions [evaluation metrics](../concepts/evaluation-metrics.md) are calculated. Model training and evaluation are only for newly defined entities with learned components; therefore, Text Analytics for health entities are excluded from model training and evaluation due to them being entities with prebuilt components. It's recommended to make sure that all your labeled entities are adequately represented in both the training and testing set.
+
+Custom Text Analytics for health supports two methods for data splitting:
+
+* **Automatically splitting the testing set from training data**:The system splits your labeled data between the training and testing sets, according to the percentages you choose. The recommended percentage split is 80% for training and 20% for testing. 
+
+ > [!NOTE]
+ > If you choose the **Automatically splitting the testing set from training data** option, only the data assigned to training set will be split according to the percentages provided.
+
+* **Use a manual split of training and testing data**: This method enables users to define which labeled documents should belong to which set. This step is only enabled if you have added documents to your testing set during [data labeling](label-data.md).
+
+## Train model
+
+# [Language studio](#tab/Language-studio)
+
+[!INCLUDE [Train model](../includes/language-studio/train-model.md)]
+
+# [REST APIs](#tab/REST-APIs)
+
+### Start training job
+
+[!INCLUDE [train model](../includes/rest-api/train-model.md)]
+
+### Get training job status
+
+Training could take sometime depending on the size of your training data and complexity of your schema. You can use the following request to keep polling the status of the training job until it's successfully completed.
+
+ [!INCLUDE [get training model status](../includes/rest-api/get-training-status.md)]
+
+---
+
+### Cancel training job
+
+# [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Cancel training](../includes/language-studio/cancel-training.md)]
+
+# [REST APIs](#tab/rest-api)
+
+[!INCLUDE [Cancel training](../includes/rest-api/cancel-training.md)]
+
+---
+
+## Next steps
+
+After training is completed, you'll be able to view the [model's performance](view-model-evaluation.md) to optionally improve your model if needed. Once you're satisfied with your model, you can deploy it, making it available to use for [extracting entities](call-api.md) from text.

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/language-studio/cancel-training.md

@@ -0,0 +1,13 @@
+---
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.custom: event-tier1-build-2022
+ms.topic: include
+ms.date: 05/24/2022
+ms.author: aahi
+---
+
+To cancel a training job from within [Language Studio](https://aka.ms/languageStudio), go to the **Training jobs** page. Select the training job you want to cancel and click on **Cancel** from the top menu. 

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/language-studio/delete-deployment.md

@@ -0,0 +1,14 @@
+---
+titleSuffix: Azure Cognitive Services
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.custom: event-tier1-build-2022
+ms.topic: include
+ms.date: 05/24/2022
+ms.author: aahi
+---
+
+To delete a deployment from within [Language Studio](https://aka.ms/laguageStudio), go to the **Deploying a model** page. Select the deployment you want to delete and click on **Delete deployment** from the top menu. 

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/language-studio/swap-deployment.md

@@ -0,0 +1,18 @@
+---
+titleSuffix: Azure Cognitive Services
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.custom: event-tier1-build-2022
+ms.topic: include
+ms.date: 05/09/2022
+ms.author: aahi
+---
+
+To swap deployments from within [Language Studio](https://aka.ms/laguageStudio):
+
+1. In the **Deploying a model** page, select the two deployments you want to swap and click on **Swap deployments** from the top menu. 
+
+2. From the window that appears, select the names of the deployments you want to swap.