Merge pull request #226175 from eric-urban/eur/openai-qs

OpenAI QS refresh

Author: v-regandowner

articles/cognitive-services/openai/how-to/create-resource.md

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: openai
 ms.topic: how-to
-ms.date: 06/30/2022
+ms.date: 02/02/2023
 zone_pivot_groups: openai-create-resource
 author: ChrisHMSFT
 ms.author: chrhoder
@@ -16,17 +16,17 @@ recommendations: false
 
 # Create a resource and deploy a model using Azure OpenAI
 
-Use this article to get started with Azure OpenAI with step-by-step instructions to create a resource and deploy a model. While the steps for resource creation and model deployment can be completed in a few minutes, the actual deployment process itself can take more than hour. It is recommended to create your resource, start your deployment, and then check back in on your deployment later rather than actively waiting for the deployment to complete.
+Use this article to get started with Azure OpenAI with step-by-step instructions to create a resource and deploy a model. While the steps for resource creation and model deployment can be completed in a few minutes, the actual deployment process itself can take more than hour. You can create your resource, start your deployment, and then check back in on your deployment later rather than actively waiting for the deployment to complete.
 
 ::: zone pivot="web-portal"
 
-[!INCLUDE [Studio quickstart](../includes/create-resource-portal.md)]
+[!INCLUDE [Studio resource](../includes/create-resource-portal.md)]
 
 ::: zone-end
 
 ::: zone pivot="cli"
 
-[!INCLUDE [Python SDK quickstart](../includes/create-resource-cli.md)]
+[!INCLUDE [Azure CLI resource](../includes/create-resource-cli.md)]
 
 ::: zone-end
 

articles/cognitive-services/openai/includes/create-resource-cli.md

@@ -9,7 +9,6 @@ ms.subservice: openai
 ms.topic: include
 ms.date: 6/30/2022
 keywords: 
-
 ---
 
 ## Prerequisites

articles/cognitive-services/openai/includes/create-resource-portal.md

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: openai
 ms.topic: include
-ms.date: 06/30/2022
+ms.date: 02/02/2023
 keywords: 
 ---
 
@@ -22,7 +22,7 @@ keywords:
 
 Resources in Azure can be created several different ways:
 
