Resource: CachedContent
A resource used in LLM queries for users to explicitly specify what to cache and how to cache.
name
string
Immutable. Identifier. The server-generated resource name of the cached content Format: projects/{project}/locations/{location}/cachedContents/{cachedContent}
displayName
string
Optional. Immutable. The user-generated meaningful display name of the cached content.
model
string
Immutable. The name of the Model
to use for cached content. Currently, only the published Gemini base models are supported, in form of projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/{MODEL}
Optional. Input only. Immutable. Developer set system instruction. Currently, text only
Optional. Input only. Immutable. The content to cache
Optional. Input only. Immutable. A list of Tools
the model may use to generate the next response
Optional. Input only. Immutable. Tool config. This config is shared for all tools
Output only. Creation time of the cache entry.
Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
or "2014-10-02T15:01:23+05:30"
.
Output only. When the cache entry was last updated in UTC time.
Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
or "2014-10-02T15:01:23+05:30"
.
Output only. metadata on the usage of the cached content.
Input only. Immutable. Customer-managed encryption key spec for a CachedContent
. If set, this CachedContent
and all its sub-resources will be secured by this key.
expiration
Union type
expiration
can be only one of the following:timestamp of when this resource is considered expired. This is always provided on output, regardless of what was sent on input.
Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
or "2014-10-02T15:01:23+05:30"
.
Input only. The TTL for this resource. The expiration time is computed: now + TTL.
A duration in seconds with up to nine fractional digits, ending with 's
'. Example: "3.5s"
.
JSON representation |
---|
{ "name": string, "displayName": string, "model": string, "systemInstruction": { object ( |
Tool
Tool details that the model may use to generate response.
A Tool
is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model. A Tool object should contain exactly one type of Tool (e.g FunctionDeclaration, Retrieval or GoogleSearchRetrieval).
Optional. Function tool type. One or more function declarations to be passed to the model along with the current user query. Model may decide to call a subset of these functions by populating FunctionCall
in the response. user should provide a FunctionResponse
for each function call in the next turn. Based on the function responses, Model will generate the final response back to the user. Maximum 128 function declarations can be provided.
Optional. Retrieval tool type. System will always execute the provided retrieval tool(s) to get external knowledge to answer the prompt. Retrieval results are presented to the model for generation.
Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.
Optional. GoogleSearchRetrieval tool type. Specialized retrieval tool that is powered by Google search.
Optional. Tool to support searching public web data, powered by Vertex AI Search and Sec4 compliance.
Optional. CodeExecution tool type. Enables the model to execute code as part of generation.
JSON representation |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
Structured representation of a function declaration as defined by the OpenAPI 3.0 specification. Included in this declaration are the function name, description, parameters and response type. This FunctionDeclaration is a representation of a block of code that can be used as a Tool
by the model and executed by the client.
name
string
Required. The name of the function to call. Must start with a letter or an underscore. Must be a-z, A-Z, 0-9, or contain underscores, dots and dashes, with a maximum length of 64.
description
string
Optional. description and purpose of the function. Model uses it to decide how and whether to call the function.
Optional. Describes the parameters to this function in JSON Schema Object format. Reflects the Open API 3.03 Parameter Object. string Key: the name of the parameter. Parameter names are case sensitive. Schema value: the Schema defining the type used for the parameter. For function with no parameters, this can be left unset. Parameter names must start with a letter or an underscore and must only contain chars a-z, A-Z, 0-9, or underscores with a maximum length of 64. Example with 1 required and 1 optional parameter: type: OBJECT properties: param1: type: STRING param2: type: INTEGER required: - param1
Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"additionalProperties": false,
"required": ["name", "age"],
"propertyOrdering": ["name", "age"]
}
This field is mutually exclusive with parameters
.
Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.
Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function.
This field is mutually exclusive with response
.
Schema
Schema is used to define the format of input/output data. Represents a select subset of an OpenAPI 3.0 schema object. More fields may be added in the future as needed.
Optional. The type of the data.
format
string
Optional. The format of the data. Supported formats: for NUMBER type: "float", "double" for INTEGER type: "int32", "int64" for STRING type: "email", "byte", etc
title
string
Optional. The title of the Schema.
description
string
Optional. The description of the data.
nullable
boolean
Optional. Indicates if the value may be null.
Optional. Default value of the data.
Optional. SCHEMA FIELDS FOR TYPE ARRAY Schema of the elements of type.ARRAY.
Optional. Minimum number of the elements for type.ARRAY.
Optional. Maximum number of the elements for type.ARRAY.
enum[]
string
Optional. Possible values of the element of primitive type with enum format. Examples: 1. We can define direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]} 2. We can define apartment number as : {type:INTEGER, format:enum, enum:["101", "201", "301"]}
Optional. SCHEMA FIELDS FOR TYPE OBJECT Properties of type.OBJECT.
propertyOrdering[]
string
Optional. The order of the properties. Not a standard field in open api spec. Only used to support the order of the properties.
required[]
string
Optional. Required properties of type.OBJECT.
Optional. Minimum number of the properties for type.OBJECT.
Optional. Maximum number of the properties for type.OBJECT.
minimum
number
Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the type.INTEGER and type.NUMBER
maximum
number
Optional. Maximum value of the type.INTEGER and type.NUMBER
Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the type.STRING
Optional. Maximum length of the type.STRING
pattern
string
Optional. Pattern of the type.STRING to restrict a string to a regular expression.
Optional. Example of the object. Will only populated when the object is the root.
Optional. The value should be validated against any (one or more) of the subschemas in the list.
Optional. Can either be a boolean or an object; controls the presence of additional properties.
ref
string
Optional. Allows indirect references between schema nodes. The value should be a valid reference to a child of the root defs
.
For example, the following schema defines a reference to a schema node named "Pet":
type: object properties: pet: ref: #/defs/Pet defs: Pet: type: object properties: name: type: string
The value of the "pet" property is a reference to the schema node named "Pet". See details in https://json-schema.org/understanding-json-schema/structuring
Optional. A map of definitions for use by ref
Only allowed at the root of the schema.
JSON representation |
---|
{ "type": enum ( |
Type
type contains the list of OpenAPI data types as defined by https://swagger.io/docs/specification/data-models/data-types/
Enums | |
---|---|
TYPE_UNSPECIFIED |
Not specified, should not be used. |
STRING |
OpenAPI string type |
NUMBER |
OpenAPI number type |
INTEGER |
OpenAPI integer type |
BOOLEAN |
OpenAPI boolean type |
ARRAY |
OpenAPI array type |
OBJECT |
OpenAPI object type |
NULL |
Null type |
Retrieval
Defines a retrieval tool that model can call to access external knowledge.
disableAttribution
(deprecated)
boolean
Optional. Deprecated. This option is no longer supported.
source
Union type
source
can be only one of the following:Set to use data source powered by Vertex AI Search.
Set to use data source powered by Vertex RAG store. user data is uploaded via the VertexRagDataService.
Use data source powered by external API for grounding.
JSON representation |
---|
{ "disableAttribution": boolean, // source "vertexAiSearch": { object ( |
VertexAISearch
Retrieve from Vertex AI Search datastore or engine for grounding. datastore and engine are mutually exclusive. See https://cloud.google.com/products/agent-builder
datastore
string
Optional. Fully-qualified Vertex AI Search data store resource id. Format: projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}
engine
string
Optional. Fully-qualified Vertex AI Search engine resource id. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}
maxResults
integer
Optional. Number of search results to return per query. The default value is 10. The maximumm allowed value is 10.
filter
string
Optional. Filter strings to be passed to the search API.
Specifications that define the specific DataStores to be searched, along with configurations for those data stores. This is only considered for Engines with multiple data stores. It should only be set if engine is used.
JSON representation |
---|
{
"datastore": string,
"engine": string,
"maxResults": integer,
"filter": string,
"dataStoreSpecs": [
{
object ( |
DataStoreSpec
Define data stores within engine to filter on in a search call and configurations for those data stores. For more information, see https://cloud.google.com/generative-ai-app-builder/docs/reference/rpc/google.cloud.discoveryengine.v1#datastorespec
dataStore
string
Full resource name of DataStore, such as Format: projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}
filter
string
Optional. Filter specification to filter documents in the data store specified by dataStore field. For more information on filtering, see Filtering
JSON representation |
---|
{ "dataStore": string, "filter": string } |
VertexRagStore
Retrieve from Vertex RAG Store for grounding.
Optional. The representation of the rag source. It can be used to specify corpus only or ragfiles. Currently only support one corpus or multiple files from one corpus. In the future we may open up multiple corpora support.
Optional. The retrieval config for the Rag query.
similarityTopK
(deprecated)
integer
Optional. Number of top k results to return from the selected corpora.
vectorDistanceThreshold
(deprecated)
number
Optional. Only return results with vector distance smaller than the threshold.
JSON representation |
---|
{ "ragResources": [ { object ( |
RagResource
The definition of the Rag resource.
ragCorpus
string
Optional. RagCorpora resource name. Format: projects/{project}/locations/{location}/ragCorpora/{ragCorpus}
ragFileIds[]
string
Optional. ragFileId. The files should be in the same ragCorpus set in ragCorpus field.
JSON representation |
---|
{ "ragCorpus": string, "ragFileIds": [ string ] } |
RagRetrievalConfig
Specifies the context retrieval config.
topK
integer
Optional. The number of contexts to retrieve.
Optional. Config for filters.
Optional. Config for ranking and reranking.
Filter
Config for filters.
metadataFilter
string
Optional. String for metadata filtering.
vector_db_threshold
Union type
vector_db_threshold
can be only one of the following:vectorDistanceThreshold
number
Optional. Only returns contexts with vector distance smaller than the threshold.
vectorSimilarityThreshold
number
Optional. Only returns contexts with vector similarity larger than the threshold.
JSON representation |
---|
{ "metadataFilter": string, // vector_db_threshold "vectorDistanceThreshold": number, "vectorSimilarityThreshold": number // Union type } |
Ranking
Config for ranking and reranking.
ranking_config
Union type
ranking_config
can be only one of the following:Optional. Config for Rank service.
Optional. Config for LlmRanker.
JSON representation |
---|
{ // ranking_config "rankService": { object ( |
RankService
Config for Rank service.
modelName
string
Optional. The model name of the rank service. Format: semantic-ranker-512@latest
JSON representation |
---|
{ "modelName": string } |
LlmRanker
Config for LlmRanker.
modelName
string
Optional. The model name used for ranking. See Supported models.
JSON representation |
---|
{ "modelName": string } |
ExternalApi
Retrieve from data source powered by external API for grounding. The external API is not owned by Google, but need to follow the pre-defined API spec.
The API spec that the external API implements.
endpoint
string
The endpoint of the external API. The system will call the API at this endpoint to retrieve the data for grounding. Example: https://acme.com:443/search
The authentication config to access the API. Deprecated. Please use authConfig instead.
The authentication config to access the API.
params
Union type
params
can be only one of the following:Parameters for the simple search API.
Parameters for the elastic search API.
JSON representation |
---|
{ "apiSpec": enum ( |
SimpleSearchParams
This type has no fields.
The search parameters to use for SIMPLE_SEARCH spec.
ElasticSearchParams
The search parameters to use for the ELASTIC_SEARCH spec.
index
string
The ElasticSearch index to use.
searchTemplate
string
The ElasticSearch search template to use.
numHits
integer
Optional. Number of hits (chunks) to request.
When specified, it is passed to Elasticsearch as the numHits
param.
JSON representation |
---|
{ "index": string, "searchTemplate": string, "numHits": integer } |
ApiSpec
The API spec that the external API implements.
Enums | |
---|---|
API_SPEC_UNSPECIFIED |
Unspecified API spec. This value should not be used. |
SIMPLE_SEARCH |
Simple search API spec. |
ELASTIC_SEARCH |
Elastic search API spec. |
AuthConfig
Auth configuration to run the extension.
type of auth scheme.
auth_config
Union type
auth_config
can be only one of the following:Config for API key auth.
Config for HTTP Basic auth.
Config for Google service Account auth.
Config for user oauth.
Config for user OIDC auth.
JSON representation |
---|
{ "authType": enum ( |
ApiKeyConfig
Config for authentication with API key.
name
string
Optional. The parameter name of the API key. E.g. If the API request is "https://example.com/act?apiKey=
apiKeySecret
string
Optional. The name of the SecretManager secret version resource storing the API key. Format: projects/{project}/secrets/{secrete}/versions/{version}
If both
apiKeySecret
andapiKeyString
are specified, this field takes precedence overapiKeyString
.If specified, the
secretmanager.versions.access
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the specified resource.
apiKeyString
string
Optional. The API key to be used in the request directly.
Optional. The location of the API key.
JSON representation |
---|
{
"name": string,
"apiKeySecret": string,
"apiKeyString": string,
"httpElementLocation": enum ( |
HttpElementLocation
Enum of location an HTTP element can be.
Enums | |
---|---|
HTTP_IN_UNSPECIFIED |
|
HTTP_IN_QUERY |
Element is in the HTTP request query. |
HTTP_IN_HEADER |
Element is in the HTTP request header. |
HTTP_IN_PATH |
Element is in the HTTP request path. |
HTTP_IN_BODY |
Element is in the HTTP request body. |
HTTP_IN_COOKIE |
Element is in the HTTP request cookie. |
HttpBasicAuthConfig
Config for HTTP Basic Authentication.
credentialSecret
string
Required. The name of the SecretManager secret version resource storing the base64 encoded credentials. Format: projects/{project}/secrets/{secrete}/versions/{version}
- If specified, the
secretmanager.versions.access
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the specified resource.
JSON representation |
---|
{ "credentialSecret": string } |
GoogleServiceAccountConfig
Config for Google service Account Authentication.
serviceAccount
string
Optional. The service account that the extension execution service runs as.
If the service account is specified, the
iam.serviceAccounts.getAccessToken
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the specified service account.If not specified, the Vertex AI Extension service Agent will be used to execute the Extension.
JSON representation |
---|
{ "serviceAccount": string } |
OauthConfig
Config for user oauth.
oauth_config
Union type
oauth_config
can be only one of the following:accessToken
string
Access token for extension endpoint. Only used to propagate token from [[ExecuteExtensionRequest.runtime_auth_config]] at request time.
serviceAccount
string
The service account used to generate access tokens for executing the Extension.
- If the service account is specified, the
iam.serviceAccounts.getAccessToken
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the provided service account.
JSON representation |
---|
{ // oauth_config "accessToken": string, "serviceAccount": string // Union type } |
OidcConfig
Config for user OIDC auth.
oidc_config
Union type
oidc_config
can be only one of the following:idToken
string
OpenID Connect formatted id token for extension endpoint. Only used to propagate token from [[ExecuteExtensionRequest.runtime_auth_config]] at request time.
serviceAccount
string
The service account used to generate an OpenID Connect (OIDC)-compatible JWT token signed by the Google OIDC Provider (accounts.google.com) for extension endpoint (https://cloud.google.com/iam/docs/create-short-lived-credentials-direct#sa-credentials-oidc).
The audience for the token will be set to the URL in the server url defined in the OpenApi spec.
If the service account is provided, the service account should grant
iam.serviceAccounts.getOpenIdToken
permission to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents).
JSON representation |
---|
{ // oidc_config "idToken": string, "serviceAccount": string // Union type } |
AuthType
type of Auth.
Enums | |
---|---|
AUTH_TYPE_UNSPECIFIED |
|
NO_AUTH |
No Auth. |
API_KEY_AUTH |
API Key Auth. |
HTTP_BASIC_AUTH |
HTTP Basic Auth. |
GOOGLE_SERVICE_ACCOUNT_AUTH |
Google service Account Auth. |
OAUTH |
OAuth auth. |
OIDC_AUTH |
OpenID Connect (OIDC) Auth. |
GoogleSearch
This type has no fields.
GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.
GoogleSearchRetrieval
Tool to retrieve public web data for grounding, powered by Google.
Specifies the dynamic retrieval configuration for the given source.
JSON representation |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
Describes the options to customize dynamic retrieval.
The mode of the predictor to be used in dynamic retrieval.
dynamicThreshold
number
Optional. The threshold to be used in dynamic retrieval. If not set, a system default value is used.
JSON representation |
---|
{
"mode": enum ( |
Mode
The mode of the predictor to be used in dynamic retrieval.
Enums | |
---|---|
MODE_UNSPECIFIED |
Always trigger retrieval. |
MODE_DYNAMIC |
Run retrieval only when system decides it is necessary. |
EnterpriseWebSearch
This type has no fields.
Tool to search public web data, powered by Vertex AI Search and Sec4 compliance.
CodeExecution
This type has no fields.
Tool that executes code generated by the model, and automatically returns the result to the model.
See also [ExecutableCode]and [CodeExecutionResult] which are input and output to this tool.
ToolConfig
Tool config. This config is shared for all tools provided in the request.
Optional. Function calling config.
Optional. Retrieval config.
JSON representation |
---|
{ "functionCallingConfig": { object ( |
FunctionCallingConfig
Function calling config.
Optional. Function calling mode.
allowedFunctionNames[]
string
Optional. Function names to call. Only set when the Mode is ANY. Function names should match [FunctionDeclaration.name]. With mode set to ANY, model will predict a function call from the set of function names provided.
JSON representation |
---|
{
"mode": enum ( |
Mode
Function calling mode.
Enums | |
---|---|
MODE_UNSPECIFIED |
Unspecified function calling mode. This value should not be used. |
AUTO |
Default model behavior, model decides to predict either function calls or natural language response. |
ANY |
Model is constrained to always predicting function calls only. If "allowedFunctionNames" are set, the predicted function calls will be limited to any one of "allowedFunctionNames", else the predicted function calls will be any one of the provided "functionDeclarations". |
NONE |
Model will not predict any function calls. Model behavior is same as when not passing any function declarations. |
RetrievalConfig
UsageMetadata
metadata on the usage of the cached content.
totalTokenCount
integer
Total number of tokens that the cached content consumes.
textCount
integer
Number of text characters.
imageCount
integer
Number of images.
videoDurationSeconds
integer
Duration of video in seconds.
audioDurationSeconds
integer
Duration of audio in seconds.
JSON representation |
---|
{ "totalTokenCount": integer, "textCount": integer, "imageCount": integer, "videoDurationSeconds": integer, "audioDurationSeconds": integer } |
Methods |
|
---|---|
|
Creates cached content, this call will initialize the cached content in the data storage, and users need to pay for the cache data storage. |
|
Deletes cached content |
|
Gets cached content configurations |
|
Lists cached contents in a project |
|
Updates cached content configurations |