Edit

How to use summarization

Summarization condenses content that users consider too long to read. The service provides summarization solutions for three types of genre: plain text, conversations, and native documents. Select the tab that matches the type of content you want to summarize.

Text summarization shortens content that users consider too long to read. Both extractive and abstractive summarization condense articles, papers, or documents to key sentences.

Extractive summarization: Produces a summary by extracting sentences that collectively represent the most important or relevant information within the original content.

Abstractive summarization: Produces a summary by generating summarized sentences from the document that capture the main idea.

Query-focused summarization: Allows you to use a query when summarizing.

Each of these capabilities can summarize around specific items of interest when specified.

The service provides the AI models that the API uses. You just have to send content for analysis.

For easier navigation, here are links to the corresponding sections for each service:

Aspect Section
Extractive Extractive Summarization
Abstractive Abstractive Summarization
Query-focused Query-focused Summarization

Features

Tip

To start using these features, see the quickstart article. You can also make example requests by using Microsoft Foundry without needing to write code.

The extractive summarization API uses natural language processing techniques to locate key sentences in an unstructured text document. These sentences collectively convey the main idea of the document.

Extractive summarization returns a rank score as part of the system response along with extracted sentences and their position in the original documents. A rank score indicates how relevant a sentence is to the main idea of a document. The model gives a score between 0 and 1 (inclusive) to each sentence and returns the highest scored sentences per request. For example, if you request a three-sentence summary, the service returns the three highest scored sentences.

Another feature in Azure Language in Foundry Tools, key phrase extraction, can extract key information. When deciding between key phrase extraction and extractive summarization, consider these factors:

  • Key phrase extraction returns phrases while extractive summarization returns sentences.
  • Extractive summarization returns sentences together with a rank score, and top ranked sentences are returned per request.
  • Extractive summarization also returns the following positional information:
    • Offset: The start position of each extracted sentence.
    • Length: The length of each extracted sentence.

Determine how to process the data (optional)

Submitting data

Submit documents to the API as strings of text. The API performs analysis upon receipt of the request. Because the API is asynchronous, there might be a delay between sending an API request and receiving the results.

When you use this feature, the API results are available for 24 hours from the time the request is ingested, and the response indicates this availability. After this time period, the results are purged and are no longer available for retrieval.

Getting text summarization results

When you get results from language detection, you can stream the results to an application or save the output to a file on the local system.

The following example shows content you might submit for summarization. The content is extracted from the Microsoft blog article A holistic representation toward integrative AI. This article is only an example. The API can accept longer input text. For more information, see data and service limits.

"At Microsoft, we are on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Foundry Tools, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that's closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."

The text summarization API request is processed upon receipt of the request by creating a job for the API backend. If the job succeeded, the output of the API is returned. The output is available for retrieval for 24 hours. After this time, the output is purged. Due to multilingual and emoji support, the response might contain text offsets. For more information, see how to process offsets.

When you use the preceding example, the API might return these summarized sentences:

Extractive summarization:

  • "At Microsoft, we're on a quest to advance AI beyond existing techniques by taking a more holistic, human-centric approach to learning and understanding."
  • "We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages."
  • "The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today."

Abstractive summarization:

  • "Microsoft is taking a more holistic, human-centric approach to learning and understanding. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. Over the past five years, we achieved human performance on key benchmarks."

Try text extractive summarization

You can use text extractive summarization to get summaries of articles, papers, or documents. To see an example, see the quickstart article.

Use the sentenceCount parameter to guide how many sentences are returned, with 3 being the default. The range is from 1 to 20.

Use the sortby parameter to specify in what order the extracted sentences are returned—either Offset or Rank, with Offset being the default.

Parameter value Description
Rank Order sentences according to their relevance to the input document, as decided by the service.
Offset Keeps the original order in which the sentences appear in the input document.

Try text abstractive summarization

The following example shows how to get started with text abstractive summarization:

  1. Copy the following command into a text editor. The BASH example uses the \ line continuation character. If your console or terminal uses a different line continuation character, use that character instead.
curl -i -X POST https://<your-language-resource-endpoint>/language/analyze-text/jobs?api-version=2023-04-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
' 
{
  "displayName": "Text Abstractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Foundry Tools, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
  "tasks": [
    {
      "kind": "AbstractiveSummarization",
      "taskName": "Text Abstractive Summarization Task 1",
    }
  ]
}
'

  1. Make the following changes in the command where needed:

    • Replace the value your-language-resource-key with your key.
    • Replace the first part of the request URL your-language-resource-endpoint with your endpoint URL.

  2. Open a command prompt window (for example: BASH).

  3. Paste the command from the text editor into the command prompt window, and then run the command.

  4. Get the operation-location from the response header. The value looks similar to the following URL:

