Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Use contextual grounding check to filter hallucinations in responses

Amazon Bedrock Guardrails supports contextual grounding checks to detect and filter hallucinations in model responses when a reference source and a user query is provided. The supported use cases include summarization, paraphrasing, and question answering. Standard tier also supports responses that include reasoning or conversational content. Classic tier does not support conversational use cases. For more information, see Safeguard tiers for contextual grounding checks on this page.

Contextual grounding checks check for relevance for each chunk processed. If any one chunk is deemed relevant, the whole response is considered relevant as it has the answer to user's query. For streaming API, this can result in scenario where an irrelevant response is returned to the user and is only marked as irrelevant after the whole response is streamed.

Contextual grounding checks the following paradigms:

Consider an example where the reference source contains "London is the capital of UK. Tokyo is the capital of Japan" and the user query is "What is the capital of Japan?". A response such as "The capital of Japan is London" will be considered ungrounded and factually incorrect, where as a response such as "The capital of UK is London" will be considered irrelevant, even if it's correct and grounded in the source.

Safeguard tiers for contextual grounding checks

Contextual grounding checks support two safeguard tiers. The tier determines how the check evaluates responses and which languages it supports.

Classic tier evaluates strict grounding. Any information in the response that is not stated in the grounding source lowers the grounding score, including reasonable inferences and conversational phrasing. Classic tier supports English, French, and Spanish.

Standard tier provides a more robust solution than Classic tier, with support for responses that include reasoning or conversational content. Standard tier returns more consistent scores for differently worded responses that have the same meaning. It supports the same languages as Standard tier content filters. For more information, see Languages supported by Amazon Bedrock Guardrails. Standard tier requires that your guardrail use cross-Region inference. Standard tier for contextual grounding checks is available in a subset of the AWS Regions that support safeguard tiers. For the list, see Supported Regions for safeguard tiers.

If you don't specify a tier, your guardrail uses Classic tier. The maximum lengths for the grounding source, query, and response are the same in both tiers.

Scores and thresholds

Contextual grounding checks generate a grounding score and a relevance score for each model response, based on the grounding source and user query that you provide. You can configure thresholds to filter model responses based on the generated scores. The filtering threshold determines the minimum score for the model response to be considered as grounded and relevant in your generative AI application. For example, if your grounding threshold and relevance threshold are each set at 0.7, all model responses with a grounding or relevance score of less than 0.7 will be detected as hallucinations and blocked in your application. As the filtering threshold is increased, the likelihood of blocking un-grounded and irrelevant content increases, and the probability of seeing hallucinated content in your application decreases. You can configure threshold values of grounding and relevance between 0 and 0.99. A threshold of 1 is invalid as that will block all content.

Contextual grounding checks require 3 components to perform the check: the grounding source, the query, and the content to guard (or the model response). These are configured differently depending on whether you are using Invoke APIs, Converse APIs, or ApplyGuardrail directly.

Ungrounded example

In this example, the content to guard is relevant to the query but is ungrounded as it does not use the grounding source correctly. This would have a low grounding score.

Irrelevant example

In this example, the content to guard is grounded but not relevant. It uses information from the grounding source but does not answer the query. This would have a low relevance score.

Ungrounded and irrelevant example

In this example, the content to guard is not grounded and not relevant. It neither uses information from the grounding source nor does it answer the query. This would have a low grounding and relevance score.

More Examples

Consider a banking application that is designed to answer questions associated with fees and charges.

Source:

Based on the above source, there can be four scenarios depending on the user's query.

Grounded and Relevant

Un-grounded but Relevant

Grounded but Irrelevant

Un-grounded and Irrelevant

Add contextual grounding checks with the console

Configure contextual grounding checks with the API

Configure contextual grounding checks for your guardrail by sending a CreateGuardrail request. The request format is as follows:

POST /guardrails HTTP/1.1
Content-type: application/json

{
   "blockedInputMessaging": "string",
   "blockedOutputsMessaging": "string",
   "contextualGroundingPolicyConfig": {
      "filtersConfig": [
         {
            "type": "GROUNDING | RELEVANCE",
            "threshold": number,
            "action": "BLOCK | NONE",
            "enabled": true
         }
      ],
      "tierConfig": {
         "tierName": "CLASSIC | STANDARD"
      }
   },
   "crossRegionConfig": {
      "guardrailProfileIdentifier": "string"
   },
   "description": "string",
   "name": "string"
}

