Skip to content

Commit e31aa79

Browse files
jbobackjboback
committed
note fix, overview reorg, rest api doc sample
1 parent 7d995c8 commit e31aa79

File tree

2 files changed

+136
-155
lines changed

2 files changed

+136
-155
lines changed

‎articles/ai-services/language-service/summarization/includes/quickstarts/rest-api.md

Lines changed: 121 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -371,144 +371,150 @@ curl -X GET $LANGUAGE_ENDPOINT/language/analyze-conversations/jobs/<my-job-id>?a
371371

372372
# [Document summarization](#tab/document-summarization)
373373

374-
|parameter |Description |
375-
|---------|---------|
376-
|`-X POST <endpoint>` | Specifies your endpoint for accessing the API. |
377-
|`-H Content-Type: application/json` | The content type for sending JSON data. |
378-
|`-H "Ocp-Apim-Subscription-Key:<key>` | Specifies the key for accessing the API. |
379-
|`-d <documents>` | The JSON containing the documents you want to send. |
374+
### Summarization sample document
380375

381-
The following cURL commands are executed from a BASH shell. Edit these commands with your own JSON values.
376+
For this project, you need a **source document** uploaded to your **source container**. You can download our [Microsoft Word sample document](https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/Language/native-document-summarization.docx) or [Adobe PDF](https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/Language/native-document-summarization.pdf) for this quickstart. The source language is English.
382377

383-
## Document summarization
378+
### Build the POST request
384379

385-
### Document extractive summarization example
380+
1. Using your preferred editor or IDE, create a new directory for your app named `native-document`.
381+
1. Create a new json file called **document-summarization.json** in your **native-document** directory.
386382

387-
The following example will get you started with document extractive summarization:
383+
1. Copy and paste the Document Summarization **request sample** into your `document-summarization.json` file. Replace **`{your-source-container-SAS-URL}`** and **`{your-target-container-SAS-URL}`** with values from your Azure portal Storage account containers instance:
388384

389-
1. Copy the command below 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.
385+
***Request sample***
390386

391-
```bash
392-
curl -i -X POST $LANGUAGE_ENDPOINT/language/analyze-text/jobs?api-version=2023-04-01 \
393-
-H "Content-Type: application/json" \
394-
-H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" \
395-
-d \
396-
'
397-
{
398-
"displayName": "Document ext Summarization Task Example",
399-
"analysisInput": {
400-
"documents": [
401-
{
402-
"id": "1",
403-
"language": "en",
404-
"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 Azure AI services, 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 will enable us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pre-trained 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."
405-
}
406-
]
407-
},
408-
"tasks": [
409-
{
410-
"kind": "ExtractiveSummarization",
411-
"taskName": "Document Extractive Summarization Task 1",
412-
"parameters": {
387+
```json
388+
{
389+
"kind": "ExtractiveSummarization",
390+
"parameters": {
413391
"sentenceCount": 6
414-
}
392+
},
393+
"analysisInput":{
394+
"documents":[
395+
{
396+
"source":{
397+
"location":"{your-source-blob-SAS-URL}"
398+
},
399+
"targets":
400+
{
401+
"location":"{your-target-container-SAS-URL}",
402+
}
403+
}
404+
]
415405
}
416-
]
417-
}
418-
'
419-
```
406+
}
407+
```
420408

421-
2. Open a command prompt window (for example: BASH).
409+
### Run the POST request
422410

423-
3. Paste the command from the text editor into the command prompt window, then run the command.
411+
Before you run the **POST** request, replace `{your-language-resource-endpoint}` and `{your-key}` with the endpoint value from your Azure portal Language resource instance.
424412

425-
4. Get the `operation-location` from the response header. The value will look similar to the following URL:
413+
> [!IMPORTANT]
414+
> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](/azure/key-vault/general/overview). For more information, *see* Azure AI services [security](/azure/ai-services/security-features).
426415
427-
```http
428-
https://<your-language-resource-endpoint>/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2023-04-01
429-
```
416+
***PowerShell***
430417

431-
5. 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:
418+
```powershell
419+
cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"
420+
```
421+
422+
***command prompt / terminal***
423+
424+
```bash
425+
curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"
426+
```
427+
428+
Here's a sample response:
429+
430+
```http
431+
HTTP/1.1 202 Accepted
432+
Content-Length: 0
433+
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
434+
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
435+
x-ms-region: West US 2
436+
Date: Thu, 25 Jan 2024 15:12:32 GMT
437+
```
438+
439+
### POST response (jobId)
440+
441+
You receive a 202 (Success) response that includes a read-only Operation-Location header. The value of this header contains a jobId that can be queried to get the status of the asynchronous operation and retrieve the results using a GET request:
442+
443+
:::image type="content" source="media/operation-location-result-id.png" alt-text="Screenshot showing the operation-location value in the POST response.":::
444+
445+
### Get analyze results (GET request)
446+
447+
1. After your successful **POST** request, poll the operation-location header returned in the POST request to view the processed data.
448+
449+
1. Here's the structure of the **GET** request:
450+
451+
```http
452+
GET {cognitive-service-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview
453+
```
454+
455+
1. Before you run the command, make these changes:
456+
457+
* Replace {**jobId**} with the Operation-Location header from the POST response.
458+
459+
* Replace {**your-language-resource-endpoint**} and {**your-key**} with the values from your Language service instance in the Azure portal.
460+
461+
### Get request
462+
463+
```powershell
464+
cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"
465+
```
432466

