Attach an Azure AI multi-service resource to a skillset in Azure AI Search

Article
10/21/2024

When configuring an optional AI enrichment pipeline in Azure AI Search, you can enrich a limited number of documents free of charge. For larger and more frequent workloads, you should attach a billable Azure AI multi-service resource.

A multi-service resource references a set of Azure AI services as the offering, rather than individual services, with access granted through a single API key. This key is specified in a skillset and allows Azure to charge you for using these services:

Azure AI Vision for image analysis and optical character recognition (OCR)
Azure AI Language for language detection, entity recognition, sentiment analysis, and key phrase extraction
Azure AI Speech for speech to text and text to speech
Azure AI Translator for machine text translation

Set the resource key

You can use the Azure portal, REST API, or an Azure SDK to attach a billable resource 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.

Sign in to the Azure portal.
Create an Azure AI multi-service resource in the same region as your search service.
Add the key to a skillset definition:
- If using the Import data wizard, enter the key in the second step, "Add AI enrichments".
- If adding the key to a new or existing skillset, provide the key in the Azure AI services tab.

Create an Azure AI multi-service resource in the same region as your search service.
Create or update a skillset, specifying cognitiveServices section in the body of the skillset request:

PUT https://[servicename].search.azure.cn/skillsets/[skillset name]?api-version=2024-07-01
api-key: [admin key]
Content-Type: application/json
{
    "name": "skillset name",
    "skills": 
    [
      {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "categories": [ "Organization" ],
        "defaultLanguageCode": "en",
        "inputs": [
          {
            "name": "text", "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "organizations", "targetName": "organizations"
          }
        ]
      }
    ],
    "cognitiveServices": {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "mycogsvcs",
        "key": "<your key goes here>"
    }
}

The following code snippet is from azure-search-dotnet-samples, trimmed for brevity.

IConfigurationBuilder builder = new ConfigurationBuilder().AddJsonFile("appsettings.json");
IConfigurationRoot configuration = builder.Build();

string searchServiceUri = configuration["SearchServiceUri"];
string adminApiKey = configuration["SearchServiceAdminApiKey"];
string cognitiveServicesKey = configuration["CognitiveServicesKey"];

SearchIndexerClient indexerClient = new SearchIndexerClient(new Uri(searchServiceUri), new AzureKeyCredential(adminApiKey));

// Create the skills
Console.WriteLine("Creating the skills...");
OcrSkill ocrSkill = CreateOcrSkill();
MergeSkill mergeSkill = CreateMergeSkill();

// Create the skillset
Console.WriteLine("Creating or updating the skillset...");
List<SearchIndexerSkill> skills = new List<SearchIndexerSkill>();
skills.Add(ocrSkill);
skills.Add(mergeSkill);

SearchIndexerSkillset skillset = CreateOrUpdateDemoSkillSet(indexerClient, skills, cognitiveServicesKey);

Remove the key

Enrichments are billable operations. If you no longer need to call Azure AI services, follow these instructions to remove the multi-region key and prevent use of the external resource. Without the key, the skillset reverts to the default allocation of 20 free transactions per indexer, per day. Execution of billable skills stops at 20 transactions and a "Time Out" message appears in indexer execution history when the allocation is used up.

Azure portal
REST

Sign in to the Azure portal and open the search service Overview page.
Under Skillsets, select the skillset containing the key you want to remove.
Scroll to the end of the file.
Remove the key from the JSON and save the skillset.

Get Skillset so that you have the full definition.
Formulate an Update Skillset request, providing the JSON definition of the skillset.

Remove the key in the body of the definition, and then send the request:

PUT https://[servicename].search.azure.cn/skillsets/[skillset name]?api-version=2024-07-01
api-key: [admin key]
Content-Type: application/json
{
    "name": "skillset name",
    "skills": 
    [
      {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "categories": [ "Organization" ],
        "defaultLanguageCode": "en",
        "inputs": [
          {
            "name": "text", "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "organizations", "targetName": "organizations"
          }
        ]
      }
    ],
    "cognitiveServices": {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "mycogsvcs",
        "key": ""
    }
}

