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: cachedContents.create
Crea la risorsa CachedContent.
Endpoint
posthttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
L'URL utilizza la sintassi di transcodifica gRPC.
Corpo della richiesta
Il corpo della richiesta contiene un'istanza di CachedContent
.
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
expiration
Union type
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.
Una durata in secondi con un massimo di nove cifre frazionarie, che 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. Il nome del Model
da utilizzare per il formato dei contenuti memorizzati nella cache: 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
Node.js
Vai
Conchiglia
Nome mittente
Python
Node.js
Vai
Dalla chat
Python
Node.js
Vai
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
gethttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
L'URL utilizza la sintassi di transcodifica gRPC.
Parametri di query
pageSize
integer
Facoltativo. Il numero massimo di contenuti memorizzati nella cache da restituire. Il servizio potrebbe restituire meno di 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 chiamata cachedContents.list
precedente. Fornisci questo valore per recuperare la pagina successiva.
Quando viene applicata la paginazione, tutti gli altri parametri forniti a cachedContents.list
devono corrispondere alla chiamata che ha fornito il token 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:
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 ( |
Metodo: cachedContents.get
Legge la risorsa CachedContent.
Endpoint
gethttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
L'URL utilizza la sintassi di transcodifica gRPC.
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
Node.js
Vai
Conchiglia
Corpo della risposta
In caso di esito positivo, il corpo della risposta contiene un'istanza di CachedContent
.
Metodo: cachedContents.patch
- Endpoint
- Parametri del percorso
- Parametri di ricerca
- Corpo della richiesta
- Corpo della risposta
- Richiesta di esempio
Aggiorna la risorsa CachedContent (solo la scadenza è aggiornabile).
Endpoint
patchhttps: / /generativelanguage.googleapis.com /v1beta /{cachedContent.name=cachedContents /*}
PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
L'URL utilizza la sintassi di transcodifica gRPC.
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 separato da virgole di nomi completi dei campi. Esempio: "user.displayName,photo"
.
Corpo della richiesta
Il corpo della richiesta contiene un'istanza di CachedContent
.
expiration
Union type
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.
Una durata in secondi con un massimo di nove cifre frazionarie, che 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}
Richiesta di esempio
Python
Node.js
Vai
Conchiglia
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
deletehttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
L'URL utilizza la sintassi di transcodifica gRPC.
Parametri del percorso
name
string
Obbligatorio. Il nome della risorsa che fa riferimento al formato della voce della cache dei contenuti: cachedContents/{id}
assume la forma cachedContents/{cachedcontent}
.
Corpo della richiesta
Il corpo della richiesta deve essere vuoto.
Richiesta di esempio
Python
Node.js
Vai
Conchiglia
Corpo della risposta
In caso di esito positivo, il corpo della risposta è vuoto.
Risorsa REST: cachedContents
- Risorsa: CachedContent
- Contenuti
- Parte
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- Lingua
- CodeExecutionResult
- Risultato
- Strumento
- FunctionDeclaration
- Schema
- Tipo
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- Modalità
- CodeExecution
- ToolConfig
- FunctionCallingConfig
- Modalità
- UsageMetadata
- Metodi
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.
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. 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 UTC.
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"
.
usageMetadata
object (UsageMetadata
)
Solo output. Metadati sull'utilizzo dei contenuti memorizzati nella cache.
expiration
Union type
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.
Una durata in secondi con un massimo di nove cifre frazionarie, che 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. Il nome del Model
da utilizzare per il formato dei contenuti memorizzati nella cache: 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.
Rappresentazione JSON |
---|
{ "contents": [ { object ( |
Contenuti
Il tipo di dati strutturati di base contenente i contenuti suddivisi in più parti di un messaggio.
Un Content
include un campo role
che designa il produttore del Content
e un campo parts
contenente dati in più parti che contengono i contenuti del turno di messaggio.
parts[]
object (Part
)
Parts
ordinati 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 ( |
Parte
Un tipo di dati contenente contenuti multimediali che fanno parte di un messaggio Content
con 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.
data
Union type
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 |
---|
{ // data "text": string, "inlineData": { object ( |
Blob
Byte multimediali non elaborati.
Il testo non deve essere inviato come byte non elaborati, utilizza il campo "text".
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.
name
string
Obbligatorio. Il nome della funzione da chiamare. Deve essere composto da lettere a-z, A-Z, numeri 0-9 o contenere trattini bassi e trattini, con una lunghezza massima di 63 caratteri.
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 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. Deve contenere il risultato di unFunctionCall
effettuato in base alla previsione del modello.
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.
mimeType
string
Facoltativo. Il tipo MIME standard IANA dei dati di origine.
fileUri
string
Obbligatorio. URI.
Rappresentazione JSON |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
Il codice generato dal modello che deve essere eseguito e il risultato 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.
language
enum (Language
)
Obbligatorio. Linguaggio di programmazione del code
.
code
string
Obbligatorio. Il codice da eseguire.
Rappresentazione JSON |
---|
{
"language": enum ( |
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
.
outcome
enum (Outcome
)
Obbligatorio. Risultato dell'esecuzione del codice.
output
string
Facoltativo. Contiene stdout se l'esecuzione del codice è riuscita, stderr o un'altra descrizione in caso contrario.
Rappresentazione JSON |
---|
{
"outcome": enum ( |
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 correttamente. |
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 potrebbe utilizzare per generare la risposta.
Un Tool
è un frammento di codice che consente al sistema di interagire con sistemi esterni per eseguire un'azione o un insieme di azioni al di fuori della conoscenza e dell'ambito del modello.
functionDeclarations[]
object (FunctionDeclaration
)
Facoltativo. Un elenco di FunctionDeclarations
disponibili per il modello che possono essere utilizzati per le chiamate di funzioni.
Il modello o il sistema non esegue la funzione. La funzione definita può invece essere restituita come FunctionCall
con argomenti 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
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.
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.
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
L'oggetto Schema
consente la definizione dei tipi di dati di input e di output. Questi tipi possono essere oggetti, ma anche elementi primitivi e array. Rappresenta un sottoinsieme selezionato di un oggetto schema OpenAPI 3.0.
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: float, double per il tipo INTEGER: int32, int64 per il tipo STRING: enum
description
string
Facoltativo. Una breve descrizione del parametro. Potrebbero essere inclusi 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.
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 fondatezza, basato su Google.
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
Specifica la configurazione del recupero dinamico per l'origine specificata.
Rappresentazione JSON |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
Descrive le opzioni per personalizzare il recupero dinamico.
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 ( |
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.
functionCallingConfig
object (FunctionCallingConfig
)
Facoltativo. Configurazione delle chiamate di funzione.
Rappresentazione JSON |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
Configurazione per specificare il comportamento di chiamata delle funzioni.
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 ( |
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.
totalTokenCount
integer
Numero totale di token consumati dai contenuti memorizzati nella cache.
Rappresentazione JSON |
---|
{ "totalTokenCount": integer } |