433467
```bash
434-
curl -X GET $LANGUAGE_ENDPOINT/language/analyze-text/jobs/<my-job-id>?api-version=2023-04-01 \
435-
-H "Content-Type: application/json" \
436-
-H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY"
468+
curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"
437469
```
438470

439-
### Text extractive summarization example JSON response
471+
#### Examine the response
472+
473+
You receive a 200 (Success) response with JSON output. The **status** field indicates the result of the operation. If the operation isn't complete, the value of **status** is "running" or "notStarted", and you should call the API again, either manually or through a script. We recommend an interval of one second or more between calls.
474+
475+
#### Sample response
440476

441477
```json
442478
{
443-
"jobId": "56e43bcf-70d8-44d2-a7a7-131f3dff069f",
444-
"lastUpdateDateTime": "2022-09-28T19:33:43Z",
445-
"createdDateTime": "2022-09-28T19:33:42Z",
446-
"expirationDateTime": "2022-09-29T19:33:42Z",
447-
"status": "succeeded",
448-
"errors": [],
449-
"displayName": "Text ext Summarization Task Example",
450-
"tasks": {
451-
"completed": 1,
452-
"failed": 0,
453-
"inProgress": 0,
454-
"total": 1,
455-
"items": [
479+
"jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
480+
"lastUpdatedDateTime": "2024-01-24T13:17:58Z",
481+
"createdDateTime": "2024-01-24T13:17:47Z",
482+
"expirationDateTime": "2024-01-25T13:17:47Z",
483+
"status": "succeeded",
484+
"errors": [],
485+
"tasks": {
486+
"completed": 1,
487+
"failed": 0,
488+
"inProgress": 0,
489+
"total": 1,
490+
"items": [
491+
{
492+
"kind": "ExtractiveSummarizationLROResults",
493+
"lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
494+
"status": "succeeded",
495+
"results": {
496+
"documents": [
456497
{
457-
"kind": "ExtractiveSummarizationLROResults",
458-
"taskName": "Text Extractive Summarization Task 1",
459-
"lastUpdateDateTime": "2022-09-28T19:33:43.6712507Z",
460-
"status": "succeeded",
461-
"results": {
462-
"documents": [
463-
{
464-
"id": "1",
465-
"sentences": [
466-
{
467-
"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.",
468-
"rankScore": 0.69,
469-
"offset": 0,
470-
"length": 160
471-
},
472-
{
473-
"text": "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).",
474-
"rankScore": 0.66,
475-
"offset": 324,
476-
"length": 192
477-
},
478-
{
479-
"text": "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.",
480-
"rankScore": 0.63,
481-
"offset": 517,
482-
"length": 203
483-
},
484-
{
485-
"text": "We believe XYZ-code will enable us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages.",
486-
"rankScore": 1.0,
487-
"offset": 721,
488-
"length": 134
489-
},
490-
{
491-
"text": "The goal is to have pre-trained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today.",
492-
"rankScore": 0.74,
493-
"offset": 856,
494-
"length": 159
495-
},
496-
{
497-
"text": "I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks.",
498-
"rankScore": 0.49,
499-
"offset": 1481,
500-
"length": 148
501-
}
502-
],
503-
"warnings": []
504-
}
505-
],
506-
"errors": [],
507-
"modelVersion": "latest"
498+
"id": "doc_0",
499+
"source": {
500+
"kind": "AzureBlob",
501+
"location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
502+
},
503+
"targets": [
504+
{
505+
"kind": "AzureBlob",
506+
"location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/ExtractiveSummarization-0001/input.result.json"
508507
}
508+
],
509+
"warnings": []
509510
}
510-
]
511-
}
511+
],
512+
"errors": [],
513+
"modelVersion": "2023-02-01-preview"
514+
}
515+
}
516+
]
517+
}
512518
}
513519
```
514520

‎articles/ai-services/language-service/summarization/overview.md

Lines changed: 15 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -69,31 +69,6 @@ This documentation contains the following article types:
6969
* **[Quickstarts](quickstart.md?pivots=rest-api&tabs=conversation-summarization)** are getting-started instructions to guide you through making requests to the service.
7070
* **[How-to guides](how-to/conversation-summarization.md)** contain instructions for using the service in more specific or customized ways.
7171

