Merge pull request #2833 from MicrosoftDocs/main

Publish to live, Sunday 4 AM PST, 2/9

Author: ttorble

articles/ai-foundry/model-inference/includes/use-chat-reasoning/about-reasoning.md

@@ -0,0 +1,22 @@
+---
+manager: nitinme
+ms.service: azure-ai-model-inference
+ms.topic: include
+ms.date: 1/31/2025
+ms.author: fasantia
+author: santiagxf
+---
+
+## Reasoning models
+
+Reasoning models can reach higher levels of performance in domains like math, coding, science, strategy, and logistics. The way these models produces outputs is by explicitly using chain of thought to explore all possible paths before generating an answer. They verify their answers as they produce them which helps them to arrive to better more accurate conclusions. This means that reasoning models may require less context in prompting in order to produce effective results. 
+
+Such way of scaling model's performance is referred as *inference compute time* as it trades performance against higher latency and cost. It contrasts to other approaches that scale through *training compute time*.
+
+Reasoning models then produce two types of outputs:
+
+> [!div class="checklist"]
+> * Reasoning completions
+> * Output completions
+
+Both of these completions count towards content generated from the model and hence, towards the token limits and costs associated with the model. Some models may output the reasoning content, like `DeepSeek-R1`. Some others, like `o1`, only outputs the output piece of the completions.

articles/ai-foundry/model-inference/includes/use-chat-reasoning/best-practices.md

@@ -0,0 +1,17 @@
+---
+manager: nitinme
+ms.service: azure-ai-model-inference
+ms.topic: include
+ms.date: 1/31/2025
+ms.author: fasantia
+author: santiagxf
+---
+
+When building prompts for reasoning models, take the following into consideration:
+
+> [!div class="checklist"]
+> * Use simple instructions and avoid using chain-of-thought techniques.
+> * Built-in reasoning capabilities make simple zero-shot prompts as effective as more complex methods. 
+> * When providing additional context or documents, like in RAG scenarios, including only the most relevant information may help preventing the model from over-complicating its response.
+> * Reasoning models may support the use of system messages. However, they may not follow them as strictly as other non-reasoning models.
+> * When creating multi-turn applications, consider only appending the final answer from the model, without it's reasoning content as explained at [Reasoning content](#reasoning-content) section.

articles/ai-foundry/model-inference/includes/use-chat-reasoning/csharp.md

@@ -11,6 +11,8 @@ author: santiagxf
 
 This article explains how to use the reasoning capabilities of chat completions models deployed to Azure AI model inference in Azure AI services.
 
+[!INCLUDE [about-reasoning](about-reasoning.md)]
+
 ## Prerequisites
 
 To complete this tutorial, you need:
@@ -73,13 +75,7 @@ ChatCompletionsOptions requestOptions = new ChatCompletionsOptions()
 Response<ChatCompletions> response = client.Complete(requestOptions);
 ```
 
-When building prompts for reasoning models, take the following into consideration:
-
-> [!div class="checklist"]
-> * Built-in reasoning capabilities make simple zero-shot prompts as effective as more complex methods.
-> * When providing additional context or documents, like in RAG scenarios, including only the most relevant information may help preventing the model from over-complicating its response.
-> * Reasoning models may support the use of system messages. However, they may not follow them as strictly as other non-reasoning models.
-> * When creating multi-turn applications, consider only appending the final answer from the model, without it's reasoning content as explained at [Reasoning content](#reasoning-content) section.
+[!INCLUDE [best-practices](best-practices.md)]
 
 The response is as follows, where you can see the model's usage statistics:
 

articles/ai-foundry/model-inference/includes/use-chat-reasoning/java.md

@@ -11,6 +11,8 @@ author: santiagxf
 
 This article explains how to use the reasoning capabilities of chat completions models deployed to Azure AI model inference in Azure AI services.
 
+[!INCLUDE [about-reasoning](about-reasoning.md)]
+
 ## Prerequisites
 
 To complete this tutorial, you need:
@@ -93,13 +95,7 @@ ChatCompletionsOptions requestOptions = new ChatCompletionsOptions()
 Response<ChatCompletions> response = client.complete(requestOptions);
 ```
 
-When building prompts for reasoning models, take the following into consideration:
-
-> [!div class="checklist"]
-> * Built-in reasoning capabilities make simple zero-shot prompts as effective as more complex methods.
-> * When providing additional context or documents, like in RAG scenarios, including only the most relevant information may help preventing the model from over-complicating its response.
-> * Reasoning models may support the use of system messages. However, they may not follow them as strictly as other non-reasoning models.
-> * When creating multi-turn applications, consider only appending the final answer from the model, without it's reasoning content as explained at [Reasoning content](#reasoning-content) section.
+[!INCLUDE [best-practices](best-practices.md)]
 
 The response is as follows, where you can see the model's usage statistics:
 

articles/ai-foundry/model-inference/includes/use-chat-reasoning/javascript.md

@@ -11,6 +11,8 @@ author: santiagxf
 
 This article explains how to use the reasoning capabilities of chat completions models deployed to Azure AI model inference in Azure AI services.
 
+[!INCLUDE [about-reasoning](about-reasoning.md)]
+
 ## Prerequisites
 
 To complete this tutorial, you need:
