O armazenamento em cache de contexto permite salvar e reutilizar tokens de entrada pré-calculados que você quer usar repetidamente, por exemplo, ao fazer perguntas diferentes sobre o mesmo arquivo de mídia. Isso pode levar a economias de custo e velocidade, dependendo do uso. Para uma introdução detalhada, consulte o guia Armazenamento em cache de contexto.
Método: cachedContents.create
Cria o recurso CachedContent.
Endpoint
posthttps: / /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
Union type
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.
Usa o RFC 3339, em que a saída gerada é sempre normalizada em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Deslocamentos diferentes de "Z" também são aceitos. Exemplos: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
ou "2014-10-02T15:01:23+05:30"
.
ttl
string (Duration
format)
Somente entrada. Novo TTL para este recurso, apenas 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 do conteúdo em cache gerado pelo usuário. Máximo de 128 caracteres Unicode.
model
string
Obrigatório. Imutável. O nome do Model
a ser usado para conteúdo em cache Formato: models/{model}
systemInstruction
object (Content
)
Opcional. Somente entrada. Imutável. O desenvolvedor definiu a instrução 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
No 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
gethttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
Parâ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
gethttps: / /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: cachedContents.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. Somente a validade pode ser atualizada.
Endpoint
patchhttps: / /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}
. Tem 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
Union type
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.
Usa o RFC 3339, em que a saída gerada é sempre normalizada em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Deslocamentos diferentes de "Z" também são aceitos. Exemplos: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
ou "2014-10-02T15:01:23+05:30"
.
ttl
string (Duration
format)
Somente entrada. Novo TTL para este recurso, apenas 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: cachedContents.delete
Exclui o recurso CachedContent.
Endpoint
deletehttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
Parâmetros de caminho
name
string
Obrigatório. O nome do recurso que se refere ao formato da entrada do cache de conteúdo: cachedContents/{id}
. Ele 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 será um objeto JSON vazio.
Recurso REST: cachedContents
- Recurso: CachedContent
- Conteúdo
- Parte
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- Idioma
- CodeExecutionResult
- Resultado
- Ferramenta
- FunctionDeclaration
- Esquema
- Tipo
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- Moda
- CodeExecution
- GoogleSearch
- ToolConfig
- FunctionCallingConfig
- Moda
- 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.
Usa o RFC 3339, em que a saída gerada é sempre normalizada em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Deslocamentos diferentes de "Z" também são aceitos. Exemplos: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
ou "2014-10-02T15:01:23+05:30"
.
updateTime
string (Timestamp
format)
Apenas saída. Quando a entrada do cache foi atualizada pela última vez no horário UTC.
Usa o RFC 3339, em que a saída gerada é sempre normalizada em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Deslocamentos diferentes de "Z" também são aceitos. Exemplos: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
ou "2014-10-02T15:01:23+05:30"
.
usageMetadata
object (UsageMetadata
)
Apenas saída. Metadados sobre o uso do conteúdo armazenado em cache.
expiration
Union type
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.
Usa o RFC 3339, em que a saída gerada é sempre normalizada em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Deslocamentos diferentes de "Z" também são aceitos. Exemplos: "2014-10-02T15:01:23Z"
, "2014-10-02T15:01:23.045123456Z"
ou "2014-10-02T15:01:23+05:30"
.
ttl
string (Duration
format)
Somente entrada. Novo TTL para este recurso, apenas 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 do conteúdo em cache gerado pelo usuário. Máximo de 128 caracteres Unicode.
model
string
Obrigatório. Imutável. O nome do Model
a ser usado para conteúdo em cache Formato: models/{model}
systemInstruction
object (Content
)
Opcional. Somente entrada. Imutável. O desenvolvedor definiu a instrução 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 estruturados de base que contém 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 mensagem.
parts[]
object (Part
)
Parts
ordenados que constituem 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 que contém 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. Um Part
só pode conter um dos tipos aceitos em Part.data
.
Um Part
precisa ter um tipo MIME IANA fixo que identifique o tipo e o subtipo da mídia se o campo inlineData
estiver preenchido com bytes brutos.
data
Union type
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
)
Um FunctionCall
previsto retornado do modelo que contém uma string que representa o 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 deve ser executado.
codeExecutionResult
object (CodeExecutionResult
)
Resultado da execução do ExecutableCode
.
Representação JSON |
---|
{ // data "text": string, "inlineData": { object ( |
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 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
Um FunctionCall
previsto retornado do modelo que contém uma string que representa o FunctionDeclaration.name
com os argumentos e os valores deles.
id
string
Opcional. O ID exclusivo da chamada de função. Se preenchido, o cliente vai executar o functionCall
e retornar a resposta com o id
correspondente.
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.
args
object (Struct
format)
Opcional. Os parâmetros e valores da função no formato de objeto JSON.
Representação JSON |
---|
{ "id": string, "name": string, "args": { object } } |
FunctionResponse
A saída do resultado 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. Ela precisa conter o resultado de uma FunctionCall
feita com base na previsão do modelo.
id
string
Opcional. O ID da chamada de função para a qual esta resposta é destinada. Preenchido pelo cliente para corresponder à chamada de função id
correspondente.
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 |
---|
{ "id": string, "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 deve ser executado e o resultado retornado ao modelo.
Só é gerado quando você usa a ferramenta CodeExecution
, em que o código é executado automaticamente e um CodeExecutionResult
correspondente também é 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 com suporte para o código gerado.
Enums | |
---|---|
LANGUAGE_UNSPECIFIED |
Idioma não especificado. Este valor não deve ser usado. |
PYTHON |
Python >= 3.10, com numpy e simpy disponíveis. |
CodeExecutionResult
Resultado da execução do ExecutableCode
.
Só é gerado quando você 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, stderr ou outra descrição.
Representação JSON |
---|
{
"outcome": enum ( |
Resultado
Enumeração de 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 uma falha. stderr precisa conter o motivo. |
OUTCOME_DEADLINE_EXCEEDED |
A execução do código demorou muito e foi cancelada. Pode haver ou não uma saída parcial. |
Ferramenta
Detalhes da ferramenta que o modelo pode usar para gerar a 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 mudar, ela pode conter um FunctionResponse
com o contexto de geração de "função" Content.role
para a próxima vez que o modelo mudar.
googleSearchRetrieval
object (GoogleSearchRetrieval
)
Opcional. Ferramenta de recuperação com a tecnologia da Pesquisa Google.
codeExecution
object (CodeExecution
)
Opcional. Permite que o modelo execute o código como parte da geração.
googleSearch
object (GoogleSearch
)
Opcional. Tipo de ferramenta do GoogleSearch. Ferramenta para oferecer suporte à Pesquisa Google no modelo. Com tecnologia do Google.
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 aberta 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.
response
object (Schema
)
Opcional. Descreve a saída dessa função no formato de esquema JSON. Reflete o objeto de resposta da API aberta 3.03. O esquema define o tipo usado para o valor de resposta da função.
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 compatíveis: para o tipo NUMBER: flutuante, duplo para o tipo INTEGER: int32, int64 para o tipo STRING: enumeração, data e hora
description
string
Opcional. Uma breve descrição do parâmetro. Isso pode incluir 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. Valores possíveis do elemento de Type.STRING com formato de tipo enumerado. 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.
propertyOrdering[]
string
Opcional. A ordem das propriedades. Não é um campo padrão na especificação da OpenAPI. É usado para determinar a ordem das propriedades na resposta.
items
object (Schema
)
Opcional. Esquema dos elementos de Type.ARRAY.
Representação JSON |
---|
{ "type": enum ( |
Tipo
O tipo contém a lista de tipos de dados da OpenAPI, conforme definido em 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. |
GoogleSearchRetrieval
Ferramenta para extrair dados públicos da Web para embasamento, com tecnologia do Google.
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
Especifica a configuração de recuperação dinâmica para a origem especificada.
Representação JSON |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
Descreve as opções para personalizar a recuperação dinâmica.
mode
enum (Mode
)
O modo do preditor a ser usado na recuperação dinâmica.
dynamicThreshold
number
O limite a ser usado na recuperação dinâmica. Se não for definido, um valor padrão do sistema será usado.
Representação JSON |
---|
{
"mode": enum ( |
Modo
O modo do preditor a ser usado na recuperação dinâmica.
Enums | |
---|---|
MODE_UNSPECIFIED |
Sempre acionar a recuperação. |
MODE_DYNAMIC |
Execute a recuperação somente quando o sistema decidir que é necessário. |
CodeExecution
Esse tipo não tem campos.
Ferramenta que executa o código gerado pelo modelo e retorna automaticamente o resultado para ele.
Consulte também ExecutableCode
e CodeExecutionResult
, que são gerados apenas ao usar essa ferramenta.
GoogleSearch
Esse tipo não tem campos.
Tipo de ferramenta do GoogleSearch. Ferramenta para oferecer suporte à Pesquisa Google no modelo. Com tecnologia do Google.
ToolConfig
A configuração da ferramenta que contém parâmetros para especificar o uso de Tool
na solicitação.
functionCallingConfig
object (FunctionCallingConfig
)
Opcional. Configuração de 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 AUTO.
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 definindo o modo de execução.
Enums | |
---|---|
MODE_UNSPECIFIED |
Modo de chamada de função não especificado. Este 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 consumidos pelo conteúdo armazenado em cache.
Representação JSON |
---|
{ "totalTokenCount": integer } |