Caching

La memorizzazione nella cache del contesto ti consente di salvare e riutilizzare i token di input precomputati che vuoi utilizzare ripetutamente, ad esempio quando fai domande diverse sullo stesso file multimediale. Ciò può comportare un risparmio in termini di costi e velocità, a seconda dell'utilizzo. Per un'introduzione dettagliata, consulta la guida alla memorizzazione nella cache del contesto.

Metodo: cacheContents.create

Crea la risorsa CachedContent.

Endpoint

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

Corpo della richiesta

Il corpo della richiesta contiene un'istanza di CachedContent.

Campi
contents[] object (Content)

(Facoltativo) Solo input. Immutabile. I contenuti da memorizzare nella cache.

tools[] object (Tool)

(Facoltativo) Solo input. Immutabile. Un elenco di Tools che il modello potrebbe utilizzare per generare la risposta successiva

Campo unione expiration. Specifica quando scadrà questa risorsa. expiration può essere solo uno dei seguenti:
expireTime string (Timestamp format)

Timestamp in UTC di quando questa risorsa è considerata scaduta. Viene sempre fornito nell'output, indipendentemente da ciò che è stato inviato nell'input.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione a livello di nanosecondo e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

Solo input. Nuovo TTL per questa risorsa, solo input.

Durata in secondi con un massimo di nove cifre frazionarie e termina con "s". Esempio: "3.5s".

name string

(Facoltativo) Identificatore. Il nome della risorsa che fa riferimento ai contenuti memorizzati nella cache. Formato: cachedContents/{id}

displayName string

(Facoltativo) Immutabile. Il nome visualizzato significativo generato dall'utente dei contenuti memorizzati nella cache. Massimo 128 caratteri Unicode.

model string

Obbligatorio. Immutabile. Nome del Model da utilizzare per i contenuti memorizzati nella cache. Formato: models/{model}

systemInstruction object (Content)

(Facoltativo) Solo input. Immutabile. Istruzione di sistema impostata dallo sviluppatore. Al momento solo testo.

toolConfig object (ToolConfig)

(Facoltativo) Solo input. Immutabile. Configurazione dello strumento. Questa configurazione è condivisa per tutti gli strumenti.

Richiesta di esempio

Di base

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());

Vai

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)

Conchiglia

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 mittente

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.");

Vai

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)

