Azure AI Language#

Azure AI Language enables users with task-oriented and optimized pre-trained or custom language models to effectively understand and analyze documents and conversations. This Prompt flow tool is a wrapper for various Azure AI Language APIs. The current list of supported capabilities is as follows:

Name

Description

Abstractive Summarization

Generate abstractive summaries from documents.

Extractive Summarization

Extract summaries from documents.

Conversation Summarization

Summarize conversations.

Entity Recognition

Recognize and categorize entities in documents.

Key Phrase Extraction

Extract key phrases from documents.

Language Detection

Detect the language of documents.

PII Entity Recognition

Recognize and redact PII entities in documents.

Conversational PII

Recognize and redact PII entities in conversations.

Sentiment Analysis

Analyze the sentiment of documents.

Conversational Language Understanding

Predict intents and entities from user’s utterances.

Translator

Translate documents.

Requirements#

PyPI package: promptflow-azure-ai-language.

  • For AzureML users: follow this wiki, starting from Prepare compute session.

  • For local users:

    pip install promptflow-azure-ai-language
    

    You may also want to install the Prompt flow for VS Code extension.

Prerequisites#

The tool calls APIs from Azure AI Language. To use it, you must create a connection to an Azure AI Language resource. Create a Language Resource first, if necessary.

  • In Prompt flow, add a new CustomConnection.

    • Under the secrets field, specify the resource’s API key: api_key: <Azure AI Language Resource api key>

    • Under the configs field, specify the resource’s endpoint: endpoint: <Azure AI Language Resource endpoint>

To use the Translator tool, you must set up an additional connection to an Azure AI Translator resource. Create a Translator resource first, if necessary.

  • In Prompt flow, add a new CustomConnection.

    • Under the secrets field, specify the resource’s API key: api_key: <Azure AI Translator Resource api key>

    • Under the configs field, specify the resource’s endpoint: endpoint: <Azure AI Translator Resource endpoint>

    • If your Translator Resource is regional and non-global, specify its region under configs as well: region: <Azure AI Translator Resource region>

Inputs#

When a tool parameter is of type Document, it requires a dict object of this specification.

Example:

my_document = {
    "id": "1",
    "text": "This is some document text!",
    "language": "en"
}

When a tool parameter is of type Conversation, it requires a dict object.

Example:

my_conversation = {
    "id": "meeting_1",
    "language": "en",
    "modality": "text",
    "domain": "generic",
    "conversationItems": [
        {
            "participantId": "person1",
            "role": "generic",
            "id": "1",
            "text": "Hello!"
        },
        {
            "participantId": "person2",
            "role": "generic",
            "id": "2",
            "text": "How are you?"
        }
    ]
}

All skills have the following (optional) inputs:

Name

Type

Description

Required

max_retries

int

The maximum number of HTTP request retries. Default value is 5.

No

max_wait

int

The maximum wait time (in seconds) in-between HTTP requests. Default value is 60.

No

parse_response

bool

Should the full API JSON output be parsed to extract the single task result. Default value is False.

No

HTTP request logic utilizes exponential backoff. See skill specific inputs below:


Abstractive Summarization

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

document

Document

The input document.

Yes

query

string

The query used to structure summarization.

Yes

summary_length

string (enum)

The desired summary length. Enum values are short, medium, and long.

No


Extractive Summarization

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

document

Document

The input document.

Yes

query

string

The query used to structure summarization.

Yes

sentence_count

int

The desired number of output summary sentences. Default value is 3.

No

sort_by

string (enum)

The sorting criteria for extractive summarization results. Enum values are Offset to sort results in order of appearance in the text and Rank to sort results in order of importance (i.e. rank score) according to model. Default value is Offset.

No


Conversation Summarization

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

conversation

Conversation

The input conversation.

Yes

summary_aspect

string (enum)

The desired summary “aspect” to obtain. Enum values are chapterTitle to obtain the chapter title of any conversation, issue to obtain the summary of issues in transcripts of web chats and service calls between customer-service agents and customers, narrative to obtain the generic summary of any conversation, resolution to obtain the summary of resolutions in transcripts of web chats and service calls between customer-service agents and customers, recap to obtain a general summary, and follow-up tasks to obtain a summary of follow-up or action items.

Yes


Entity Recognition

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

document

Document

The input document.

Yes


Key Phrase Extraction

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

document

Document

The input document.

Yes


Language Detection

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

text

string

The input text.

Yes


PII Entity Recognition

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

document

Document

The input document.

Yes

domain

string (enum)

The PII domain used for PII Entity Recognition. Enum values are none for no domain, or phi to indicate that entities in the Personal Health domain should be redacted. Default value is none.

No

pii_categories

list[string]

Describes the PII categories to return.

No


Conversational PII

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

conversation

Conversation

The input conversation.

Yes

pii_categories

list[string]

Describes the PII categories to return for detection. Default value is ['Default'].

No

redact_audio_timing

bool

Should audio stream offset and duration for any detected entities be redacted. Default value is False.

No

redaction source

string (enum)

For transcript conversations, this parameter provides information regarding which content type should be used for entity detection. The details of the entities detected - such as the offset, length, and the text itself - will correspond to the text type selected here. Enum values are lexical, itn, maskedItn, and text. Default value is lexical.

No

exclude_pii_categories

list[string]

Describes the PII categories to exclude for detection. Default value is [].

No


Sentiment Analysis

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

document

Document

The input document.

Yes

opinion_mining

bool

Should opinion mining be enabled. Default value is False.

No


Conversational Language Understanding

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Language resource.

Yes

language

string

The ISO 639-1 code for the language of the input.

Yes

utterances

string

A single user utterance or a json array of user utterances.

Yes

project_name

string

The Conversational Language Understanding project to be called.

Yes

deployment_name

string

The Conversational Language Understanding project deployment to be called.

Yes


Translator

Name

Type

Description

Required

connection

CustomConnection

The created connection to an Azure AI Translator resource.

Yes

text

string

The input text.

Yes

to

list[string]

The languages to translate the input text to.

Yes

source_language

string

The language of the input text.

No

category

string

The category (domain) of the translation. This parameter is used to get translations from a customized system built with Custom Translator. Default value is general.

No

text_type

string (enum)

The type of the text being translated. Possible values are plain (default) or html.

No

Outputs#

  • When the input parameter parse_response is set to False (default value), the full API JSON response will be returned (as a dict object).

  • When the input parameter parse_response is set to True, the full API JSON response will be parsed to extract the single task result associated with the tool’s given skill. Output will depend on the skill (but will still be a dict object).

  • Note: for Conversational Language Understanding (CLU), output will be a list of responses (either full or parsed), one for each detected user utterance in the input.

Refer to Azure AI Language’s REST API reference for details on API response format, specific task result formats, etc.

Sample Flows#

Find example flows using the promptflow-azure-ai-language package here.

Contact#

Please reach out to Azure AI Language (taincidents@microsoft.com) with any issues.