Caching

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 em cache de contexto.

Método: cachedContents.create

Cria o recurso CachedContent.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/cachedContents

Corpo da solicitação

O corpo da solicitação contém uma instância de CachedContent.

Campos
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

Campo de união 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 do conteúdo em cache gerado pelo usuário. No máximo 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. Instrução do sistema definida pelo desenvolvedor. 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

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
print(cache)

model = genai.GenerativeModel.from_cached_content(cache)
response = model.generate_content("Please summarize this transcript")
print(response.text)

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});

console.log(cacheResult);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(cacheResult);
const result = await model.generateContent(
  "Please summarize this transcript.",
);
console.log(result.response.text());

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
prompt := "Please summarize this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

Concha

wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-1.5-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d @request.json \
 > cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-001:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

Nome do remetente

Python

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
cache_name = cache.name  # Save the name for later

# Later
cache = genai.caching.CachedContent.get(cache_name)
apollo_model = genai.GenerativeModel.from_cached_content(cache)
response = apollo_model.generate_content("Find a lighthearted moment from this transcript")
print(response.text)

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
const cacheName = cacheResult.name; // Save the name for later.

// Later
const getCacheResult = await cacheManager.get(cacheName);
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(getCacheResult);
model.generateContent("Please summarize this transcript.");

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

// Save the name for later
cacheName := cc.Name

// ... Later
cc2, err := client.GetCachedContent(ctx, cacheName)
if err != nil {
	log.Fatal(err)
}
modelWithCache := client.GenerativeModelFromCachedContent(cc2)
prompt := "Find a lighthearted moment from this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

Do chat

Python

model_name = "gemini-1.5-flash-001"
system_instruction = "You are an expert analyzing transcripts."

model = genai.GenerativeModel(model_name=model_name, system_instruction=system_instruction)
chat = model.start_chat()
document = genai.upload_file(path=media / "a11.txt")
response = chat.send_message(["Hi, could you summarize this transcript?", document])
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    ["Okay, could you tell me more about the trans-lunar injection"]
)
print("\n\nmodel:  ", response.text)

# To cache the conversation so far, pass the chat history as the list of "contents".
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction=system_instruction,
    contents=chat.history,
)
model = genai.GenerativeModel.from_cached_content(cached_content=cache)

# Continue the chat where you left off.
chat = model.start_chat()
response = chat.send_message(
    "I didn't understand that last part, could you explain it in simpler language?"
)
print("\n\nmodel:  ", response.text)

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash-001" });
const chat = model.startChat();

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

let result = await chat.sendMessage([
  "Hi, could you summarize this transcript?",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(`\n\nmodel: ${result.response.text()}`);
result = await chat.sendMessage(
  "Okay, could you tell me more about the trans-lunar injection",
);
console.log(`\n\nmodel: ${result.response.text()}`);

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: await chat.getHistory(),
});

const newModel = genAI.getGenerativeModelFromCachedContent(cacheResult);

const newChat = newModel.startChat();
result = await newChat.sendMessage(
  "I didn't understand that last part, could you explain it in simpler language?",
);
console.log(`\n\nmodel: ${result.response.text()}`);

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

modelName := "gemini-1.5-flash-001"
model := client.GenerativeModel(modelName)
model.SystemInstruction = genai.NewUserContent(genai.Text("You are an expert analyzing transcripts."))

cs := model.StartChat()
resp, err := cs.SendMessage(ctx, genai.Text("Hi, could you summarize this transcript?"), fd)
if err != nil {
	log.Fatal(err)
}

resp, err = cs.SendMessage(ctx, genai.Text("Okay, could you tell me more about the trans-lunar injection"))
if err != nil {
	log.Fatal(err)
}

// To cache the conversation so far, pass the chat history as the list of
// contents.

argcc := &genai.CachedContent{
	Model:             modelName,
	SystemInstruction: model.SystemInstruction,
	Contents:          cs.History,
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
cs = modelWithCache.StartChat()
resp, err = cs.SendMessage(ctx, genai.Text("I didn't understand that last part, could you please explain it in simpler language?"))
if err != nil {
	log.Fatal(err)
}
printResponse(resp)

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

get https://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:

Campos
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 (CachedContent)
    }
  ],
  "nextPageToken": string
}

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

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
print(genai.caching.CachedContent.get(name=cache.name))

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
const cacheGetResult = await cacheManager.get(cacheResult.name);
console.log(cacheGetResult);

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

