Merge pull request #199385 from aahill/baher-3

custom ner updates
MicrosoftDocs · May 26, 2022 · 2c5cb78 · 2c5cb78
2 parents d810001 + c7fa402
commit 2c5cb78
Show file tree

Hide file tree

Showing 19 changed files with 243 additions and 314 deletions.
diff --git a/...ge-service/custom-named-entity-recognition/includes/rest-api/cancel-training.md b/...ge-service/custom-named-entity-recognition/includes/rest-api/cancel-training.md
@@ -9,23 +9,22 @@ ms.date: 05/06/2022
 ms.author: aahi
 ---
 
-
-Create a **POST** request using the following URL, headers, and JSON body to cancel a training job. 
+Create a **POST** request by using the following URL, headers, and JSON body to cancel a training job. 
 
 ### Request URL
 
 Use the following URL when creating your API request. Replace the placeholder values below with your own values. 
 
 ```rest
-{ENDPOINT}/language/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}/:cancel?api-version={API-VERSION}
+{Endpoint}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}/:cancel?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.   | `EmailApp` |
-|`{JOB-ID}          | This is the training job ID|                                  |`XXXXX-XXXXX-XXXX-XX|
-|`{API-VERSION}`     | The version of the API you are calling. The value referenced here is for the latest released [model version](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data)  | `2022-03-01-preview` |
+|`{JOB-ID}`       | This value is the training job ID.|  `XXXXX-XXXXX-XXXX-XX`|
+|`{API-VERSION}`     | The version of the API you're calling. The value referenced is for the latest released [model version](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data).  | `2022-05-01` |
 
 ### Headers
 
@@ -35,4 +34,4 @@ Use the following header to authenticate your request.
 |--|--|
 |`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 204 response indicating success, which means your training job has been canceled.
+After you send your API request, you'll receive a 202 response with an `Operation-Location` header used to check the status of the job.
diff --git a/...age-service/custom-named-entity-recognition/includes/rest-api/create-project.md b/...age-service/custom-named-entity-recognition/includes/rest-api/create-project.md
@@ -8,21 +8,27 @@ ms.topic: include
 ms.date: 04/06/2022
 ms.author: aahi
 ---
+To start creating a custom named entity recognition 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.
+> The project name is case-sensitive for all operations.
 
-Create a **POST** request using the following URL, headers, and JSON body to create your project and import the tags file.
+Create a **PATCH** request using the following URL, headers, and JSON body to create your project.
 
-Use the following URL to create a project and import your tags file. Replace the placeholder values below with your own values. 
+### Request URL
+
+Use the following URL to create a project. Replace the placeholder values below with your own values. 
 
 ```rest
-{YOUR-ENDPOINT}/language/analyze-text/projects/{projectName}/:import?api-version=2021-11-01-preview
+{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
 ```
 
 |Placeholder  |Value  | Example |
 |---------|---------|---------|
-|`{YOUR-ENDPOINT}`     | The endpoint for authenticating your API request.   | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
+|`{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](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions.  | `2022-05-01` |
+
 
 ### Headers
 
@@ -34,91 +40,34 @@ Use the following header to authenticate your request.
 
 ### Body
 
-Use the following JSON in your request. Replace the placeholder values below with your own values. Use the tags file available in the [sample data](https://github.com/Azure-Samples/cognitive-services-sample-data-files) tab
+Use the following JSON in your request. Replace the placeholder values below with your own values.
 
 ```json
 {
-    "api-version": "2021-11-01-preview",
-    "metadata": {
-        "name": "MyProject",
-        "multiLingual": true,
-        "description": "Trying out custom NER",
-        "modelType": "Extraction",
-        "language": "string",
-        "storageInputContainerName": "YOUR-CONTAINER-NAME",
-        "settings": {}
-    },
-    "assets": {
-        "extractors": [
-        {
-            "name": "Entity1"
-        },
-        {
-            "name": "Entity2"
-        }
-    ],
-    "documents": [
-        {
-            "location": "doc1.txt",
-            "language": "en-us",
-            "dataset": "Train",
-            "extractors": [
-                {
-                    "regionOffset": 0,
-                    "regionLength": 500,
-                    "labels": [
-                        {
-                            "extractorName": "Entity1",
-                            "offset": 25,
-                            "length": 10
-                        },                    
-                        {
-                            "extractorName": "Entity2",
-                            "offset": 120,
-                            "length": 8
-                        }
-                    ]
-                }
-            ]
-        },
-        {
-            "location": "doc2.txt",
-            "language": "en-us",
-            "dataset": "Test",
-            "extractors": [
-                {
-                    "regionOffset": 0,
-                    "regionLength": 100,
-                    "labels": [
-                        {
-                            "extractorName": "Entity2",
-                            "offset": 20,
-                            "length": 5
-                        }
-                    ]
-                }
-            ]
-        }
-    ]
-    }
+  "projectName": "{PROJECT-NAME}",
+  "language": "{LANGUAGE-CODE}",
+  "projectKind": "CustomEntityRecognition",
+  "description": "Project description",
+  "multilingual": "True",
+  "storageInputContainerName": "{CONTAINER-NAME}"
 }
