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

When configuring an 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.

A resource key is specified in a skillset and allows Microsoft to charge you for using these APIs:

The key is used for billing, but not connections. Internally, a search service connects to a Cognitive Services resource that's co-located in the same physical region.

Key requirements

A resource key is required for billable built-in skills that are used more than 20 times a day on the same indexer. Skills that make backend calls to Cognitive Services include Entity Linking, Entity Recognition, Image Analysis, Key Phrase Extraction, Language Detection, OCR, PII Detection, Sentiment, or Text Translation.

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.

You can omit the key and the Cognitive Services section for skillsets that consist solely of custom skills or utility skills (Conditional, Document Extraction, Shaper, Text Merge, Text Split). You can also omit the section if your usage of billable skills is under 20 transactions per indexer per day.

How billing works

  • Azure Cognitive Search uses the Cognitive Services resource key you provide on a skillset to bill for image and text enrichment. Execution of billable skills is at the Cognitive Services pay-as-you go price.

  • Image extraction is an Azure Cognitive Search operation that occurs when documents are cracked prior to enrichment. Image extraction is billable on all tiers, with the exception of 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.

  • Text extraction also occurs during the document cracking phrase. It is not billable.

  • Skills that do not call Cognitive Services, including Conditional, Shaper, Text Merge, and Text Split skills, are not billable.

    As noted, Custom Entity Lookup is a special case in that it requires a key, but is metered by Cognitive Search.

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.

Same-region requirement

Both Cognitive Search and Cognitive Services must exist within the same physical region, as indicated on the product availability page. Most regions that offer Cognitive Search also offer Cognitive Services.

If you attempt AI enrichment in region that doesn't have both services, you'll see this message: "Provided key is not 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 non-regional services, see the Cognitive Services product by region page.

Use Free resources

You can use a limited, free processing option to complete the AI enrichment tutorial and quickstart exercises.

Free (Limited enrichments) resources are restricted to 20 documents per day, per indexer. You can reset the indexer to reset the counter.

If you are using the Import data wizard for AI enrichment, you'll find the "Attach Cognitive Services" options on the Add AI enrichment (Optional) page.

Expanded Attach Cognitive Services section

Use billable resources

For workloads that create more than 20 billable enrichments per day, make sure to attach a Cognitive Services resource.

If you're using the Import data wizard, you can configure a billable resource from the Add AI enrichment (Optional) page.

  1. Expand Attach Cognitive Services and then select Create new Cognitive Services resource. A new tab opens so that you can create the resource:

    Create a Cognitive Services resource

  2. In the Location list, select the same region that has your search service.

  3. In the Pricing tier list, select S0 to get the all-in-one collection of Cognitive Services features, including the Vision and Language features that back the built-in skills provided by Azure Cognitive Search.

    For the S0 tier, you can find rates for specific workloads on the Cognitive Services pricing page.

    • In the Select Offer list, make sure Cognitive Services is selected.
    • Under Language features, the rates for Text Analytics Standard apply to AI indexing.
    • Under Vision features, the rates for Computer Vision S1 apply.
  4. Select Create to provision the new Cognitive Services resource.

  5. Return to the previous tab. Select Refresh to show the Cognitive Services resource, and then select the resource:

    Select the Cognitive Services resource

  6. Expand the Add cognitive skills section to select the specific cognitive skills that you want to run on your data. Complete the rest of the wizard.

Attach an existing skillset to a Cognitive Services resource

If you have an existing skillset, you can attach it to a new or different Cognitive Services resource.

  1. On the search service overview page, select Skillsets:

    Skillsets tab

  2. Select the name of the skillset, and then select an existing resource or create a new one. Select OK to confirm your changes.

    Skillset resource list

    Remember that the Free (Limited enrichments) option limits you to 20 documents daily, and that you can use Create new Cognitive Services resource to provision a new billable resource. If you create a new resource, select Refresh to refresh the list of Cognitive Services resources, and then select the resource.

Attach Cognitive Services programmatically

When you're defining the skillset programmatically, add a cognitiveServices section to the skillset. In that section, include the key of the Cognitive Services resource that you want to associate with the skillset. Remember that the resource must be in the same region as your Azure Cognitive Search resource. Also include @odata.type, and set it to #Microsoft.Azure.Search.CognitiveServicesByKey.

The following example shows this pattern. Notice the cognitiveServices section at the end of the definition.

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

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.

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

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

  3. 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 equals 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.

Next steps