Added text-davinci-002 & code-davinci-002, clarified terminology, naming convention, and other model-related language.

Author: DenKenMSFT

articles/cognitive-services/openai/concepts/models.md

@@ -1,7 +1,7 @@
 ---
-title: Azure OpenAI Models
+title: Azure OpenAI models
 titleSuffix: Azure OpenAI
-description: Learn about the different AI models that are available. 
+description: Learn about the different models that are available in Azure OpenAI. 
 ms.service: cognitive-services
 ms.topic: conceptual 
 ms.date: 06/24/2022
@@ -13,41 +13,58 @@ recommendations: false
 keywords: 
 ---
 
-# Azure OpenAI Models
+# Azure OpenAI models
 
-The service provides access to many different models. Models describe a family of models and are broken out as follows:
+The service provides access to many different models, grouped by family and capability. A model family typically associates models by their intended task. The following table describes model families currently available in Azure OpenAI.
 
-|Modes | Description|
+| Model family | Description |
 |--|--|
-| GPT-3 series | A set of GPT-3 models that can understand and generate natural language |
-| Codex Series | A set of models that can understand and generate code, including translating natural language to code |
-| Embeddings Series | An embedding is a special format of data representation that can be easily utilized by machine learning models and algorithms. The embedding is an information dense representation of the semantic meaning of a piece of text. Currently we offer three families of embedding models for different functionalities: text search, text similarity and code search |
+| [GPT-3](#gpt-3-models) | A series of models that can understand and generate natural language. |
+| [Codex](#codex-models) | A series of models that can understand and generate code, including translating natural language to code. |
+| [Embeddings](#embedding-models) | A set of models that can understand and use embeddings. An embedding is a special format of data representation that can be easily utilized by machine learning models and algorithms. The embedding is an information dense representation of the semantic meaning of a piece of text. Currently, we offer three families of Embeddings models for different functionalities: text search, text similarity, and code search. |
+
+## Model capabilities
+
+Each model family has a series of models that are further distinguished by capability. These capabilities are typically identified by names, and the alphabetical order of these names generally signifies the relative capability and cost of that model within a given model family. For example, GPT-3 models use names such as Ada, Babbage, Curie, and Davinci to indicate relative capability and cost. Davinci is more capable (at a higher cost) than Curie, which in turn is more capable (at a higher cost) than Babbage, and so on.
+
+> [!NOTE]
+> Any task that can be performed by a less capable model like Ada can be performed by a more capable model like Curie or Davinci.
 
 ## Naming convention
 
-Azure OpenAI's models follow a standard naming convention: `{task}-{model name}-{version #}`. For example, our most powerful natural language model is called `text-davinci-001` and a Codex series model would look like `code-cushman-001`.
+Azure OpenAI's model names typically correspond to the following standard naming convention:
 
-> Older versions of the GPT-3 models are available as `ada`, `babbage`, `curie`, `davinci` and do not follow these conventions. These models are primarily intended to be used for fine-tuning and search.
+`{family}-{capability}[-{input-type}]-{identifier}`
+
+| Element | Description |
+| --- | --- |
+| `{family}` | The model family of the model. For example, [GPT-3 models](#gpt-3-models) uses `text`, while [Codex models](#codex-models) use `code`.|
+| `{capability}` | The relative capability of the model. For example, GPT-3 models include `ada`, `babbage`, `curie`, and `davinci`.|
+| `{input-type}` | ([Embeddings models](#embeddings-models) only) The input type of the embedding supported by the model. For example, text search embedding models include `doc` and `query`.|
+| `{identifier}` | The version identifier of the model. |
+
+For example, most powerful GPT-3 model is called `text-davinci-002`, while our most powerful Codex model is called `code-davinci-002`.
+
+> Older versions of the GPT-3 models are available, named `ada`, `babbage`, `curie`, and `davinci`. These older models do not follow the standard naming conventions, and they are primarily intended for fine tuning. For more information, see [Learn how to customize a model for your application](../how-to/fine-tuning.md).
 
 ## Finding what models are available
 
 You can easily see the models you have available for both inference and fine-tuning in your resource by using the [Models API](../reference.md#models).
 
+## GPT-3 models
 
-## GPT-3 Series
-
-The GPT-3 models can understand and generate natural language. The service offers four model types with different levels of power suitable for different tasks. Davinci is the most capable model, and Ada is the fastest. Going forward these models are named with the following convention: `text-{model name}-XXX` where `XXX` refers to a numerical value for different versions of the model. Currently the latest versions are:
+The GPT-3 models can understand and generate natural language. The service offers four model capabilities, each with different levels of power and speed suitable for different tasks. Davinci is the most capable model, while Ada is the fastest. The following list represents the latest versions of GPT-3 models, ordered by increasing capability.
 
-- text-ada-001
-- text-babbage-001
-- text-curie-001
-- text-davinci-001
+- `text-ada-001`
+- `text-babbage-001`
+- `text-curie-001`
+- `text-davinci-002`
 
-While Davinci is the most capable, the other models provide significant speed advantages. Our recommendation is for users to start with Davinci while experimenting since it will produce the best results and validate the value our service can provide. Once you have a prototype working, you can then optimize your model choice with the best latency - performance tradeoff for your application.
+While Davinci is the most capable, the other models provide significant speed advantages. Our recommendation is for users to start with Davinci while experimenting, because it will produce the best results and validate the value our service can provide. Once you have a prototype working, you can then optimize your model choice with the best latency/performance balance for your application.
 
-### Davinci
+### <a id="gpt-3-davinci"></a>Davinci
 
-Davinci is the most capable model and can perform any task the other models can perform and often with less instruction. For applications requiring deep understanding of the content, like summarization for a specific audience and creative content generation, Davinci is going to produce the best results. These increased capabilities require more compute resources, so Davinci costs more and isn't as fast as the other models.
+Davinci is the most capable model and can perform any task the other models can perform, often with less instruction. For applications requiring deep understanding of the content, like summarization for a specific audience and creative content generation, Davinci produces the best results. These increased capabilities require more compute resources, so Davinci costs more and isn't as fast as the other models.
 
 Another area where Davinci excels is in understanding the intent of text. Davinci is excellent at solving many kinds of logic problems and explaining the motives of characters. Davinci has been able to solve some of the most challenging AI problems involving cause and effect.
 
@@ -61,7 +78,7 @@ Curie is powerful, yet fast. While Davinci is stronger when it comes to analyzin
 
 ### Babbage
 
-Babbage can perform straightforward tasks like simple classification. It’s also capable when it comes to semantic search ranking how well documents match up with search queries.
+Babbage can perform straightforward tasks like simple classification. It’s also capable when it comes to semantic search,  ranking how well documents match up with search queries.
 
 **Use for**: Moderate classification, semantic search classification
 
@@ -71,58 +88,65 @@ Ada is usually the fastest model and can perform tasks like parsing text, addres
 
 **Use For** Parsing text, simple classification, address correction, keywords
 
-> [!NOTE]
-> Any task performed by a faster model like Ada can be performed by a more powerful model like Curie or Davinci.
-
-## Codex Series
+## Codex models
 
 The Codex models are descendants of our base GPT-3 models that can understand and generate code. Their training data contains both natural language and billions of lines of public code from GitHub.
 
-They’re most capable in Python and proficient in over a dozen languages, including C#, JavaScript, Go, Perl, PHP, Ruby, Swift, TypeScript, SQL, and even Shell.
+They’re most capable in Python and proficient in over a dozen languages, including C#, JavaScript, Go, Perl, PHP, Ruby, Swift, TypeScript, SQL, and even Shell. The following list represents the latest versions of Codex models, ordered by increasing capability.
+
+- `code-cushman-001`
+- `code-davinci-002`
+
+### <a id="codex-davinci"></a>Davinci
+
+Similar to GPT-3, Davinci is the most capable Codex model and can perform any task the other models can perform, often with less instruction. For applications requiring deep understanding of the content, like summarization for a specific audience and creative content generation, Davinci produces the best results. These increased capabilities require more compute resources, so Davinci costs more and isn't as fast as the other models.
+
+### Cushman
+
+Cushman is powerful, yet fast. While Davinci is stronger when it comes to analyzing complicated tasks, Cushman is quite capable for many code generation tasks and typically runs faster (and at a lower cost) than Davinci.
 
-Currently we only offer one Codex model: `code-cushman-001`.
+## Embeddings models
 
-## Embeddings Models
+Currently, we offer three families of Embeddings models for different functionalities: text search, text similarity, and code search. Each family includes models across the following spectrum of capabilities:
 
-Currently we offer three families of embedding models for different functionalities: text search, text similarity and code search. Each family includes up to four models across a spectrum of capabilities:
+- Ada: 1024 dimensions
+- Babbage: 2048 dimensions
+- Curie: 4096 dimensions
+- Davinci: 12,288 dimensions
 
-Ada (1024 dimensions),
-Babbage (2048 dimensions),
-Curie (4096 dimensions),
-Davinci (12,288 dimensions).
 Davinci is the most capable, but is slower and more expensive than the other models. Ada is the least capable, but is both faster and cheaper.
 
-These embedding models are specifically created to be good at a particular task.
+These Embeddings models are specifically created to be good at a particular task.
 
-### Similarity embeddings
+### Similarity embedding
 
 These models are good at capturing semantic similarity between two or more pieces of text.
 
-| USE CASES | AVAILABLE MODELS |
+| Use cases | Models |
 |---|---|
-| Clustering, regression, anomaly detection, visualization |Text-similarity-ada-001, <br> text-similarity-babbage-001, <br> text-similarity-curie-001, <br> text-similarity-davinci-001 <br>|
+| Clustering, regression, anomaly detection, visualization | `text-similarity-ada-001` <br> `text-similarity-babbage-001` <br> `text-similarity-curie-001` <br> `text-similarity-davinci-001` <br>|
 
-### Text search embeddings
+### Text search embedding
 
-These models help measure whether long documents are relevant to a short search query. There are two types: one for embedding the documents to be retrieved, and one for embedding the search query.
+These models help measure whether long documents are relevant to a short search query. There are two input types supported by this family: `doc`, for embedding the documents to be retrieved, and `query`, for embedding the search query.
 
-| USE CASES | AVAILABLE MODELS |
+| Use cases | Models |
 |---|---|
-| Search, context relevance, information retrieval | text-search-ada-doc-001, <br> text-search-ada-query-001 <br> text-search-babbage-doc-001, <br> text-search-babbage-query-001, <br> text-search-curie-doc-001, <br> text-search-curie-query-001, <br> text-search-davinci-doc-001, <br> text-search-davinci-query-001 <br> |
+| Search, context relevance, information retrieval | `text-search-ada-doc-001` <br> `text-search-ada-query-001` <br> `text-search-babbage-doc-001` <br> `text-search-babbage-query-001` <br> `text-search-curie-doc-001` <br> `text-search-curie-query-001` <br> `text-search-davinci-doc-001` <br> `text-search-davinci-query-001` <br> |
 
-### Code search embeddings
+### Code search embedding
 
-Similar to text search embeddings, there are two types: one for embedding code snippets to be retrieved and one for embedding natural language search queries.
+Similar to text search embedding models, there are two input types supported by this family: `code`, for embedding code snippets to be retrieved, and `text`, for embedding natural language search queries.
 
-| USE CASES | AVAILABLE MODELS |
+| Use cases | Models |
 |---|---|
-| Code search and relevance | code-search-ada-code-001, <br> code-search-ada-text-001, <br> code-search-babbage-code-001, <br> code-search-babbage-text-001 |
+| Code search and relevance | `code-search-ada-code-001` <br> `code-search-ada-text-001` <br> `code-search-babbage-code-001` <br> `code-search-babbage-text-001` |
 
-When using our embedding models, keep in mind their limitations and risks.
+When using our Embeddings models, keep in mind their limitations and risks.
 
 ## Finding the right model
 
-We recommend starting with our Davinci model since it will be the best way to understand what the service is capable of. After you have an idea of what you want to accomplish, you can either stay with Davinci if you’re not concerned about cost and speed, or you can move onto Curie or another model and try to optimize around its capabilities.
+We recommend starting with the most powerful model in a model family, such as the Davinci model, because it's the best way to understand what the service is capable of. After you have an idea of what you want to accomplish, you can either stay with that model or, if balancing capability and cost is a concern for your application, you can move to a model with lower capability and cost, such as Curie or Cushman, and optimize around its capability.
 
 ## Next steps
 

articles/cognitive-services/openai/how-to/completions.md

@@ -295,7 +295,7 @@ While all prompts result in completions, it can be helpful to think of text comp
 Vertical farming provides a novel solution for producing food locally, reducing transportation costs and
 ```
 
-This next prompt shows how you can use completion to help write React components. We send some code to the API, and it's able to continue the rest because it has an understanding of the React library. We recommend using OpenAI's Codex models for tasks that involve understanding or generating code. Currently only `code-cushman-001` is supported.
+This next prompt shows how you can use completion to help write React components. We send some code to the API, and it's able to continue the rest because it has an understanding of the React library. We recommend using models from our Codex series for tasks that involve understanding or generating code. Currently, we support two Codex models: `code-davinci-002` and `code-cushman-001`. For more information about Codex models, see the [Codex models](../concepts/models.md#codex-models) section in [Models](../concepts/models.md).
 
 ```
 import React from 'react';
@@ -355,7 +355,7 @@ Q:
 
 ## Working with code
 
-The Codex model series is a descendant of OpenAI's base GPT-3 series that's been trained on both natural language and billions of lines of code. It's most capable in Python and proficient in over a dozen languages including JavaScript, Go, Perl, PHP, Ruby, Swift, TypeScript, SQL, and even Shell. 
+The Codex model series is a descendant of OpenAI's base GPT-3 series that's been trained on both natural language and billions of lines of code. It's most capable in Python and proficient in over a dozen languages including C#, JavaScript, Go, Perl, PHP, Ruby, Swift, TypeScript, SQL, and even Shell. 
 
 You can use Codex for a variety of tasks including:
 
@@ -503,7 +503,7 @@ Create a list of random animals and species
 animals  = [ {"name": "Chomper", "species": "Hamster"}, {"name":
 ```
 
-**Lower temperatures give more precise results.** Setting the API temperature to 0, or close to zero (such as 0.1 or 0.2) tends to give better results in most cases. Unlike GPT-3, where a higher temperature can provide useful creative and random results, higher temperatures with Codex may give you really random or erratic responses.
+**Lower temperatures give more precise results.** Setting the API temperature to 0, or close to zero (such as 0.1 or 0.2) tends to give better results in most cases. Unlike GPT-3 models, where a higher temperature can provide useful creative and random results, higher temperatures with Codex models may give you really random or erratic responses.
 
 In cases where you need Codex to provide different potential results, start at zero and then increment upwards by .1 until you find suitable variation.
 

articles/cognitive-services/openai/how-to/integrate-synapseml.md

@@ -171,7 +171,7 @@ display(completed_autobatch_df)
 
 ### Prompt engineering for translation
 
-The Azure OpenAI service can solve many different natural language tasks through [prompt engineering](completions.md). Here we show an example of prompting for language translation:
+The Azure OpenAI service can solve many different natural language tasks through [prompt engineering](completions.md). Here, we show an example of prompting for language translation:
 
 ```python
 translate_df = spark.createDataFrame(
@@ -186,7 +186,7 @@ display(completion.transform(translate_df))
 
 ### Prompt for question answering
 
-Here, we prompt GPT-3 for general-knowledge question answering:
+Here, we prompt the GPT-3 model for general-knowledge question answering:
 
 ```python
 qa_df = spark.createDataFrame(

articles/cognitive-services/openai/how-to/work-with-code.md

@@ -15,7 +15,7 @@ keywords:
 
 # Codex models and Azure OpenAI
 
-The Codex model series is a descendant of our GPT-3 series that's been trained on both natural language and billions of lines of code. It's most capable in Python and proficient in over a dozen languages including JavaScript, Go, Perl, PHP, Ruby, Swift, TypeScript, SQL, and even Shell.
+The Codex model series is a descendant of our GPT-3 series that's been trained on both natural language and billions of lines of code. It's most capable in Python and proficient in over a dozen languages including C#, JavaScript, Go, Perl, PHP, Ruby, Swift, TypeScript, SQL, and even Shell.
 
 You can use Codex for a variety of tasks including:
 
@@ -27,7 +27,7 @@ You can use Codex for a variety of tasks including:
 
 ## How to use the Codex models
 
-Here are a few examples of using Codex that can be tested in the [Azure OpenAI Studio's](https://oai.azure.com) playground with a deployment of a code series model such as `code-cushman-001`.
+Here are a few examples of using Codex that can be tested in the [Azure OpenAI Studio's](https://oai.azure.com) playground with a deployment of a Codex series model, such as `code-davinci-002`.
 
 ### Saying "Hello" (Python)
 
@@ -180,7 +180,7 @@ animals  = [ {"name": "Chomper", "species": "Hamster"}, {"name":
 
 ### Lower temperatures give more precise results
 
-Setting the API temperature to 0, or close to zero (such as 0.1 or 0.2) tends to give better results in most cases. Unlike GPT-3, where a higher temperature can provide useful creative and random results, higher temperatures with Codex may give you really random or erratic responses.
+Setting the API temperature to 0, or close to zero (such as 0.1 or 0.2) tends to give better results in most cases. Unlike GPT-3 models, where a higher temperature can provide useful creative and random results, higher temperatures with Codex models may give you really random or erratic responses.
 
 In cases where you need Codex to provide different potential results, start at zero and then increment upwards by 0.1 until you find suitable variation.