72-
# [Document summarization](#tab/document-summarization)
73-
74-
This documentation contains the following article types:
75-
76-
* **[Quickstarts](quickstart.md?pivots=rest-api&tabs=text-summarization)** are getting-started instructions to guide you through making requests to the service.
77-
* **[How-to guides](how-to/document-summarization.md)** contain instructions for using the service in more specific or customized ways.
78-
79-
Document summarization uses natural language processing techniques to generate a summary for documents. There are two supported API approaches to automatic summarization: extractive and abstractive.
80-
81-
---
82-
83-
# [Text summarization](#tab/text-summarization)
84-
85-
A native document refers to the file format used to create the original document such as Microsoft Word (docx) or a portable document file (pdf). Native document support eliminates the need for text preprocessing prior to using Azure AI Language resource capabilities. Currently, native document support is available for both [**AbstractiveSummarization**](../summarization/how-to/document-summarization.md#try-text-abstractive-summarization) and [**ExtractiveSummarization**](../summarization/how-to/document-summarization.md#try-text-extractive-summarization) capabilities.
86-
87-
Currently **Text Summarization** supports the following native document formats:
88-
89-
|File type|File extension|Description|
90-
|---------|--------------|-----------|
91-
|Text| `.txt`|An unformatted text document.|
92-
|Adobe PDF| `.pdf` |A portable document file formatted document.|
93-
|Microsoft Word|`.docx`|A Microsoft Word document file.|
94-
95-
For more information, *see* [**Use native documents for language processing**](../native-document-support/use-native-documents.md)
96-
9772
## Key features for conversation summarization
9873

9974
Conversation summarization supports the following features:
@@ -104,14 +79,6 @@ Conversation summarization supports the following features:
10479
* [**Narrative summarization**](how-to/conversation-summarization.md#get-narrative-summarization): Generates detail call notes, meeting notes or chat summaries of the input conversation.
10580
* [**Follow-up tasks**](how-to/conversation-summarization.md#get-narrative-summarization): Gives a list of follow-up tasks discussed in the input conversation.
10681

107-
## When to use issue and resolution summarization
108-
109-
* When there are aspects of an "issue" and "resolution" such as:
110-
* The reason for a service chat/call (the issue).
111-
* That resolution for the issue.
112-
* You only want a summary that focuses on related information about issues and resolutions.
113-
* When there are two participants in the conversation, and you want to summarize what each had said.
114-
11582
As an example, consider the following example conversation:
11683

11784
**Agent**: "*Hello, you're chatting with Rene. How may I help you?*"
@@ -139,16 +106,26 @@ Conversation summarization feature would simplify the text as follows:
139106
| Customer wants to use the wifi connection on their Smart Brew 300. But it didn't work. | One or two sentences | issue |
140107
| Checked if the power light is blinking slowly. Checked the Contoso coffee app. It had no prompt. Tried to do a factory reset. | One or more sentences, generated from multiple lines of the transcript. | resolution |
141108

142-
# [Conversation summarization](#tab/conversation-summarization)
109+
# [Document summarization](#tab/document-summarization)
143110

144-
No information currently available.
111+
This documentation contains the following article types:
145112

146-
# [Document summarization](#tab/document-summarization)
113+
* **[Quickstarts](quickstart.md?pivots=rest-api&tabs=text-summarization)** are getting-started instructions to guide you through making requests to the service.
114+
* **[How-to guides](how-to/document-summarization.md)** contain instructions for using the service in more specific or customized ways.
147115

148-
No information currently available.
116+
Document summarization uses natural language processing techniques to generate a summary for documents. There are two supported API approaches to automatic summarization: extractive and abstractive.
149117

150-
---
118+
A native document refers to the file format used to create the original document such as Microsoft Word (docx) or a portable document file (pdf). Native document support eliminates the need for text preprocessing prior to using Azure AI Language resource capabilities. Currently, native document support is available for both [**AbstractiveSummarization**](../summarization/how-to/document-summarization.md#try-text-abstractive-summarization) and [**ExtractiveSummarization**](../summarization/how-to/document-summarization.md#try-text-extractive-summarization) capabilities.
151119

120+
Currently **Text Summarization** supports the following native document formats:
121+
122+
|File type|File extension|Description|
123+
|---------|--------------|-----------|
124+
|Text| `.txt`|An unformatted text document.|
125+
|Adobe PDF| `.pdf` |A portable document file formatted document.|
126+
|Microsoft Word|`.docx`|A Microsoft Word document file.|
127+
128+
For more information, *see* [**Use native documents for language processing**](../native-document-support/use-native-documents.md)
152129

153130
## Get started with summarization
154131

@@ -171,10 +148,8 @@ No information currently available.
171148
* Summarization takes text for analysis. For more information, see [Data and service limits](../concepts/data-limits.md) in the how-to guide.
172149
* Summarization works with various written languages. For more information, see [language support](language-support.md?tabs=document-summarization).
173150

174-
175151
---
176152

177-
178153
## Reference documentation and code samples
179154

180155
As you use text summarization in your applications, see the following reference documentation and samples for Azure AI Language:

0 commit comments

Comments
 (0)