// Save the name for later
cacheName := cc.Name

// ... Later
cc2, err := client.GetCachedContent(ctx, cacheName)
if err != nil {
	log.Fatal(err)
}
modelWithCache := client.GenerativeModelFromCachedContent(cc2)
prompt := "Find a lighthearted moment from this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

Concha

curl "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY"

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de CachedContent.

Método: cachedContents.patch

Atualiza o recurso CachedContent. Somente a validade pode ser atualizada.

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}. 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.

Campos
Campo de união 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

import datetime

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)

# You can update the ttl
cache.update(ttl=datetime.timedelta(hours=2))
print(f"After update:\n {cache}")

# Or you can update the expire_time
cache.update(expire_time=datetime.datetime.now() + datetime.timedelta(minutes=15))

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
console.log("initial cache data:", cacheResult);
const cacheUpdateResult = await cacheManager.update(cacheResult.name, {
  cachedContent: {
    // 2 hours
    ttlSeconds: 60 * 60 * 2,
  },
});
console.log("updated cache data:", cacheUpdateResult);

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

Concha

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

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 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

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
cache.delete()

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
await cacheManager.delete(cacheResult.name);

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

Concha

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY"

Corpo da resposta

Se a solicitação for concluída, o corpo da resposta estará vazio.

Recurso REST: cacheContents

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.

Campos
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.

Campo de união 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 do conteúdo em cache gerado pelo usuário. No máximo 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. Instrução do sistema definida pelo desenvolvedor. 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 (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "usageMetadata": {
    object (UsageMetadata)
  },

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
  "name": string,
  "displayName": string,
  "model": string,
  "systemInstruction": {
    object (Content)
  },
  "toolConfig": {
    object (ToolConfig)
  }
}

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 troca de mensagens.

Campos
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 conversas com vários turnos. Caso contrário, pode ser deixado em branco ou sem definição.

Representação JSON
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

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.

Campos

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)

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 será executado.

codeExecutionResult object (CodeExecutionResult)

Resultado da execução do ExecutableCode.

Representação JSON
{

  // Union field data can be only one of the following:
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  }
  // End of list of possible types for union field data.
}

Blob

Bytes de mídia brutos.

O texto não deve ser enviado como bytes brutos. Use o campo "texto".

Campos
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

Um FunctionCall previsto retornado do modelo que contém uma string que representa o FunctionDeclaration.name com os argumentos e os valores deles.

Campos
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

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.

Campos
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.

Campos
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.

Gerado somente ao usar a ferramenta CodeExecution, em que o código será executado automaticamente e um CodeExecutionResult correspondente também será gerado.

Campos
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 (Language),
  "code": string
}

Idioma

Linguagens de programação compatíveis 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 de ExecutableCode.

Só é gerado quando se usa CodeExecution e sempre segue um part que contém ExecutableCode.

Campos
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 (Outcome),
  "output": string
}

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 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 a 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.

Campos
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 da "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 código como parte da geração.

Representação JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  }
}

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.

Campos
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 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 (Schema)
  }
}

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.

Campos
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. 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.

items object (Schema)

Opcional. Esquema dos elementos de Type.ARRAY.

Representação JSON
{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "items": {
    object (Schema)
  }
}

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.

Campos
dynamicRetrievalConfig object (DynamicRetrievalConfig)

Especifica a configuração de recuperação dinâmica para a origem especificada.

Representação JSON
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

Descreve as opções para personalizar a recuperação dinâmica.

Campos
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 (Mode),
  "dynamicThreshold": number
}

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 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.

Campos
functionCallingConfig object (FunctionCallingConfig)

Opcional. Config. da chamada de função.

Representação JSON
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  }
}

FunctionCallingConfig

Configuração para especificar o comportamento de chamada de função.

Campos
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 ANY, o modelo prevê uma chamada de função do conjunto de nomes de função fornecido.

Representação JSON
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

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 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 que ocorre quando nenhuma declaração de função é transmitida.

UsageMetadata

Metadados sobre o uso do conteúdo armazenado em cache.

Campos
totalTokenCount integer

Número total de tokens consumidos pelo conteúdo armazenado em cache.

Representação JSON
{
  "totalTokenCount": integer
}