feat: tutorial

Author: santiagxf

articles/ai-foundry/model-inference/includes/code-create-chat-reasoning.md

@@ -0,0 +1,93 @@
+---
+manager: nitinme
+ms.service: azure-ai-model-inference
+ms.topic: include
+ms.date: 1/21/2025
+ms.author: fasantia
+author: santiagxf
+---
+
+# [Python](#tab/python)
+
+```python
+from azure.ai.inference.models import SystemMessage, UserMessage
+
+response = client.complete(
+    messages=[
+        UserMessage(content="Explain Riemann's conjecture in 1 paragraph"),
+    ],
+    model="DeepSeek-R1"
+)
+
+print(response.choices[0].message.content)
+```
+
+# [JavaScript](#tab/javascript)
+
+```javascript
+var messages = [
+    { role: "user", content: "Explain Riemann's conjecture in 1 paragraph" },
+];
+
+var response = await client.path("/chat/completions").post({
+    body: {
+        messages: messages,
+        model: "DeepSeek-R1"
+    }
+});
+
+console.log(response.choices[0].message.content)
+```
+
+# [C#](#tab/csharp)
+
+```csharp
+requestOptions = new ChatCompletionsOptions()
+{
+    Messages = {
+        new ChatRequestUserMessage("Explain Riemann's conjecture in 1 paragraph")
+    },
+    Model = "DeepSeek-R1"
+};
+
+response = client.Complete(requestOptions);
+Console.WriteLine($"Response: {response.Value.Content}");
+```
+
+# [Java](#tab/java)
+
+```java
+List<ChatRequestMessage> chatMessages = new ArrayList<>();
+chatMessages.add(new ChatRequestUserMessage("Explain Riemann's conjecture in 1 paragraph"));
+
+ChatCompletions chatCompletions = client.complete(new ChatCompletionsOptions(chatMessages, "DeepSeek-R1"));
+
+for (ChatChoice choice : chatCompletions.getChoices()) {
+    ChatResponseMessage message = choice.getMessage();
+    System.out.println("Response:" + message.getContent());
+}
+```
+
+# [REST](#tab/rest)
+
+__Request__
+
+```HTTP/1.1
+POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
+api-key: <api-key>
+Content-Type: application/json
+```
+
+```JSON
+{
+    "messages": [
+        {
+            "role": "user",
+            "content": "Explain Riemann's conjecture in 1 paragraph"
+        }
+    ],
+    "model": "DeepSeek-R1"
+}
+```
+
+---

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

@@ -11,7 +11,7 @@ author: santiagxf
 
 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*.
+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:
 

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

@@ -14,4 +14,6 @@ When building prompts for reasoning models, take the following into consideratio
 > * 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.
+> * 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.
+
+Notice that reasoning models can take longer times to generate responses. They use long reasoning chains of thought that enabled deeper and more structured problem-solving. They also perform self-verification to cross-check its own answers and correct its own mistakes, showcasing emergent self-reflective behaviors.

articles/ai-foundry/model-inference/media/quickstart-get-started-deepseek-r1/model-deploy.png

@@ -24,6 +24,10 @@ items:
       href: ./how-to/quickstart-github-models.md 
     - name: Configure AI projects to work with Azure AI model inference
       href: ./how-to/quickstart-ai-project.md
+- name: Tutorials
+  items:
+    - name: Get started with DeepSeek-R1 reasoning model
+      href: ./tutorials/get-started-deepseek-r1.md
 - name: Concepts
   items:
     - name: Available models

articles/ai-foundry/model-inference/media/quickstart-get-started-deepseek-r1/models-deploy-agree.png

