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
.
Exemplo de solicitação
Básico
Python
Node.js
Nome do remetente
Python
Node.js
Do chat
Python
Node.js
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
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
.
Exemplo de solicitação
Python
Node.js
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
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 solicitações posteriores ao GenerativeService.
O conteúdo armazenado em cache só pode ser usado com o modelo para o qual foi criado.
Representação JSON |
---|
{ "contents": [ { object ( |
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.
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.
Representação JSON |
---|
{
"parts": [
{
object ( |
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 "modelo".
Útil para definir para conversas de várias interações. Caso contrário, pode ser deixado em branco ou sem definição.
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.
Representação JSON |
---|
{ // Union field |
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
.
Blob
Bytes de mídia bruta.
O texto não deve ser enviado como bytes brutos. Use o "texto" .
Representação JSON |
---|
{ "mimeType": string, "data": string } |
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.
FunctionCall
Uma previsão FunctionCall
retornada do modelo que contém uma string representando FunctionDeclaration.name
com os argumentos e os valores deles.
Representação JSON |
---|
{ "name": string, "args": { object } } |
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.
FunctionResponse
A saída resultante de um FunctionCall
que contém uma string que representa 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.
Representação JSON |
---|
{ "name": string, "response": { object } } |
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.
FileData
Dados baseados em URI.
Representação JSON |
---|
{ "mimeType": string, "fileUri": string } |
mimeType
string
Opcional. O tipo MIME padrão da IANA dos dados de origem.
fileUri
string
Obrigatório. URI.
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.
Representação JSON |
---|
{
"language": enum ( |
language
enum (Language
)
Obrigatório. Linguagem de programação do code
.
code
string
Obrigatório. O código a ser executado.
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
.
Representação JSON |
---|
{
"outcome": enum ( |
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.
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. |
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.
Representação JSON |
---|
{ "functionDeclarations": [ { object ( |
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.
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.
Representação JSON |
---|
{
"name": string,
"description": string,
"parameters": {
object ( |
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.
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.
Representação JSON |
---|
{ "type": enum ( |
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"]}
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.
Representação JSON |
---|
{
"functionCallingConfig": {
object ( |
functionCallingConfig
object (FunctionCallingConfig
)
Opcional. Config. da chamada de função.
FunctionCallingConfig
Configuração para especificar o comportamento de chamada de função.
Representação JSON |
---|
{
"mode": enum ( |
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.
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.
Representação JSON |
---|
{ "totalTokenCount": integer } |
totalTokenCount
integer
Número total de tokens que o conteúdo em cache consome.