Merge branch 'main' into diberry/0602-AzureClientOptions

Author: diberry

articles/ai-studio/how-to/custom-policy-model-deployment.md renamed to articles/ai-foundry/model-inference/how-to/configure-deployment-policies.md

@@ -1,20 +1,21 @@
 ---
-title: Control AI model deployment with custom policies
+title: Control model deployment with custom policies
 titleSuffix: Azure AI Foundry
 description: "Learn how to use custom Azure Policies to control Azure AI services and Azure OpenAI model deployment with Azure AI Foundry."
+manager: scottpolly
+ms.service: azure-ai-foundry
+ms.topic: how-to #Don't change
+ms.date: 02/11/2025
 author: Blackmist
 ms.author: larryfr
-ms.service: azure-ai-studio
-ms.topic: how-to #Don't change
-ms.date: 10/25/2024
-
-#customer intent: As an admin, I want control what Azure AI services and Azure OpenAI models can be deployed by my developers.
+reviewer: santiagxf
+ms.reviewer: fasantia
 
 ---
 
-# Control AI model deployment with custom policies in Azure AI Foundry portal
+# Control model deployment with custom policies
 
-When using models from Azure AI services and Azure OpenAI with Azure AI Foundry, you might need to use custom policies to control what models your developers can deploy. Custom Azure Policies allow you to create policy definitions that meet your organization's unique requirements. This article shows you how to create and assign an example custom policy to control model deployment.
+When using models from Azure AI Services and Azure OpenAI with Azure AI Foundry, you might need to use custom policies to control which [type of deployment](../concepts/deployment-types.md) options are available to users or which specific models users can deploy. This article guides you on how to create policies to control model deployments using Azure Policies. 
 
 ## Prerequisites
 
@@ -24,71 +25,125 @@ When using models from Azure AI services and Azure OpenAI with Azure AI Foundry,
 
 ## Create a custom policy
 