@@ -78,13 +80,7 @@ var response = await client.path("/chat/completions").post({
 });
 ```
 
-When building prompts for reasoning models, take the following into consideration:
-
-> [!div class="checklist"]
-> * Built-in reasoning capabilities make simple zero-shot prompts as effective as more complex methods.
-> * When providing additional context or documents, like in RAG scenarios, including only the most relevant information may help preventing the model from over-complicating its response.
-> * Reasoning models may support the use of system messages. However, they may not follow them as strictly as other non-reasoning models.
-> * When creating multi-turn applications, consider only appending the final answer from the model, without it's reasoning content as explained at [Reasoning content](#reasoning-content) section.
+[!INCLUDE [best-practices](best-practices.md)]
 
 The response is as follows, where you can see the model's usage statistics:
 

articles/ai-foundry/model-inference/includes/use-chat-reasoning/python.md

@@ -11,6 +11,8 @@ author: santiagxf
 
 This article explains how to use the reasoning capabilities of chat completions models deployed to Azure AI model inference in Azure AI services.
 
+[!INCLUDE [about-reasoning](about-reasoning.md)]
+
 ## Prerequisites
 
 To complete this tutorial, you need:
@@ -75,13 +77,7 @@ response = client.complete(
 )
 ```
 
-When building prompts for reasoning models, take the following into consideration:
-
-> [!div class="checklist"]
-> * Built-in reasoning capabilities make simple zero-shot prompts as effective as more complex methods.
-> * When providing additional context or documents, like in RAG scenarios, including only the most relevant information may help preventing the model from over-complicating its response.
-> * Reasoning models may support the use of system messages. However, they may not follow them as strictly as other non-reasoning models.
-> * When creating multi-turn applications, consider only appending the final answer from the model, without it's reasoning content as explained at [Reasoning content](#reasoning-content) section.
+[!INCLUDE [best-practices](best-practices.md)]
 
 The response is as follows, where you can see the model's usage statistics:
 

articles/ai-foundry/model-inference/includes/use-chat-reasoning/rest.md

@@ -11,6 +11,8 @@ author: santiagxf
 
 This article explains how to use the reasoning capabilities of chat completions models deployed to Azure AI model inference in Azure AI services.
 
+[!INCLUDE [about-reasoning](about-reasoning.md)]
+
 ## Prerequisites
 
 To complete this tutorial, you need:
@@ -58,13 +60,7 @@ The following example shows how you can create a basic chat request to the model
 }
 ```
 
-When building prompts for reasoning models, take the following into consideration:
-
-> [!div class="checklist"]
-> * Built-in reasoning capabilities make simple zero-shot prompts as effective as more complex methods.
-> * When providing additional context or documents, like in RAG scenarios, including only the most relevant information may help preventing the model from over-complicating its response.
-> * Reasoning models may support the use of system messages. However, they may not follow them as strictly as other non-reasoning models.
-> * When creating multi-turn applications, consider only appending the final answer from the model, without it's reasoning content as explained at [Reasoning content](#reasoning-content) section.
+[!INCLUDE [best-practices](best-practices.md)]
 
 The response is as follows, where you can see the model's usage statistics:
 

articles/ai-services/content-safety/limited-access.md

@@ -6,7 +6,7 @@ author: PatrickFarley
 ms.author: pafarley
 manager: nitinme
 ms.topic: conceptual
-ms.service: azure-ai-speech
+ms.service: azure-ai-content-safety
 ms.date: 09/23/2024
 ---
 

articles/ai-services/document-intelligence/how-to-guides/includes/v4-0/python-sdk.md

@@ -80,6 +80,7 @@ import os
 from azure.core.credentials import AzureKeyCredential
 from azure.ai.documentintelligence import DocumentIntelligenceClient
 from azure.ai.documentintelligence.models import AnalyzeResult
+from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
 
 # use your `key` and `endpoint` environment variables
 key = os.environ.get('DI_KEY')
@@ -183,6 +184,7 @@ import os
 from azure.core.credentials import AzureKeyCredential
 from azure.ai.documentintelligence import DocumentIntelligenceClient
 from azure.ai.documentintelligence.models import AnalyzeResult
+from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
 
 
 # use your `key` and `endpoint` environment variables
@@ -263,6 +265,7 @@ import os
 from azure.core.credentials import AzureKeyCredential
 from azure.ai.documentintelligence import DocumentIntelligenceClient
 from azure.ai.documentintelligence.models import AnalyzeResult
+from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
 
 # use your `key` and `endpoint` environment variables
 key = os.environ.get('DI_KEY')
@@ -458,6 +461,7 @@ import os
 from azure.core.credentials import AzureKeyCredential
 from azure.ai.documentintelligence import DocumentIntelligenceClient
 from azure.ai.documentintelligence.models import AnalyzeResult
+from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
 
 # use your `key` and `endpoint` environment variables
 key = os.environ.get('DI_KEY')
@@ -648,6 +652,7 @@ import os
 from azure.core.credentials import AzureKeyCredential
 from azure.ai.documentintelligence import DocumentIntelligenceClient
 from azure.ai.documentintelligence.models import AnalyzeResult
+from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
 
 # use your `key` and `endpoint` environment variables
 key = os.environ.get('DI_KEY')
@@ -740,6 +745,7 @@ import os
 from azure.core.credentials import AzureKeyCredential
 from azure.ai.documentintelligence import DocumentIntelligenceClient
 from azure.ai.documentintelligence.models import AnalyzeResult
+from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
 
 # use your `key` and `endpoint` environment variables
 key = os.environ.get('DI_KEY')