Attach a Cognitive Services resource to a skillset in Azure Cognitive Search

Article
09/16/2022
5 minutes to read

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

A multi-service resource references "Cognitive 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 Microsoft to charge you for using these APIs:

Computer Vision for image analysis and optical character recognition (OCR)
Language service for language detection, entity recognition, sentiment analysis, and key phrase extraction
Translator for machine text translation

Tip

Azure provides infrastructure for you to monitor billing and budgets. For more information about monitoring Cognitive Services, see Plan and manage costs for Azure Cognitive Services.

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 will attempt to use the free enrichments available to your indexer on a daily basis. Execution of billable skills will stop at 20 transactions per indexer invocation and a "Time Out" message will appear in indexer execution history.

Sign in to Azure portal.
Create a multi-service Cognitive Services 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 Cognitive Services tab.

Create a multi-service Cognitive Services 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.windows.net/skillsets/[skillset name]?api-version=2020-06-30
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);

How the key is used

Key-based billing applies when API calls to Cognitive Services resources exceed 20 API calls per indexer, per day.

The key is used for billing, but not connections. For connections, a search service connects over the internal network to a Cognitive Services resource that's co-located in the same physical region. Most regions that offer Cognitive Search also offer Cognitive Services.

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."

Note

Some built-in skills are based on non-regional Cognitive 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 Cognitive Search region. For more information on non-regional services, see the Cognitive Services product by region page.

Key requirements special cases

Custom Entity Lookup is metered by Azure Cognitive Search, not Cognitive Services, but it requires a Cognitive Services 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 a Cognitive Services 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 Cognitive 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 non-billable. Text extraction occurs during the document cracking phase and isn't technically an enrichment, but it occurs during AI enrichment and is thus noted here.

Billable enrichments

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

Billable built-in skills that make backend calls to Cognitive 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 Cognitive 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 Cognitive Search pricing page.

Tip

To lower the cost of skillset processing, enable incremental enrichment (preview) 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 Cognitive 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 prices of transactions, see See Cognitive 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.