@@ -0,0 +1,137 @@
+---
+title: "Tutorial: Getting started with DeepSeek-R1 reasoning model in Azure AI model inference"
+titleSuffix: Azure AI Foundry
+description: Learn about the reasoning capabilities of DeepSeek-R1 in Azure AI model inference.
+manager: scottpolly
+ms.service: azure-ai-model-inference
+ms.topic: tutorial
+ms.date: 03/01/2025
+ms.reviewer: fasantia
+ms.author: msakande
+author: mopeakande
+---
+
+# Tutorial: Get started with DeepSeek-R1 reasoning model in Azure AI model inference
+
+In this tutorial, you learn:
+
+> [!div class="checklist"]
+> * How to create and configure the Azure resources to use DeepSeek-R1 model in Azure AI model inference.
+> * How to configure the model deployment.
+> * How to use DeepSeek-R1 using the Azure AI Inference SDK or REST APIs.
+> * How to use DeepSeek-R1 using other SDKs.
+
+## Prerequisites
+
+To complete this article, you need:
+
+* An Azure subscription. If you're using [GitHub Models](https://docs.github.com/en/github-models/), you can upgrade your experience and create an Azure subscription in the process. Read [Upgrade from GitHub Models to Azure AI model inference](../../how-to/quickstart-github-models.md) if that's your case.
+
+[!INCLUDE [about-reasoning](../includes/use-chat-reasoning/about-reasoning.md)]
+
+## Create the resources
+
+Azure AI model inference is a capability in Azure AI Services resources in Azure. You can create model deployments under the resource to consume their predictions. You can also connect the resource to Azure AI Hubs and Projects in Azure AI Foundry to create intelligent applications if needed. The following picture shows the high level architecture.
+
+:::image type="content" source="../media/quickstart-get-started-deepseek-r1/resources-architecture.png" alt-text="A diagram showing the high level architecture of the resources created in the tutorial." lightbox="../media/quickstart-get-started-deepseek-r1/resources-architecture.png":::
+
+To create an Azure AI project that supports model inference for DeepSeek-R1, follow these steps:
+
+1. Go to [Azure AI Foundry portal](https://ai.azure.com) and log in with your account.
+
+2. On the landing page, select **Create project**.
+
+3. Give the project a name, for example "my-project".
+
+4. In this tutorial, we create a brand new project under a new AI hub, hence, select **Create new hub**. Hubs are containers for multiple projects and allow you to share resources across all the projects.
+
+5. Give the hub a name, for example "my-hub" and select **Next**.
+
+6. The wizard updates with details about the resources that are going to be created. Select **Azure resources to be created** to see the details.
+
+    :::image type="content" source="../media/create-resources/create-project-with-hub-details.png" alt-text="Screenshot showing the details of the project and hub to be created." lightbox="../media/create-resources/create-project-with-hub-details.png":::    
+
+7. You can see that the following resources are created:
+
+    | Property       | Description |
+    | -------------- | ----------- |
+    | Resource group | The main container for all the resources in Azure. This helps get resources that work together organized. It also helps to have a scope for the costs associated with the entire project. |
+    | Location       | The region of the resources that you're creating. |
+    | Hub            | The main container for AI projects in Azure AI Foundry. Hubs promote collaboration and allow you to store information for your projects. |
+    | AI Services    | The resource enabling access to the flagship models in Azure AI model catalog. In this tutorial, a new account is created, but Azure AI services resources can be shared across multiple hubs and projects. Hubs use a connection to the resource to have access to the model deployments available there. To learn how, you can create connections between projects and Azure AI Services to consume Azure AI model inference you can read [Connect your AI project](../../how-to/configure-project-connection.md). |
+
+8. Select **Create**. The resources creation process starts. 
+
+9. Once completed, your project is ready to be configured.
+
+10. Azure AI model inference is a Preview feature that needs to be turned on in Azure AI Foundry. At the top navigation bar, over the right corner, select the **Preview features** icon. A contextual blade shows up at the right of the screen.
+
+11. Turn the feature **Deploy models to Azure AI model inference service** on.
+
+    :::image type="content" source="../media/quickstart-ai-project/ai-project-inference-endpoint.gif" alt-text="An animation showing how to turn on the Azure AI model inference service deploy models feature in Azure AI Foundry portal." lightbox="../media/quickstart-ai-project/ai-project-inference-endpoint.gif":::
+
+12. Close the panel.
+
+
+## Add DeepSeek-R1 model deployment
+
+Let's now create a new model deployment for DeepSeek-R1:
+
+1. Go to **Model catalog** section in [Azure AI Foundry portal](https://ai.azure.com/explore/models) and find the model [DeepSeek-R1]() model.
+
+3. You can review the details of the model in the model card.
+
+4. Select **Deploy**.
+
+5. The wizard shows the model's terms and conditions. DeepSeek-R1 is offered as a Microsoft first party consumption service. You can review our privacy and security commitments under [Data, privacy, and Security](). Accept the terms on those cases by selecting **Subscribe and deploy**.
+
+   :::image type="content" source="../media/quickstart-get-started-deepseek-r1/models-deploy-agree.png" alt-text="Screenshot showing how to agree the terms and conditions of a DeepSeek-R1 model." lightbox="../media/quickstart-get-started-deepseek-r1/models-deploy-agree.png":::
+
+6. You can configure the deployment settings at this time. By default, the deployment receives the name of the model you're deploying. The deployment name is used in the `model` parameter for request to route to this particular model deployment. This allows you to also configure specific names for your models when you attach specific configurations.
+
+7. We automatically select an Azure AI Services connection depending on your project. Use the **Customize** option to change the connection based on your needs. DeepSeek-R1 is currently offered under the **Global Standard** deployment type which offers higher throughput and performance.
+
+8. Select **Deploy**.
+
+   :::image type="content" source="../media/quickstart-get-started-deepseek-r1/models-deploy.png" alt-text="Screenshot showing how to deploy the model." lightbox="../media/quickstart-get-started-deepseek-r1/models-deploy.png":::
+
+9.  Once the deployment completes, the new model is listed in the page and it's ready to be used.
+
+## Use the model in playground
+
+You can get started by using the model in the playground to have an idea of the model capabilities.
+
+1. On the deployment details page, select **Open in playground** option in the top bar.
+
+2. In the **Deployment** drop down, the deployment you created has been automatically selected.
+
+3. Configure the system prompt as needed. In general, reasoning models don't use system messages in the same way that other types of models.
+
+   :::image type="content" source="../media/quickstart-get-started-deepseek-r1/playground-chat-models.png" alt-text="Screenshot showing how to select a model deployment to use in playground, configure the system message, and test it out." lightbox="../media/quickstart-get-started-deepseek-r1/playground-chat-models.png":::
+
+4. Type your prompt and see the outputs.
+
+5. Additionally, you can use **View code** so see details about how to access the model deployment programmatically.
+
+[!INCLUDE [best-practices](../includes/use-chat-reasoning/best-practices.md)]
+
+## Use the model in code
+
+[!INCLUDE [code-chat-reasoning](../includes/code-create-chat-reasoning.md)]
+
+Reasoning may generate longer responses and consume a larger amount of tokens. You can see the [rate limits](../quotas-limits.md) that apply to DeepSeek-R1 models. Consider having a retry strategy to handle rate limits being applied. You can also [request increases to the default limits](../quotas-limits.md#request-increases-to-the-default-limits).
+
+### Parameters
+
+In general, reasoning models don't support the following parameters you can find in chat completion models:
+
+* Temperature
+* Presence penalty
+* Repetition penalty
+* Parameter `top_p`
+
+## Related content
+
+* [Use chat reasoning models](../how-to/use-chat-reasoning.md)
+* [Use image embedding models](../how-to/use-image-embeddings.md)
+* [Azure AI Model Inference API](.././reference/reference-model-inference-api.md)