Method: projects.locations.generateGroundedContent

Generates grounded content.

HTTP request

POST https://discoveryengine.googleapis.com/v1alpha/{location=projects/*/locations/*}:generateGroundedContent

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
location

string

Required. Location resource.

Format: projects/{project}/locations/{location}.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "systemInstruction": {
    object (GroundedGenerationContent)
  },
  "contents": [
    {
      object (GroundedGenerationContent)
    }
  ],
  "generationSpec": {
    object (GenerationSpec)
  },
  "groundingSpec": {
    object (GroundingSpec)
  },
  "userLabels": {
    string: string,
    ...
  }
}
Fields
systemInstruction

object (GroundedGenerationContent)

Content of the system instruction for the current API.

These instructions will take priority over any other prompt instructions if the selected model is supporting them.
contents[]

object (GroundedGenerationContent)

Content of the current conversation with the model.

For single-turn queries, this is a single instance. For multi-turn queries, this is a repeated field that contains conversation history + latest request.
generationSpec

object (GenerationSpec)

Content generation specification.
groundingSpec

object (GroundingSpec)

Grounding specification.
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 for the locations.generateGroundedContent method.

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

JSON representation 
{
  "candidates": [
    {
      object (Candidate)
    }
  ]
}
Fields
candidates[]

object (Candidate)

Generated candidates.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the Authentication Overview.

GroundedGenerationContent

Base structured datatype containing multi-part content of a message.

JSON representation 
{
  "role": string,
  "parts": [
    {
      object (Part)
    }
  ]
}
Fields
role

string

producer of the content. Must be either user or model.

Intended to be used for multi-turn conversations. Otherwise, it can be left unset.
parts[]

object (Part)

Ordered Parts that constitute a single message.

Part

Single part of content.

JSON representation 
{

  // Union field data can be only one of the following:
  "text": string
  // End of list of possible types for union field data.
}
Fields
Union field data. Holder of data. It only supports text for now. data can be only one of the following:
text

string

Inline text.

GenerationSpec

Content generation specification.

JSON representation 
{
  "modelId": string,
  "languageCode": string,
  "temperature": number,
  "topP": number,
  "topK": integer,
  "frequencyPenalty": number,
  "seed": integer,
  "presencePenalty": number,
  "maxOutputTokens": integer
}
Fields
modelId

string

Specifies which Vertex model id to use for generation.
languageCode

string

Language code for content. Use language tags defined by BCP47.
temperature

number

If specified, custom value for the temperature will be used.
topP

number

If specified, custom value for nucleus sampling will be used.
topK

integer

If specified, custom value for top-k sampling will be used.
frequencyPenalty

number

If specified, custom value for frequency penalty will be used.
seed

integer

If specified, custom value for the seed will be used.
presencePenalty

number

If specified, custom value for presence penalty will be used.
maxOutputTokens

integer

If specified, custom value for max output tokens will be used.

GroundingSpec

Grounding specification.

JSON representation 
{
  "groundingSources": [
    {
      object (GroundingSource)
    }
  ]
}
Fields
groundingSources[]

object (GroundingSource)

Grounding sources.

GroundingSource

Grounding source.

JSON representation 
{

  // Union field source can be only one of the following:
  "inlineSource": {
    object (InlineSource)
  },
  "searchSource": {
    object (SearchSource)
  },
  "googleSearchSource": {
    object (GoogleSearchSource)
  }
  // End of list of possible types for union field source.
}
Fields
Union field source. Sources. source can be only one of the following:
inlineSource

object (InlineSource)

If set, grounding is performed with inline content.
searchSource

object (SearchSource)

If set, grounding is performed with Vertex AI Search.
googleSearchSource

object (GoogleSearchSource)

If set, grounding is performed with Google Search.

InlineSource

Message to be used for grounding based on inline content.

JSON representation 
{
  "groundingFacts": [
    {
      object (GroundingFact)
    }
  ],
  "attributes": {
    string: string,
    ...
  }
}
Fields
groundingFacts[]

object (GroundingFact)

List of facts to be used for grounding.
attributes

map (key: string, value: string)

Attributes associated with the content.

Common attributes include source (indicating where the content was sourced from) and author (indicating the author of the content).

SearchSource

Message to be used for grounding with Vertex AI Search.

JSON representation 
{
  "servingConfig": string,
  "maxResultCount": integer,
  "filter": string,
  "safeSearch": boolean
}
Fields
servingConfig

string

The resource name of the Engine to use.

Format: projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}/servingConfigs/{servingConfigId}
maxResultCount

integer

Number of search results to return.

The default value is 10. The maximumm allowed value is 10.
filter

string

Filter expression to be applied to the search.

The syntax is the same as SearchRequest.filter.

GoogleSearchSource

Google Search config parameters.

JSON representation 
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfiguration)
  }
}
Fields
dynamicRetrievalConfig

object (DynamicRetrievalConfiguration)

Optional. Specifies the dynamic retrieval configuration for the given source.

DynamicRetrievalConfiguration

Describes the options to customize dynamic retrieval.