+Follow these steps to create and assign an example custom policy to control model deployments:
+
 1. From the [Azure portal](https://portal.azure.com), select **Policy** from the left side of the page. You can also search for **Policy** in the search bar at the top of the page.
-1. From the left side of the Azure Policy Dashboard, select **Authoring**, **Definitions**, and then select **+ Policy definition** from the top of the page.
-1. In the **Policy Definition** form, use the following values:
+
+2. From the left side of the Azure Policy Dashboard, select **Authoring**, **Definitions**, and then select **+ Policy definition** from the top of the page.
+
+    :::image type="content" source="../media/configure-deployment-policies/create-new-policy.png" alt-text="An screenshot showing how to create a new policy definition in Azure Policies." lightbox="../media/configure-deployment-policies/create-new-policy.png":::
+
+3. In the **Policy Definition** form, use the following values:
 
     - **Definition location**: Select the subscription or management group where you want to store the policy definition.
     - **Name**: Enter a unique name for the policy definition. For example, `Custom allowed Azure AI services and Azure OpenAI models`.
     - **Description**: Enter a description for the policy definition.
     - **Category**: You can either create a new category or use an existing one. For example, "AI model governance."
-    - **Policy rule**: Enter the policy rule in JSON format. The following example shows a policy rule that allows the deployment of specific Azure AI services and Azure OpenAI models:
 
-        > [!TIP]
-        > Azure AI services was originally named Azure Cognitive Services. This name is still used internally by Azure, such as this custom policy where you see a value of `Microsoft.CognitiveServices`. Azure OpenAI is part of Azure AI services, so this policy also applies to Azure OpenAI models.
+4. On **Policy rule**, enter the policy rule details in JSON format. Select the scenario that applies to your case better:
 
-        ```json
-        {
-              "mode": "All",
-              "policyRule": {
-                "if": {
-                  "allOf": [
-                    {
-                      "field": "type",
-                      "equals": "Microsoft.CognitiveServices/accounts/deployments"
-                    },
-                    {
-                      "not": {
-                        "value": "[concat(field('Microsoft.CognitiveServices/accounts/deployments/model.name'), ',', field('Microsoft.CognitiveServices/accounts/deployments/model.version'))]",
-                        "in": "[parameters('allowedModels')]"
-                      }
-                    }
-                  ]
+    # [Enforce specific models](#tab/models)
+
+    The following policy allows you to control which specific models and versions are available for deployment. You can enforce this policy at different levels depending on your needs.
+
+    ```json
+    {
+          "mode": "All",
+          "policyRule": {
+            "if": {
+              "allOf": [
+                {
+                  "field": "type",
+                  "equals": "Microsoft.CognitiveServices/accounts/deployments"
                 },
-                "then": {
-                  "effect": "deny"
-                }
-              },
-              "parameters": {
-                "allowedModels": {
-                  "type": "Array",
-                  "metadata": {
-                    "displayName": "Allowed AI models",
-                    "description": "The list of allowed models to be deployed."
+                {
+                  "not": {
+                    "value": "[concat(field('Microsoft.CognitiveServices/accounts/deployments/model.name'), ',', field('Microsoft.CognitiveServices/accounts/deployments/model.version'))]",
+                    "in": "[parameters('allowedModels')]"
                   }
                 }
+              ]
+            },
+            "then": {
+              "effect": "deny"
+            }
+          },
+          "parameters": {
+            "allowedModels": {
+              "type": "Array",
+              "metadata": {
+                "displayName": "Allowed AI models",
+                "description": "The list of allowed models to be deployed."
               }
+            }
         }
-        ```
+    }
+    ```
+
+    # [Enforce specific deployment types](#tab/deployments)
 
-1. Select **Save** to save the policy definition. After saving, you arrive at the policy definition's overview page.
-1. From the policy definition's overview page, select **Assign policy** to assign the policy definition.
-1. From the **Assign policy** page, use the following values on the **Basics** tab:
+    The following policy allows you to control which types of deployments are allowed in the Azure AI Services or Azure OpenAI Resources. For example, you might want to prevent developers from creating deployments that result in data processed in a different region. Follow these steps to create a policy that denies creating global processing deployment types.
+
+    ```json
+    {
+        "mode": "All",
+        "policyRule": {
+            "if": {
+                "allOf": [
+                    {
+                        "field": "type",
+                        "equals": "Microsoft.CognitiveServices/accounts/deployments"
+                    },
+                    {
+                        "field": "Microsoft.CognitiveServices/accounts/deployments/sku.name",
+                        "equals": "GlobalStandard"
+                    }
+                ]
+            },
+            "then": {
+                "effect": "deny"
+            }
+        }
+    }
+    ```
+
+    ---
+
+    > [!TIP]
+    > Azure AI services was originally named Azure Cognitive Services. This name is still used internally by Azure, such as this custom policy where you see a value of `Microsoft.CognitiveServices`. Azure OpenAI is part of Azure AI services, so this policy also applies to Azure OpenAI models.
+
+5. Select **Save** to save the policy definition. After saving, you arrive at the policy definition's overview page.
+
+6. From the policy definition's overview page, select **Assign policy** to assign the policy definition.
+
+7. From the **Assign policy** page, use the following values on the **Basics** tab:
 
     - **Scope**: Select the scope where you want to assign the policy. The scope can be a management group, subscription, or resource group.
     - **Policy definition**: This field is prepopulated with the title of policy definition you created previously.
     - **Assignment name**: Enter a unique name for the assignment.
     - **Policy enforcement**: Make sure that the **Policy enforcement** field is set to **Enabled**. If it isn't enabled, the policy isn't enforced.
 
     Select **Next** at the bottom of the page, or the **Parameters** tab at the top of the page.
-1. From the **Parameters** tab, set **Allowed AI models** to the list of models that you want to allow. The list should be a comma-separated list of model names and approved versions, surrounded by square brackets. For example, `["gpt-4,0613", "gpt-35-turbo,0613"]`.
+
+8. Configure the parameters for the policy (if any): 
+
+    # [Enforce specific models](#tab/models)
+
+    From the **Parameters** tab, set **Allowed AI models** to the list of models that you want to allow. The list should be a comma-separated list of model names and approved versions, surrounded by square brackets. For example, `["gpt-4,0613", "gpt-35-turbo,0613"]`.
 
     > [!TIP]
     > You can find the model names and their versions in the [Azure AI Foundry Model Catalog](https://ai.azure.com/explore/models). Select the model to view the details, and then copy the model name and their version in the title.
 
-1. Optionally, select the **Non-compliance messages** tab at the top of the page and set a custom message for noncompliance.
-1. Select **Review + create** tab and verify that the policy assignment is correct. When ready, select **Create** to assign the policy.
-1. Notify your developers that the policy is in place. They receive an error message if they try to deploy a model that isn't in the list of allowed models.
+    # [Enforce specific deployment types](#tab/deployments)
+
+    This policy doesn't require parameters. 
+
+9. Optionally, select the **Non-compliance messages** tab at the top of the page and set a custom message for noncompliance.
+
+10. Select **Review + create** tab and verify that the policy assignment is correct. When ready, select **Create** to assign the policy.
+
+11. Notify your developers that the policy is in place. They receive an error message if they try to deploy a model that isn't in the list of allowed models.
+
 
 ## Verify policy assignment
 
@@ -99,7 +154,10 @@ To verify that the policy is assigned, navigate to **Policy** in the Azure porta
 To monitor compliance with the policy, follow these steps:
 
 1. From the [Azure portal](https://portal.azure.com), select **Policy** from the left side of the page. You can also search for **Policy** in the search bar at the top of the page.
-1. From the left side of the Azure Policy Dashboard, select **Compliance**. Each policy assignment is listed with the compliance status. To view more details, select the policy assignment.
+
+1. From the left side of the Azure Policy Dashboard, select **Compliance**. Each policy assignment is listed with the compliance status. To view more details, select the policy assignment. The following example shows the compliance report for a policy that blocks deployments of type *Global standard*.
+
+    :::image type="content" source="../media/configure-deployment-policies/policy-compliance.png" alt-text="An screenshot showing an example of a policy compliance report for a policy that blocks Global standard deployment SKUs." lightbox="../media/configure-deployment-policies/policy-compliance.png":::
 
 ## Update the policy assignment
 
@@ -112,7 +170,6 @@ To update an existing policy assignment with new models, follow these steps:
 
 ## Best practices
 
-- **Obtaining model names**: Use the [Azure AI Foundry Model Catalog](https://ai.azure.com/explore/models), then select the model to view details. Use the model name in the title with the policy.
 - **Granular scoping**: Assign policies at the appropriate scope to balance control and flexibility. For example, apply at the subscription level to control all resources in the subscription, or apply at the resource group level to control resources in a specific group.
 - **Policy naming**: Use a consistent naming convention for policy assignments to make it easier to identify the purpose of the policy. Include information such as the purpose and scope in the name.
 - **Documentation**: Keep records of policy assignments and configurations for auditing purposes. Document any changes made to the policy over time.
@@ -123,6 +180,5 @@ To update an existing policy assignment with new models, follow these steps:
 ## Related content
 
 - [Azure Policy overview](/azure/governance/policy/overview)
-- [Azure AI Foundry model catalog](model-catalog-overview.md)
-- [Azure AI services documentation](/azure/ai-services)
+- [Deployment types](../concepts/deployment-types.md)
 

articles/ai-foundry/model-inference/how-to/quickstart-ai-project.md

@@ -125,10 +125,10 @@ You can use any of the supported SDKs to get predictions out from the endpoint.
 
 * OpenAI SDK
 * Azure OpenAI SDK
-* Azure AI Inference SDK
-* Azure AI Foundry SDK
+* Azure AI Inference package
+* Azure AI Projects package
 
-See the [supported languages and SDKs](../supported-languages.md) section for more details and examples. The following example shows how to use the Azure AI model inference SDK with the newly deployed model:
+See the [supported languages and SDKs](../supported-languages.md) section for more details and examples. The following example shows how to use the Azure AI Inference package with the newly deployed model:
 
 [!INCLUDE [code-create-chat-client](../includes/code-create-chat-client.md)]
 

articles/ai-foundry/model-inference/how-to/quickstart-create-resources.md

@@ -26,7 +26,3 @@ zone_pivot_groups: azure-ai-models-deployment
 ::: zone pivot="programming-language-bicep"
 [!INCLUDE [bicep](../includes/create-resources/bicep.md)]
 ::: zone-end
-
-## Next steps
-
-* [Develop applications using Azure AI model inference service in Azure AI services](../supported-languages.md)

articles/ai-foundry/model-inference/how-to/quickstart-github-models.md

@@ -47,7 +47,7 @@ To obtain the key and endpoint:
 
 5. If your existing account is a free account, you first have to upgrade to a Pay as you go plan. Once you upgrade, go back to the playground and select **Get API key** again, then sign in with your upgraded account.
 
-6. Once you've signed in to your Azure account, you're taken to [Azure AI Studio > GitHub](https://ai-azure.com/GitHub). It might take one or two minutes to load your initial model details in AI Studio.
+6. Once you've signed in to your Azure account, you're taken to [Azure AI Studio > GitHub](https://ai.azure.com/GitHub). It might take one or two minutes to load your initial model details in AI Studio.
 
 7. The page is loaded with your model's details. Select the **Deploy** button to deploy the model to your account.
 

articles/ai-foundry/model-inference/includes/create-resources/bicep.md

@@ -40,6 +40,8 @@ The tutorial helps you create:
 > * (Optionally) An Azure AI project and hub.
 > * (Optionally) A connection between the hub and the models in Azure AI Services.
 
+Notice that **you have to deploy an Azure AI project and hub** if you plan to use the Azure AI Foundry portal for managing the resource, using playground, or any other feature from the portal.
+
 You are using the following assets to create those resources:
 
 1. Use the template `modules/ai-services-template.bicep` to describe your Azure AI Services resource:
@@ -54,7 +56,7 @@ You are using the following assets to create those resources:
 
     :::code language="bicep" source="~/azureai-model-inference-bicep/infra/modules/ai-services-deployment-template.bicep":::
 
-3. For convenience, we define the model we want to have available in the service using a JSON file. The file [__infra/models.json__](https://github.com/Azure-Samples/azureai-model-inference-bicep/blob/main/infra/models.json) contains a list of JSON object with keys `name`,`version`, `provider`, and `sku`, which defines the models the deployment will provision. Since the models support pay-as-you-go, adding model deployments doesn't incur on extra cost. Modify the file removing/adding the model entries you want to have available. The following example **shows only the first 7 lines** of the JSON file:
+3. For convenience, we define the model we want to have available in the service using a JSON file. The file [__infra/models.json__](https://github.com/Azure-Samples/azureai-model-inference-bicep/blob/main/infra/models.json) contains a list of JSON object with keys `name`,`version`, `provider`, and `sku`, which defines the models the deployment will provision. Since the models support pay-as-you-go, adding model deployments doesn't incur on extra cost. Modify the file by **removing/adding the model entries you want to have available**. The following example **shows only the first 7 lines** of the JSON file:
 
     __models.json__
 
@@ -118,4 +120,9 @@ In your console, follow these steps:
       --template-file deploy.bicep
     ```
 
-7. The template outputs the Azure AI model inference endpoint that you can use to consume any of the model deployments you have created.
+7. The template outputs the Azure AI model inference endpoint that you can use to consume any of the model deployments you have created.
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Use the inference endpoint](../../how-to/inference.md)

articles/ai-foundry/model-inference/includes/create-resources/portal.md

@@ -54,5 +54,7 @@ To create a project with an Azure AI Services account, follow these steps:
 
 10. To use Azure AI model inference, you need to add model deployments to your Azure AI services account.
 
-    > [!div class="nextstepaction"]
-    > [Add and configure models](../../how-to/create-model-deployments.md)
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Add and configure models](../../how-to/create-model-deployments.md)

articles/ai-foundry/model-inference/includes/feature-preview.md

@@ -3,7 +3,7 @@ title: include file
 description: include file
 author: msakande
 ms.author: mopeakande
-ms.service: azure-ai-studio
+ms.service: azure-ai-foundry
 ms.topic: include
 ms.date: 1/28/2025
 ms.custom: include file

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.