Merge pull request #271956 from MicrosoftDocs/main

4/11/2024 PM Publish

Author: Taojunshen

.openpublishing.publish.config.json

@@ -974,6 +974,12 @@
       "branch": "main",
       "branch_mapping": {}
     },
+    {
+      "path_to_root": "azure-typescript-e2e-apps",
+      "url": "https://github.com/Azure-Samples/azure-typescript-e2e-apps",
+      "branch": "main",
+      "branch_mapping": {}
+    },
     {
       "path_to_root": "azure-webpubsub",
       "url": "https://github.com/Azure/azure-webpubsub",

.openpublishing.redirection.json

@@ -3974,6 +3974,11 @@
             "source_path_from_root":"/articles/trusted-signing/concept.md",
             "redirect_url":"/azure/trusted-signing/concept-trustedsigning-resources-roles",
             "redirect_document_id":false 
+        },
+        {
+            "source_path_from_root":"/articles/container-instances/availability-zones.md",
+            "redirect_url":"/azure/reliability/reliability-containers",
+            "redirect_document_id":false 
         }
     ]
 }

articles/ai-services/openai/assistants-quickstart.md

@@ -42,6 +42,12 @@ Azure OpenAI Assistants (Preview) allows you to create AI assistants tailored to
 
 ::: zone-end
 
+::: zone pivot="programming-language-javascript"
+
+[!INCLUDE [JavaScript quickstart](includes/assistants-javascript.md)]
+
+::: zone-end
+
 ::: zone pivot="rest-api"
 
 [!INCLUDE [REST API quickstart](includes/assistants-rest.md)]

articles/ai-services/openai/how-to/azure-developer-cli.md

@@ -0,0 +1,87 @@
+---
+title: 'Use the Azure Developer CLI to deploy resources for Azure OpenAI On Your Data'
+titleSuffix: Azure OpenAI
+description: Use this article to learn how to automate resource deployment for Azure OpenAI On Your Data.
+manager: nitinme
+ms.service: azure-ai-openai
+ms.topic: quickstart
+author: aahill
+ms.author: aahi
+ms.date: 04/09/2024
+recommendations: false
+---
+
+# Use the Azure Developer CLI to deploy resources for Azure OpenAI On Your Data 
+
+Use this article to learn how to automate resource deployment for Azure OpenAI On Your Data. The Azure Developer CLI (`azd`) is an open-source, command-line tool that streamlines provisioning and deploying resources to Azure using a template system. The template contains infrastructure files to provision the necessary Azure OpenAI resources and configurations and includes the completed sample app code.
+
+## Prerequisites
+
+- An Azure subscription - <a href="https://azure.microsoft.com/free/cognitive-services" target="_blank">Create one for free</a>.
+- Access granted to Azure OpenAI in the desired Azure subscription.
+
+  Azure OpenAI requires registration and is currently only available to approved enterprise customers and partners. [See Limited access to Azure OpenAI Service](/legal/cognitive-services/openai/limited-access?context=/azure/ai-services/openai/context/context) for more information. You can apply for access to Azure OpenAI by completing the form at <a href="https://aka.ms/oai/access" target="_blank">https://aka.ms/oai/access</a>. Open an issue on this repo to contact us if you have an issue.
+
+- The Azure Developer CLI [installed](/azure/developer/azure-developer-cli/install-azd) on your machine
+
+## Clone and initialize the Azure Developer CLI template
+
+
+
+1. For the steps ahead, clone and initialize the template.
+
+    ```bash
+    azd init --template openai-chat-your-own-data
+    ```
+    
+2. The `azd init` command prompts you for the following information:
+
+    * Environment name: This value is used as a prefix for all Azure resources created by Azure Developer CLI. The name must be unique across all Azure subscriptions and must be between 3 and 24 characters long. The name can contain numbers and lowercase letters only.
+
+## Use the template to deploy resources
+
+1. Sign-in to Azure:
+
+    ```bash
+    azd auth login
+    ```
+
+1. Provision and deploy the OpenAI resource to Azure:
+
+    ```bash
+    azd up
+    ```
+    
+    `azd` prompts you for the following information:
+    
+    * Subscription: The Azure subscription that your resources are deployed to.
+    * Location: The Azure region where your resources are deployed.
+    
+    > [!NOTE]
+    > The sample `azd` template uses the `gpt-35-turbo-16k` model. A recommended region for this template is East US, since different Azure regions support different OpenAI models. You can visit the [Azure OpenAI Service Models](/azure/ai-services/openai/concepts/models) support page for more details about model support by region.
+    
+    > [!NOTE]
+    > The provisioning process may take several minutes to complete. Wait for the task to finish before you proceed to the next steps.
+        
+1. Click the link `azd` outputs to navigate to the new resource group in the Azure portal. You should see the following top level resources:
+    
+    * An Azure OpenAI service with a deployed model
+    * An Azure Storage account you can use to upload your own data files
+    * An Azure AI Search service configured with the proper indexes and data sources
+
+## Upload data to the storage account
+
+`azd` provisioned all of the required resources for you to chat with your own data, but you still need to upload the data files you want to make available to your AI service.
+
+1. Navigate to the new storage account in the Azure portal.
+1. On the left navigation, select **Storage browser**.
+1. Select **Blob containers** and then navigate into the **File uploads** container.
+1. Click the **Upload** button at the top of the screen. 
+1. In the flyout menu that opens, upload _contoso_benefits_document_example.pdf_ file in the root `documents` folder of the example repo.
+ 
+> [!NOTE]
+> The search indexer is set to run every 5 minutes to index the data in the storage account. You can either wait a few minutes for the uploaded data to be indexed, or you can manually run the indexer from the search service page.
+
+## Connect or create an application
+
+After running the `azd` template and uploading your data, you're ready to start using Azure OpenAI on Your Data. See the [quickstart article](../use-your-data-quickstart.md) for code samples you can use to build your applications.