+
 ```
-For the metadata key: 
 
-|Key  |Value  | Example |
-|---------|---------|---------|
-| `modelType`    | Your Model type. | Extraction |
-|`storageInputContainerName`   | The name of your Azure blob storage container.   | `myContainer` |
+|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](../../language-support.md) to learn more about supported language codes. |`en-us`|
+| projectKind | `CustomEntityRecognition` | Your project kind. | `CustomEntityRecognition` |
+| 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](../../language-support.md#multi-lingual-option) to learn more about multilingual support.  | `true`|
+| storageInputContainerName | `{CONTAINER-NAME` | The name of your Azure storage container where you have uploaded your documents.   | `myContainer` |
 
-For the documents key: 
 
-|Key  |Value  | Example |
-|---------|---------|---------|
-| `location`    | Document name on the blob store. | `doc2.txt` |
-|`language`   | The language of the document.   | `en-us` |
-|`dataset`   |  Optional field to specify the dataset which this document will belong to. | `Train` or `Test` | 
 
 
-This request will return an error if:
+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. 
+
diff --git a/...-service/custom-named-entity-recognition/includes/rest-api/delete-deployment.md b/...-service/custom-named-entity-recognition/includes/rest-api/delete-deployment.md
@@ -16,16 +16,15 @@ Create a **DELETE** request using the following URL, headers, and JSON body to d
 ### Request URL
 
 ```rest
-{ENDPOINT}/language/analyze-text/projects/{PROJECT-NAME}/deployments/{deploymentName}?api-version={API-VERSION}
+{Endpoint}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{deploymentName}?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` |
 |`{DEPLOYMENT-NAME}`     | The name for your deployment name. This value is case-sensitive.   | `prod` |
-|`{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](../../../concepts/model-lifecycle.md#api-versions)  | `2022-03-01-preview` |
-
+|`{API-VERSION}`     | The version of the API you are calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions.  | `2022-05-01` |
 
 ### Headers
 
@@ -34,7 +33,8 @@ 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.|
-|`Content-Type` | application/json |
 
 
-Once you send your API request, you will receive a `202` response indicating success, which means your deployment has been deleted.
+Once you send your API request, you will receive a `202` response indicating success, which means your deployment has been deleted. A successful call results with an `Operation-Location` header used to check the status of the job.
+
+
diff --git a/...guage-service/custom-named-entity-recognition/includes/rest-api/delete-model.md b/...guage-service/custom-named-entity-recognition/includes/rest-api/delete-model.md
@@ -10,24 +10,21 @@ ms.date: 05/09/2022
 ms.author: aahi
 ---
 
-
-
-Create a **DELETE** request using the following URL, headers, and JSON body to delete a model.
+Create a **DELETE** request using the following URL, headers, and JSON body to delete a trained model.
 
 
 ### Request URL
 
 ```rest
-{ENDPOINT}/language/analyze-text/projects/{PROJECT-NAME}/models/{trainedModelLabel}?api-version={API-VERSION}
+{Endpoint}/language/authoring/analyze-text/projects/{PROJECT-NAME}/models/{trainedModelLabel}?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` |
 |`{trainedModelLabel}`     | The name for your model name. This value is case-sensitive.   | `model1` |
-|`{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](../../../concepts/model-lifecycle.md#api-versions)  | `2022-03-01-preview` |
-
+|`{API-VERSION}`     | The version of the API you are calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions.  | `2022-05-01` |
 
 ### Headers
 
@@ -38,4 +35,4 @@ Use the following header to authenticate your request.
 |`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 model has been deleted.
+Once you send your API request, you will receive a `204` response indicating success, which means your trained model has been deleted.
diff --git a/...age-service/custom-named-entity-recognition/includes/rest-api/delete-project.md b/...age-service/custom-named-entity-recognition/includes/rest-api/delete-project.md
@@ -12,15 +12,14 @@ ms.author: aahi
 When you no longer need your project, you can delete it with the following **DELETE** request. Replace the placeholder values with your own values.   
 
 ```rest
-{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}?api-version={API-VERSION}
+{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. Learn more about other available [API versions](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data)  | `2022-03-01-preview` |
-
+|`{API-VERSION}`     | The version of the API you are calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions.  | `2022-05-01` |
 
 ### Headers
 
@@ -31,4 +30,4 @@ Use the following header to authenticate your request.
 |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.
+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.
diff --git a/...guage-service/custom-named-entity-recognition/includes/rest-api/deploy-model.md b/...guage-service/custom-named-entity-recognition/includes/rest-api/deploy-model.md
@@ -13,16 +13,15 @@ ms.author: aahi
 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. 
 
 ```rest
-{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}
+{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?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](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data)  | `2022-03-01-preview` |
-
+|`{API-VERSION}`     | The version of the API you are calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions.  | `2022-05-01` |
 
 #### Headers
 
@@ -46,10 +45,10 @@ Use the following JSON in the body of your request. Use the name of the model yo
 |---------|---------|-----|----|
 | 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: 
+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: 
 
 ```rest
 {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.  
+`{JOB-ID}` is used to identify your request, since this operation is asynchronous. You can use this URL to get the deployment status.
diff --git a/...age-service/custom-named-entity-recognition/includes/rest-api/export-project.md b/...age-service/custom-named-entity-recognition/includes/rest-api/export-project.md
@@ -17,15 +17,14 @@ Create a **POST** request using the following URL, headers, and JSON body to exp
 Use the following URL when creating your API request. Replace the placeholder values below with your own values. 
 
 ```rest
-{ENDPOINT}/language/analyze-text/projects/{PROJECT-NAME}/:export?api-version={API-VERSION}
+{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&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](../../../concepts/model-lifecycle.md#api-versions)  | `2022-03-01-preview` |
-
+|`{API-VERSION}`     | The version of the API you are calling. The value referenced here is the latest [model version](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) released.  | `2022-05-01` |
 
 ### Headers
 
@@ -51,4 +50,4 @@ Once you send your API request, you’ll receive a `202` response indicating tha
 {ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/export/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 export job status.  
+`{JOB-ID}` is used to identify your request, since this operation is asynchronous. You’ll use this URL to get the export job status.