Text Groundedness Detection Operations - Detect Groundedness Options

Reference

Service:: Cognitive Services

API Version:: 2024-02-15-preview

Detect Groundedness
A synchronous API for the analysis of language model outputs to determine alignment with user-provided information or identify fictional content.

POST {endpoint}/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	Supported Cognitive Services endpoints (protocol and hostname, for example: https://.cognitiveservices.azure.com).
api-version	query	True	string	The API version to use for this operation.

Request Body

Name	Required	Type	Description
groundingSources	True	string[]	Leverages a vast array of grounding sources to validate AI-generated text. Limit: Restrictions on the total amount of grounding sources that can be analyzed in a single request are 55K characters.
text	True	string	The specific text that needs to be checked.
domain		GroundednessDomain	The domain of the text for analysis. Allowed values: Medical, Generic. This field is optional, with a default value of Generic.
llmResource		LLMResource	Connection details for the LLM resource. This field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored.
qna		QnAOptions	The user's question input in a QnA scenario. This field is optional, but if the task type is set to QnA, it becomes required.
reasoning		boolean	A value indicating if the output includes an explanation for the identified groundedness. This field is optional, with a default value of false.
task		GroundednessTask	The task type for the text analysis. Type of task: QnA, Summarization. This field is optional, with a default value of Summarization.

Responses

Name	Type	Description
200 OK	AnalyzeTextGroundednessResult	The request has succeeded.
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

AnalyzeTextGroundednessResult

The request has succeeded.

Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: application
Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token

Scopes

Name	Description
https://cognitiveservices.azure.com/.default

Examples

Detect Groundedness

Sample request

HTTP

POST {endpoint}/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview

{
  "domain": "Generic",
  "task": "Summarization",
  "text": "The sun rises from the west.",
  "groundingSources": [
    "The sun rises from the east due to the visual effect caused by the Earth"
  ],
  "reasoning": true,
  "llmResource": {
    "resourceType": "AzureOpenAI",
    "azureOpenAIEndpoint": "https://your-azure-openai-name.openai.azure.com",
    "azureOpenAIDeploymentName": "deployment-1130"
  }
}

Sample response

Status code:: 200

{
  "ungroundedDetected": true,
  "ungroundedPercentage": 0,
  "ungroundedDetails": [
    {
      "text": "string",
      "offset": {
        "utf8": 0,
        "utf16": 0,
        "codePoint": 0
      },
      "length": {
        "utf8": 28,
        "utf16": 28,
        "codePoint": 28
      },
      "reason": "The sun rises from the east due to the visual effect caused by the Earth"
    }
  ]
}

Definitions

Name	Description
AnalyzeTextGroundednessOptions	The request of groundedness detection.
AnalyzeTextGroundednessResult	The response of groundedness detection.
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
GroundednessDomain	The domain of the text for analysis. Allowed values: Medical, Generic. This field is optional, with a default value of Generic.
GroundednessTask	The task type for the text analysis. Type of task: QnA, Summarization. This field is optional, with a default value of Summarization.
IndexDetails	The index details.
LLMResource	Connection details for the LLM resource.
LLMResourceType	LLM resource type. The default value is AzureOpenAI.
QnAOptions	The request of QnA options.
UngroundednessDetails	The detailed information about a text identified as ungroundedness.

AnalyzeTextGroundednessOptions

The request of groundedness detection.

Name	Type	Default value	Description
domain	GroundednessDomain	Generic	The domain of the text for analysis. Allowed values: Medical, Generic. This field is optional, with a default value of Generic.
groundingSources	string[]		Leverages a vast array of grounding sources to validate AI-generated text. Limit: Restrictions on the total amount of grounding sources that can be analyzed in a single request are 55K characters.
llmResource	LLMResource		Connection details for the LLM resource. This field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored.
qna	QnAOptions		The user's question input in a QnA scenario. This field is optional, but if the task type is set to QnA, it becomes required.
reasoning	boolean		A value indicating if the output includes an explanation for the identified groundedness. This field is optional, with a default value of false.
task	GroundednessTask	Summarization	The task type for the text analysis. Type of task: QnA, Summarization. This field is optional, with a default value of Summarization.
text	string		The specific text that needs to be checked.

AnalyzeTextGroundednessResult

The response of groundedness detection.

Name	Type	Description
ungroundedDetails	UngroundednessDetails[]	Provides insights into ungrounded content with specific examples and percentages.
ungroundedDetected	boolean	Indicates whether the text exhibits ungroundedness.
ungroundedPercentage	number	Specifies the proportion of the text identified as ungrounded, expressed as a decimal between 0 and 1, where 0 indicates no grounded content and 1 indicates entirely grounded content..

Azure.Core.Foundations.Error

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

GroundednessDomain

The domain of the text for analysis. Allowed values: Medical, Generic. This field is optional, with a default value of Generic.

Name	Type	Description
Generic	string
Medical	string

GroundednessTask

The task type for the text analysis. Type of task: QnA, Summarization. This field is optional, with a default value of Summarization.

Name	Type	Description
QnA	string
Summarization	string

IndexDetails

The index details.

Name	Type	Description
codePoint	integer	Indicate the index with code point format.
utf16	integer	Indicate the index when encoding is UTF-16.
utf8	integer	Indicate the index when encoding is UTF-8.

LLMResource

Connection details for the LLM resource.

Name	Type	Default value	Description
azureOpenAIDeploymentName	string		Deployment model name.
azureOpenAIEndpoint	string		Endpoint for Azure OpenAI resource.
resourceType	LLMResourceType	AzureOpenAI	LLM resource type. The default value is AzureOpenAI.

LLMResourceType

LLM resource type. The default value is AzureOpenAI.

Name	Type	Description
AzureOpenAI	string	Azure OpenAI resource type.

QnAOptions

The request of QnA options.

Name	Type	Description
query	string	The user's question input in a QnA scenario.

UngroundednessDetails

The detailed information about a text identified as ungroundedness.

Name	Type	Description
length	IndexDetails	The length of the grounded text.
offset	IndexDetails	The offset when grounded text starts.
reason	string	The explanation for detected ungroundedness, enhancing understanding. Only when the 'reasoning' field in the input is set to true 'reason' field will be returned.
text	string	The grounded text.

Share via

Text Groundedness Detection Operations - Detect Groundedness Options

URI Parameters

Request Body

Responses

Security

Ocp-Apim-Subscription-Key

OAuth2Auth

Scopes

Examples

Detect Groundedness

Sample request

Sample response

Definitions

AnalyzeTextGroundednessOptions

AnalyzeTextGroundednessResult

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

GroundednessDomain

GroundednessTask

IndexDetails

LLMResource

LLMResourceType

QnAOptions

UngroundednessDetails

Additional resources