JSON representation 
{
  "predictor": {
    object (DynamicRetrievalPredictor)
  }
}
Fields
predictor

object (DynamicRetrievalPredictor)

Specification for the predictor for dynamic retrieval.

DynamicRetrievalPredictor

Describes the predictor settings for dynamic retrieval.

JSON representation 
{
  "version": enum (Version),
  "threshold": number
}
Fields
version

enum (Version)

The version of the predictor to be used in dynamic retrieval.
threshold

number

The value of the threshold. If the predictor will predict a value smaller than this, it would suppress grounding in the source.

Version

The version of the predictor to be used in dynamic retrieval.

Enums
VERSION_UNSPECIFIED Automatically choose the best version of the retrieval predictor.
V1_INDEPENDENT The V1 model which is evaluating each source independently.

Candidate

A response candidate generated from the model.

JSON representation 
{
  "index": integer,
  "content": {
    object (GroundedGenerationContent)
  },
  "groundingMetadata": {
    object (GroundingMetadata)
  },
  "groundingScore": number
}
Fields
index

integer

Index of the candidate.
content

object (GroundedGenerationContent)

Content of the candidate.
groundingMetadata

object (GroundingMetadata)

Grounding metadata for the generated content.
groundingScore

number

The overall grounding score for the candidate, in the range of [0, 1].

GroundingMetadata

Citation for the generated content.

JSON representation 
{
  "retrievalMetadata": [
    {
      object (RetrievalMetadata)
    }
  ],
  "supportChunks": [
    {
      object (FactChunk)
    }
  ],
  "webSearchQueries": [
    string
  ],
  "searchEntryPoint": {
    object (SearchEntryPoint)
  },
  "groundingSupport": [
    {
      object (GroundingSupport)
    }
  ]
}
Fields
retrievalMetadata[]

object (RetrievalMetadata)

Retrieval metadata to provide an understanding in the retrieval steps performed by the model. There can be multiple such messages which can correspond to different parts of the retrieval. This is a mechanism used to ensure transparency to our users.
supportChunks[]

object (FactChunk)

List of chunks to be attributed across all claims in the candidate. These are derived from the grounding sources supplied in the request.
webSearchQueries[]

string

Web search queries for the following-up web search.
searchEntryPoint

object (SearchEntryPoint)

Google search entry for the following-up web searches.
groundingSupport[]

object (GroundingSupport)

GroundingSupport across all claims in the answer candidate. An support to a fact indicates that the claim is supported by the fact.

RetrievalMetadata

Describes the metadata associated with a retrieval step.

JSON representation 
{
  "source": enum (Source),
  "dynamicRetrievalMetadata": {
    object (DynamicRetrievalMetadata)
  }
}
Fields
source

enum (Source)

Describes the source to which the metadata is referring to.
dynamicRetrievalMetadata

object (DynamicRetrievalMetadata)

metadata for dynamic retrieval.

Source

Describes the source to which the metadata is associated to.

Enums
SOURCE_UNSPECIFIED Unspecified source.
INLINE_CONTENT User inline provided content.
GOOGLE_MAPS Google Maps.

DynamicRetrievalMetadata

Describes the metadata about dynamic retrieval.

JSON representation 
{
  "predictorMetadata": {
    object (DynamicRetrievalPredictorMetadata)
  }
}
Fields
predictorMetadata

object (DynamicRetrievalPredictorMetadata)

metadata for the dynamic retrieval predictor.

DynamicRetrievalPredictorMetadata

Describes the metadata about the dynamic retrieval predictor.

JSON representation 
{
  "version": enum (Version),
  "prediction": number
}
Fields
version

enum (Version)

The version of the predictor which was used in dynamic retrieval.
prediction

number

The value of the predictor. This should be between [0, 1] where a value of 0 means that the query would not benefit from grounding, while a value of 1.0 means that the query would benefit the most. In between values allow to differentiate between different usefulness scores for grounding.

Version

The version of the predictor which was used in dynamic retrieval.

Enums
VERSION_UNSPECIFIED Unspecified version, should never be used.
V1_INDEPENDENT The V1 model which is evaluating each source independently.

SearchEntryPoint

Google search entry point.

JSON representation 
{
  "renderedContent": string,
  "sdkBlob": string
}
Fields
renderedContent

string

Web content snippet that can be embedded in a web page or an app webview.
sdkBlob

string (bytes format)

Base64 encoded JSON representing array of <search term, search url> tuple.

A base64-encoded string.

GroundingSupport

Grounding info for a claim in the candidate and its support.

JSON representation 
{
  "claimText": string,
  "supportChunkIndices": [
    integer
  ],
  "supportScore": number
}
Fields
claimText

string

Text for the claim in the candidate. Always provided when a support is found.
supportChunkIndices[]

integer

A list of indices (into 'supportChunks') specifying the citations associated with the claim. For instance [1,3,4] means that supportChunks[1], supportChunks[3], supportChunks[4] are the chunks attributed to the claim.
supportScore

number

A score in the range of [0, 1] describing how grounded is a specific claim in the support chunks indicated. Higher value means that the claim is better supported by the chunks.