CLU container update

Author: jboback

articles/ai-services/cognitive-services-container-support.md

@@ -56,6 +56,7 @@ Azure AI containers provide the following set of Docker containers, each of whic
 | [Language service][ta-containers-pii] | **Personally Identifiable Information (PII) detection** ([image](https://mcr.microsoft.com/en-us/product/azure-cognitive-services/textanalytics/pii/tags))| Detect and redact personally identifiable information entities from text. | Generally available. <br>This container can also [run in disconnected environments](containers/disconnected-containers.md). |
 | [Language service][ta-containers-cner] |  **Custom Named Entity Recognition** ([image](https://mcr.microsoft.com/product/azure-cognitive-services/textanalytics/customner/about))| Extract named entities from text, using a custom model you create using your data. | Generally available |
 | [Language service][ta-containers-summarization] | **Summarization** ([image](https://mcr.microsoft.com/product/azure-cognitive-services/textanalytics/summarization/about))| Summarize text from various sources. | Public preview. <br>This container can also [run in disconnected environments](containers/disconnected-containers.md). |
+| [Language service][ta-containers-clu] | **Conversational Language Understanding** ([image](https://mcr.microsoft.com/product/azure-cognitive-services/textanalytics/clu/about))| Interpret conversational language. | Generally Available. <br>This container can also [run in disconnected environments](containers/disconnected-containers.md). |
 | [Translator][tr-containers] | **Translator** ([image](https://mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation/about))| Translate text in several languages and dialects. | Generally available. Gated - [request access](https://aka.ms/csgate-translator). <br>This container can also [run in disconnected environments](containers/disconnected-containers.md). |
 
 ### Speech containers
@@ -132,6 +133,7 @@ Install and explore the functionality provided by containers in Azure AI service
 [ta-containers-cner]: language-service/custom-named-entity-recognition/how-to/use-containers.md
 [ta-containers-summarization]: language-service/summarization/how-to/use-containers.md
 [ta-containers-ner]: language-service/named-entity-recognition/how-to/use-containers.md
-[ta-containers-pii]: language-service/personally-identifiable-information//how-to/use-containers.md
+[ta-containers-pii]: language-service/personally-identifiable-information/how-to/use-containers.md
+[ta-contatiners-clu]: language-service/conversational-language-understanding/how-to/use-containers.md
 [tr-containers]: translator/containers/translator-how-to-install-container.md
 [request-access]: https://aka.ms/csgate

articles/ai-services/containers/disconnected-containers.md

@@ -28,6 +28,7 @@ Containers enable you to run Azure AI services APIs in your own environment, and
   * [Summarization](../language-service/summarization/how-to/use-containers.md)
   * [Named Entity Recognition](../language-service/named-entity-recognition/how-to/use-containers.md)
   * [Personally Identifiable Information (PII) detection](../language-service/personally-identifiable-information/how-to/use-containers.md)
+  * [Conversational Language Understanding (CLU)](../language-service/conversational-language-understanding/how-to/use-containers.md)
 * [Azure AI Vision - Read](../computer-vision/computer-vision-how-to-install-containers.md)
 * [Document Intelligence](../../ai-services/document-intelligence/containers/disconnected.md)
 
@@ -90,6 +91,7 @@ See the following documentation for steps on downloading and configuring the con
 * [Language Detection](../language-service/language-detection/how-to/use-containers.md#run-the-container-disconnected-from-the-internet)
 * [Named Entity Recognition](../language-service/named-entity-recognition/how-to/use-containers.md#run-the-container-disconnected-from-the-internet)
 * [Personally Identifiable Information (PII) detection](../language-service/personally-identifiable-information/how-to/use-containers.md#run-the-container-disconnected-from-the-internet)
+* [Conversational Language Understanding (CLU)](../language-service/conversational-language-understanding/how-to/use-containers.md#run-the-container-disconnected-from-the-internet)
 
 ## Environment variable names in Kubernetes deployments
 Some Azure AI Containers, for example Translator, require users to pass environmental variable names that include colons (`:`) when running the container. This will work fine when using Docker, but Kubernetes does not accept colons in environmental variable names.

articles/ai-services/language-service/conversational-language-understanding/how-to/use-containers.md

@@ -45,24 +45,74 @@ It is recommended to have a CPU with AVX-512 instruction set, for the best exper
 
 |                     | Minimum host specs     | Recommended host specs |
 |---------------------|------------------------|------------------------|
-| **CLU**   | 1 core, 2GB memory     | 4 cores, 8GB memory    |
+| **CLU**             | 1 core, 2GB memory     | 4 cores, 8GB memory    |
 
 CPU core and memory correspond to the `--cpus` and `--memory` settings, which are used as part of the `docker run` command.
 
+## Export your Conversational Language Understanding model 
+
+Before you proceed with running the docker image, you will need to export your own trained model to expose it to your container. Use the following command to extract your model and replace the placeholders below with your own values: 
+
+|Placeholder |Value|Format or example|
+|------------|-----|-----------------|
+|**{API_KEY}** |The key for your Language resource. You can find it on your resource's **Key and endpoint** page, on the Azure portal.|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx|
+|**{ENDPOINT_URI}**|The endpoint for accessing the Conversational Language Understanding API. You can find it on your resource's **Key and endpoint** page, on the Azure portal.|https://<your-custom-subdomain>.cognitiveservices.azure.com|
+|**{PROJECT_NAME}**|The name of the project containing the model that you want to export. You can find it on your projects tab in the Language Studio portal.|myProject|
+|**{TRAINED_MODEL_NAME}** |The name of the trained model you want to export. You can find your trained models on your model evaluation tab under your project in the Language Studio portal|myTrainedModel 
+|**{EXPORTED_MODEL_NAME}** |The name to assign for the new exported model created.|myExportedModel |
+
+```bash
+curl --location --request PUT '{ENDPOINT_URI}/language/authoring/analyze-conversations/projects/{PROJECT_NAME}/exported-models/{EXPORTED_MODEL_NAME}?api-version=2024-11-15-preview' \ 
+--header 'Ocp-Apim-Subscription-Key: {API_KEY}' \ 
+--header 'Content-Type: application/json' \ 
+--data-raw '{ 
+    "TrainedModelLabel": "{TRAINED_MODEL_NAME}" 
+}' 
+```
+
 ## Get the container image with `docker pull`
 
-The CLU container image can be found on the `mcr.microsoft.com` container registry syndicate. It resides within the `azure-cognitive-services/textanalytics/` repository and is named `clu`. The fully qualified container image name is, `mcr.microsoft.com/azure-cognitive-services/textanalytics/clu`
+The CLU container image can be found on the `mcr.microsoft.com` container registry syndicate. It resides within the `azure-cognitive-services/language/` repository and is named `clu`. The fully qualified container image name is, `mcr.microsoft.com/azure-cognitive-services/language/clu`
 
- To use the latest version of the container, you can use the `latest` tag, which is for English. You can also find a full list of containers for supported languages using the [tags on the MCR](https://mcr.microsoft.com/product/azure-cognitive-services/textanalytics/clu/tags).
+ To use the latest version of the container, you can use the `latest` tag, which is for English. You can also find a full list of containers for supported languages using the [tags on the MCR](https://mcr.microsoft.com/product/azure-cognitive-services/language/clu/tags).
 
 The latest CLU container is available in several languages. To download the container for the English container, use the command below. 
 
 ```
-docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/clu:latest
+docker pull mcr.microsoft.com/azure-cognitive-services/language/clu:latest
 ```
 
 [!INCLUDE [Tip for using docker list](../../../includes/cognitive-services-containers-docker-list-tip.md)]
 
+## Run the container in download model mode 
+
+After creating the exported model in the section above, users will have to run the container in order to download the deployment package that was created specifically for their exported models. 
+
+|Placeholder|Value|Format or example|
+|-----------|-----|-----------------|
+|**{API_KEY}** |The key for your Language resource. You can find it on your resource's **Key and endpoint** page, on the Azure portal. |xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx|  
+|**{ENDPOINT_URI}** |The endpoint for accessing the API. You can find it on your resource's **Key and endpoint** page, on the Azure portal.  |https://<your-custom-subdomain>.cognitiveservices.azure.com  |
+|**{IMAGE_TAG}** |The image tag representing the language of the container you want to run. Make sure this matches the `docker pull` command you used.  |latest  |
+|**{LOCAL_CLU_PORT}** |Port number assigned for the container in local machine. |5000 |
+|**{LOCAL_MODEL_DIRECTORY}** |Absolute directory in host machine where exported models will be saved in. |C:\usr\local\myDeploymentPackage |
+|**{PROJECT_NAME}** |Name of the project that the exported model belongs to |myProject |
+|**{EXPORTED_MODEL_NAME}** |Exported model to be downloaded |myExportedModel |
+
+```bash
+docker run --rm -it -p {LOCAL_CLU_PORT}:80 \ 
+mcr.microsoft.com/azure-cognitive-services/language/clu:{IMAGE_TAG} \   
+-v {LOCAL_MODEL_DIRECTORY}:/DeploymentPackage \ 
+Billing={ENDPOINT_URI} \   
+ApiKey={API_KEY} \ 
+downloadmodel \ 
+projectName={PROJECT_NAME} \ 
+exportedModelName={EXPORTED_MODEL_NAME} 
+```
+
+DO NOT alter the downloaded files. Even altering the name or folder structure can affect the integrity of the container and might break it. 
+
+Repeat those steps to download as many models as you'd like to test. They can belong to different projects and have different exported model names. 
+
 ## Run the container with `docker run`
 
 Once the container is on the host computer, use the [docker run](https://docs.docker.com/engine/reference/commandline/run/) command to run the containers. The container will continue to run until you stop it. Replace the placeholders below with your own values:
@@ -79,10 +129,14 @@ To run the CLU container, execute the following `docker run` command. Replace th
 | **{API_KEY}** | The key for your Language resource. You can find it on your resource's **Key and endpoint** page, on the Azure portal. |`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`|
 | **{ENDPOINT_URI}** | The endpoint for accessing the API. You can find it on your resource's **Key and endpoint** page, on the Azure portal. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
 | **{IMAGE_TAG}** | The image tag representing the language of the container you want to run. Make sure this matches the `docker pull` command you used. | `latest` |
+|**{LOCAL_CLU_PORT}** |Port number assigned for the container in local machine. |5000 |
+|**{LOCAL_NER_PORT}** |Port number of the NER container. See Run NER Container section below. |5001 (Has to be different that the above port number) |
+|**{LOCAL_LOGGING_DIRECTORY}** |Absolute directory in host machine where that logs will be saved in. |C:\usr\local\mylogs |
+|**{LOCAL_MODEL_DIRECTORY}** |Absolute directory in host machine where exported models are saved in. |C:\usr\local\myDeploymentPackage |
 
 ```bash
 docker run --rm -it -p 5000:5000 --memory 8g --cpus 1 \
-mcr.microsoft.com/azure-cognitive-services/textanalytics/clu:{IMAGE_TAG} \
+mcr.microsoft.com/azure-cognitive-services/language/clu:{IMAGE_TAG} \
 Eula=accept \
 Billing={ENDPOINT_URI} \
 ApiKey={API_KEY}
@@ -97,6 +151,13 @@ This command:
 
 [!INCLUDE [Running multiple containers on the same host](../../../includes/cognitive-services-containers-run-multiple-same-host.md)]
 
+## Running NER Container 
+CLU relies on NER to handle prebuilt entities. The CLU container will work properly without NER if users decide not to integrate it. NER billing is disabled when it’s used through CLU, no extra charges are generated unless a call is made directly to NER’s container. 
+ 
+To set NER up in CLU container 
+- Follow the [NER container documentation](../../named-entity-recognition/how-to/use-containers.md). 
+- When running CLU container, make sure to set the parameter `Ner_Url `so that `Ner_Url=http://host.docker.internal:{LOCAL_NER_PORT}` 
+
 ## Query the container's prediction endpoint
 
 The container provides REST-based query prediction endpoint APIs.