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 economias de custo e velocidade, dependendo do uso. Para uma introdução detalhada, consulte o guia Armazenamento de contexto em cache.
Método: cacheContents.create
Cria o recurso CachedContent.
Endpoint
postar
https://generativelanguage.googleapis.com/v1beta/cachedContents
Corpo 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 este 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. Máximo de 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: cacheContents.list
Lista CachedContents.
Endpoint
recebe
https://generativelanguage.googleapis.com/v1beta/cachedContents
Parâmetros de consulta
pageSize
integer
Opcional. O número máximo de conteúdo em cache a ser retornado. O serviço pode retornar menos que esse valor. Se não for especificado, será retornado algum número de itens padrão (abaixo do máximo). 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: cacheContents.get
Lê o recurso CachedContent.
Endpoint
recebe
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 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 (apenas a expiração é atualizável).
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 este 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
excluir
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 (em inglês)
- FunctionResponse (em inglês)
- FileData (link em inglês)
- ExecutableCode
- Idioma
- CodeExecutionResult
- Resultado
- Ferramenta
- FunctionDeclaration (em inglês)
- Esquema
- Tipo
- CodeExecution
- ToolConfig (em inglês)
- FunctionCallingConfig (em inglês)
- Mode
- UsageMetadata (em inglês)
- Métodos
Recurso: CachedContent
Conteúdo que foi pré-processado e pode ser usado em solicitações posteriores ao GenerativeService.
O conteúdo armazenado 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 este 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. Máximo de 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 "modelo".
Útil para definir para conversas de várias interações. 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
)
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.
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 bruta.
O texto não deve ser enviado como bytes brutos. Use o "texto" .
mimeType
string
O tipo MIME padrão da IANA dos dados de origem. Exemplos: - image/png - image/jpeg Se um tipo MIME incompatível for fornecido, será retornado um erro. Para uma lista completa dos tipos compatíveis, 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 vai 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 a-z, A-Z, 0-9 ou conter sublinhados e traços, com comprimento 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 da 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 com o código gerado.
Enums | |
---|---|
LANGUAGE_UNSPECIFIED |
Idioma não especificado. Esse valor não deve ser usado. |
PYTHON |
versão 3.10 ou mais recente do Python, com numpy e simpy disponíveis. |
CodeExecutionResult
Resultado da execução de ExecutableCode
.
Gerado somente ao usar o CodeExecution
e sempre segue um part
contendo o 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. Esse 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 presente. |
Ferramenta
Detalhes da ferramenta que o modelo pode usar para gerar uma resposta.
Um Tool
é um trecho de 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 pode ser usada 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 uma [FunctionCall][content.part.function_call] com argumentos para execução no lado do cliente. O modelo pode decidir chamar um subconjunto dessas funções preenchendo [FunctionCall][content.part.function_call] na resposta. A próxima conversa pode conter uma [FunctionResponse][content.part.function_response] com a "função" [content.role] de geração de valor para a próxima rodada do modelo.
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 (em inglês). Essa declaração inclui o nome e os parâmetros da função. Essa FunctionDeclaration é uma representação de um bloco de código que pode ser usado como um Tool
pelo modelo e executado pelo cliente.
name
string
Obrigatório. O nome da função. Precisa ser a-z, A-Z, 0-9 ou conter sublinhados e traços, com comprimento máximo de 63.
description
string
Obrigatório. Uma breve descrição da função.
parameters
object (Schema
)
Opcional. Descreve os parâmetros para esta função. Reflete a chave da string do objeto de parâmetro da OpenAPI 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 com suporte: para NUMBER, tipo: float, double para INTEGER tipo: int32, int64 para STRING tipo: enum
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.
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 de número 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 somente 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 fornecidos, 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 QUALQUER, o modelo vai prever uma chamada de função do conjunto de nomes de função fornecidos.
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: o modelo 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 definida, a chamada de função prevista será limitada a qualquer um dos "allowedFunctionNames". Caso contrário, a chamada da 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 de 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 consumidos pelo conteúdo em cache.
Representação JSON |
---|
{ "totalTokenCount": integer } |