La mise en cache du contexte vous permet d'enregistrer et de réutiliser les jetons d'entrée précalculés que vous souhaitez utiliser à plusieurs reprises, par exemple lorsque vous posez différentes questions sur le même fichier multimédia. Cela peut permettre de réaliser des économies en termes de coûts et de vitesse, en fonction de l'utilisation. Pour une présentation détaillée, consultez le guide Mise en cache du contexte.
Méthode: cachedContents.create
Crée une ressource CachedContent.
Point de terminaison
post https://generativelanguage.googleapis.com/v1beta/cachedContentsCorps de la requête
Le corps de la requête contient une instance de CachedContent
.
contents[]
object (Content
)
Facultatif. Uniquement en entrée. Immuable. Contenu à mettre en cache.
tools[]
object (Tool
)
Facultatif. Uniquement en entrée. Immuable. Liste de Tools
que le modèle peut utiliser pour générer la réponse suivante
expiration
. Indique quand cette ressource expirera. expiration
ne peut être qu'un des éléments suivants :
expireTime
string (Timestamp
format)
Code temporel en UTC du moment où cette ressource est considérée comme expirée. Cette valeur est toujours fournie en sortie, quel que soit ce qui a été envoyé en entrée.
Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z"
et "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Uniquement en entrée. Nouveau TTL pour cette ressource, en entrée uniquement.
Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s
". Exemple : "3.5s"
name
string
Facultatif. Identifiant. Nom de la ressource faisant référence au contenu mis en cache. Format : cachedContents/{id}
displayName
string
Facultatif. Immuable. Nom à afficher significatif généré par l'utilisateur pour le contenu mis en cache. 128 caractères Unicode maximum.
model
string
Obligatoire. Immuable. Nom de l'Model
à utiliser pour le contenu mis en cache. Format: models/{model}
systemInstruction
object (Content
)
Facultatif. Uniquement en entrée. Immuable. Instruction concernant le système défini par le développeur. Actuellement, le texte uniquement.
toolConfig
object (ToolConfig
)
Facultatif. Uniquement en entrée. Immuable. Configuration de l'outil Cette configuration est partagée pour tous les outils.
Exemple de requête
De base
Python
Node.js
Go
Coquille Rose
Nom de l'expéditeur
Python
Node.js
Go
Depuis le chat
Python
Node.js
Go
Corps de la réponse
Si la requête aboutit, le corps de la réponse contient une nouvelle instance de CachedContent
.
Méthode: cachedContents.list
Répertorie les CachedContents.
Point de terminaison
obtenir https://generativelanguage.googleapis.com/v1beta/cachedContentsParamètres de requête
pageSize
integer
Facultatif. Nombre maximal de contenus mis en cache à renvoyer. Le service peut renvoyer un nombre inférieur à cette valeur. Si ce paramètre n'est pas spécifié, un nombre d'éléments par défaut (inférieur au maximum) est renvoyé. La valeur maximale est 1 000. Les valeurs supérieures sont réduites à 1 000.
pageToken
string
Facultatif. Jeton de page reçu d'un appel cachedContents.list
précédent. Fournissez-le pour récupérer la page suivante.
Lors de la pagination, tous les autres paramètres fournis à cachedContents.list
doivent correspondre à l'appel ayant fourni le jeton de page.
Corps de la requête
Le corps de la requête doit être vide.
Corps de la réponse
Réponse avec la liste CachedContents.
Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :
cachedContents[]
object (CachedContent
)
Liste des contenus mis en cache.
nextPageToken
string
Jeton pouvant être envoyé en tant que pageToken
pour récupérer la page suivante. Si ce champ est omis, il n'y a pas d'autres pages.
Représentation JSON |
---|
{
"cachedContents": [
{
object ( |
Méthode: cacheContents.get
- Point de terminaison
- Paramètres de chemin d'accès
- Corps de la requête
- Corps de la réponse
- Exemple de requête
Lit la ressource CachedContent.
Point de terminaison
get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}Paramètres de chemin d'accès
name
string
Obligatoire. Nom de la ressource faisant référence à l'entrée de cache de contenu. Format: cachedContents/{id}
Il se présente sous la forme cachedContents/{cachedcontent}
.
Corps de la requête
Le corps de la requête doit être vide.
Exemple de requête
Python
Node.js
Go
Coquille Rose
Corps de la réponse
Si la requête aboutit, le corps de la réponse contient une instance de CachedContent
.
Méthode: cachedContents.patch
- Point de terminaison
- Paramètres de chemin d'accès
- Paramètres de requête
- Corps de la requête
- Corps de la réponse
- Exemple de requête
Met à jour la ressource CachedContent (seule l'expiration peut être modifiée).
Point de terminaison
patch https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
Paramètres de chemin d'accès
cachedContent.name
string
Facultatif. Identifiant. Nom de la ressource faisant référence au contenu mis en cache. Format: cachedContents/{id}
. Il se présente sous la forme cachedContents/{cachedcontent}
.
Paramètres de requête
updateMask
string (FieldMask
format)
Liste des champs à mettre à jour.
Il s'agit d'une liste de noms de champs complets séparés par une virgule. Exemple : "user.displayName,photo"
Corps de la requête
Le corps de la requête contient une instance de CachedContent
.
expiration
. Indique quand cette ressource expirera. expiration
ne peut être qu'un des éléments suivants :
expireTime
string (Timestamp
format)
Code temporel en UTC du moment où cette ressource est considérée comme expirée. Cette valeur est toujours fournie en sortie, quel que soit ce qui a été envoyé en entrée.
Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z"
et "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Uniquement en entrée. Nouveau TTL pour cette ressource, en entrée uniquement.
Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s
". Exemple : "3.5s"
name
string
Facultatif. Identifiant. Nom de la ressource faisant référence au contenu mis en cache. Format : cachedContents/{id}
Exemple de requête
Python
Node.js
Go
Coquille Rose
Corps de la réponse
Si la requête aboutit, le corps de la réponse contient une instance de CachedContent
.
Méthode: cacheContents.delete
- Point de terminaison
- Paramètres de chemin d'accès
- Corps de la requête
- Corps de la réponse
- Exemple de requête
Supprime la ressource CachedContent.
Point de terminaison
delete https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}Paramètres de chemin d'accès
name
string
Obligatoire. Nom de la ressource faisant référence à l'entrée de cache de contenu. Format: cachedContents/{id}
. Se présente sous la forme cachedContents/{cachedcontent}
.
Corps de la requête
Le corps de la requête doit être vide.
Exemple de requête
Python
Node.js
Go
Coquille Rose
Corps de la réponse
Si la requête aboutit, le corps de la réponse est vide.
Ressource REST: cacheContents
- Ressource: CachedContent
- Contenu
- Partie
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- Langue
- CodeExecutionResult
- Résultat
- Outil
- FunctionDeclaration
- Schéma
- Type
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- Mode
- CodeExecution
- ToolConfig
- FunctionCallingConfig
- Mode
- UsageMetadata
- Méthodes
Ressource: CachedContent
Contenu qui a été prétraité et qui peut être utilisé dans les requêtes ultérieures envoyées à GenerativeService.
Le contenu mis en cache ne peut être utilisé qu'avec le modèle pour lequel il a été créé.
contents[]
object (Content
)
Facultatif. Uniquement en entrée. Immuable. Contenu à mettre en cache.
tools[]
object (Tool
)
Facultatif. Uniquement en entrée. Immuable. Liste de Tools
que le modèle peut utiliser pour générer la réponse suivante
createTime
string (Timestamp
format)
Uniquement en sortie. Heure de création de l'entrée de cache.
Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z"
et "2014-10-02T15:01:23.045123456Z"
.
updateTime
string (Timestamp
format)
Uniquement en sortie. Date et heure de la dernière mise à jour de l'entrée de cache en UTC.
Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z"
et "2014-10-02T15:01:23.045123456Z"
.
usageMetadata
object (UsageMetadata
)
Uniquement en sortie. Métadonnées sur l'utilisation du contenu mis en cache.
expiration
. Indique quand cette ressource expirera. expiration
ne peut être qu'un des éléments suivants :
expireTime
string (Timestamp
format)
Code temporel en UTC du moment où cette ressource est considérée comme expirée. Cette valeur est toujours fournie en sortie, quel que soit ce qui a été envoyé en entrée.
Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z"
et "2014-10-02T15:01:23.045123456Z"
.
ttl
string (Duration
format)
Uniquement en entrée. Nouveau TTL pour cette ressource, en entrée uniquement.
Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s
". Exemple : "3.5s"
name
string
Facultatif. Identifiant. Nom de la ressource faisant référence au contenu mis en cache. Format : cachedContents/{id}
displayName
string
Facultatif. Immuable. Nom à afficher significatif généré par l'utilisateur pour le contenu mis en cache. 128 caractères Unicode maximum.
model
string
Obligatoire. Immuable. Nom de l'Model
à utiliser pour le contenu mis en cache. Format: models/{model}
systemInstruction
object (Content
)
Facultatif. Uniquement en entrée. Immuable. Instruction concernant le système défini par le développeur. Actuellement, le texte uniquement.
toolConfig
object (ToolConfig
)
Facultatif. Uniquement en entrée. Immuable. Configuration de l'outil Cette configuration est partagée pour tous les outils.
Représentation JSON |
---|
{ "contents": [ { object ( |
Contenu
Type de données structurées de base comportant un contenu en plusieurs parties d'un message.
Un Content
inclut un champ role
désignant le producteur de l'Content
et un champ parts
contenant des données en plusieurs parties incluant le contenu du tour du message.
parts[]
object (Part
)
Parts
ordonnés qui constituent un seul message. Les parties peuvent avoir différents types MIME.
role
string
Facultatif. Producteur du contenu. Doit être "user" ou "model".
Utile pour les conversations multitours. Sinon, vous pouvez laisser ce champ vide ou non défini.
Représentation JSON |
---|
{
"parts": [
{
object ( |
Partie
Type de données contenant du contenu multimédia faisant partie d'un message Content
en plusieurs parties.
Un Part
est constitué de données auxquelles un type de données est associé. Un Part
ne peut contenir qu'un seul des types acceptés dans Part.data
.
Un Part
doit avoir un type MIME IANA fixe qui identifie le type et le sous-type du contenu multimédia si le champ inlineData
est rempli d'octets bruts.
Champ d'union data
.
data
ne peut être qu'un des éléments suivants :
text
string
Texte intégré.
inlineData
object (Blob
)
Octets multimédias intégrés.
functionCall
object (FunctionCall
)
Une valeur FunctionCall
prédite renvoyée par le modèle et qui contient une chaîne représentant le FunctionDeclaration.name
avec les arguments et leurs valeurs.
functionResponse
object (FunctionResponse
)
Le résultat d'une FunctionCall
contenant une chaîne représentant la FunctionDeclaration.name
et un objet JSON structuré contenant tout résultat de la fonction est utilisé comme contexte pour le modèle.
fileData
object (FileData
)
Données basées sur l'URI.
executableCode
object (ExecutableCode
)
Code généré par le modèle et destiné à être exécuté.
codeExecutionResult
object (CodeExecutionResult
)
Résultat de l'exécution de ExecutableCode
.
Représentation JSON |
---|
{ // Union field |
Blob
Octets de contenu multimédia bruts.
Le texte ne doit pas être envoyé sous forme d'octets bruts. Utilisez le champ "text".
mimeType
string
Type MIME standard IANA des données sources. Exemples: - image/png - image/jpeg Si un type MIME non compatible est fourni, une erreur est renvoyée. Pour obtenir la liste complète des types de fichiers compatibles, consultez Formats de fichiers acceptés.
data
string (bytes format)
Octets bruts pour les formats multimédias.
Chaîne encodée en base64.
Représentation JSON |
---|
{ "mimeType": string, "data": string } |
FunctionCall
Une valeur FunctionCall
prédite renvoyée par le modèle et qui contient une chaîne représentant le FunctionDeclaration.name
avec les arguments et leurs valeurs.
name
string
Obligatoire. Nom de la fonction à appeler. Il doit être composé de a-z, A-Z, 0-9, ou contenir des traits de soulignement et des tirets, avec une longueur maximale de 63.
args
object (Struct
format)
Facultatif. Paramètres et valeurs de la fonction au format d'objet JSON.
Représentation JSON |
---|
{ "name": string, "args": { object } } |
FunctionResponse
Le résultat d'une FunctionCall
contenant une chaîne représentant la FunctionDeclaration.name
et un objet JSON structuré contenant tout résultat de la fonction est utilisé comme contexte pour le modèle. Doit contenir le résultat d'une opération FunctionCall
effectuée en fonction de la prédiction du modèle.
name
string
Obligatoire. Nom de la fonction à appeler. Il doit être composé de a-z, A-Z, 0-9, ou contenir des traits de soulignement et des tirets, avec une longueur maximale de 63.
response
object (Struct
format)
Obligatoire. Réponse de la fonction au format d'objet JSON.
Représentation JSON |
---|
{ "name": string, "response": { object } } |
FileData
Données basées sur l'URI.
mimeType
string
Facultatif. Type MIME standard IANA des données sources.
fileUri
string
Obligatoire. URI.
Représentation JSON |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
Code généré par le modèle qui doit être exécuté et résultat renvoyé au modèle.
Ne sont générés que lorsque vous utilisez l'outil CodeExecution
, dans lequel le code est exécuté automatiquement et qu'un CodeExecutionResult
correspondant est également généré.
language
enum (Language
)
Obligatoire. Langage de programmation de l'code
.
code
string
Obligatoire. Code à exécuter.
Représentation JSON |
---|
{
"language": enum ( |
Langue
Langages de programmation compatibles pour le code généré.
Enums | |
---|---|
LANGUAGE_UNSPECIFIED |
Langue non précisée. Cette valeur ne doit pas être utilisée. |
PYTHON |
Python >= 3.10, avec numpy et simpy disponibles. |
CodeExecutionResult
Résultat de l'exécution de ExecutableCode
.
Générée uniquement lors de l'utilisation de CodeExecution
et suit toujours une part
contenant la ExecutableCode
.
outcome
enum (Outcome
)
Obligatoire. Résultat de l'exécution du code.
output
string
Facultatif. Contient "stdout" lorsque l'exécution du code a réussi, "stderr" ou une autre description dans le cas contraire.
Représentation JSON |
---|
{
"outcome": enum ( |
Résultat
Énumération des résultats possibles de l'exécution du code.
Enums | |
---|---|
OUTCOME_UNSPECIFIED |
État non spécifié. Cette valeur ne doit pas être utilisée. |
OUTCOME_OK |
L'exécution du code a bien été effectuée. |
OUTCOME_FAILED |
L'exécution du code s'est terminée, mais avec un échec. stderr doit contenir le motif. |
OUTCOME_DEADLINE_EXCEEDED |
L'exécution du code a duré trop longtemps et a été annulée. Il peut y avoir ou non une sortie partielle. |
Outil
Détails de l'outil que le modèle peut utiliser pour générer une réponse.
Un Tool
est un morceau de code qui permet au système d'interagir avec des systèmes externes pour effectuer une action ou un ensemble d'actions en dehors du champ d'application et des connaissances du modèle.
functionDeclarations[]
object (FunctionDeclaration
)
Facultatif. Liste des FunctionDeclarations
disponibles pour le modèle et pouvant être utilisés pour l'appel de fonction.
Le modèle ou le système n'exécute pas la fonction. À la place, la fonction définie peut être renvoyée en tant que FunctionCall
avec des arguments côté client pour l'exécution. Le modèle peut décider d'appeler un sous-ensemble de ces fonctions en remplissant FunctionCall
dans la réponse. Le prochain tour de conversation peut contenir un FunctionResponse
avec le contexte de génération de la "fonction" Content.role
pour le prochain tour du modèle.
googleSearchRetrieval
object (GoogleSearchRetrieval
)
Facultatif. Outil de récupération alimenté par la recherche Google.
codeExecution
object (CodeExecution
)
Facultatif. Permet au modèle d'exécuter du code lors de la génération.
Représentation JSON |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
Représentation structurée d'une déclaration de fonction telle que définie par la spécification OpenAPI 3.03. Cette déclaration inclut le nom et les paramètres de la fonction. Cette déclaration de fonction est une représentation d'un bloc de code qui peut être utilisé comme Tool
par le modèle et exécuté par le client.
name
string
Obligatoire. Nom de la fonction. Il doit être composé de a-z, A-Z, 0-9, ou contenir des traits de soulignement et des tirets, avec une longueur maximale de 63.
description
string
Obligatoire. Brève description de la fonction.
parameters
object (Schema
)
Facultatif. Décrit les paramètres de cette fonction. Reflète la clé de la chaîne de l'objet du paramètre Open API 3.03: nom du paramètre. Les noms des paramètres sont sensibles à la casse. "Schema Value" : le schéma définissant le type utilisé pour le paramètre.
Représentation JSON |
---|
{
"name": string,
"description": string,
"parameters": {
object ( |
Schéma
L'objet Schema
permet de définir les types de données d'entrée et de sortie. Ces types peuvent être des objets, mais aussi des primitifs et des tableaux. Représente un sous-ensemble spécifique d'un objet Schéma OpenAPI 3.0.
type
enum (Type
)
Obligatoire. Type de données
format
string
Facultatif. Format des données. Cette option n'est utilisée que pour les types de données primitifs. Formats acceptés: pour le type NUMBER: float, double pour le type INTEGER: int32, int64 pour le type STRING: enum
description
string
Facultatif. Brève description du paramètre. Il peut contenir des exemples d'utilisation. La description du paramètre peut être mise en forme en Markdown.
nullable
boolean
Facultatif. Indique si la valeur peut être nulle.
enum[]
string
Facultatif. Valeurs possibles de l'élément de Type.STRING au format enum. Par exemple, il est possible de définir une direction d'énumération comme suit : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
maxItems
string (int64 format)
Facultatif. Nombre maximal d'éléments pour Type.ARRAY.
minItems
string (int64 format)
Facultatif. Nombre minimal d'éléments pour Type.ARRAY.
properties
map (key: string, value: object (Schema
))
Facultatif. Propriétés de Type.OBJECT.
Objet contenant une liste de paires "key": value
. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }
.
required[]
string
Facultatif. Propriétés obligatoires de Type.OBJECT.
items
object (Schema
)
Facultatif. Schéma des éléments de Type.ARRAY.
Type
Type contient la liste des types de données OpenAPI tels que définis par https://spec.openapis.org/oas/v3.0.3#data-types.
Enums | |
---|---|
TYPE_UNSPECIFIED |
Non spécifié, ne doit pas être utilisé. |
STRING |
Type de chaîne. |
NUMBER |
Type de numéro. |
INTEGER |
Type entier. |
BOOLEAN |
Type booléen. |
ARRAY |
Type de tableau. |
OBJECT |
Type d'objet. |
GoogleSearchRetrieval
Outil de récupération de données Web publiques pour l'ancrage, optimisé par Google.
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
Spécifie la configuration de récupération dynamique pour la source donnée.
Représentation JSON |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
Décrit les options permettant de personnaliser la récupération dynamique.
mode
enum (Mode
)
Mode du prédicteur à utiliser pour la récupération dynamique.
dynamicThreshold
number
Seuil à utiliser pour la récupération dynamique. Si elle n'est pas définie, une valeur par défaut du système est utilisée.
Représentation JSON |
---|
{
"mode": enum ( |
Mode
Mode du prédicteur à utiliser pour la récupération dynamique.
Enums | |
---|---|
MODE_UNSPECIFIED |
Toujours déclencher la récupération. |
MODE_DYNAMIC |
Exécutez la récupération uniquement lorsque le système décide qu'elle est nécessaire. |
CodeExecution
Ce type ne comporte aucun champ.
Outil qui exécute le code généré par le modèle et renvoie automatiquement le résultat au modèle.
Consultez également ExecutableCode
et CodeExecutionResult
, qui ne sont générés que lorsque vous utilisez cet outil.
ToolConfig
Configuration de l'outil contenant des paramètres permettant de spécifier l'utilisation de Tool
dans la requête.
functionCallingConfig
object (FunctionCallingConfig
)
Facultatif. Configuration de l'appel de fonction.
Représentation JSON |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
Configuration permettant de spécifier le comportement d'appel de fonction.
mode
enum (Mode
)
Facultatif. Spécifie le mode d'exécution de l'appel de fonction. Si elle n'est pas spécifiée, la valeur par défaut est AUTO.
allowedFunctionNames[]
string
Facultatif. Ensemble de noms de fonctions qui, lorsqu'il est fourni, limite les fonctions que le modèle appellera.
Cette valeur ne doit être définie que lorsque le mode est "ANY". Les noms de fonction doivent correspondre à [FunctionDeclaration.name]. Lorsque le mode est défini sur "ANY" (TOUT), le modèle prédit un appel de fonction à partir de l'ensemble de noms de fonctions fournis.
Représentation JSON |
---|
{
"mode": enum ( |
Mode
Définit le comportement d'exécution pour l'appel de fonction en définissant le mode d'exécution.
Enums | |
---|---|
MODE_UNSPECIFIED |
Mode d'appel de fonction non spécifié. Cette valeur ne doit pas être utilisée. |
AUTO |
Comportement par défaut du modèle. Le modèle décide de prédire un appel de fonction ou une réponse en langage naturel. |
ANY |
Le modèle est contraint de toujours prédire un seul appel de fonction. Si les paramètres "allowedFunctionNames" sont définis, l'appel de fonction prédit est limité à l'une des valeurs "allowedFunctionNames", sinon l'appel de la fonction prédit est l'une des "functionDeclarations" fournies. |
NONE |
Le modèle ne prédit aucun appel de fonction. Le comportement du modèle est le même que lorsqu'il ne transmet aucune déclaration de fonction. |
UsageMetadata
Métadonnées sur l'utilisation du contenu mis en cache.
totalTokenCount
integer
Nombre total de jetons consommés par le contenu mis en cache.
Représentation JSON |
---|
{ "totalTokenCount": integer } |