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 runtime.
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:

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

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

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

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

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

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

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

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.