Dalla 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()}`);

Vai

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

In caso di esito positivo, il corpo della risposta contiene un'istanza di CachedContent appena creata.

Metodo: cachedContents.list

Elenca CachedContents.

Endpoint

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

Parametri di query

pageSize integer

(Facoltativo) Il numero massimo di contenuti memorizzati nella cache da restituire. Il servizio potrebbe restituire un valore inferiore a questo valore. Se non viene specificato, verrà restituito un numero predefinito (inferiore al massimo) di elementi. Il valore massimo è 1000; i valori superiori a 1000 verranno forzati a 1000.

pageToken string

(Facoltativo) Un token di pagina, ricevuto da una precedente chiamata a cachedContents.list. Fornisci questo valore per recuperare la pagina successiva.

Durante l'impaginazione, tutti gli altri parametri forniti a cachedContents.list devono corrispondere alla chiamata che ha fornito il token della pagina.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

Risposta con l'elenco CachedContents.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Campi
cachedContents[] object (CachedContent)

Elenco dei contenuti memorizzati nella cache.

nextPageToken string

Un token che può essere inviato come pageToken per recuperare la pagina successiva. Se questo campo viene omesso, non verranno visualizzate altre pagine.

Rappresentazione JSON
{
  "cachedContents": [
    {
      object (CachedContent)
    }
  ],
  "nextPageToken": string
}

Metodo: cacheContents.get

Legge la risorsa CachedContent.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

Parametri del percorso

name string

Obbligatorio. Il nome della risorsa che fa riferimento alla voce della cache dei contenuti. Formato: cachedContents/{id} Deve avere il formato cachedContents/{cachedcontent}.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Richiesta di esempio

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

Vai

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)

Conchiglia

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

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di CachedContent.

Metodo: cachedContents.patch

Aggiorna la risorsa CachedContent (solo la scadenza è aggiornabile).

Endpoint

patch https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}

PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}

Parametri del percorso

cachedContent.name string

(Facoltativo) Identificatore. Il nome della risorsa che fa riferimento ai contenuti memorizzati nella cache. Formato: cachedContents/{id} Deve avere il formato cachedContents/{cachedcontent}.

Parametri di query

updateMask string (FieldMask format)

L'elenco dei campi da aggiornare.

Si tratta di un elenco di nomi completi dei campi separati da virgole. Esempio: "user.displayName,photo".

Corpo della richiesta

Il corpo della richiesta contiene un'istanza di CachedContent.

Campi
Campo unione expiration. Specifica quando questa risorsa scadrà. expiration può essere solo uno dei seguenti:
expireTime string (Timestamp format)

Timestamp in UTC di quando questa risorsa è considerata scaduta. Viene sempre fornito nell'output, indipendentemente da ciò che è stato inviato nell'input.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione a livello di nanosecondo e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

Solo input. Nuovo TTL per questa risorsa, solo input.

Durata in secondi con un massimo di nove cifre frazionarie e termina con "s". Esempio: "3.5s".

name string

(Facoltativo) Identificatore. Il nome della risorsa che fa riferimento ai contenuti memorizzati nella cache. Formato: cachedContents/{id}

Esempio di richiesta

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

Vai

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)

Conchiglia

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

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di CachedContent.

Metodo: cachedContents.delete

Elimina la risorsa CachedContent.

Endpoint

elimina https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

Parametri del percorso

name string

Obbligatorio. Il nome della risorsa che fa riferimento al formato della voce di cache dei contenuti: cachedContents/{id} Ha il formato cachedContents/{cachedcontent}.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Richiesta di esempio

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

Vai

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)

Conchiglia

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

Corpo della risposta

In caso di esito positivo, il corpo della risposta è vuoto.

Risorsa REST: cachedContents

Risorsa: CachedContent

Contenuti che sono stati pre-elaborati e possono essere utilizzati nella richiesta successiva a GenerativeService.

I contenuti memorizzati nella cache possono essere utilizzati solo con il modello per cui sono stati creati.

Campi
contents[] object (Content)

(Facoltativo) Solo input. Immutabile. I contenuti da memorizzare nella cache.

tools[] object (Tool)

(Facoltativo) Solo input. Immutabile. Un elenco di Tools che il modello potrebbe utilizzare per generare la risposta successiva

createTime string (Timestamp format)

Solo output. Data/ora di creazione della voce della cache.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione a livello di nanosecondo e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

updateTime string (Timestamp format)

Solo output. Data e ora dell'ultimo aggiornamento della voce della cache in ora UTC.

Un timestamp nel formato "Zulu" RFC3339 UTC, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

usageMetadata object (UsageMetadata)

Solo output. Metadati sull'utilizzo dei contenuti memorizzati nella cache.

Campo unione expiration. Specifica quando questa risorsa scadrà. expiration può essere solo uno dei seguenti:
expireTime string (Timestamp format)

Timestamp in UTC di quando questa risorsa è considerata scaduta. Viene sempre fornito nell'output, indipendentemente da ciò che è stato inviato nell'input.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione a livello di nanosecondo e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

Solo input. Nuovo TTL per questa risorsa, solo input.

Durata in secondi con un massimo di nove cifre frazionarie e termina con "s". Esempio: "3.5s".

name string

(Facoltativo) Identificatore. Il nome della risorsa che fa riferimento ai contenuti memorizzati nella cache. Formato: cachedContents/{id}

displayName string

(Facoltativo) Immutabile. Il nome visualizzato significativo generato dall'utente dei contenuti memorizzati nella cache. Massimo 128 caratteri Unicode.

model string

Obbligatorio. Immutabile. Nome del Model da utilizzare per i contenuti memorizzati nella cache. Formato: models/{model}

systemInstruction object (Content)

(Facoltativo) Solo input. Immutabile. Istruzione di sistema impostata dallo sviluppatore. Al momento solo testo.

toolConfig object (ToolConfig)

(Facoltativo) Solo input. Immutabile. Configurazione strumento Questa configurazione è condivisa per tutti gli strumenti.

Rappresentazione 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)
  }
}

Contenuti

Il tipo di dati strutturati di base contenente i contenuti in più parti di un messaggio.

Un Content include un campo role che indica il produttore del Content e un campo parts contenente dati in più parti con i contenuti della turno del messaggio.

Campi
parts[] object (Part)

Parts ordinato che costituiscono un singolo messaggio. Le parti possono avere tipi MIME diversi.

role string

(Facoltativo) Il produttore dei contenuti. Deve essere "user" o "model".

È utile impostarlo per le conversazioni a più turni, altrimenti può essere lasciato vuoto o non impostato.

Rappresentazione JSON
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

Parte

Un tipo di dati contenente elementi multimediali che fanno parte di un messaggio Content in più parti.

Un Part è costituito da dati a cui è associato un tipo di dati. Un Part può contenere solo uno dei tipi accettati in Part.data.

Un Part deve avere un tipo MIME IANA fisso che identifichi il tipo e il sottotipo dei contenuti multimediali se il campo inlineData è compilato con byte non elaborati.

Campi

Campo unione data.

data può essere solo uno dei seguenti:

text string

Testo in linea.

inlineData object (Blob)

Byte di media in linea.

functionCall object (FunctionCall)

Un FunctionCall previsto restituito dal modello che contiene una stringa che rappresenta il FunctionDeclaration.name con gli argomenti e i relativi valori.

functionResponse object (FunctionResponse)

L'output del risultato di un FunctionCall contenente una stringa che rappresenta il FunctionDeclaration.name e un oggetto JSON strutturato contenente qualsiasi output della funzione viene utilizzato come contesto per il modello.

fileData object (FileData)

Dati basati su URI.

executableCode object (ExecutableCode)

Codice generato dal modello che deve essere eseguito.

codeExecutionResult object (CodeExecutionResult)

Risultato dell'esecuzione del ExecutableCode.

Rappresentazione 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

Byte multimediali non elaborati.

Il testo non deve essere inviato come byte non elaborati, utilizza il campo "text".

Campi
mimeType string

Il tipo MIME standard IANA dei dati di origine. Esempi: - image/png - image/jpeg Se viene fornito un tipo MIME non supportato, verrà restituito un errore. Per un elenco completo dei tipi supportati, consulta Formati file supportati.

data string (bytes format)

Byte non elaborati per i formati multimediali.

Una stringa con codifica Base64.

Rappresentazione JSON
{
  "mimeType": string,
  "data": string
}

FunctionCall

Un FunctionCall previsto restituito dal modello che contiene una stringa che rappresenta il FunctionDeclaration.name con gli argomenti e i relativi valori.

Campi
name string

Obbligatorio. Il nome della funzione da chiamare. Deve essere a-z, A-Z, 0-9 o contenere trattini bassi e trattini, con una lunghezza massima di 63.

args object (Struct format)

(Facoltativo) I parametri e i valori della funzione in formato oggetto JSON.

Rappresentazione JSON
{
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

L'output del risultato di un oggetto FunctionCall che contiene una stringa che rappresenta il valore FunctionDeclaration.name e un oggetto JSON strutturato contenente qualsiasi output della funzione viene utilizzato come contesto per il modello. Deve contenere il risultato di unFunctionCall effettuato in base alla previsione del modello.

Campi
name string

Obbligatorio. Il nome della funzione da chiamare. Deve essere a-z, A-Z, 0-9 o contenere trattini bassi e trattini, con una lunghezza massima di 63.

response object (Struct format)

Obbligatorio. La risposta della funzione in formato oggetto JSON.

Rappresentazione JSON
{
  "name": string,
  "response": {
    object
  }
}

FileData

Dati basati su URI.

Campi
mimeType string

(Facoltativo) Il tipo MIME standard IANA dei dati di origine.

fileUri string

Obbligatorio. URI.

Rappresentazione JSON
{
  "mimeType": string,
  "fileUri": string
}

ExecutableCode

Codice generato dal modello che deve essere eseguito e il risultato è stato restituito al modello.

Viene generato solo quando utilizzi lo strumento CodeExecution, in cui il codice verrà eseguito automaticamente e verrà generato anche un CodeExecutionResult corrispondente.

Campi
language enum (Language)

Obbligatorio. Linguaggio di programmazione di code.

code string

Obbligatorio. Il codice da eseguire.

Rappresentazione JSON
{
  "language": enum (Language),
  "code": string
}

Lingua

Linguaggi di programmazione supportati per il codice generato.

Enum
LANGUAGE_UNSPECIFIED Lingua non specificata. Questo valore non deve essere utilizzato.
PYTHON Python >= 3.10, con numpy e simpy disponibili.

CodeExecutionResult

Risultato dell'esecuzione del ExecutableCode.

Viene generato solo quando si utilizza CodeExecution e segue sempre un part contenente ExecutableCode.

Campi
outcome enum (Outcome)

Obbligatorio. Risultato dell'esecuzione del codice.

output string

(Facoltativo) Contiene stdout quando l'esecuzione del codice è riuscita, stderr o un'altra descrizione in caso contrario.

Rappresentazione JSON
{
  "outcome": enum (Outcome),
  "output": string
}

Risultato

Enumerazione dei possibili risultati dell'esecuzione del codice.

Enum
OUTCOME_UNSPECIFIED Stato non specificato. Questo valore non deve essere utilizzato.
OUTCOME_OK Esecuzione del codice completata.
OUTCOME_FAILED L'esecuzione del codice è stata completata, ma con un errore. stderr deve contenere il motivo.
OUTCOME_DEADLINE_EXCEEDED L'esecuzione del codice è durata troppo a lungo ed è stata annullata. Potrebbe essere presente o meno un output parziale.

Strumento

Dettagli dello strumento che il modello può utilizzare per generare la risposta.

Un Tool è una porzione di codice che consente al sistema di interagire con sistemi esterni per eseguire un'azione o un insieme di azioni al di fuori delle conoscenze e dell'ambito del modello.

Campi
functionDeclarations[] object (FunctionDeclaration)

(Facoltativo) Un elenco di FunctionDeclarations disponibili per il modello, che possono essere utilizzati per le chiamate di funzione.

Il modello o il sistema non esegue la funzione. La funzione definita può invece essere restituita come FunctionCall con argomenti al lato client per l'esecuzione. Il modello può decidere di chiamare un sottoinsieme di queste funzioni compilando FunctionCall nella risposta. Il turno di conversazione successivo potrebbe contenere un FunctionResponse con il contesto di generazione della "funzione" Content.role per il turno del modello successivo.

googleSearchRetrieval object (GoogleSearchRetrieval)

(Facoltativo) Strumento di recupero basato sulla Ricerca Google.

codeExecution object (CodeExecution)

(Facoltativo) Consente al modello di eseguire il codice durante la generazione.

Rappresentazione JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  }
}

FunctionDeclaration

Rappresentazione strutturata di una dichiarazione di funzione come definita dalla specifica OpenAPI 3.03. Questa dichiarazione include il nome e i parametri della funzione. Questa dichiarazione di funzione è una rappresentazione di un blocco di codice che può essere utilizzato come Tool dal modello ed eseguito dal client.

Campi
name string

Obbligatorio. Il nome della funzione. Deve essere a-z, A-Z, 0-9 o contenere trattini bassi e trattini, con una lunghezza massima di 63 caratteri.

description string

Obbligatorio. Una breve descrizione della funzione.

parameters object (Schema)

(Facoltativo) Descrive i parametri di questa funzione. Riflette la chiave stringa dell'oggetto parametro Open API 3.03: il nome del parametro. I nomi dei parametri sono sensibili alle maiuscole. Valore schema: lo schema che definisce il tipo utilizzato per il parametro.

Rappresentazione JSON
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  }
}

Schema

L'oggetto Schema consente la definizione dei tipi di dati di input e di output. Questi tipi possono essere oggetti, ma anche primitive e array. Rappresenta un sottoinsieme selezionato di un oggetto schema OpenAPI 3.0.

Campi
type enum (Type)

Obbligatorio. Tipo di dati.

format string

(Facoltativo) Il formato dei dati. Viene utilizzato solo per i tipi di dati primitivi. Formati supportati: per il tipo NUMBER: numero in virgola mobile, doppio per il tipo INTEGER: int32, int64 per il tipo STRING: enum

description string

(Facoltativo) Una breve descrizione del parametro. Potrebbero contenere esempi di utilizzo. La descrizione del parametro può essere formattata in Markdown.

nullable boolean

(Facoltativo) Indica se il valore può essere null.

enum[] string

(Facoltativo) Possibili valori dell'elemento di tipo Type.STRING con formato enum. Ad esempio, possiamo definire una direzione Enum come : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

maxItems string (int64 format)

(Facoltativo) Numero massimo di elementi per Type.ARRAY.

minItems string (int64 format)

(Facoltativo) Numero minimo di elementi per Type.ARRAY.

properties map (key: string, value: object (Schema))

(Facoltativo) Proprietà di Type.OBJECT.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

required[] string

(Facoltativo) Proprietà obbligatorie di Type.OBJECT.

items object (Schema)

(Facoltativo) Schema degli elementi di Type.ARRAY.

Rappresentazione 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

Il tipo contiene l'elenco dei tipi di dati OpenAPI come definito da https://spec.openapis.org/oas/v3.0.3#data-types

Enum
TYPE_UNSPECIFIED Non specificato, non deve essere utilizzato.
STRING Tipo di stringa.
NUMBER Tipo di numero.
INTEGER Tipo di numero intero.
BOOLEAN Tipo booleano.
ARRAY Tipo di array.
OBJECT Tipo di oggetto.

GoogleSearchRetrieval

Strumento per il recupero di dati web pubblici per la verifica della realtà, basato su Google.

Campi
dynamicRetrievalConfig object (DynamicRetrievalConfig)

Specifica la configurazione del recupero dinamico per l'origine specificata.

Rappresentazione JSON
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

Descrive le opzioni per personalizzare il recupero dinamico.

Campi
mode enum (Mode)

La modalità dell'algoritmo di previsione da utilizzare nel recupero dinamico.

dynamicThreshold number

La soglia da utilizzare nel recupero dinamico. Se non viene impostato, viene utilizzato un valore predefinito di sistema.

Rappresentazione JSON
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

Modalità

La modalità dell'algoritmo di previsione da utilizzare nel recupero dinamico.

Enum
MODE_UNSPECIFIED Attiva sempre il recupero.
MODE_DYNAMIC Esegui il recupero solo quando il sistema ritiene che sia necessario.

CodeExecution

Questo tipo non contiene campi.

Strumento che esegue il codice generato dal modello e restituisce automaticamente il risultato al modello.

Vedi anche ExecutableCode e CodeExecutionResult, che vengono generati solo quando utilizzi questo strumento.

ToolConfig

La configurazione dello strumento contenente i parametri per specificare l'utilizzo di Tool nella richiesta.

Campi
functionCallingConfig object (FunctionCallingConfig)

(Facoltativo) Configurazione delle chiamate di funzione.

Rappresentazione JSON
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  }
}

FunctionCallingConfig

Configurazione per specificare il comportamento di chiamata delle funzioni.

Campi
mode enum (Mode)

(Facoltativo) Specifica la modalità di esecuzione della chiamata di funzione. Se non specificato, il valore predefinito sarà AUTO.

allowedFunctionNames[] string

(Facoltativo) Un insieme di nomi di funzioni che, se specificati, limita le funzioni che verranno chiamate dal modello.

Questo valore deve essere impostato solo quando la modalità è QUALSIASI. I nomi delle funzioni devono corrispondere a [FunctionDeclaration.name]. Con la modalità impostata su QUALSIASI, il modello prevede una chiamata di funzione dall'insieme di nomi di funzioni forniti.

Rappresentazione JSON
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

Modalità

Definisce il comportamento di esecuzione per la chiamata di funzioni definendo la modalità di esecuzione.

Enum
MODE_UNSPECIFIED Modalità di chiamata di funzione non specificata. Questo valore non deve essere utilizzato.
AUTO Il comportamento predefinito del modello, che decide di prevedere una chiamata di funzione o una risposta in linguaggio naturale.
ANY Il modello è vincolato a prevedere sempre solo una chiamata di funzione. Se sono impostati "allowedFunctionNames", la chiamata di funzione prevista sarà limitata a uno dei valori "allowedFunctionNames", altrimenti sarà una delle "functionDeclarations" fornite.
NONE Il modello non prevede alcuna chiamata di funzione. Il comportamento del modello è lo stesso che si ottiene quando non vengono passate dichiarazioni di funzioni.

UsageMetadata

Metadati sull'utilizzo dei contenuti memorizzati nella cache.

Campi
totalTokenCount integer

Numero totale di token utilizzati dai contenuti memorizzati nella cache.

Rappresentazione JSON
{
  "totalTokenCount": integer
}