-- Within the Azure portal
+- Within the [Azure portal](https://portal.azure.com/?microsoft_azure_marketplace_ItemHideKey=microsoft_openai_tip#create/Microsoft.CognitiveServicesOpenAI)
 - Using the REST APIs, Azure CLI, PowerShell or client libraries
 - Via ARM templates
 
@@ -43,14 +43,21 @@ This guide walks you through the Azure portal creation experience.
 
 ## Deploy a model
 
-Before you can generate text or inference, you need to deploy a model. This is done by selecting **create new deployment** on the **deployments** page. From here, you can select from one of our many available models. For getting started, we recommend `text-davinci-002` for users in South Central and `text-davinci-001` for users in West Europe (text-davinci-002 is not available in this region). You can do this in the Azure OpenAI Studio.
+Before you can generate text or inference, you need to deploy a model. You can select from one of several available models in the Azure OpenAI Studio.
 
-1. Go to the [Azure OpenAI Studio](https://oai.azure.com)
+Davinci is the most capable model family and can perform any task the other models can perform and often with less instruction. For applications requiring a lot of understanding of the content, like summarization for a specific audience and creative content generation, Davinci is going to produce the best results.
 
-1. Login with the resource you want to use
+To deploy a model, follow these steps:
 
-1. Select the **Go to Deployments** button under **Manage deployments in your resource** to navigate to the **Deployments** page
+1. Sign in to the [Azure OpenAI Studio](https://oai.azure.com).
+1. Select the subscription and OpenAI resource to work with. 
+1. Select **Manage deployments in your resource** > **Go to Deployments** under **Manage your deployments and models**. You might first need to scroll down on the landing page.
 
     :::image type="content" source="../media/create-resource/deployment.png" alt-text="Screenshot of the Azure OpenAI Studio page with the 'Go to Deployments' button highlighted." lightbox="../media/create-resource/deployment.png":::
 
-1. Create a new deployment called `text-davinci-002` and choose the `text-davinci-002` model from the drop-down.
+1. Select **Create new deployment** from the **Management** > **Deployments** page.
+1. Select a model from the drop-down. For getting started in the East US region, we recommend the `text-davinci-003` model. In other regions you should start with the `text-davinci-002` model. Some models are not available in all regions. For a list of available models per region, see [Model Summary table and region availability](../concepts/models.md#model-summary-table-and-region-availability).
+1. Enter a model name to help you identify the model. Choose a name carefully. The model name will be used as the deployment name via OpenAI client libraries and API. 
+1. Select **Create** to deploy the model. 
+
+The deployments table displays a new entry that corresponds to this newly created model. Your deployment status will move to succeeded when the deployment is complete and ready for use.

articles/cognitive-services/openai/includes/python.md

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: openai
 ms.topic: include
-ms.date: 12/14/2022
+ms.date: 02/02/2023
 keywords: 
 ---
 
@@ -21,18 +21,18 @@ keywords:
     Currently, access to this service is granted only by application. You can apply for access to the Azure OpenAI service 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://www.python.org/" target="_blank">Python 3.7.1 or later version</a>
 - The following Python libraries: os, requests, json
-- An Azure OpenAI Service resource with a model deployed. If you don't have a resource/model the process is documented in our [resource deployment guide](../how-to/create-resource.md)
+- An Azure OpenAI Service resource with a model deployed. For more information about model deployment, see the [resource deployment guide](../how-to/create-resource.md).
 
 ## Set up
 
-1. Install the client library. You can install the client library with:
+Install the OpenAI Python client library with:
 
 ```console
 pip install openai
 ```
 
 > [!NOTE]
-> This library is maintained by OpenAI and is currently a preview release. Use the [version.py commit history](https://github.com/openai/openai-python/commits/main/openai/version.py) to track the latest updates to the library.
+> This library is maintained by OpenAI and is currently in preview. Refer to the [release history](https://github.com/openai/openai-python/releases) or the [version.py commit history](https://github.com/openai/openai-python/commits/main/openai/version.py) to track the latest updates to the library.
 
 ## Retrieve key and endpoint
 
@@ -42,7 +42,7 @@ To successfully make a call against the Azure OpenAI service, you'll need the fo
 |--------------------------|-------------|
 | `ENDPOINT`               | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. Alternatively, you can find the value in the **Azure OpenAI Studio** > **Playground** > **Code View**. An example endpoint is: `https://docs-test-001.openai.azure.com/`.|
 | `API-KEY` | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. You can use either `KEY1` or `KEY2`.|
-| `DEPLOYMENT-NAME` | This will correspond to the custom name you chose for your deployment when you deployed a model. This value can be found under **Resource Management** > **Deployments** in the Azure portal or alternatively under **Management** > **Deployments** in Azure OpenAI Studio.|
+| `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** > **Deployments** in the Azure portal or alternatively under **Management** > **Deployments** in Azure OpenAI Studio.|
 
 Go to your resource in the Azure portal. The **Endpoint and Keys** 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.
 
@@ -52,7 +52,7 @@ Go to your resource in the Azure portal. The **Endpoint and Keys** can be found
 
 1. Create a new Python file called quickstart.py. Then open it up in your preferred editor or IDE.
 
-2. Replace the contents of quickstart.py with the following code. Modify the code to add your key, endpoint, and deployment name:
+2. Replace the contents of quickstart.py with the following code. Modify the code to add your key, endpoint, and deployment name: 
 
     ```python
     import os
@@ -65,27 +65,29 @@ Go to your resource in the Azure portal. The **Endpoint and Keys** can be found
     openai.api_type = 'azure'
     openai.api_version = '2022-12-01' # this may change in the future
 
-    deployment_id='REPLACE_WITH_YOUR_DEPLOYMENT_NAME' #This will correspond to the custom name you chose for your deployment when you deployed a model. 
+    deployment_name='REPLACE_WITH_YOUR_DEPLOYMENT_NAME' #This will correspond to the custom name you chose for your deployment when you deployed a model. 
 
     # Send a completion call to generate an answer
     print('Sending a test completion job')
     start_phrase = 'Write a tagline for an ice cream shop. '
-    response = openai.Completion.create(engine=deployment_id, prompt=start_phrase, max_tokens=10)
+    response = openai.Completion.create(engine=deployment_name, prompt=start_phrase, max_tokens=10)
     text = response['choices'][0]['text'].replace('\n', '').replace(' .', '.').strip()
     print(start_phrase+text)
     ```
 
-> [!IMPORTANT]
-> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../key-vault/general/overview.md). See the Cognitive Services [security](../../cognitive-services-security.md) article for more information.
+    > [!IMPORTANT]
+    > Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../key-vault/general/overview.md). See the Cognitive Services [security](../../cognitive-services-security.md) article for more information.
 
-1. Run the application with the `python` command on your quickstart file
+1. Run the application with the `python` command on your quickstart file:
 
     ```console
     python quickstart.py
     ```
 
 ## Output
 
+The output will include response text following the `Write a tagline for an ice cream shop.` prompt. The Azure OpenAI Service returned `The coldest ice cream in town!` in this example.
+
 ```console
 Sending a test completion job
 Write a tagline for an ice cream shop. The coldest ice cream in town!
@@ -95,7 +97,7 @@ Run the code a few more times to see what other types of responses you get as th
 
 ### Understanding your results
 
-Since our example of `Write a tagline for an ice cream shop.` provides very little context, it's normal for the model to not always return expected results. You can adjust the maximum number of tokens if the response seems unexpected or truncated.
+Since our example of `Write a tagline for an ice cream shop.` provides little context, it's normal for the model to not always return expected results. You can adjust the maximum number of tokens if the response seems unexpected or truncated.
 
 The Azure OpenAI Service also performs content moderation on the prompt inputs and generated outputs. The prompts or responses may be filtered if harmful content is detected. For more information, see the [content filter](../concepts/content-filter.md) article.
 

articles/cognitive-services/openai/includes/rest.md

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: openai
 ms.topic: include
-ms.date: 12/14/2022
+ms.date: 02/02/2023
 keywords: 
 ---
 
@@ -19,7 +19,7 @@ keywords:
     Currently, access to this service is granted only by application. You can apply for access to the Azure OpenAI service 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://www.python.org/" target="_blank">Python 3.7.1 or later version</a>
 - The following Python libraries: os, requests, json
-- An Azure OpenAI Service resource with a model deployed. If you don't have a resource/model the process is documented in our [resource deployment guide](../how-to/create-resource.md)
+- An Azure OpenAI Service resource with a model deployed. For more information about model deployment, see the [resource deployment guide](../how-to/create-resource.md).
 
 ## Retrieve key and endpoint
 
@@ -29,7 +29,7 @@ To successfully make a call against the Azure OpenAI service, you'll need the fo
 |--------------------------|-------------|
 | `ENDPOINT`               | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. Alternatively, you can find the value in the **Azure OpenAI Studio** > **Playground** > **Code View**. An example endpoint is: `https://docs-test-001.openai.azure.com/`.|
 | `API-KEY` | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. You can use either `KEY1` or `KEY2`.|
-| `DEPLOYMENT-NAME` | This will correspond to the custom name you chose for your deployment when you deployed a model. This value can be found under **Resource Management** > **Deployments** in the Azure portal or alternatively under **Management** > **Deployments** in Azure OpenAI Studio.|
+| `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** > **Deployments** in the Azure portal or alternatively under **Management** > **Deployments** in Azure OpenAI Studio.|
 
 Go to your resource in the Azure portal. The **Endpoint and Keys** 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.
 
@@ -46,19 +46,19 @@ Create a new Python file called quickstart.py. Then open it up in your preferred
     import requests
     import json
 
-    apiKey = "REPLACE_WITH_YOUR_API_KEY_HERE"
+    api_key = "REPLACE_WITH_YOUR_API_KEY_HERE"
     base_url = "REPLACE_WITH_YOUR_ENDPOINT_HERE"
-    deploymentName ="REPLACE_WITH_YOUR_DEPLOYMENT_NAME_HERE"
+    deployment_name ="REPLACE_WITH_YOUR_DEPLOYMENT_NAME_HERE"
 
-    url = base_url + "/openai/deployments/" + deploymentName + "/completions?api-version=2022-12-01"
+    url = base_url + "/openai/deployments/" + deployment_name + "/completions?api-version=2022-12-01"
     prompt = "Once upon a time"
     payload = {        
         "prompt":prompt
         }
 
     r = requests.post(url, 
           headers={
-            "api-key": apiKey,
+            "api-key": api_key,
             "Content-Type": "application/json"
           },
           json = payload
@@ -70,10 +70,10 @@ Create a new Python file called quickstart.py. Then open it up in your preferred
     print(formatted_response)
     ```
 
-> [!IMPORTANT]
-> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials. For example, [Azure Key Vault](../../../key-vault/general/overview.md).
+    > [!IMPORTANT]
+    > Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials. For example, [Azure Key Vault](../../../key-vault/general/overview.md).
 
-1. Run the application with the `python` command on your quickstart file
+1. Run the application with the `python` command on your quickstart file:
 
     ```console
     python quickstart.py
@@ -84,20 +84,25 @@ Create a new Python file called quickstart.py. Then open it up in your preferred
 The output from the completions API will look as follows.
 
 ```json
-  {
-    "id": "id of your call",
+{
+    "id": "ID of your call",
     "object": "text_completion",
-    "created": 1589478378,
-    "model": "model used",
+    "created": 1675444965,
+    "model": "text-davinci-002",
     "choices": [
         {
-        "text": " there was a girl who",
-        "index": 0,
-        "logprobs": null,
-        "finish_reason": "length"
+            "text": " there lived in a little village a woman who was known as the meanest",
+            "index": 0,
+            "finish_reason": "length",
+            "logprobs": null
         }
-    ]
+    ],
+    "usage": {
+        "completion_tokens": 16,
+        "prompt_tokens": 3,
+        "total_tokens": 19
     }
+}
 ```
 
 The Azure OpenAI Service also performs content moderation on the prompt inputs and generated outputs. The prompts or responses may be filtered if harmful content is detected. For more information, see the [content filter](../concepts/content-filter.md) article.