articles/ai-services/openai/includes/assistants-javascript.md

@@ -0,0 +1,166 @@
+---
+title: 'Quickstart: Use the OpenAI Service via the JavaScript SDK'
+titleSuffix: Azure OpenAI Service
+description: Walkthrough on how to get started with Azure OpenAI and make your first completions call with the JavaScript SDK. 
+manager: nitinme
+author: mrbullwinkle
+ms.author: mbullwin
+ms.service: azure-ai-openai
+ms.topic: include
+ms.date: 04/10/2024
+ms.custom: passwordless-js, devex-track-javascript
+---
+
+<a href="/javascript/api/@azure/openai-assistants" target="_blank">Reference documentation</a> | <a href="https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/openai/openai-assistants" target="_blank">Library source code</a> | <a href="https://www.npmjs.com/package/@azure/openai-assistants" target="_blank">Package (npm)</a> |
+
+## Prerequisites
+
+- An Azure subscription - <a href="https://azure.microsoft.com/free/cognitive-services" target="_blank">Create one for free</a>
+- Access granted to Azure OpenAI in the desired Azure subscription
+
+    Currently, access to this service is granted only by application. You can apply for access to Azure OpenAI by completing the form at <a href="https://aka.ms/oai/access" target="_blank">https://aka.ms/oai/access</a>. Open an issue on this repo to contact us if you have an issue.
+- <a href="https://nodejs.org/" target="_blank">Node.js LTS with TypeScript or ESM support.</a>
+- [Azure CLI](/cli/azure/install-azure-cli) used for passwordless authentication in a local development environment, create the necessary context by signing in with the Azure CLI. 
+- Azure OpenAI Assistants are currently available in Sweden Central, East US 2, and Australia East. For more information about model availability in those regions, see the [models guide](../concepts/models.md).
+- We recommend reviewing the [Responsible AI transparency note](/legal/cognitive-services/openai/transparency-note?context=%2Fazure%2Fai-services%2Fopenai%2Fcontext%2Fcontext&tabs=text) and other [Responsible AI resources](/legal/cognitive-services/openai/overview?context=%2Fazure%2Fai-services%2Fopenai%2Fcontext%2Fcontext) to familiarize yourself with the capabilities and limitations of the Azure OpenAI Service.
+- An Azure OpenAI resource with the `gpt-4 (1106-preview)` model deployed was used testing this example. 
+
+## Passwordless authentication is recommended
+
+For passwordless authentication, you need to 
+
+1. Use the `@azure/identity` package.
+1. Assign the `Cognitive Services User` role to your user account. This can be done in the Azure portal under **Access control (IAM)** > **Add role assignment**.
+1. Sign in with the Azure CLI such as `az login`.
+
+## Set up
+
+1. Install the OpenAI Assistants client library for JavaScript with:
+
+    ```console
+    npm install @azure/openai-assistants
+    ```
+
+2. For the **recommended** passwordless authentication:
+
+    ```console
+    npm install @azure/identity
+    ```
+
+    Or to use the service key connection:
+
+    ```console
+    npm install @azure/core-auth
+    ```
+
+## Retrieve key and endpoint
+
+To successfully make a call against the Azure OpenAI service, you'll need the following:
+
+|Variable name | Value |
+|--------------------------|-------------|
+| `ENDPOINT`               | This value can be found in the **Keys and Endpoint** section when examining your resource from the Azure portal. Alternatively, you can find the value in **Azure OpenAI Studio** > **Playground** > **View code**. An example endpoint is: `https://docs-test-001.openai.azure.com/`.|
+| `API-KEY` | This value can be found in the **Keys and Endpoint** section when examining your resource from the Azure portal. You can use either `KEY1` or `KEY2`.|
+| `DEPLOYMENT-NAME` | This value will correspond to the custom name you chose for your deployment when you deployed a model. This value can be found under **Resource Management** > **Model Deployments** in the Azure portal or alternatively under **Management** > **Deployments** in Azure OpenAI Studio.|
+
+Go to your resource in the Azure portal. The **Keys and Endpoint** can be found in the **Resource Management** section. Copy your endpoint and access key as you'll need both for authenticating your API calls. You can use either `KEY1` or `KEY2`. Always having two keys allows you to securely rotate and regenerate keys without causing a service disruption.
+
+:::image type="content" source="../media/quickstarts/endpoint.png" alt-text="Screenshot of the overview blade for an OpenAI Resource in the Azure portal with the endpoint & access keys location circled in red." lightbox="../media/quickstarts/endpoint.png":::
+
+Create and assign persistent environment variables for your key and endpoint.
+
+[!INCLUDE [environment-variables](environment-variables.md)]
+
+Add an additional environment variable for the deployment name: `AZURE_OPENAI_DEPLOYMENT_NAME`.
+
+Create and assign persistent environment variables for your key and endpoint.
+
+# [Command Line](#tab/command-line)
+
+```cmd
+setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME" 
+```
+
+# [PowerShell](#tab/powershell)
+
+```powershell
+[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_DEPLOYMENT_NAME', 'REPLACE_WITH_YOUR_DEPLOYMENT_NAME', 'User')
+```
+
+# [Bash](#tab/bash)
+
+```bash
+export AZURE_OPENAI_DEPLOYMENT_NAME="REPLACE_WITH_YOUR_DEPLOYMENT_NAME"
+```
+
+---
+
+## Create an assistant
+
+In our code we are going to specify the following values:
+
+| **Name** | **Description** |
+|:---|:---|
+| **Assistant name** | Your deployment name that is associated with a specific model. |
+| **Instructions** | Instructions are similar to system messages this is where you give the model guidance about how it should behave and any context it should reference when generating a response. You can describe the assistant's personality, tell it what it should and shouldn't answer, and tell it how to format responses. You can also provide examples of the steps it should take when answering responses. |
+| **Model** | This is the deployment name. |
+| **Code interpreter** | Code interpreter provides access to a sandboxed Python environment that can be used to allow the model to test and execute code. |
+
+### Tools
+
+An individual assistant can access up to 128 tools including `code interpreter`, as well as any custom tools you create via [functions](../how-to/assistant-functions.md).
+
+#### [TypeScript](#tab/typescript)
+
+Sign in to Azure with `az login` then create and run an assistant with the following **recommended** passwordless TypeScript module (index.ts):
+
+:::code language="typescript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/ts/src/index.ts" :::
+
+To use the service key for authentication, you can create and run an assistant with the following TypeScript module (index.ts):
+
+:::code language="typescript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/ts/src/index-using-password.ts" :::
+
+#### [JavaScript](#tab/javascript)
+
+Sign in to Azure with `az login` then create and run an assistant with the following **recommended** passwordless Javascript module (index.mjs):
+
+:::code language="javascript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/js/src/index.mjs" :::
+
+To use the service key for authentication, you can create and run an assistant with the following JavaScript module (index.mjs):
+
+:::code language="javascript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/js/src/index-using-password.mjs" :::
+
+
+--- 
+
+## Output
+
+```console
+Assistant created: {"id":"asst_zXaZ5usTjdD0JGcNViJM2M6N","createdAt":"2024-04-08T19:26:38.000Z","name":"Math Tutor","description":null,"model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"fileIds":[],"metadata":{}}
+Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}}
+Message created:  {"id":"msg_o0VkXnQj3juOXXRCnlZ686ff","createdAt":"2024-04-08T19:26:38.000Z","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","role":"user","content":[{"type":"text","text":{"value":"I need to solve the equation `3x + 11 = 14`. Can you help me?","annotations":[]},"imageFile":{}}],"assistantId":null,"runId":null,"fileIds":[],"metadata":{}}
+Created run
+Run created:  {"id":"run_P8CvlouB8V9ZWxYiiVdL0FND","object":"thread.run","status":"queued","model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"metadata":{},"usage":null,"assistantId":"asst_zXaZ5usTjdD0JGcNViJM2M6N","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","fileIds":[],"createdAt":"2024-04-08T19:26:39.000Z","expiresAt":"2024-04-08T19:36:39.000Z","startedAt":null,"completedAt":null,"cancelledAt":null,"failedAt":null}
+Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
+Message content: "Yes, of course! To solve the equation \\( 3x + 11 = 14 \\), we can follow these steps:\n\n1. Subtract 11 from both sides of the equation to isolate the term with x.\n2. Then, divide by 3 to find the value of x.\n\nLet me calculate that for you."
+Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?"
+```
+
+It is important to remember that while the code interpreter gives the model the capability to respond to more complex queries by converting the questions into code and running that code iteratively in JavaScript until it reaches a solution, you still need to validate the response to confirm that the model correctly translated your question into a valid representation in code.
+
+## Clean up resources
+
+If you want to clean up and remove an Azure OpenAI resource, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.
+
+- [Portal](../../multi-service-resource.md?pivots=azportal#clean-up-resources)
+- [Azure CLI](../../multi-service-resource.md?pivots=azcli#clean-up-resources)
+
+## Sample code
+
+* [Quickstart sample code](https://github.com/Azure-Samples/azure-typescript-e2e-apps/tree/main/quickstarts/azure-openai-assistants)
+
+## See also
+
+* Learn more about how to use Assistants with our [How-to guide on Assistants](../how-to/assistant.md).
+* [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants)
+

articles/ai-services/openai/includes/assistants-python.md

@@ -215,4 +215,4 @@ If you want to clean up and remove an Azure OpenAI resource, you can delete the
 * Learn more about how to use Assistants with our [How-to guide on Assistants](../how-to/assistant.md).
 * [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants)
 
--->
+

articles/ai-services/openai/includes/connect-your-data-studio.md

@@ -12,6 +12,9 @@ recommendations: false
 
 ## Add your data using Azure OpenAI Studio
 
+> [!TIP]
+> You can [use the Azure Developer CLI](../how-to/azure-developer-cli.md) to programmatically create the resources needed for Azure OpenAI On Your Data 
+
 Navigate to [Azure OpenAI Studio](https://oai.azure.com/) and sign-in with credentials that have access to your Azure OpenAI resource. During or after the sign-in workflow, select the appropriate directory, Azure subscription, and Azure OpenAI resource.
 
 1. Select the **Bring your own data** tile

articles/ai-services/openai/toc.yml

@@ -145,6 +145,8 @@ items:
         href: ./how-to/use-your-data-securely.md
       - name: Deploy and use web apps
         href: ./how-to/use-web-app.md
+      - name: Use the Azure Developer CLI
+        href: ./how-to/azure-developer-cli.md
   - name: Migrate to OpenAI Python v1.x
     href: ./how-to/migration.md
   - name: Models