|
| 1 | +--- |
| 2 | +title: 'Quickstart: Use the OpenAI Service via the JavaScript SDK' |
| 3 | +titleSuffix: Azure OpenAI Service |
| 4 | +description: Walkthrough on how to get started with Azure OpenAI and make your first completions call with the JavaScript SDK. |
| 5 | +manager: nitinme |
| 6 | +author: mrbullwinkle |
| 7 | +ms.author: mbullwin |
| 8 | +ms.service: azure-ai-openai |
| 9 | +ms.topic: include |
| 10 | +ms.date: 04/10/2024 |
| 11 | +ms.custom: passwordless-js, devex-track-javascript |
| 12 | +--- |
| 13 | + |
| 14 | +<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> | |
| 15 | + |
| 16 | +## Prerequisites |
| 17 | + |
| 18 | +- An Azure subscription - <a href="https://azure.microsoft.com/free/cognitive-services" target="_blank">Create one for free</a> |
| 19 | +- Access granted to Azure OpenAI in the desired Azure subscription |
| 20 | + |
| 21 | + 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. |
| 22 | +- <a href="https://nodejs.org/" target="_blank">Node.js LTS with TypeScript or ESM support.</a> |
| 23 | +- [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. |
| 24 | +- 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). |
| 25 | +- 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. |
| 26 | +- An Azure OpenAI resource with the `gpt-4 (1106-preview)` model deployed was used testing this example. |
| 27 | + |
| 28 | +## Passwordless authentication is recommended |
| 29 | + |
| 30 | +For passwordless authentication, you need to |
| 31 | + |
| 32 | +1. Use the `@azure/identity` package. |
| 33 | +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**. |
| 34 | +1. Sign in with the Azure CLI such as `az login`. |
| 35 | + |
| 36 | +## Set up |
| 37 | + |
| 38 | +1. Install the OpenAI Assistants client library for JavaScript with: |
| 39 | + |
| 40 | + ```console |
| 41 | + npm install @azure/openai-assistants |
| 42 | + ``` |
| 43 | + |
| 44 | +2. For the **recommended** passwordless authentication: |
| 45 | + |
| 46 | + ```console |
| 47 | + npm install @azure/identity |
| 48 | + ``` |
| 49 | + |
| 50 | + Or to use the service key connection: |
| 51 | + |
| 52 | + ```console |
| 53 | + npm install @azure/core-auth |
| 54 | + ``` |
| 55 | + |
| 56 | +## Retrieve key and endpoint |
| 57 | + |
| 58 | +To successfully make a call against the Azure OpenAI service, you'll need the following: |
| 59 | + |
| 60 | +|Variable name | Value | |
| 61 | +|--------------------------|-------------| |
| 62 | +| `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/`.| |
| 63 | +| `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`.| |
| 64 | +| `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.| |
| 65 | + |
| 66 | +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. |
| 67 | + |
| 68 | +:::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"::: |
| 69 | + |
| 70 | +Create and assign persistent environment variables for your key and endpoint. |
| 71 | + |
| 72 | +[!INCLUDE [environment-variables](environment-variables.md)] |
| 73 | + |
| 74 | +Add an additional environment variable for the deployment name: `AZURE_OPENAI_DEPLOYMENT_NAME`. |
| 75 | + |
| 76 | +Create and assign persistent environment variables for your key and endpoint. |
| 77 | + |
| 78 | +# [Command Line](#tab/command-line) |
| 79 | + |
| 80 | +```cmd |
| 81 | +setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME" |
| 82 | +``` |
| 83 | + |
| 84 | +# [PowerShell](#tab/powershell) |
| 85 | + |
| 86 | +```powershell |
| 87 | +[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_DEPLOYMENT_NAME', 'REPLACE_WITH_YOUR_DEPLOYMENT_NAME', 'User') |
| 88 | +``` |
| 89 | + |
| 90 | +# [Bash](#tab/bash) |
| 91 | + |
| 92 | +```bash |
| 93 | +export AZURE_OPENAI_DEPLOYMENT_NAME="REPLACE_WITH_YOUR_DEPLOYMENT_NAME" |
| 94 | +``` |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## Create an assistant |
| 99 | + |
| 100 | +In our code we are going to specify the following values: |
| 101 | + |
| 102 | +| **Name** | **Description** | |
| 103 | +|:---|:---| |
| 104 | +| **Assistant name** | Your deployment name that is associated with a specific model. | |
| 105 | +| **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. | |
| 106 | +| **Model** | This is the deployment name. | |
| 107 | +| **Code interpreter** | Code interpreter provides access to a sandboxed Python environment that can be used to allow the model to test and execute code. | |
| 108 | + |
| 109 | +### Tools |
| 110 | + |
| 111 | +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). |
| 112 | + |
| 113 | +#### [TypeScript](#tab/typescript) |
| 114 | + |
| 115 | +Sign in to Azure with `az login` then create and run an assistant with the following **recommended** passwordless TypeScript module (index.ts): |
| 116 | + |
| 117 | +:::code language="typescript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/ts/src/index.ts" ::: |
| 118 | + |
| 119 | +To use the service key for authentication, you can create and run an assistant with the following TypeScript module (index.ts): |
| 120 | + |
| 121 | +:::code language="typescript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/ts/src/index-using-password.ts" ::: |
| 122 | + |
| 123 | +#### [JavaScript](#tab/javascript) |
| 124 | + |
| 125 | +Sign in to Azure with `az login` then create and run an assistant with the following **recommended** passwordless Javascript module (index.mjs): |
| 126 | + |
| 127 | +:::code language="javascript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/js/src/index.mjs" ::: |
| 128 | + |
| 129 | +To use the service key for authentication, you can create and run an assistant with the following JavaScript module (index.mjs): |
| 130 | + |
| 131 | +:::code language="javascript" source="~/azure-typescript-e2e-apps/quickstarts/azure-openai-assistants/js/src/index-using-password.mjs" ::: |
| 132 | + |
| 133 | + |
| 134 | +--- |
| 135 | + |
| 136 | +## Output |
| 137 | + |
| 138 | +```console |
| 139 | +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":{}} |
| 140 | +Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}} |
| 141 | +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":{}} |
| 142 | +Created run |
| 143 | +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} |
| 144 | +Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)." |
| 145 | +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." |
| 146 | +Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?" |
| 147 | +``` |
| 148 | + |
| 149 | +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. |
| 150 | + |
| 151 | +## Clean up resources |
| 152 | + |
| 153 | +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. |
| 154 | + |
| 155 | +- [Portal](../../multi-service-resource.md?pivots=azportal#clean-up-resources) |
| 156 | +- [Azure CLI](../../multi-service-resource.md?pivots=azcli#clean-up-resources) |
| 157 | + |
| 158 | +## Sample code |
| 159 | + |
| 160 | +* [Quickstart sample code](https://github.com/Azure-Samples/azure-typescript-e2e-apps/tree/main/quickstarts/azure-openai-assistants) |
| 161 | + |
| 162 | +## See also |
| 163 | + |
| 164 | +* Learn more about how to use Assistants with our [How-to guide on Assistants](../how-to/assistant.md). |
| 165 | +* [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants) |
| 166 | + |
0 commit comments