docs: update readme

manekinekko · manekinekko · commit e77e25dcd1f1 · 2024-06-14T13:10:11.000+02:00
diff --git a/README.md b/README.md
@@ -7,7 +7,9 @@
 ![Node version](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
 [![License](https://img.shields.io/badge/License-MIT-pink?style=flat-square)](LICENSE)
 
-:star: Like and fork this sample to receive lastest changes and updates!
+Azure OpenAI Assistants allows you to create AI assistants tailored to your needs through custom instructions and augmented by advanced tools like code interpreter, and custom functions. In this article, we provide an in-depth walkthrough of getting started with the Assistants API.
+
+(Like and fork this sample to receive lastest changes and updates)
 
 [![Overview](https://img.shields.io/badge/Getting%20Started-blue?style=flat-square)](#overview)
 [![Get started](https://img.shields.io/badge/Get%20Started-blue?style=flat-square)](#get-started)
@@ -23,9 +25,15 @@
 
 This sample shows how to quickly get started with [OpenAI Assistant](https://learn.microsoft.com/azure/ai-services/openai/how-to/assistant) on Azure. The application is hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview) and [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript). You can use it as a starting point for building more complex Assistant and Agent applications.
 
-## Overview
+## Features
 
-Azure OpenAI Assistants allows you to create AI assistants tailored to your needs through custom instructions and augmented by advanced tools like code interpreter, and custom functions. In this article, we provide an in-depth walkthrough of getting started with the Assistants API.
+This project demonstrates how to build a simple Assistant application using Azure OpenAI Assistants. The Assistant can help you: 
+- Retrieve financial information, such as stock values.
+- Answer questions.
+- Send emails, 
+- Run custom functions.
+
+## Architecture Diagram
 
 <div align="center">
   <img src="./docs/architecture-diagram-assistant-javascript.png" alt="Screenshot showing the assistant app high level diagram" width="640px" />
@@ -37,13 +45,86 @@ This application is built around two main components:
 
 - A serverless API built with [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript) and using OpenAI JavaScript SDK. The code is located in the [`api`](./api/) folder.
 
-## Get started
+## Getting Started
+
+You have a few options for getting started with this template. The quickest way to get started is [GitHub Codespaces](#github-codespaces), since it will setup all the tools for you, but you can also [set it up locally](#local-environment). You can also use a [VS Code dev container](#vs-code-dev-containers)
+
+This template uses `gpt-35-turbo` version `1106`  which may not be available in all Azure regions. Check for [up-to-date region availability](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and select a region during deployment accordingly
+
+  * We recommend using `swedencentral`
+
+### GitHub Codespaces
 
-There are multiple ways to get started with this project.
+You can run this template virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:
 
-The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below.
+1. Open the template (this may take several minutes)
+    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/azure-openai-assistant-javascript?hide_repo_select=true&ref&quickstart=true)
+2. Open a terminal window
+3. Sign into your Azure account:
+
+    ```shell
+     azd auth login --use-device-code
+    ```
+4. Provision the Azure resources and deploy your code:
+
+    ```shell
+     azd up
+    ```
+5. Open a terminal and navigate to the root of the project, then run the API server first:
+
+    ```bash
+     npm install --prefix api
+     npm start --prefix api
+    ```
+
+6. Open another terminal and navigate to the root of the project, then run the webapp server:
+
+    ```bash
+     npm install
+     npm start
+    ```
+
+Open the URL `http://localhost:4280` in your browser to interact with the Assistant.
 
-### Use your local environment
+### VS Code Dev Containers
+
+A related option is VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
+
+1. Start Docker Desktop (install it if not already installed)
+2. Open the project:
+    [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/azure-openai-assistant-javascript)
+3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
+4. Sign into your Azure account:
+
+    ```shell
+     azd auth login
+    ```
+4. Provision the Azure resources and deploy your code:
+
+    ```shell
+     azd up
+    ```
+5. Open a terminal and navigate to the root of the project, then run the API server first:
+
+    ```bash
+     npm install --prefix api
+     npm start --prefix api
+    ```
+6. Open another terminal and navigate to the root of the project, then run the webapp server:
+
+    ```bash
+     npm install
+     npm start
+    ```
+8. Configure a CI/CD pipeline:
+
+    ```shell
+    azd pipeline config
+    ```
+
+### Local Environment
+
+#### Prerequisites
 
 You need to install following tools to work on your local machine:
 
@@ -55,30 +136,47 @@ You need to install following tools to work on your local machine:
   - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell.
   - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.
 - (Optional - if you are not using SWA CLI) [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=macos%2Cisolated-process%2Cnode-v4%2Cpython-v2%2Chttp-trigger%2Ccontainer-apps&pivots=programming-language-javascript) _(should be installed automatically with NPM, only install manually if the API fails to start)_
+- This template uses `gpt-35-turbo` version `1106` which may not be available in all Azure regions. Check for [up-to-date region availability](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and select a region during deployment accordingly
+  * We recommend using `swedencentral`
 
 Then you can get the project code:
 
 1. [**Fork**](https://github.com/Azure-Samples/azure-openai-assistant-javascript/fork) the project to create your own copy of this repository.
 2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository.
 3. Open a terminal and run this command to clone the repo: <code> git clone &lt;your-repo-url&gt; </code>
 
-### Use GitHub Codespaces
+#### Quickstart (with Azure OpenAI models)
 
-You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:
+1. Bring down the template code:
 
-[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&label=GitHub+Codespaces&message=Open&color=blue&logo=github)](https://codespaces.new/Azure-Samples/azure-openai-assistant-javascript?hide_repo_select=true&ref&quickstart=true)
+    ```shell
+    azd init --template azure-openai-assistant-javascript
+    ```
 
-### Use a VS Code dev container
+    This will perform a git clone
 
-A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+2. Sign into your Azure account:
 
-You will also need to have [Docker](https://www.docker.com/products/docker-desktop) installed on your machine to run the container.
+    ```shell
+     azd auth login
+    ```
 
-[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/azure-openai-assistant-javascript)
+3. Install all dependencies:
 
-## Run the sample locally (with Azure OpenAI models)
+    ```bash
+     npm install
+     npm install --prefix api
+    ```
+4. Provision and deploy the project to Azure:
 
-First you need to provision the Azure resources needed to run the sample. Follow the instructions in the [Deploy the sample to Azure](#deploy-the-sample-to-azure) section to deploy the sample to Azure, then you'll be able to run the sample locally using the deployed Azure resources.
+    ```shell
+    azd up
+    ```
+4. Configure a CI/CD pipeline:
+
+    ```shell
+    azd pipeline config
+    ```
 
 Once your deployment is complete, you should see a `.env` file in the `api` folder. This file contains the environment variables needed to run the application using Azure resources.
 
@@ -94,51 +192,48 @@ EMAIL_SENDER_APP_PASSWORD="foobar"
 
 **Important: Please follow [this guide](https://support.microsoft.com/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9) to generate an Application Password if you are using MFA.**
 
+#### Local Development
+
 To run the sample, run the following commands, which will start the web app, and the API locally.
 
 1. Open a terminal and navigate to the root of the project, then run the API server first:
 
-```bash
-npm install --prefix api
-npm start --prefix api
-```
-
+    ```bash
+     npm start --prefix api
+    ```
 2. Open another terminal and navigate to the root of the project, then run the webapp server:
 
-```bash
-npm install
-npm start
-```
+    ```bash
+     npm start
+    ```
 
 Open the URL `http://localhost:4280` in your browser to interact with the Assistant.
 
-### Deploy the sample to Azure
+## Guidance
 
-#### Azure prerequisites
+### Region Availability
 
-- **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free) to get free Azure credits to get started. If you're a student, you can also get free credits with [Azure for Students](https://aka.ms/azureforstudents).
-- **Azure subscription with access enabled for the Azure OpenAI Service**. You can request access with [this form](https://aka.ms/oaiapply).
+This template uses `gpt-35-turbo` version `1106` which may not be available in all Azure regions. Check for [up-to-date region availability](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and select a region during deployment accordingly
+  * We recommend using `swedencentral`
 
-#### Deploy the sample
+### Costs
 
-1. Open a terminal and navigate to the root of the project.
-2. Authenticate with Azure by running `azd auth login`.
-3. Run `azd up` to deploy the application to Azure. This will provision Azure resources, deploy this sample.
-   - You will be prompted to select a base location for the resources.
-   - By default, the OpenAI resource will be deployed to `swedencentral`. You can set a different location with `azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION <location>`. Currently only a short list of locations is accepted. **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](https://learn.microsoft.com/azure/ai-services/openai/concepts/models).**
+Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage.
+However, you can use the [Azure pricing calculator](https://azure.com/e/bf51ef20b57a4da08e47511938ad5415) for the resources below to get an estimate.
 
-The deployment process will take a few minutes. Once it's done, you'll see the URL of the web app in the terminal.
+- Azure Container Apps: Consumption plan, Free for the first 2M executions. Pricing per execution and memory used. [Pricing](https://azure.microsoft.com/en-us/pricing/details/container-apps/)
+- Azure OpenAI: Standard tier, GPT and Ada models. Pricing per 1K tokens used, and at least 1K tokens are used per question. [Pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/)
 
-You can now open the web app in your browser and start chatting with the bot.
+> [!WARNING]
+> To avoid unnecessary costs, remember to take down your app if it's no longer in use, either by deleting the resource group in the Portal or running `azd down --purge`.
 
-#### Clean up
+### Security
 
-To clean up all the Azure resources created by this sample:
+> [!NOTE]
+> When implementing this template please specify whether the template uses Managed Identity or Key Vault
 
-1. Run `azd down --purge`
-2. When asked if you are sure you want to continue, enter `y`
+This template has either [Managed Identity](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) or Key Vault built in to eliminate the need for developers to manage these credentials. Applications can use managed identities to obtain Microsoft Entra tokens without having to manage any credentials. Additionally, we have added a [GitHub Action tool](https://github.com/microsoft/security-devops-action) that scans the infrastructure-as-code files and generates a report containing any detected issues. To ensure best practices in your repo we recommend anyone creating solutions based on our templates ensure that the [Github secret scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning) setting is enabled in your repos.
 
-The resource group and all the resources will be deleted.
 
 ## Resources
 
