La caché de contexto te permite guardar y reutilizar tokens de entrada calculados previamente que deseas usar de forma reiterada, por ejemplo, cuando haces diferentes preguntas sobre el mismo archivo multimedia. Esto puede generar ahorros de costos y velocidad, según el uso. Para obtener una introducción detallada, consulta la guía Almacenamiento en caché de contexto.
Método: cachedContents.create
Crea un recurso CachedContent.
Extremo
post https://generativelanguage.googleapis.com/v1beta/cachedContentsCuerpo de la solicitud
El cuerpo de la solicitud contiene una instancia de CachedContent
.
contents[]
object (Content
)
Opcional. Solo entrada. Inmutable. El contenido que se almacenará en caché.
tools[]
object (Tool
)
Opcional. Solo entrada. Inmutable. Una lista de Tools
que el modelo puede usar para generar la siguiente respuesta
expiration
. Especifica cuándo vencerá este recurso. Las direcciones (expiration
) solo pueden ser una de las siguientes opciones:
expireTime
string (Timestamp
format)
Marca de tiempo en UTC del momento en que este recurso se consideró vencido. Esto siempre se proporciona en la salida, sin importar si se envió en la entrada.
Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z"
y "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Solo entrada. TTL nuevo para este recurso, solo entrada.
Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s
”. Ejemplo: "3.5s"
.
name
string
Opcional. Identificador. Es el nombre del recurso que hace referencia al contenido almacenado en caché. Formato: cachedContents/{id}
displayName
string
Opcional. Inmutable. Es el nombre visible significativo generado por el usuario del contenido almacenado en caché. Máximo 128 caracteres Unicode.
model
string
Obligatorio. Inmutable. Es el nombre del Model
que se usará para el contenido almacenado en caché. Formato: models/{model}
systemInstruction
object (Content
)
Opcional. Solo entrada. Inmutable. Instrucción del sistema establecida por el desarrollador Actualmente, solo texto.
toolConfig
object (ToolConfig
)
Opcional. Solo entrada. Inmutable. Configuración de herramientas Esta configuración se comparte para todas las herramientas.
Ejemplo de solicitud
Básico
Python
Node.js
Go
Una caracola
Nombre del remitente
Python
Node.js
Go
Desde el chat
Python
Node.js
Go
Cuerpo de la respuesta
Si el proceso se realiza de forma correcta, el cuerpo de la respuesta contiene una instancia recién creada de CachedContent
.
Método: cachedContents.list
Enumera CachedContents.
Extremo
get https://generativelanguage.googleapis.com/v1beta/cachedContentsParámetros de consulta
pageSize
integer
Opcional. Es la cantidad máxima de contenido almacenado en caché que se mostrará. El servicio puede mostrar menos que este valor. Si no se especifica, se mostrará una cantidad predeterminada (inferior a la máxima) de elementos. El valor máximo es 1,000; valores superiores a 1,000 se convertirán en 1,000.
pageToken
string
Opcional. Un token de página, recibido desde una llamada cachedContents.list
anterior. Proporciona esto para recuperar la página siguiente.
Cuando se pagina, todos los demás parámetros proporcionados a cachedContents.list
deben coincidir con la llamada que proporcionó el token de la página.
Cuerpo de la solicitud
El cuerpo de la solicitud debe estar vacío.
Cuerpo de la respuesta
Respuesta con la lista CachedContents.
Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:
cachedContents[]
object (CachedContent
)
Es una lista del contenido almacenado en caché.
nextPageToken
string
Un token, que se puede enviar como pageToken
para recuperar la página siguiente. Si se omite este campo, no habrá páginas siguientes.
Representación JSON |
---|
{
"cachedContents": [
{
object ( |
Método: cachedContents.get
Lee el recurso CachedContent.
Extremo
get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}Parámetros de ruta
name
string
Obligatorio. Es el nombre del recurso que hace referencia a la entrada de caché de contenido. Formato: cachedContents/{id}
Toma la forma cachedContents/{cachedcontent}
.
Cuerpo de la solicitud
El cuerpo de la solicitud debe estar vacío.
Ejemplo de solicitud
Python
Node.js
Go
Una caracola
Cuerpo de la respuesta
Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene una instancia de CachedContent
.
Método: cachedContents.patch
- Extremo
- Parámetros de ruta de acceso
- Parámetros de consulta
- Cuerpo de la solicitud
- Cuerpo de la respuesta
- Ejemplo de solicitud
Actualiza el recurso CachedContent (solo se puede actualizar el vencimiento).
Extremo
patch https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
Parámetros de ruta
cachedContent.name
string
Opcional. Identificador. El nombre del recurso que hace referencia al contenido almacenado en caché. Formato: cachedContents/{id}
Tiene el formato cachedContents/{cachedcontent}
.
Parámetros de consulta
updateMask
string (FieldMask
format)
La lista de campos que se deben actualizar.
Esta es una lista separada por comas de los nombres de campos totalmente calificados. Ejemplo: "user.displayName,photo"
.
Cuerpo de la solicitud
El cuerpo de la solicitud contiene una instancia de CachedContent
.
expiration
. Especifica cuándo vencerá este recurso. Las direcciones (expiration
) solo pueden ser una de las siguientes opciones:
expireTime
string (Timestamp
format)
Marca de tiempo en UTC del momento en que este recurso se consideró vencido. Esto siempre se proporciona en la salida, sin importar si se envió en la entrada.
Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z"
y "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Solo entrada. TTL nuevo para este recurso, solo entrada.
Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s
”. Ejemplo: "3.5s"
.
name
string
Opcional. Identificador. Es el nombre del recurso que hace referencia al contenido almacenado en caché. Formato: cachedContents/{id}
Ejemplo de solicitud
Python
Node.js
Go
Una caracola
Cuerpo de la respuesta
Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene una instancia de CachedContent
.
Método: cachedContents.delete
Borra el recurso CachedContent.
Extremo
delete https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}Parámetros de ruta
name
string
Obligatorio. El nombre del recurso que hace referencia a la entrada de la caché de contenido Formato: cachedContents/{id}
Toma la forma cachedContents/{cachedcontent}
.
Cuerpo de la solicitud
El cuerpo de la solicitud debe estar vacío.
Ejemplo de solicitud
Python
Node.js
Go
Una caracola
Cuerpo de la respuesta
Si se ejecuta correctamente, el cuerpo de la respuesta está vacío.
Recurso de REST: cachedContents
- Recurso: CachedContent
- Contenido
- Parte
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- Idioma
- CodeExecutionResult
- Resultado
- Herramienta
- FunctionDeclaration
- Esquema
- Tipo
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- Modo
- CodeExecution
- ToolConfig
- FunctionCallingConfig
- Modo
- UsageMetadata
- Métodos
Recurso: CachedContent
Es el contenido que se procesó previamente y se puede usar en solicitudes posteriores a GenerativeService.
El contenido almacenado en caché solo se puede usar con el modelo para el que se creó.
contents[]
object (Content
)
Opcional. Solo entrada. Inmutable. Es el contenido que se almacenará en caché.
tools[]
object (Tool
)
Opcional. Solo entrada. Inmutable. Una lista de Tools
que el modelo puede usar para generar la siguiente respuesta
createTime
string (Timestamp
format)
Solo salida. Es la hora de creación de la entrada de caché.
Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z"
y "2014-10-02T15:01:23.045123456Z"
.
updateTime
string (Timestamp
format)
Solo salida. Indica cuándo se actualizó la entrada de la caché por última vez en la hora UTC.
Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z"
y "2014-10-02T15:01:23.045123456Z"
.
usageMetadata
object (UsageMetadata
)
Solo salida. Metadatos sobre el uso del contenido almacenado en caché
expiration
. Especifica cuándo vencerá este recurso. Las direcciones (expiration
) solo pueden ser una de las siguientes opciones:
expireTime
string (Timestamp
format)
Marca de tiempo en UTC del momento en que este recurso se consideró vencido. Esto siempre se proporciona en la salida, sin importar si se envió en la entrada.
Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z"
y "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Solo entrada. TTL nuevo para este recurso, solo entrada.
Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s
”. Ejemplo: "3.5s"
.
name
string
Opcional. Identificador. Es el nombre del recurso que hace referencia al contenido almacenado en caché. Formato: cachedContents/{id}
displayName
string
Opcional. Inmutable. Es el nombre visible significativo generado por el usuario del contenido almacenado en caché. Máximo 128 caracteres Unicode.
model
string
Obligatorio. Inmutable. Es el nombre del Model
que se usará para el contenido almacenado en caché. Formato: models/{model}
systemInstruction
object (Content
)
Opcional. Solo entrada. Inmutable. Instrucción del sistema establecida por el desarrollador Actualmente, solo texto.
toolConfig
object (ToolConfig
)
Opcional. Solo entrada. Inmutable. Configuración de la herramienta Esta configuración se comparte para todas las herramientas.
Representación JSON |
---|
{ "contents": [ { object ( |
Contenido
El tipo de datos estructurados base que incluye contenido de varias partes de un mensaje.
Un Content
incluye un campo role
que designa al productor del Content
y un campo parts
que contiene datos de varias partes que contienen el contenido del turno del mensaje.
parts[]
object (Part
)
Se ordenaron Parts
que constituyen un solo mensaje. Las partes pueden tener diferentes tipos de MIME.
role
string
Opcional. Es el productor del contenido. Debe ser "user" o "model".
Es útil para establecer conversaciones de varios turnos; de lo contrario, puede dejarse en blanco o no configurarse.
Representación JSON |
---|
{
"parts": [
{
object ( |
Pieza
Un tipo de datos que contiene contenido multimedia que forma parte de un mensaje Content
de varias partes.
Un Part
consta de datos que tienen un tipo de datos asociado. Un Part
solo puede contener uno de los tipos aceptados en Part.data
.
Un Part
debe tener un tipo de MIME IANA fijo que identifique el tipo y el subtipo del contenido multimedia si el campo inlineData
está lleno de bytes sin procesar.
Campo de unión data
.
data
puede ser una de las siguientes opciones:
text
string
Texto intercalado
inlineData
object (Blob
)
Bytes de contenido multimedia intercalados
functionCall
object (FunctionCall
)
Un FunctionCall
predicho que muestra el modelo que contiene una cadena que representa el FunctionDeclaration.name
con los argumentos y sus valores.
functionResponse
object (FunctionResponse
)
El resultado del resultado de una FunctionCall
que contiene una cadena que representa el FunctionDeclaration.name
y un objeto JSON estructurado que contiene cualquier resultado de la función se usa como contexto para el modelo.
fileData
object (FileData
)
Datos basados en URI.
executableCode
object (ExecutableCode
)
Es el código que genera el modelo y que se debe ejecutar.
codeExecutionResult
object (CodeExecutionResult
)
Es el resultado de ejecutar ExecutableCode
.
Representación JSON |
---|
{ // Union field |
BLOB
Bytes de contenido multimedia sin procesar.
El texto no se debe enviar como bytes sin procesar, usa el campo "text".
mimeType
string
El tipo de MIME estándar de la IANA de los datos de origen. Ejemplos: - image/png - image/jpeg Si se proporciona un tipo de MIME no admitido, se mostrará un error. Para obtener una lista completa de los tipos admitidos, consulta Formatos de archivo compatibles.
data
string (bytes format)
Bytes sin procesar para formatos multimedia.
String codificada en base64.
Representación JSON |
---|
{ "mimeType": string, "data": string } |
FunctionCall
Un FunctionCall
predicho que muestra el modelo que contiene una cadena que representa el FunctionDeclaration.name
con los argumentos y sus valores.
name
string
Obligatorio. El nombre de la función a la que se llamará. Debe tener caracteres de la A a la Z (mayúsculas o minúsculas), o números del 0 al 9, o contener guiones bajos y guiones, con una longitud máxima de 63.
args
object (Struct
format)
Opcional. Los parámetros y valores de la función en formato de objeto JSON
Representación JSON |
---|
{ "name": string, "args": { object } } |
FunctionResponse
El resultado de una FunctionCall
que contiene una cadena que representa el FunctionDeclaration.name
y un objeto JSON estructurado que contiene cualquier resultado de la función se usa como contexto para el modelo. Esto debería contener el resultado de unFunctionCall
basado en la predicción del modelo.
name
string
Obligatorio. El nombre de la función a la que se llamará. Debe ser a-z, A-Z, del 0 al 9 o contener guiones bajos y guiones, con una longitud máxima de 63.
response
object (Struct
format)
Obligatorio. La respuesta de la función en formato de objeto JSON.
Representación JSON |
---|
{ "name": string, "response": { object } } |
FileData
Datos basados en URI.
mimeType
string
Opcional. Es el tipo de MIME estándar de IANA de los datos de origen.
fileUri
string
Obligatorio. URI.
Representación JSON |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
Es el código que genera el modelo y que se debe ejecutar, y el resultado que se muestra al modelo.
Solo se genera cuando se usa la herramienta CodeExecution
, en la que el código se ejecutará automáticamente y también se generará el CodeExecutionResult
correspondiente.
language
enum (Language
)
Obligatorio. Es el lenguaje de programación de code
.
code
string
Obligatorio. Es el código que se ejecutará.
Representación JSON |
---|
{
"language": enum ( |
Idioma
Lenguajes de programación admitidos para el código generado.
Enumeraciones | |
---|---|
LANGUAGE_UNSPECIFIED |
Idioma no especificado. No se debe usar este valor. |
PYTHON |
Python >= 3.10, con numpy y simpy disponibles |
CodeExecutionResult
Es el resultado de ejecutar ExecutableCode
.
Solo se genera cuando se usa CodeExecution
y siempre sigue a un part
que contiene ExecutableCode
.
outcome
enum (Outcome
)
Obligatorio. Resultado de la ejecución del código.
output
string
Opcional. Contiene stdout cuando la ejecución de código se realiza correctamente, stderr o alguna otra descripción de lo contrario.
Representación JSON |
---|
{
"outcome": enum ( |
Resultado
Enumeración de los posibles resultados de la ejecución del código.
Enumeraciones | |
---|---|
OUTCOME_UNSPECIFIED |
Estado sin especificar. No se debe usar este valor. |
OUTCOME_OK |
La ejecución del código se completó correctamente. |
OUTCOME_FAILED |
Se completó la ejecución del código, pero con un error. stderr debe contener el motivo. |
OUTCOME_DEADLINE_EXCEEDED |
La ejecución de código se ejecutó durante demasiado tiempo y se canceló. Puede haber o no una salida parcial presente. |
Herramienta
Detalles de las herramientas que el modelo puede usar para generar una respuesta.
Un Tool
es un fragmento de código que permite que el sistema interactúe con sistemas externos para realizar una acción o un conjunto de acciones fuera del conocimiento y el alcance del modelo.
functionDeclarations[]
object (FunctionDeclaration
)
Opcional. Es una lista de FunctionDeclarations
disponible para el modelo que se puede usar para las llamadas a función.
El modelo o sistema no ejecuta la función. En su lugar, la función definida se puede mostrar como una FunctionCall
con argumentos para la ejecución del cliente. El modelo puede decidir llamar a un subconjunto de estas funciones propagando FunctionCall
en la respuesta. El siguiente turno de conversación puede contener un FunctionResponse
con el contexto de generación de "función" Content.role
para el siguiente turno del modelo.
googleSearchRetrieval
object (GoogleSearchRetrieval
)
Opcional. Herramienta de recuperación que se basa en la Búsqueda de Google.
codeExecution
object (CodeExecution
)
Opcional. Permite que el modelo ejecute código como parte de la generación.
Representación JSON |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
Representación estructurada de una declaración de función según lo definido por la especificación de OpenAPI 3.03. En esta declaración, se incluyen el nombre y los parámetros de la función. Esta FunctionDeclaration es una representación de un bloque de código que el modelo puede usar como Tool
y que el cliente ejecuta.
name
string
Obligatorio. Es el nombre de la función. Debe tener caracteres de la A a la Z (mayúsculas o minúsculas), o números del 0 al 9, o contener guiones bajos y guiones, con una longitud máxima de 63.
description
string
Obligatorio. Una breve descripción de la función.
parameters
object (Schema
)
Opcional. Describe los parámetros de esta función. Refleja la clave de cadena del objeto de parámetro de Open API 3.03: el nombre del parámetro. Los nombres de los parámetros distinguen mayúsculas de minúsculas. Valor del esquema: Es el esquema que define el tipo que se usa para el parámetro.
Representación JSON |
---|
{
"name": string,
"description": string,
"parameters": {
object ( |
Esquema
El objeto Schema
permite definir tipos de datos de entrada y salida. Estos tipos pueden ser objetos, pero también primitivos y arrays. Representa un subconjunto selecto de un objeto de esquema de OpenAPI 3.0.
type
enum (Type
)
Obligatorio. Tipo de datos.
format
string
Opcional. El formato de los datos. Esto solo se usa para tipos de datos primitivos. Formatos admitidos: para el tipo NUMBER: número de punto flotante, doble para el tipo INTEGER: int32, int64 para el tipo STRING: enum
description
string
Opcional. Una breve descripción del parámetro. Esto podría incluir ejemplos de uso. La descripción del parámetro puede tener formato Markdown.
nullable
boolean
Opcional. Indica si el valor puede ser nulo.
enum[]
string
Opcional. Valores posibles del elemento de Type.STRING con formato de enumeración. Por ejemplo, podemos definir una dirección de enumeración de la siguiente forma : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
maxItems
string (int64 format)
Opcional. Cantidad máxima de elementos para Type.ARRAY.
minItems
string (int64 format)
Opcional. Es la cantidad mínima de elementos para Type.ARRAY.
properties
map (key: string, value: object (Schema
))
Opcional. Propiedades de Type.OBJECT.
Es un objeto que contiene una lista de pares "key": value
. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }
.
required[]
string
Opcional. Propiedades obligatorias de Type.OBJECT.
items
object (Schema
)
Opcional. Esquema de los elementos de Type.ARRAY.
Tipo
Type contiene la lista de tipos de datos de OpenAPI, según se define en https://spec.openapis.org/oas/v3.0.3#data-types.
Enumeraciones | |
---|---|
TYPE_UNSPECIFIED |
No se especifica. No se debe usar. |
STRING |
Tipo de cadena. |
NUMBER |
Tipo de número. |
INTEGER |
Es un tipo de número entero. |
BOOLEAN |
Tipo booleano. |
ARRAY |
Es el tipo de array. |
OBJECT |
Tipo de objeto. |
GoogleSearchRetrieval
Herramienta de Google para recuperar datos web públicos para la fundamentación.
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
Especifica la configuración de recuperación dinámica para la fuente determinada.
Representación JSON |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
Describe las opciones para personalizar la recuperación dinámica.
mode
enum (Mode
)
El modo del predictor que se usa en la recuperación dinámica.
dynamicThreshold
number
El umbral que se usará en la recuperación dinámica. Si no se establece, se usa un valor predeterminado del sistema.
Representación JSON |
---|
{
"mode": enum ( |
Modo
Es el modo del predictor que se usará en la recuperación dinámica.
Enumeraciones | |
---|---|
MODE_UNSPECIFIED |
Activa siempre la recuperación. |
MODE_DYNAMIC |
Ejecuta la recuperación solo cuando el sistema decida que es necesario. |
CodeExecution
Este tipo no tiene campos.
Es una herramienta que ejecuta el código generado por el modelo y muestra automáticamente el resultado al modelo.
Consulta también ExecutableCode
y CodeExecutionResult
, que solo se generan cuando se usa esta herramienta.
ToolConfig
La configuración de la herramienta que contiene parámetros para especificar el uso de Tool
en la solicitud.
functionCallingConfig
object (FunctionCallingConfig
)
Opcional. Configuración de llamadas a función
Representación JSON |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
Configuración para especificar el comportamiento de las llamadas a funciones.
mode
enum (Mode
)
Opcional. Especifica el modo en el que se debe ejecutar la llamada a función. Si no se especifica, el valor predeterminado se establecerá en AUTO.
allowedFunctionNames[]
string
Opcional. Es un conjunto de nombres de funciones que, cuando se proporcionan, limitan las funciones a las que llamará el modelo.
Esto solo debe configurarse cuando el Modo es ANY. Los nombres de las funciones deben coincidir con [FunctionDeclaration.name]. Con el modo establecido en CUALQUIERA, el modelo predecirá una llamada a función del conjunto de nombres de función proporcionados.
Representación JSON |
---|
{
"mode": enum ( |
Modo
Define el comportamiento de ejecución de las llamadas a función definiendo el modo de ejecución.
Enumeraciones | |
---|---|
MODE_UNSPECIFIED |
Modo de llamada a función no especificado. No se debe usar este valor. |
AUTO |
En el comportamiento predeterminado del modelo, el modelo decide predecir una llamada a función o una respuesta de lenguaje natural. |
ANY |
El modelo está limitado para predecir siempre solo una llamada a función. Si se establece "allowedFunctionNames", la llamada a función prevista se limitará a cualquiera de "allowedFunctionNames"; de lo contrario, la llamada a función prevista será cualquiera de las "functionDeclarations" proporcionadas. |
NONE |
El modelo no predecirá ninguna llamada a función. El comportamiento del modelo es el mismo que cuando no se pasa ninguna declaración de función. |
UsageMetadata
Metadatos sobre el uso del contenido almacenado en caché
totalTokenCount
integer
Es la cantidad total de tokens que consume el contenido almacenado en caché.
Representación JSON |
---|
{ "totalTokenCount": integer } |