Method: projects.locations.groundingConfigs.check

Performs a grounding check.

HTTP request

POST https://discoveryengine.googleapis.com/v1/{groundingConfig=projects/*/locations/*/groundingConfigs/*}:check

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
groundingConfig

string

Required. The resource name of the grounding config, such as projects/*/locations/global/groundingConfigs/default_grounding_config.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "answerCandidate": string,
  "facts": [
    {
      object (GroundingFact)
    }
  ],
  "groundingSpec": {
    object (CheckGroundingSpec)
  },
  "userLabels": {
    string: string,
    ...
  }
}
Fields
answerCandidate

string

Answer candidate to check. It can have a maximum length of 4096 tokens.
facts[]

object (GroundingFact)

List of facts for the grounding check. We support up to 200 facts.
groundingSpec

object (CheckGroundingSpec)

Configuration of the grounding check.
userLabels

map (key: string, value: string)

The user labels applied to a resource must meet the following requirements:

  • Each resource can have multiple labels, up to a maximum of 64.
  • Each label must be a key-value pair.
  • Keys have a minimum length of 1 character and a maximum length of 63 characters and cannot be empty. Values can be empty and have a maximum length of 63 characters.
  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed.
  • The key portion of a label must be unique. However, you can use the same key with multiple resources.
  • Keys must start with a lowercase letter or international character.

See Google Cloud Document for more details.

Response body

Response message for the GroundedGenerationService.CheckGrounding method.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "citedChunks": [
    {
      object (FactChunk)
    }
  ],
  "citedFacts": [
    {
      object (CheckGroundingFactChunk)
    }
  ],
  "claims": [
    {
      object (Claim)
    }
  ],
  "supportScore": number
}
Fields
citedChunks[]

object (FactChunk)

List of facts cited across all claims in the answer candidate. These are derived from the facts supplied in the request.
citedFacts[]

object (CheckGroundingFactChunk)

List of facts cited across all claims in the answer candidate. These are derived from the facts supplied in the request.
claims[]

object (Claim)

Claim texts and citation info across all claims in the answer candidate.
supportScore

number

The support score for the input answer candidate. Higher the score, higher is the fraction of claims that are supported by the provided facts. This is always set when a response is returned.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the groundingConfig resource:

  • discoveryengine.groundingConfigs.check

For more information, see the IAM documentation.

GroundingFact

Grounding Fact.

JSON representation 
{
  "factText": string,
  "attributes": {
    string: string,
    ...
  }
}
Fields
factText

string

Text content of the fact. Can be at most 10K characters long.
attributes

map (key: string, value: string)

Attributes associated with the fact. Common attributes include source (indicating where the fact was sourced from), author (indicating the author of the fact), and so on.

CheckGroundingSpec

Specification for the grounding check.

JSON representation 
{
  "citationThreshold": number
}
Fields
citationThreshold

number

The threshold (in [0,1]) used for determining whether a fact must be cited for a claim in the answer candidate. Choosing a higher threshold will lead to fewer but very strong citations, while choosing a lower threshold may lead to more but somewhat weaker citations. If unset, the threshold will default to 0.6.

FactChunk

Fact Chunk.

JSON representation 
{
  "chunkText": string,
  "source": string,
  "index": integer,
  "sourceMetadata": {
    string: string,
    ...
  }
}
Fields
chunkText

string

Text content of the fact chunk. Can be at most 10K characters long.
source

string

Source from which this fact chunk was retrieved. If it was retrieved from the GroundingFacts provided in the request then this field will contain the index of the specific fact from which this chunk was retrieved.
index

integer

The index of this chunk. Currently, only used for the streaming mode.
sourceMetadata

map (key: string, value: string)

More fine-grained information for the source reference.

CheckGroundingFactChunk

Fact chunk for grounding check.

JSON representation 
{
  "chunkText": string
}
Fields
chunkText

string

Text content of the fact chunk. Can be at most 10K characters long.

Claim

Text and citation info for a claim in the answer candidate.

JSON representation 
{
  "claimText": string,
  "citationIndices": [
    integer
  ],
  "startPos": integer,
  "endPos": integer,
  "groundingCheckRequired": boolean
}
Fields
claimText

string

Text for the claim in the answer candidate. Always provided regardless of whether citations or anti-citations are found.
citationIndices[]

integer

A list of indices (into 'citedChunks') specifying the citations associated with the claim. For instance [1,3,4] means that citedChunks[1], citedChunks[3], citedChunks[4] are the facts cited supporting for the claim. A citation to a fact indicates that the claim is supported by the fact.
startPos

integer

Position indicating the start of the claim in the answer candidate, measured in bytes.
endPos

integer

Position indicating the end of the claim in the answer candidate, exclusive.
groundingCheckRequired

boolean

Indicates that this claim required grounding check. When the system decided this claim doesn't require attribution/grounding check, this field will be set to false. In that case, no grounding check was done for the claim and therefore citationIndices should not be returned.