Calling contextual grounding check with Invoke APIs

To mark the grounding source and query within the input, use the following tags that work the same way as input tags. These tags are amazon-bedrock-guardrails-groundingSource_xyz and amazon-bedrock-guardrails-query_xyz, where xyz is the tag suffix. For example:

{
    "text": """
<amazon-bedrock-guardrails-groundingSource_xyz>London is the capital of UK. Tokyo is the capital of Japan. </amazon-bedrock-guardrails-groundingSource_xyz>

<amazon-bedrock-guardrails-query_xyz>What is the capital of Japan?</amazon-bedrock-guardrails-query_xyz>
""",
    "amazon-bedrock-guardrailConfig": {
        "tagSuffix": "xyz",
    },
}    
        

Note that the model response is required to perform the contextual grounding checks and so the checks will only be performed on output and not on the prompt.

These tags can be used alongside the guardContent tags. Content inside groundingSource and query tags is excluded from policy evaluations other than contextual grounding (word filters, topic filters, content filters, sensitive information detection).

The behavior of the remaining policies depends on whether you use guardContent tags:

To have grounding source or query content also evaluated by the remaining policies, nest the contextual grounding tag inside a guardContent tag:

<amazon-bedrock-guardrails-guardContent_xyz><amazon-bedrock-guardrails-groundingSource_xyz>London is the capital of UK. Tokyo is the capital of Japan.</amazon-bedrock-guardrails-groundingSource_xyz></amazon-bedrock-guardrails-guardContent_xyz>

<amazon-bedrock-guardrails-query_xyz>What is the capital of Japan?</amazon-bedrock-guardrails-query_xyz>
        

In this example, the grounding source content is both used as the contextual grounding reference source and evaluated by other policies because it is also wrapped in a guardContent tag.

Calling contextual grounding check with Converse APIs

To mark the grounding source and query for Converse APIs, use the qualifiers field in each guard content block. For example:

[
    {
        "role": "user",
        "content": [
            {
                "guardContent": {
                    "text": {
                        "text": "London is the capital of UK. Tokyo is the capital of Japan",
                        "qualifiers": ["grounding_source"],
                    }
                }
            },
            {
                "guardContent": {
                    "text": {
                        "text": "What is the capital of Japan?",
                        "qualifiers": ["query"],
                    }
                }
            },
        ],
    }
]
        

Note that the model response is required to perform the contextual grounding checks and so the checks will only be performed on output and not on the prompt.

The behavior of policies other than contextual grounding depends on the qualifiers assigned to each guardContent block:

If you want your grounding source or query content to also be evaluated by other guardrail policies, add guard_content to the qualifiers list alongside the contextual grounding qualifier.

Calling contextual grounding check with ApplyGuardrail API

Using contextual grounding check with ApplyGuardrail is similar to using it with the Converse APIs. To mark the grounding source and query for ApplyGuardrail, use the qualifiers field in each content block. However, because a model is not invoked with ApplyGuardrail, you must also provide an extra content block with the content to be guarded. This content block can be optionally qualified with guard_content and is equivalent to the model response in the Invoke* or Converse* APIs. For example:

[
    {
        "text": {
            "text": "London is the capital of UK. Tokyo is the capital of Japan",
            "qualifiers": [
                "grounding_source"
            ]
        }
    },
    {
        "text": {
            "text": "What is the capital of Japan?",
            "qualifiers": [
                "query"
            ]
        }
    },
    {
        "text": {
            "text": "The capital of Japan is Tokyo."
        }
    }
]
        

Note that the model response is required to perform the contextual grounding checks and so the checks will only be performed on output and not on the prompt.

How qualifiers affect policy evaluation

Content blocks with grounding_source or query qualifiers are evaluated only by the contextual grounding check. These blocks are excluded from all other guardrail policy evaluations (word filters, topic filters, content filters, sensitive information detection, and prompt attack detection).

To have a content block evaluated by both the contextual grounding check and other guardrail policies, use both qualifiers together. For example, specify ["grounding_source", "guard_content"] to mark a content block as a grounding source that is also subject to all other configured policies.

For policies other than contextual grounding to evaluate content, at least one content block must be unqualified or explicitly qualified with guard_content. A content block is unqualified when it has no qualifiers field.

The following table summarizes how each qualifier combination affects policy evaluation.