Alternatively, you can set "cognitiveServices" to null:

"cognitiveServices": null,

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.

The key is used for billing, but not for enrichment operations' connections. For connections, a search service connects over the internal network to an Azure AI services resource that's located in the same physical region. 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."

Currently, billing for built-in skills 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 implemented with an Azure Function that supports private endpoints and add the Azure AI services resource to the same VNET. In this way, you can call Azure AI services resource directly from the custom skill using private endpoints.

Note

Some built-in skills are based on non-regional Azure AI services (for example, the Text Translation Skill). Using a non-regional skill means that your request might be serviced in a region other than the Azure AI Search region. For more information on non-regional services, see the Azure AI services product by region page.

Key requirements special cases

Custom Entity Lookup is metered by Azure AI Search, not Azure AI services, but it requires an Azure AI multi-service resource key to unlock transactions beyond 20 per indexer, per day. For this skill only, the resource key unblocks the number of transactions, but is unrelated to billing.

Free enrichments

AI enrichment offers a small quantity of free processing of billable enrichments so that you can complete short exercises without having to attach an Azure AI multi-service resource. Free enrichments are 20 documents per day, per indexer. You can reset the indexer to reset the counter if you want to repeat an exercise.

Some enrichments are always free:

Utility skills that don't call Azure AI services (namely, Conditional, Document Extraction, Shaper, Text Merge, and Text Split skills) aren't billable.
Text extraction from PDF documents and other application files is nonbillable. Text extraction, which occurs during the document cracking, isn't an AI enrichment, but it occurs during AI enrichment and is thus noted here.

Billable enrichments

During AI enrichment, Azure AI Search calls the Azure AI services APIs for built-in skills that are based on Azure AI Vision, Translator, and Azure AI Language.

Billable built-in skills that make backend calls to Azure AI services include Entity Linking, Entity Recognition, Image Analysis, Key Phrase Extraction, Language Detection, OCR, Personally Identifiable Information (PII) Detection, Sentiment, and Text Translation.

Image extraction is an Azure AI Search operation that occurs when documents are cracked prior to enrichment. Image extraction is billable on all tiers, except for 20 free daily extractions on the free tier. Image extraction costs apply to image files inside blobs, embedded images in other files (PDF and other app files), and for images extracted using Document Extraction. For image extraction pricing, see the Azure AI Search pricing page.

Tip

To lower the cost of skillset processing, enable incremental enrichment to cache and reuse any enrichments that are unaffected by changes made to a skillset. Caching requires Azure Storage (see pricing but the cumulative cost of skillset execution is lower if existing enrichments can be reused, especially for skillsets that use image extraction and analysis.

Example: Estimate costs

To estimate the costs associated with Azure AI Search indexing, start with an idea of what an average document looks like so you can run some numbers. For example, you might approximate:

1,000 PDFs.
Six pages each.
One image per page (6,000 images).
3,000 characters per page.

Assume a pipeline that consists of document cracking of each PDF, image and text extraction, optical character recognition (OCR) of images, and entity recognition of organizations.

The prices shown in this article are hypothetical. They're used to illustrate the estimation process. Your costs could be lower. For the actual price of transactions, see Azure AI services pricing.

For document cracking with text and image content, text extraction is currently free. For 6,000 images, assume $1 for every 1,000 images extracted. That's a cost of $6.00 for this step.
For OCR of 6,000 images in English, the OCR cognitive skill uses the best algorithm (DescribeText). Assuming a cost of $2.50 per 1,000 images to be analyzed, you would pay $15.00 for this step.
For entity extraction, you'd have a total of three text records per page. Each record is 1,000 characters. Three text records per page multiplied by 6,000 pages equal 18,000 text records. Assuming $2.00 per 1,000 text records, this step would cost $36.00.

Putting it all together, you'd pay about $57.00 to ingest 1,000 PDF documents of this type with the described skillset.