https://<your-language-resource-endpoint>/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-10-01-preview
  1. To get the results of the request, use the following cURL command. Be sure to replace <my-job-id> with the numerical ID value you received from the previous operation-location response header:
curl -X GET https://<your-language-resource-endpoint>/language/analyze-text/jobs/<my-job-id>?api-version=2022-10-01-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>"

Abstractive text summarization example JSON response

{
    "jobId": "cd6418fe-db86-4350-aec1-f0d7c91442a6",
    "lastUpdateDateTime": "2022-09-08T16:45:14Z",
    "createdDateTime": "2022-09-08T16:44:53Z",
    "expirationDateTime": "2022-09-09T16:44:53Z",
    "status": "succeeded",
    "errors": [],
    "displayName": "Text Abstractive Summarization Task Example",
    "tasks": {
        "completed": 1,
        "failed": 0,
        "inProgress": 0,
        "total": 1,
        "items": [
            {
                "kind": "AbstractiveSummarizationLROResults",
                "taskName": "Text Abstractive Summarization Task 1",
                "lastUpdateDateTime": "2022-09-08T16:45:14.0717206Z",
                "status": "succeeded",
                "results": {
                    "documents": [
                        {
                            "summaries": [
                                {
                                    "text": "Microsoft is taking a more holistic, human-centric approach to AI. We've developed a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We've achieved human performance on benchmarks in conversational speech recognition, machine translation, ...... and image captions.",
                                    "contexts": [
                                        {
                                            "offset": 0,
                                            "length": 247
                                        }
                                    ]
                                }
                            ],
                            "id": "1"
                        }
                    ],
                    "errors": [],
                    "modelVersion": "latest"
                }
            }
        ]
    }
}
Parameter Description
-X POST <endpoint> Specifies your endpoint for accessing the API.
-H Content-Type: application/json The content type for sending JSON data.
-H "Ocp-Apim-Subscription-Key:<key> Specifies the key for accessing the API.
-d <documents> The JSON containing the documents you want to send.

The following cURL commands are executed from a BASH shell. Edit these commands with your own resource name, resource key, and JSON values.

Query based summarization

The query-based text summarization API is an extension to the existing text summarization API.

The biggest difference is a new query field in the request body (under tasks > parameters > query).

Tip

Query-based summarization has some differentiation in the utilization of length control based on the type of query based summarization you're using:

  • Query-based extractive summarization supports length control by specifying sentenceCount.
  • Query-based abstractive summarization doesn't support length control.

Here's an example request:

curl -i -X POST https://<your-language-resource-endpoint>/language/analyze-text/jobs?api-version=2023-11-15-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
' 
{
  "displayName": "Text Extractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Foundry Tools, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
"tasks": [
    {
      "kind": "AbstractiveSummarization",
      "taskName": "Query-based Abstractive Summarization",
      "parameters": {
          "query": "XYZ-code",
          "summaryLength": "short"
      }
    },    {
      "kind": "ExtractiveSummarization",
      "taskName": "Query_based Extractive Summarization",
      "parameters": {
          "query": "XYZ-code"
      }
    }
  ]
}
'

Summary length control

Using the summaryLength parameter in abstractive summarization

If you don't specify summaryLength, the model determines the summary length.

For the summaryLength parameter, three values are accepted:

  • oneSentence: Generates a summary of mostly one sentence, with around 80 tokens.
  • short: Generates a summary of mostly two to three sentences, with around 120 tokens.
  • medium: Generates a summary of mostly four to six sentences, with around 170 tokens.
  • long: Generates a summary of mostly over seven sentences, with around 210 tokens.

Here's an example request:

curl -i -X POST https://<your-language-resource-endpoint>/language/analyze-text/jobs?api-version=2023-04-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
' 
{
  "displayName": "Text Abstractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Foundry Tools, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
  "tasks": [
    {
      "kind": "AbstractiveSummarization",
      "taskName": "Length controlled Abstractive Summarization",
          "parameters": {
          "summaryLength": "short"
      }
    }
  ]
}
'

Using the sentenceCount parameter in extractive summarization

For the sentenceCount parameter, enter a value from 1 to 20 to indicate the desired number of output sentences.

Here's an example request:

curl -i -X POST https://<your-language-resource-endpoint>/language/analyze-text/jobs?api-version=2023-11-15-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
' 
{
  "displayName": "Text Extractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Foundry Tools, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
"tasks": [
    {
      "kind": "ExtractiveSummarization",
      "taskName": "Length controlled Extractive Summarization",
      "parameters": {
          "sentenceCount": "5"
      }
    }
  ]
}
'

Service and data limits

For information on the size and number of requests you can send per minute and second, see the service limits article.

See also

  • Last updated on