L'API Live est une API avec état qui utilise WebSockets. Cette section contient des informations supplémentaires sur l'API WebSockets.
Sessions
Une connexion WebSocket établit une session entre le client et le serveur Gemini. Une fois qu'un client a établi une nouvelle connexion, la session peut échanger des messages avec le serveur pour:
- Envoyer du texte, de l'audio ou de la vidéo au serveur Gemini
- Recevoir des requêtes d'appel audio, textuel ou de fonction à partir du serveur Gemini
Connexion WebSocket
Pour démarrer une session, connectez-vous à ce point de terminaison WebSocket:
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent
Configuration de la session
Le message initial après la connexion définit la configuration de la session, qui comprend le modèle, les paramètres de génération, les instructions système et les outils.
Vous pouvez modifier les paramètres de configuration, à l'exception du modèle, pendant la session.
Consultez l'exemple de configuration suivant. Notez que la casse des noms dans les SDK peut varier. Vous pouvez consulter les options de configuration du SDK Python ici.
{
"model": string,
"generationConfig": {
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseModalities": [string],
"speechConfig": object,
"mediaResolution": object
},
"systemInstruction": string,
"tools": [object]
}
Pour en savoir plus sur le champ de l'API, consultez generationConfig.
Envoyer des messages
Pour échanger des messages via la connexion WebSocket, le client doit envoyer un objet JSON via une connexion WebSocket ouverte. L'objet JSON doit comporter exactement un des champs de l'ensemble d'objets suivant:
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
Messages client compatibles
Consultez les messages client acceptés dans le tableau suivant:
Message | Description |
---|---|
BidiGenerateContentSetup |
Configuration de la session à envoyer dans le premier message |
BidiGenerateContentClientContent |
Mise à jour incrémentielle du contenu de la conversation en cours envoyée par le client |
BidiGenerateContentRealtimeInput |
Saisie audio, vidéo ou textuelle en temps réel |
BidiGenerateContentToolResponse |
Réponse à un ToolCallMessage reçu du serveur |
Recevoir des messages
Pour recevoir des messages de Gemini, écoutez l'événement "message" WebSocket, puis analysez le résultat conformément à la définition des messages de serveur compatibles.
Consultez les références suivantes :
async with client.aio.live.connect(model='...', config=config) as session:
await session.send(input='Hello world!', end_of_turn=True)
async for message in session.receive():
print(message)
Les messages du serveur peuvent comporter un champ usageMetadata
, mais incluent exactement un des autres champs du message BidiGenerateContentServerMessage
. (L'union messageType
n'est pas exprimée en JSON. Le champ apparaît donc au niveau supérieur du message.)
Messages et événements
ActivityEnd
Ce type ne comporte aucun champ.
Indique la fin de l'activité de l'utilisateur.
ActivityHandling
Différentes façons de gérer l'activité des utilisateurs.
Enums | |
---|---|
ACTIVITY_HANDLING_UNSPECIFIED |
Si aucune valeur n'est spécifiée, le comportement par défaut est START_OF_ACTIVITY_INTERRUPTS . |
START_OF_ACTIVITY_INTERRUPTS |
Si la valeur est "true", le début de l'activité interrompt la réponse du modèle (également appelé "barrage"). La réponse actuelle du modèle sera interrompue au moment de l'interruption. Il s'agit du comportement par défaut. |
NO_INTERRUPTION |
La réponse du modèle ne sera pas interrompue. |
ActivityStart
Ce type ne comporte aucun champ.
Indique le début de l'activité de l'utilisateur.
AudioTranscriptionConfig
Ce type ne comporte aucun champ.
Configuration de la transcription audio.
AutomaticActivityDetection
Configure la détection automatique de l'activité.
Champs | |
---|---|
disabled |
Facultatif. Si cette option est activée (valeur par défaut), la saisie vocale et textuelle détectée est comptabilisée comme activité. Si elle est désactivée, le client doit envoyer des signaux d'activité. |
startOfSpeechSensitivity |
Facultatif. Détermine la probabilité de détection de la parole. |
prefixPaddingMs |
Facultatif. Durée requise de la parole détectée avant que le début de la parole ne soit validé. Plus cette valeur est faible, plus la détection du début de la parole est sensible et plus la parole peut être courte. Cependant, cela augmente également la probabilité de faux positifs. |
endOfSpeechSensitivity |
Facultatif. Détermine la probabilité que la parole détectée soit terminée. |
silenceDurationMs |
Facultatif. Durée requise de contenu non vocal détecté (par exemple, silence) avant que la fin de la parole ne soit confirmée. Plus cette valeur est élevée, plus les pauses de parole peuvent être longues sans interrompre l'activité de l'utilisateur. Toutefois, cela augmente la latence du modèle. |
BidiGenerateContentClientContent
Mise à jour incrémentielle de la conversation en cours envoyée par le client. Tout le contenu est ajouté sans condition à l'historique de la conversation et utilisé dans l'invite envoyée au modèle pour générer du contenu.
Un message s'affichera pour interrompre toute génération de modèle en cours.
Champs | |
---|---|
turns[] |
Facultatif. Contenu ajouté à la conversation en cours avec le modèle. Pour les requêtes à un seul tour, il s'agit d'une instance unique. Pour les requêtes multitours, il s'agit d'un champ répété contenant l'historique de la conversation et la dernière requête. |
turnComplete |
Facultatif. Si la valeur est "true", la génération de contenu du serveur doit commencer par l'invite actuellement accumulée. Sinon, le serveur attend d'autres messages avant de commencer la génération. |
BidiGenerateContentRealtimeInput
Entrée utilisateur envoyée en temps réel.
Les différentes modalités (audio, vidéo et texte) sont gérées en tant que flux simultanés. L'ordre de ces flux n'est pas garanti.
Cette méthode diffère de BidiGenerateContentClientContent
de plusieurs manières:
- Peut être envoyé en continu sans interruption pour la génération du modèle.
- Si vous devez mélanger des données entrelacées sur
BidiGenerateContentClientContent
etBidiGenerateContentRealtimeInput
, le serveur tente d'optimiser la réponse, mais aucune garantie n'est fournie. - La fin du tour n'est pas spécifiée explicitement, mais dérive de l'activité de l'utilisateur (par exemple, la fin de la parole).
- Même avant la fin du tour, les données sont traitées de manière incrémentielle pour optimiser le démarrage rapide de la réponse du modèle.
Champs | |
---|---|
mediaChunks[] |
Facultatif. Données d'octets intégrées pour l'entrée multimédia. Plusieurs "DEPRECATED" (Obsolète) : utilisez plutôt |
audio |
Facultatif. Ils constituent le flux d'entrée audio en temps réel. |
video |
Facultatif. Ils constituent le flux d'entrée vidéo en temps réel. |
activityStart |
Facultatif. Indique le début de l'activité de l'utilisateur. Cette information ne peut être envoyée que si la détection automatique (c'est-à-dire côté serveur) de l'activité est désactivée. |
activityEnd |
Facultatif. Indique la fin de l'activité de l'utilisateur. Cette information ne peut être envoyée que si la détection automatique (c'est-à-dire côté serveur) de l'activité est désactivée. |
audioStreamEnd |
Facultatif. Indique que le flux audio a pris fin, par exemple parce que le micro a été désactivé. Cette valeur ne doit être envoyée que lorsque la détection automatique des activités est activée (par défaut). Le client peut rouvrir le flux en envoyant un message audio. |
text |
Facultatif. Ils constituent le flux d'entrée de texte en temps réel. |
BidiGenerateContentServerContent
Mise à jour incrémentielle du serveur générée par le modèle en réponse aux messages client.
Le contenu est généré aussi rapidement que possible, et non en temps réel. Les clients peuvent choisir de mettre en mémoire tampon et de lire le contenu en temps réel.
Champs | |
---|---|
generationComplete |
Uniquement en sortie. Si la valeur est "true", cela signifie que la génération du modèle est terminée. Lorsque le modèle est interrompu pendant la génération, aucun message "generation_complete" n'est envoyé pendant le tour interrompu. Il passe par "interrupted > turn_complete". Lorsque le modèle suppose une lecture en temps réel, un délai s'écoule entre generation_complete et turn_complete, car le modèle attend la fin de la lecture. |
turnComplete |
Uniquement en sortie. Si la valeur est "true", cela signifie que le modèle a terminé son tour. La génération ne commencera qu'en réponse à des messages client supplémentaires. |
interrupted |
Uniquement en sortie. Si la valeur est "true", cela indique qu'un message client a interrompu la génération de modèle en cours. Si le client lit le contenu en temps réel, c'est un bon signal pour arrêter et vider la file d'attente de lecture actuelle. |
groundingMetadata |
Uniquement en sortie. Métadonnées de référence pour le contenu généré. |
outputTranscription |
Uniquement en sortie. Transcrire l'audio. La transcription est envoyée indépendamment des autres messages du serveur. Aucun ordre n'est garanti, en particulier entre |
modelTurn |
Uniquement en sortie. Contenu généré par le modèle dans le cadre de la conversation en cours avec l'utilisateur. |
BidiGenerateContentServerMessage
Message de réponse pour l'appel BidiGenerateContent.
Champs | |
---|---|
usageMetadata |
Uniquement en sortie. Métadonnées d'utilisation des réponses. |
Champ d'union messageType . Type du message. messageType ne peut être qu'un des éléments suivants : |
|
setupComplete |
Uniquement en sortie. Envoyée en réponse à un message |
serverContent |
Uniquement en sortie. Contenu généré par le modèle en réponse aux messages des clients. |
toolCall |
Uniquement en sortie. Demandez au client d'exécuter |
toolCallCancellation |
Uniquement en sortie. Notification au client indiquant qu'un |
goAway |
Uniquement en sortie. Notification indiquant que le serveur sera bientôt déconnecté. |
sessionResumptionUpdate |
Uniquement en sortie. Mise à jour de l'état de reprise de la session. |
BidiGenerateContentSetup
Message à envoyer dans le premier (et seul) BidiGenerateContentClientMessage
. Contient la configuration qui s'appliquera pendant toute la durée de l'RPC en streaming.
Les clients doivent attendre un message BidiGenerateContentSetupComplete
avant d'envoyer des messages supplémentaires.
Champs | |
---|---|
model |
Obligatoire. Nom de la ressource du modèle. Il s'agit d'un identifiant que le modèle doit utiliser. Format : |
generationConfig |
Facultatif. Configuration de génération. Les champs suivants ne sont pas acceptés:
|
systemInstruction |
Facultatif. Instructions système fournies par l'utilisateur pour le modèle. Remarque: Seul du texte doit être utilisé dans les parties et le contenu de chaque partie figurera dans un paragraphe distinct. |
tools[] |
Facultatif. Liste des Un |
realtimeInputConfig |
Facultatif. Configure la gestion des entrées en temps réel. |
sessionResumption |
Facultatif. Configure le mécanisme de reprise de session. Si elle est incluse, le serveur envoie des messages |
contextWindowCompression |
Facultatif. Configure un mécanisme de compression de fenêtre de contexte. Si elle est incluse, le serveur réduit automatiquement la taille du contexte lorsqu'elle dépasse la longueur configurée. |
outputAudioTranscription |
Facultatif. Si défini, active la transcription de la sortie audio du modèle. La transcription correspond au code de langue spécifié pour l'audio de sortie, le cas échéant. |
BidiGenerateContentSetupComplete
Ce type ne comporte aucun champ.
Envoyée en réponse à un message BidiGenerateContentSetup
du client.
BidiGenerateContentToolCall
Demandez au client d'exécuter functionCalls
et de renvoyer les réponses avec les id
correspondants.
Champs | |
---|---|
functionCalls[] |
Uniquement en sortie. Appel de fonction à exécuter. |
BidiGenerateContentToolCallCancellation
Notification au client indiquant qu'une ToolCallMessage
précédemment émise avec les id
spécifiées n'aurait pas dû être exécutée et doit être annulée. Si ces appels d'outils ont des effets secondaires, les clients peuvent essayer de les annuler. Ce message ne s'affiche que lorsque les clients interrompent les tours du serveur.
Champs | |
---|---|
ids[] |
Uniquement en sortie. ID des appels d'outil à annuler. |
BidiGenerateContentToolResponse
Réponse générée par le client à un ToolCall
reçu du serveur. Les objets FunctionResponse
individuels sont mis en correspondance avec les objets FunctionCall
respectifs par le champ id
.
Notez que dans les API GenerateContent unary et server-streaming, l'appel de fonction s'effectue en échangeant les parties Content
, tandis que dans les API GenerateContent bidi, l'appel de fonction s'effectue sur cet ensemble de messages dédié.
Champs | |
---|---|
functionResponses[] |
Facultatif. Réponse aux appels de fonction. |
BidiGenerateContentTranscription
Transcription de l'audio (entrée ou sortie).
Champs | |
---|---|
text |
Texte de la transcription. |
ContextWindowCompressionConfig
Active la compression de la fenêtre de contexte, un mécanisme permettant de gérer la fenêtre de contexte du modèle afin qu'elle ne dépasse pas une longueur donnée.
Champs | |
---|---|
Champ d'union compressionMechanism . Mécanisme de compression de la fenêtre de contexte utilisé. compressionMechanism ne peut être qu'un des éléments suivants : |
|
slidingWindow |
Un mécanisme de fenêtre glissante. |
triggerTokens |
Nombre de jetons (avant l'exécution d'un tour) requis pour déclencher une compression de la fenêtre de contexte. Vous pouvez l'utiliser pour équilibrer la qualité et la latence, car des fenêtres contextuelles plus courtes peuvent entraîner des réponses plus rapides du modèle. Toutefois, toute opération de compression entraîne une augmentation temporaire de la latence. Par conséquent, elles ne doivent pas être déclenchées fréquemment. Si ce paramètre n'est pas défini, la valeur par défaut est de 80% de la limite de la fenêtre contextuelle du modèle. Il reste donc 20% pour la prochaine requête utilisateur/réponse du modèle. |
EndSensitivity
Détermine comment la fin de la parole est détectée.
Enums | |
---|---|
END_SENSITIVITY_UNSPECIFIED |
La valeur par défaut est END_SENSITIVITY_HIGH. |
END_SENSITIVITY_HIGH |
La détection automatique met fin à la parole plus souvent. |
END_SENSITIVITY_LOW |
La détection automatique met fin à la parole moins souvent. |
GoAway
Notification indiquant que le serveur sera bientôt déconnecté.
Champs | |
---|---|
timeLeft |
Temps restant avant que la connexion ne soit arrêtée en tant que "ABORTED". Cette durée ne sera jamais inférieure à une durée minimale spécifique au modèle, qui sera spécifiée avec les limites de débit du modèle. |
RealtimeInputConfig
Configure le comportement des entrées en temps réel dans BidiGenerateContent
.
Champs | |
---|---|
automaticActivityDetection |
Facultatif. Si ce champ n'est pas défini, la détection automatique des activités est activée par défaut. Si la détection vocale automatique est désactivée, le client doit envoyer des signaux d'activité. |
activityHandling |
Facultatif. Définit l'effet de l'activité. |
turnCoverage |
Facultatif. Définit l'entrée incluse au tour de l'utilisateur. |
SessionResumptionConfig
Configuration de la reprise de session.
Ce message est inclus dans la configuration de la session sous la forme BidiGenerateContentSetup.sessionResumption
. Si le serveur est configuré, il envoie des messages SessionResumptionUpdate
.
Champs | |
---|---|
handle |
Poignée d'une session précédente. Si ce n'est pas le cas, une session est créée. Les poignées de session proviennent des valeurs |
SessionResumptionUpdate
Mise à jour de l'état de reprise de la session.
N'est envoyé que si BidiGenerateContentSetup.sessionResumption
a été défini.
Champs | |
---|---|
newHandle |
Nouvel identifiant représentant un état pouvant être repris. Vide si |
resumable |
"True" si la session en cours peut être reprise à ce stade. La reprise n'est pas possible à certains moments de la session. Par exemple, lorsque le modèle exécute des appels de fonction ou génère des données. La reprise de la session (à l'aide d'un jeton de session précédent) dans cet état entraînera une perte de données. Dans ce cas, |
SlidingWindow
La méthode SlidingWindow fonctionne en supprimant le contenu au début de la fenêtre de contexte. Le contexte obtenu commence toujours au début d'un tour de rôle UTILISATEUR. Les instructions système et les BidiGenerateContentSetup.prefixTurns
restent toujours au début du résultat.
Champs | |
---|---|
targetTokens |
Nombre cible de jetons à conserver. La valeur par défaut est "trigger_tokens/2". L'abandon de parties de la fenêtre de contexte entraîne une augmentation temporaire de la latence. Cette valeur doit donc être calibrée pour éviter les opérations de compression fréquentes. |
StartSensitivity
Détermine comment le début de la parole est détecté.
Enums | |
---|---|
START_SENSITIVITY_UNSPECIFIED |
La valeur par défaut est START_SENSITIVITY_HIGH. |
START_SENSITIVITY_HIGH |
La détection automatique détectera plus souvent le début de la parole. |
START_SENSITIVITY_LOW |
La détection automatique détectera moins souvent le début de la parole. |
TurnCoverage
Options concernant l'entrée incluse dans le tour de l'utilisateur.
Enums | |
---|---|
TURN_COVERAGE_UNSPECIFIED |
Si aucune valeur n'est spécifiée, le comportement par défaut est TURN_INCLUDES_ONLY_ACTIVITY . |
TURN_INCLUDES_ONLY_ACTIVITY |
Le tour de l'utilisateur n'inclut que l'activité depuis le dernier tour, à l'exclusion de l'inactivité (par exemple, le silence sur le flux audio). Il s'agit du comportement par défaut. |
TURN_INCLUDES_ALL_INPUT |
Le tour de l'utilisateur inclut toutes les entrées en temps réel depuis le dernier tour, y compris l'inactivité (par exemple, le silence sur le flux audio). |
UsageMetadata
Métadonnées d'utilisation des réponses.
Champs | |
---|---|
promptTokenCount |
Uniquement en sortie. Nombre de jetons dans l'invite. Lorsque |
cachedContentTokenCount |
Nombre de jetons dans la partie mise en cache de l'invite (le contenu mis en cache) |
responseTokenCount |
Uniquement en sortie. Nombre total de jetons pour toutes les réponses candidates générées. |
toolUsePromptTokenCount |
Uniquement en sortie. Nombre de jetons présents dans la ou les requêtes d'utilisation de l'outil. |
thoughtsTokenCount |
Uniquement en sortie. Nombre de jetons de pensées pour les modèles de réflexion. |
totalTokenCount |
Uniquement en sortie. Nombre total de jetons pour la requête de génération (invite + candidats de réponse). |
promptTokensDetails[] |
Uniquement en sortie. Liste des modalités traitées dans l'entrée de la requête. |
cacheTokensDetails[] |
Uniquement en sortie. Liste des modalités du contenu mis en cache dans l'entrée de la requête. |
responseTokensDetails[] |
Uniquement en sortie. Liste des modalités renvoyées dans la réponse. |
toolUsePromptTokensDetails[] |
Uniquement en sortie. Liste des modalités qui ont été traitées pour les entrées de requêtes d'utilisation d'outils. |
En savoir plus sur les types courants
Pour en savoir plus sur les types de ressources d'API couramment utilisés (Blob
, Content
, FunctionCall
, FunctionResponse
, GenerationConfig
, GroundingMetadata
, ModalityTokenCount
et Tool
), consultez la section Générer du contenu.