AI Services keyless billing

HeidiSteen · HeidiSteen · commit e69df427aaae · 2024-11-05T11:15:10.000-08:00
diff --git a/articles/search/cognitive-search-attach-cognitive-services.md b/articles/search/cognitive-search-attach-cognitive-services.md
@@ -8,46 +8,110 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 10/21/2024
+ms.date: 11/19/2024
 ---
 
 # Attach an Azure AI multi-service resource to a skillset in Azure AI Search
 
 When configuring an optional [AI enrichment pipeline](cognitive-search-concept-intro.md) in Azure AI Search, you can enrich a small number of documents free of charge, limited to 20 transactions daily per index. For larger and more frequent workloads, you should attach a billable [**Azure AI multi-service resource**](/azure/ai-services/multi-service-resource?pivots=azportal). 
 
-A multi-service account provides a collection of Azure AI services, rather than individual services. The account has an associated [resource key](/azure/ai-services/authentication#authenticate-with-a-multi-service-resource-key). This key is specified in an Azure AI Search [**skillset**](/rest/api/searchservice/skillsets/create) and allows Microsoft to charge you for using these services:
+A multi-service account provides a collection of Azure AI services, rather than individual services. Providing an account in an Azure AI Search [**skillset**](/rest/api/searchservice/skillsets/create) allows Microsoft to charge you for using these services:
 
 + [Azure AI Vision](/azure/ai-services/computer-vision/overview) for image analysis, optical character recognition (OCR), and multimodal text and image embedding.
 + [Azure AI Language](/azure/ai-services/language-service/overview) for language detection, entity recognition, sentiment analysis, and key phrase extraction
 + [Azure AI Speech](/azure/ai-services/speech-service/overview) for speech to text and text to speech
 + [Azure AI Translator](/azure/ai-services/translator/translator-overview) for machine text translation
 
-The key is used for billing, not connections. You must provide a key in the skillset even if you're using other mechanisms, such as role assignments and managed identities, on the connection.
+You must provide connection information to the Azure AI multi-resource in the skillset. Azure AI Search doesn't use the connection for skillset workloads, but it does use the connection to access the billing meters on the resource. As such, your Azure AI services account is used for billing, not skills processing. Azure AI Search uses separate dedicated resources for skills processing.
+
+You can use a key on the connection, or implement a keyless approach that's currently in preview.
 
 > [!TIP]
 > Azure provides infrastructure for you to monitor billing and budgets. For more information about monitoring Azure AI services, see [Plan and manage costs for Azure AI services](/azure/ai-services/plan-manage-costs).
 
-## Get the resource key for an Azure AI multi-service account
+## Billing through a keyless connection to Azure AI multi-service
 
-1. Sign in to the [Azure portal](https://portal.azure.com).
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
 
-1. Create an [Azure AI multi-service resource](/azure/ai-services/multi-service-resource?pivots=azportal) in the [same region](#same-region-requirement) as your search service.
+Using the Azure portal or newer preview REST APIs and beta SDK packages, you can attach a multi-service resource using a managed identity and permissions. The advantage of this approach is that billing is keyless and has no dependency on regions.
 
-1. Get the resource key from the **Resources** > **Keys and endpoint** page.
+1. [Configure Azure AI Search to use a managed identity](search-howto-managed-identities-data-sources.md).
+
+1. On your Azure AI multi-service resource, [assign the identity to the **Cognitive Services User** role](/azure/role-based-access-control/role-assignments-portal).
+
+1. Using the Azure portal, or the [Skillset 2024-11-01-preview REST API](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2024-11-01-preview&preserve-view=true), or an Azure SDK beta package that provides the syntax, configure a skillset to use an identity:
+
+   + The managed identity used on the connection belongs to the search service.
+   + It can be either a system managed identity (identity=null) or a user managed identity.
+   + The managed identity must have **Cognitive Services User** permissions on the Azure AI multiservice account.
+   + The `@odata.type` is always `#Microsoft.Azure.Search.AIServicesByIdentity`.
+   + the `subdomainUrl` is the endpoint of your Azure AI multi-service account and it can be in [any region that's jointly supported](search-region-support.md#azure-public-regions) by Azure AI Search and Azure AI services.
+
+As with keys, the details you provide about the Azure AI Services resource are used for billing, not connections.  All API requests made by Azure AI Search to Azure AI services for built-in skills processing continue to be internal and managed by Microsoft.
+
+### Example: system-assigned managed identity
+
+Identity is set to null.
+
+```http
+POST https://[service-name].search.windows.net/skillsets/[skillset-name]?api-version=2024-11-01-Preview  
+
+{  
+    "name": "my skillset name",  
+    "skills":   
+    [  
+      // skills definition goes here 
+    ],  
+    "cognitiveServices": {  
+        "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",  
+        "description": "",  
+        "subdomainUrl": “https://[subdomain-name].cognitiveservices.azure.com",  
+      "identity": null 
+    }  
+} 
+```
 
-## Add the resource key to a skillset
+### Example: user-assigned managed identity
 
-You can use the Azure portal, REST API, or an Azure SDK to add the key to a skillset.
+Identity is set to the resource ID of the user-assigned managed identity.
+
+```http
+POST https://[service-name].search.windows.net/skillsets/[skillset-name]?api-version=2024-11-01-Preview  
+
+{  
+    "name": "my skillset name",  
+    "skills":   
+    [  
+      // skills definition goes here 
+    ],  
+    "cognitiveServices": {  
+        "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",  
+        "description": "",  
+        "subdomainUrl": “https://[subdomain-name].cognitiveservices.azure.com",  
+      "identity": null 
+    }  
+}
+```
+
+## Billing through an Azure AI multi-service resources key
+
+This approach is the default and is generally available. You can use the Azure portal, REST API, or an Azure SDK to add the key to a skillset.
 
 If you leave the property unspecified, your search service attempts to use the free enrichments available to your indexer on a daily basis. Execution of billable skills stops at 20 transactions per indexer invocation and a "Time Out" message appears in indexer execution history.
 
 ### [**Azure portal**](#tab/portal)
 
-Add the key to a skillset definition:
+1. Sign in to the [Azure portal](https://portal.azure.com).
 
-+ If using an [Import data wizard](search-import-data-portal.md), create or select the Azure AI account. The wizard adds the resource key to your skillset definition. 
+1. Create an [Azure AI multi-service resource](/azure/ai-services/multi-service-resource?pivots=azportal) in the [same region](#same-region-requirement) as your search service.
+
+1. Get the resource key from the **Resources** > **Keys and endpoint** page.
 
-+ For a new or existing skillset, provide the key in skillset definition.
+1. Add the key to a skillset definition:
+
+   + If using an [Import data wizard](search-import-data-portal.md), create or select the Azure AI account. The wizard adds the resource key to your skillset definition. 
+
+   + For a new or existing skillset, provide the key in skillset definition.
 
   :::image type="content" source="media/cognitive-search-attach-cognitive-services/attach-existing2.png" alt-text="Screenshot of the key page." border="true":::
 
@@ -187,9 +251,11 @@ Enrichments are billable operations. If you no longer need to call Azure AI serv
 
 ## How the key is used
 
-Key-based billing applies when API calls to Azure AI services resources exceed 20 API calls per indexer, per day. You can [reset the indexer](search-howto-run-reset-indexers.md) to reset the API count.
+Billing goes into effect when API calls to Azure AI services resources exceed 20 API calls per indexer, per day. You can [reset the indexer](search-howto-run-reset-indexers.md) to reset the API count.
+
+Keyless and key-based connections are used for billing, but not for enrichment operations' connections. For connections, a search service [connects over the internal network](search-security-overview.md#internal-traffic) to an Azure AI services resource that's located in the [same physical region](search-region-support.md). Most regions that offer Azure AI Search also offer other Azure AI services such as Language. If you attempt AI enrichment in a region that doesn't have both services, you'll see this message: "Provided key isn't a valid CognitiveServices type key for the region of your search service."
 
-The key is used for billing, but not for enrichment operations' connections. For connections, a search service [connects over the internal network](search-security-overview.md#internal-traffic) to an Azure AI services resource that's located in the [same physical region](search-region-support.md). Most regions that offer Azure AI Search also offer other Azure AI services such as Language. If you attempt AI enrichment in a region that doesn't have both services, you'll see this message: "Provided key isn't a valid CognitiveServices type key for the region of your search service."
+Indexers can be configured to run in a [private execution environment](search-howto-run-reset-indexers.md#indexer-execution) for dedicated processing using just the search nodes of your own search service. Even if you're using private execution environment, Azure AI Search still uses its internally provisioned Azure AI multiservice resource to perform all skill enrichments.
 
 Currently, billing for [built-in skills](cognitive-search-predefined-skills.md) requires a public connection from Azure AI Search to another Azure AI service. Disabling public network access breaks billing. If disabling public networks is a requirement, you can configure a [Custom Web API skill](cognitive-search-custom-skill-interface.md) implemented with an [Azure Function](cognitive-search-create-custom-skill-example.md) that supports [private endpoints](/azure/azure-functions/functions-create-vnet) and add the [Azure AI services resource to the same VNET](/azure/ai-services/cognitive-services-virtual-networks). In this way, you can call Azure AI services resource directly from the custom skill using private endpoints.
 
diff --git a/articles/search/tutorial-rag-build-solution-pipeline.md b/articles/search/tutorial-rag-build-solution-pipeline.md
@@ -8,7 +8,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: tutorial
-ms.date: 10/04/2024
+ms.date: 11/19/2024
 
 ---
 
@@ -155,7 +155,7 @@ Skills are the basis for integrated data chunking and vectorization. At a minimu
 
 In this skillset, an extra skill is used to create structured data in the index. The [Entity Recognition skill](cognitive-search-skill-entity-recognition-v3.md) is used to identify locations, which can range from proper names to generic references, such as "ocean" or "mountain". Having structured data gives you more options for creating interesting queries and boosting relevance.
 
-The AZURE_AI_MULTISERVICE_KEY is needed even if you're using role-based access control. Azure AI Search uses the key for billing purposes and it's required unless your workloads stay under the free limit.
+The AZURE_AI_MULTISERVICE_KEY is needed even if you're using role-based access control. Azure AI Search uses the key for billing purposes and it's required unless your workloads stay under the free limit. You can also a keyless connection if you're using the most recent preview API or beta packages. For more information, see [Attach an Azure AI multi-service resource to a skillset](cognitive-search-attach-cognitive-services.md).
 
 ```python
 from azure.search.documents.indexes.models import (
