次の方法で共有


Text Groundedness Detection Operations - Detect Groundedness Options

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

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

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

{
  "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.