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 |
No |
max_wait |
int |
The maximum wait time (in seconds) in-between HTTP requests. Default value is |
No |
parse_response |
bool |
Should the full API JSON output be parsed to extract the single task result. Default value is |
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 |
|
The input document. |
Yes |
|
query |
string |
The query used to structure summarization. |
Yes |
|
summary_length |
string (enum) |
The desired summary length. Enum values are |
No |
Extractive Summarization |
Name |
Type |
Description |
Required |
---|---|---|---|---|
connection |
CustomConnection |
The created connection to an Azure AI Language resource. |
Yes |
|
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 |
No |
|
sort_by |
string (enum) |
The sorting criteria for extractive summarization results. Enum values are |
No |
Conversation Summarization |
Name |
Type |
Description |
Required |
---|---|---|---|---|
connection |
CustomConnection |
The created connection to an Azure AI Language resource. |
Yes |
|
conversation |
|
The input conversation. |
Yes |
|
summary_aspect |
string (enum) |
The desired summary “aspect” to obtain. Enum values are |
Yes |
Entity Recognition |
Name |
Type |
Description |
Required |
---|---|---|---|---|
connection |
CustomConnection |
The created connection to an Azure AI Language resource. |
Yes |
|
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 |
|
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 |
|
The input document. |
Yes |
|
domain |
string (enum) |
The PII domain used for PII Entity Recognition. Enum values are |
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 |
|
The input conversation. |
Yes |
|
pii_categories |
list[string] |
Describes the PII categories to return for detection. Default value is |
No |
|
redact_audio_timing |
bool |
Should audio stream offset and duration for any detected entities be redacted. Default value is |
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 |
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 |
|
The input document. |
Yes |
|
opinion_mining |
bool |
Should opinion mining be enabled. Default value is |
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 |
No |
|
text_type |
string (enum) |
The type of the text being translated. Possible values are |
No |
Outputs#
When the input parameter
parse_response
is set toFalse
(default value), the full API JSON response will be returned (as adict
object).When the input parameter
parse_response
is set toTrue
, 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 adict
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.