O armazenamento em cache de contexto permite salvar e reutilizar tokens de entrada pré-computados que você quer usar repetidamente, por exemplo, ao fazer perguntas diferentes sobre o mesmo arquivo de mídia. Isso pode gerar economia de custos e velocidade, dependendo do uso. Para uma introdução detalhada, consulte o guia Armazenamento de contexto em cache.
Método: cachedContents.create
Cria o recurso CachedContent.
Endpoint
post https://generativelanguage.googleapis.com/v1beta/cachedContentsCorpo da solicitação
O corpo da solicitação contém uma instância de CachedContent
.
contents[]
object (Content
)
Opcional. Somente entrada. Imutável. O conteúdo a ser armazenado em cache.
tools[]
object (Tool
)
Opcional. Somente entrada. Imutável. Uma lista de Tools
que o modelo pode usar para gerar a próxima resposta
expiration
. Especifica quando esse recurso vai expirar. expiration
pode ser apenas de um dos tipos a seguir:
expireTime
string (Timestamp
format)
Carimbo de data/hora em UTC de quando o recurso será considerado expirado. Isso é sempre fornecido na saída, independente do que tiver sido enviado na entrada.
Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z"
e "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Somente entrada. Novo TTL para este recurso, somente entrada.
Duração em segundos com até nove dígitos fracionários, terminando em "s
". Exemplo: "3.5s"
.
name
string
Opcional. Identificador. O nome do recurso que se refere ao conteúdo armazenado em cache. Formato: cachedContents/{id}
displayName
string
Opcional. Imutável. O nome de exibição significativo gerado pelo usuário do conteúdo armazenado em cache. No máximo 128 caracteres Unicode.
model
string
Obrigatório. Imutável. O nome do Model
que será usado para conteúdo em cache. Formato: models/{model}
systemInstruction
object (Content
)
Opcional. Somente entrada. Imutável. O desenvolvedor definiu as instruções do sistema. No momento, somente texto.
toolConfig
object (ToolConfig
)
Opcional. Somente entrada. Imutável. Configuração da ferramenta. Essa configuração é compartilhada para todas as ferramentas.
Exemplo de solicitação
Básico
Python
Node.js
Go
Concha
Nome do remetente
Python
Node.js
Go
Do chat
Python
Node.js
Go
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta incluirá uma instância de CachedContent
.
Método: cachedContents.list
Lista CachedContents.
Endpoint
recebe https://generativelanguage.googleapis.com/v1beta/cachedContentsParâmetros de consulta
pageSize
integer
Opcional. O número máximo de conteúdos em cache a serem retornados. O serviço pode retornar menos que esse valor. Se não for especificado, um número padrão (abaixo do máximo) de itens será retornado. O valor máximo é 1.000. Valores maiores serão convertidos para 1.000.
pageToken
string
Opcional. Um token de página recebido de uma chamada cachedContents.list
anterior. Forneça isso para recuperar a página subsequente.
Ao paginar, todos os outros parâmetros fornecidos para cachedContents.list
precisam corresponder à chamada que forneceu o token da página.
Corpo da solicitação
O corpo da solicitação precisa estar vazio.
Corpo da resposta
Resposta com a lista CachedContents.
Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:
cachedContents[]
object (CachedContent
)
Lista de conteúdo armazenado em cache.
nextPageToken
string
Um token, que pode ser enviado como pageToken
para recuperar a próxima página. Se esse campo for omitido, não haverá páginas subsequentes.
Representação JSON |
---|
{
"cachedContents": [
{
object ( |
Método: cachedContents.get
Lê o recurso CachedContent.
Endpoint
get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}Parâmetros de caminho
name
string
Obrigatório. O nome do recurso que se refere à entrada do cache de conteúdo. Formato: cachedContents/{id}
. Tem o formato cachedContents/{cachedcontent}
.
Corpo da solicitação
O corpo da solicitação precisa estar vazio.
Exemplo de solicitação
Python
Node.js
Go
Concha
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de CachedContent
.
Método: cacheContents.patch
- Endpoint
- Parâmetros de caminho
- Parâmetros de consulta
- Corpo da solicitação
- Corpo da resposta
- Exemplo de solicitação
Atualiza o recurso CachedContent. Só é possível atualizar a validade.
Endpoint
patch https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
Parâmetros de caminho
cachedContent.name
string
Opcional. Identificador. O nome do recurso que se refere ao conteúdo armazenado em cache. Formato: cachedContents/{id}
. Ele assume o formato cachedContents/{cachedcontent}
.
Parâmetros de consulta
updateMask
string (FieldMask
format)
Lista de campos a serem atualizados.
É uma lista separada por vírgulas de nomes de campos totalmente qualificados. Exemplo: "user.displayName,photo"
.
Corpo da solicitação
O corpo da solicitação contém uma instância de CachedContent
.
expiration
. Especifica quando esse recurso vai expirar. expiration
pode ser apenas de um dos tipos a seguir:
expireTime
string (Timestamp
format)
Carimbo de data/hora em UTC de quando o recurso será considerado expirado. Isso é sempre fornecido na saída, independente do que tiver sido enviado na entrada.
Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z"
e "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Somente entrada. Novo TTL para este recurso, somente entrada.
Duração em segundos com até nove dígitos fracionários, terminando em "s
". Exemplo: "3.5s"
.
name
string
Opcional. Identificador. O nome do recurso que se refere ao conteúdo armazenado em cache. Formato: cachedContents/{id}
Exemplo de solicitação
Python
Node.js
Go
Concha
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de CachedContent
.
Método: cacheContents.delete
Exclui o recurso CachedContent.
Endpoint
delete https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}Parâmetros de caminho
name
string
Obrigatório. O nome do recurso que se refere à entrada do cache de conteúdo. Formato: cachedContents/{id}
. Ele assume o formato cachedContents/{cachedcontent}
.
Corpo da solicitação
O corpo da solicitação precisa estar vazio.
Exemplo de solicitação
Python
Node.js
Go
Concha
Corpo da resposta
Se a solicitação for concluída, o corpo da resposta estará vazio.
Recurso REST: cacheContents
- Recurso: CachedContent
- Conteúdo
- Parte
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- Idioma
- CodeExecutionResult
- Resultado
- Ferramenta
- FunctionDeclaration
- Esquema
- Tipo
- CodeExecution
- ToolConfig
- FunctionCallingConfig
- Mode
- UsageMetadata
- Métodos
Recurso: CachedContent
Conteúdo que foi pré-processado e pode ser usado em uma solicitação subsequente para o GenerativeService.
O conteúdo em cache só pode ser usado com o modelo para o qual foi criado.
contents[]
object (Content
)
Opcional. Somente entrada. Imutável. O conteúdo a ser armazenado em cache.
tools[]
object (Tool
)
Opcional. Somente entrada. Imutável. Uma lista de Tools
que o modelo pode usar para gerar a próxima resposta
createTime
string (Timestamp
format)
Apenas saída. Hora de criação da entrada do cache.
Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z"
e "2014-10-02T15:01:23.045123456Z"
.
updateTime
string (Timestamp
format)
Apenas saída. Quando a entrada do cache foi atualizada pela última vez no horário UTC.
Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z"
e "2014-10-02T15:01:23.045123456Z"
.
usageMetadata
object (UsageMetadata
)
Apenas saída. Metadados sobre o uso do conteúdo armazenado em cache.
expiration
. Especifica quando esse recurso vai expirar. expiration
pode ser apenas de um dos tipos a seguir:
expireTime
string (Timestamp
format)
Carimbo de data/hora em UTC de quando o recurso será considerado expirado. Isso é sempre fornecido na saída, independente do que tiver sido enviado na entrada.
Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z"
e "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Somente entrada. Novo TTL para este recurso, somente entrada.
Duração em segundos com até nove dígitos fracionários, terminando em "s
". Exemplo: "3.5s"
.
name
string
Opcional. Identificador. O nome do recurso que se refere ao conteúdo armazenado em cache. Formato: cachedContents/{id}
displayName
string
Opcional. Imutável. O nome de exibição significativo gerado pelo usuário do conteúdo armazenado em cache. No máximo 128 caracteres Unicode.
model
string
Obrigatório. Imutável. O nome do Model
que será usado para conteúdo em cache. Formato: models/{model}
systemInstruction
object (Content
)
Opcional. Somente entrada. Imutável. O desenvolvedor definiu as instruções do sistema. No momento, somente texto.
toolConfig
object (ToolConfig
)
Opcional. Somente entrada. Imutável. Configuração da ferramenta. Essa configuração é compartilhada para todas as ferramentas.
Representação JSON |
---|
{ "contents": [ { object ( |
Conteúdo
O tipo de dados estruturado base que contém o conteúdo de várias partes de uma mensagem.
Uma Content
inclui um campo role
que designa o produtor da Content
e um campo parts
que contém dados de várias partes com o conteúdo da troca de mensagens.
parts[]
object (Part
)
Ordem de Parts
que constitui uma única mensagem. As partes podem ter diferentes tipos MIME.
role
string
Opcional. O produtor do conteúdo. Precisa ser "user" ou "model".
Útil para definir conversas com vários turnos. Caso contrário, pode ser deixado em branco ou sem definição.
Representação JSON |
---|
{
"parts": [
{
object ( |
Parte
Um tipo de dados contendo mídia que faz parte de uma mensagem Content
de várias partes.
Um Part
consiste em dados que têm um tipo de dados associado. Uma Part
só pode conter um dos tipos aceitos no Part.data
.
Um Part
precisa ter um tipo MIME IANA fixo que identifica o tipo e o subtipo da mídia se o campo inlineData
estiver preenchido com bytes brutos.
Campo de união data
.
data
pode ser apenas de um dos tipos a seguir:
text
string
Texto inline.
inlineData
object (Blob
)
Bytes de mídia inline.
functionCall
object (FunctionCall
)
Uma previsão FunctionCall
retornada do modelo que contém uma string representando FunctionDeclaration.name
com os argumentos e os valores deles.
functionResponse
object (FunctionResponse
)
A saída resultante de uma FunctionCall
que contém uma string que representa o FunctionDeclaration.name
e um objeto JSON estruturado com qualquer saída da função é usada como contexto para o modelo.
fileData
object (FileData
)
Dados baseados em URI.
executableCode
object (ExecutableCode
)
Código gerado pelo modelo que precisa ser executado.
codeExecutionResult
object (CodeExecutionResult
)
Resultado da execução de ExecutableCode
.
Representação JSON |
---|
{ // Union field |
Blob
Bytes de mídia brutos.
O texto não deve ser enviado como bytes brutos. Use o campo "text".
mimeType
string
O tipo MIME padrão da IANA dos dados de origem. Exemplos: - image/png - image/jpeg Se um tipo MIME não aceito for fornecido, um erro será retornado. Para conferir uma lista completa de tipos aceitos, consulte Formatos de arquivo compatíveis.
data
string (bytes format)
Bytes brutos para formatos de mídia.
Uma string codificada em base64.
Representação JSON |
---|
{ "mimeType": string, "data": string } |
FunctionCall
Uma previsão FunctionCall
retornada do modelo que contém uma string representando FunctionDeclaration.name
com os argumentos e os valores deles.
name
string
Obrigatório. O nome da função a ser chamada. Precisa ser a-z, A-Z, 0-9 ou conter sublinhados e traços, com comprimento máximo de 63.
args
object (Struct
format)
Opcional. Os parâmetros e valores da função no formato de objeto JSON.
Representação JSON |
---|
{ "name": string, "args": { object } } |
FunctionResponse
O resultado de uma FunctionCall
que contém uma string representando o FunctionDeclaration.name
e um objeto JSON estruturado contendo qualquer saída da função é usada como contexto para o modelo. Ela precisa conter o resultado de uma FunctionCall
feita com base na previsão do modelo.
name
string
Obrigatório. O nome da função a ser chamada. Precisa ser az, AZ, 0-9 ou conter sublinhados e traços, com um tamanho máximo de 63.
response
object (Struct
format)
Obrigatório. A resposta da função no formato de objeto JSON.
Representação JSON |
---|
{ "name": string, "response": { object } } |
FileData
Dados baseados em URI.
mimeType
string
Opcional. O tipo MIME padrão IANA dos dados de origem.
fileUri
string
Obrigatório. URI.
Representação JSON |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
Código gerado pelo modelo que precisa ser executado e o resultado retornado ao modelo.
Gerado somente ao usar a ferramenta CodeExecution
, em que o código será executado automaticamente e um CodeExecutionResult
correspondente também será gerado.
language
enum (Language
)
Obrigatório. Linguagem de programação do code
.
code
string
Obrigatório. O código a ser executado.
Representação JSON |
---|
{
"language": enum ( |
Idioma
Linguagens de programação compatíveis para o código gerado.
Enums | |
---|---|
LANGUAGE_UNSPECIFIED |
Idioma não especificado. Esse valor não deve ser usado. |
PYTHON |
Python >= 3.10, com numpy e simpy disponíveis. |
CodeExecutionResult
Resultado da execução de ExecutableCode
.
Só é gerado quando se usa CodeExecution
e sempre segue um part
que contém ExecutableCode
.
outcome
enum (Outcome
)
Obrigatório. Resultado da execução do código.
output
string
Opcional. Contém stdout quando a execução do código é bem-sucedida. Caso contrário, contém stderr ou outra descrição.
Representação JSON |
---|
{
"outcome": enum ( |
Resultado
Enumeração dos possíveis resultados da execução do código.
Enums | |
---|---|
OUTCOME_UNSPECIFIED |
Status não especificado. Este valor não deve ser usado. |
OUTCOME_OK |
A execução do código foi concluída. |
OUTCOME_FAILED |
A execução do código foi concluída, mas com falha. stderr precisa conter o motivo. |
OUTCOME_DEADLINE_EXCEEDED |
A execução do código levou muito tempo e foi cancelada. Pode haver ou não uma saída parcial. |
Ferramenta
Detalhes da ferramenta que o modelo pode usar para gerar uma resposta.
Um Tool
é um código que permite ao sistema interagir com sistemas externos para realizar uma ação ou conjunto de ações fora do conhecimento e do escopo do modelo.
functionDeclarations[]
object (FunctionDeclaration
)
Opcional. Uma lista de FunctionDeclarations
disponíveis para o modelo que podem ser usados para chamar funções.
O modelo ou sistema não executa a função. Em vez disso, a função definida pode ser retornada como um FunctionCall
com argumentos para o lado do cliente para execução. O modelo pode decidir chamar um subconjunto dessas funções preenchendo FunctionCall
na resposta. A próxima vez que a conversa for iniciada, ela poderá conter um FunctionResponse
com o contexto de geração da "função" Content.role
para a próxima vez que o modelo for iniciado.
codeExecution
object (CodeExecution
)
Opcional. Permite que o modelo execute código como parte da geração.
Representação JSON |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
Representação estruturada de uma declaração de função, conforme definido pela especificação OpenAPI 3.03. Essa declaração inclui o nome e os parâmetros da função. Essa declaração de função é uma representação de um bloco de código que pode ser usado como Tool
pelo modelo e executado pelo cliente.
name
string
Obrigatório. O nome da função. Precisa ser az, AZ, 0-9 ou conter sublinhados e traços, com um tamanho máximo de 63.
description
string
Obrigatório. Uma breve descrição da função.
parameters
object (Schema
)
Opcional. Descreve os parâmetros dessa função. Reflete a chave de string do objeto de parâmetro da API Open 3.03: o nome do parâmetro. Os nomes dos parâmetros diferenciam maiúsculas de minúsculas. Valor do esquema: o esquema que define o tipo usado para o parâmetro.
Representação JSON |
---|
{
"name": string,
"description": string,
"parameters": {
object ( |
Esquema
O objeto Schema
permite a definição de tipos de dados de entrada e saída. Esses tipos podem ser objetos, mas também primitivos e matrizes. Representa um subconjunto selecionado de um objeto de esquema da OpenAPI 3.0.
type
enum (Type
)
Obrigatório. Tipo de dados.
format
string
Opcional. O formato dos dados. Isso é usado apenas para tipos de dados primitivos. Formatos aceitos: para o tipo NUMBER: flutuante, duplo para o tipo INTEGER: int32, int64 para o tipo STRING: enumeração
description
string
Opcional. Uma breve descrição do parâmetro. Ela pode conter exemplos de uso. A descrição do parâmetro pode ser formatada como Markdown.
nullable
boolean
Opcional. Indica se o valor pode ser nulo.
enum[]
string
Opcional. Possíveis valores do elemento de Type.STRING com formato de enumeração. Por exemplo, podemos definir uma Direção de tipo enumerado como : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
maxItems
string (int64 format)
Opcional. Número máximo de elementos para Type.ARRAY.
minItems
string (int64 format)
Opcional. Número mínimo de elementos para Type.ARRAY.
properties
map (key: string, value: object (Schema
))
Opcional. Propriedades de Type.OBJECT.
Um objeto com uma lista de pares "key": value
. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }
.
required[]
string
Opcional. Propriedades obrigatórias de Type.OBJECT.
items
object (Schema
)
Opcional. Esquema dos elementos de Type.ARRAY.
Tipo
Tipo contém a lista de tipos de dados OpenAPI, conforme definido por https://spec.openapis.org/oas/v3.0.3#data-types
Enums | |
---|---|
TYPE_UNSPECIFIED |
Não especificado, não deve ser usado. |
STRING |
Tipo de string. |
NUMBER |
Tipo de número. |
INTEGER |
Tipo inteiro. |
BOOLEAN |
Tipo booleano. |
ARRAY |
Tipo de matriz. |
OBJECT |
Tipo de objeto. |
CodeExecution
Esse tipo não tem campos.
Ferramenta que executa o código gerado pelo modelo e retorna automaticamente o resultado ao modelo.
Consulte também ExecutableCode
e CodeExecutionResult
, que são gerados apenas ao usar essa ferramenta.
ToolConfig
A configuração da ferramenta que contém parâmetros para especificar o uso de Tool
na solicitação.
functionCallingConfig
object (FunctionCallingConfig
)
Opcional. Config. da chamada de função.
Representação JSON |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
Configuração para especificar o comportamento de chamada de função.
mode
enum (Mode
)
Opcional. Especifica o modo em que a chamada de função precisa ser executada. Se não for especificado, o valor padrão será definido como AUTOMÁTICO.
allowedFunctionNames[]
string
Opcional. Um conjunto de nomes de função que, quando fornecido, limita as funções que o modelo vai chamar.
Isso só deve ser definido quando o modo for QUALQUER. Os nomes das funções precisam corresponder a [FunctionDeclaration.name]. Com o modo definido como ANY, o modelo prevê uma chamada de função do conjunto de nomes de função fornecido.
Representação JSON |
---|
{
"mode": enum ( |
Modo
Define o comportamento de execução para a chamada de função ao definir o modo de execução.
Enums | |
---|---|
MODE_UNSPECIFIED |
Modo de chamada de função não especificado. Esse valor não deve ser usado. |
AUTO |
Comportamento padrão do modelo, em que ele decide prever uma chamada de função ou uma resposta de linguagem natural. |
ANY |
O modelo é restrito a sempre prever apenas uma chamada de função. Se "allowedFunctionNames" estiver definido, a chamada de função prevista será limitada a qualquer um dos "allowedFunctionNames". Caso contrário, a chamada de função prevista será qualquer uma das "functionDeclarations" fornecidas. |
NONE |
O modelo não vai prever nenhuma chamada de função. O comportamento do modelo é o mesmo que ocorre quando nenhuma declaração de função é transmitida. |
UsageMetadata
Metadados sobre o uso do conteúdo armazenado em cache.
totalTokenCount
integer
Número total de tokens que o conteúdo em cache consome.
Representação JSON |
---|
{ "totalTokenCount": integer } |