La API de Live es una API con estado que usa WebSockets. En esta sección, encontrarás detalles adicionales sobre la API de WebSockets.
Sesiones
Una conexión WebSocket establece una sesión entre el cliente y el servidor Gemini. Después de que un cliente inicia una conexión nueva, la sesión puede intercambiar mensajes con el servidor para realizar las siguientes acciones:
- Enviar texto, audio o video al servidor de Gemini
- Recibir solicitudes de llamadas de audio, texto o función del servidor de Gemini
Conexión de WebSocket
Para iniciar una sesión, conéctate a este extremo de websocket:
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent
Configuración de la sesión
El mensaje inicial después de la conexión establece la configuración de la sesión, que incluye el modelo, los parámetros de generación, las instrucciones del sistema y las herramientas.
Puedes cambiar los parámetros de configuración, excepto el modelo, durante la sesión.
Consulta la siguiente configuración de ejemplo. Ten en cuenta que la mayúscula o minúscula de los nombres en los SDKs puede variar. Puedes buscar las opciones de configuración del SDK de Python aquí.
{
"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]
}
Para obtener más información sobre el campo de la API, consulta generationConfig.
Cómo enviar mensajes
Para intercambiar mensajes a través de la conexión WebSocket, el cliente debe enviar un objeto JSON a través de una conexión WebSocket abierta. El objeto JSON debe tener exactamente uno de los campos del siguiente conjunto de objetos:
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
Mensajes de cliente compatibles
Consulta los mensajes de cliente admitidos en la siguiente tabla:
Mensaje | Descripción |
---|---|
BidiGenerateContentSetup |
Configuración de la sesión que se enviará en el primer mensaje |
BidiGenerateContentClientContent |
Actualización incremental del contenido de la conversación actual que se entrega desde el cliente |
BidiGenerateContentRealtimeInput |
Entrada de audio, video o texto en tiempo real |
BidiGenerateContentToolResponse |
Respuesta a un ToolCallMessage recibido del servidor |
Recibir mensajes
Para recibir mensajes de Gemini, escucha el evento "message" de WebSocket y, luego, analiza el resultado según la definición de los mensajes del servidor compatibles.
Consulta lo siguiente:
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)
Los mensajes del servidor pueden tener un campo usageMetadata
, pero, de lo contrario, incluirán exactamente uno de los otros campos del mensaje BidiGenerateContentServerMessage
. (La unión messageType
no se expresa en JSON, por lo que el campo aparecerá en el nivel superior del mensaje).
Mensajes y eventos
ActivityEnd
Este tipo no tiene campos.
Marca el final de la actividad del usuario.
ActivityHandling
Las diferentes formas de controlar la actividad del usuario
Enumeraciones | |
---|---|
ACTIVITY_HANDLING_UNSPECIFIED |
Si no se especifica, el comportamiento predeterminado es START_OF_ACTIVITY_INTERRUPTS . |
START_OF_ACTIVITY_INTERRUPTS |
Si es verdadero, el inicio de la actividad interrumpirá la respuesta del modelo (también llamada "interrupción"). La respuesta actual del modelo se cortará en el momento de la interrupción. Este es el comportamiento predeterminado. |
NO_INTERRUPTION |
La respuesta del modelo no se interrumpirá. |
ActivityStart
Este tipo no tiene campos.
Marca el inicio de la actividad del usuario.
AudioTranscriptionConfig
Este tipo no tiene campos.
La configuración de la transcripción de audio
AutomaticActivityDetection
Configura la detección automática de actividad.
Campos | |
---|---|
disabled |
Opcional. Si está habilitada (configuración predeterminada), la entrada de voz y texto detectada se registra como actividad. Si está inhabilitado, el cliente debe enviar indicadores de actividad. |
startOfSpeechSensitivity |
Opcional. Determina la probabilidad de que se detecte la voz. |
prefixPaddingMs |
Opcional. Es la duración requerida de la voz detectada antes de que se confirme el inicio de la voz. Cuanto más bajo sea este valor, más sensible será la detección del inicio de la voz y se podrá reconocer una voz más corta. Sin embargo, esto también aumenta la probabilidad de falsos positivos. |
endOfSpeechSensitivity |
Opcional. Determina la probabilidad de que haya finalizado la voz detectada. |
silenceDurationMs |
Opcional. Es la duración requerida de la detección de audio sin voz (p.ej., silencio) antes de que se confirme el final de la voz. Cuanto mayor sea este valor, más largas pueden ser las pausas de voz sin interrumpir la actividad del usuario, pero esto aumentará la latencia del modelo. |
BidiGenerateContentClientContent
Es la actualización incremental de la conversación actual que se entrega desde el cliente. Todo el contenido aquí se agrega sin condiciones al historial de conversaciones y se usa como parte de la instrucción para que el modelo genere contenido.
Un mensaje aquí interrumpirá cualquier generación de modelos actual.
Campos | |
---|---|
turns[] |
Opcional. Es el contenido que se adjunta a la conversación actual con el modelo. Para consultas de un solo turno, esta es una instancia única. Para las consultas de varios turnos, este es un campo repetido que contiene el historial de conversaciones y la solicitud más reciente. |
turnComplete |
Opcional. Si es verdadero, indica que la generación de contenido del servidor debe comenzar con la instrucción acumulada actualmente. De lo contrario, el servidor espera mensajes adicionales antes de iniciar la generación. |
BidiGenerateContentRealtimeInput
Entrada del usuario que se envía en tiempo real.
Las diferentes modalidades (audio, video y texto) se controlan como transmisiones simultáneas. No se garantiza el orden de estas transmisiones.
Esto es diferente de BidiGenerateContentClientContent
en algunos aspectos:
- Se pueden enviar de forma continua sin interrupciones a la generación de modelos.
- Si es necesario mezclar datos intercalados entre
BidiGenerateContentClientContent
yBidiGenerateContentRealtimeInput
, el servidor intenta realizar optimizaciones para obtener la mejor respuesta, pero no hay garantías. - El final de la toma de turno no se especifica de forma explícita, sino que se deriva de la actividad del usuario (por ejemplo, el final de la voz).
- Incluso antes de que finalice el turno, los datos se procesan de forma incremental para optimizar un inicio rápido de la respuesta del modelo.
Campos | |
---|---|
mediaChunks[] |
Opcional. Datos de bytes intercalados para la entrada de contenido multimedia. No se admiten varios OBSOLETO: En su lugar, usa uno de |
audio |
Opcional. Estos forman la transmisión de entrada de audio en tiempo real. |
video |
Opcional. Estos forman el flujo de entrada de video en tiempo real. |
activityStart |
Opcional. Marca el inicio de la actividad del usuario. Solo se puede enviar si la detección automática de actividad (es decir, del servidor) está inhabilitada. |
activityEnd |
Opcional. Marca el final de la actividad del usuario. Solo se puede enviar si la detección automática de actividad (es decir, del servidor) está inhabilitada. |
audioStreamEnd |
Opcional. Indica que finalizó la transmisión de audio, p.ej., porque se apagó el micrófono. Solo se debe enviar cuando la detección automática de actividades está habilitada (que es la configuración predeterminada). El cliente puede volver a abrir la transmisión enviando un mensaje de audio. |
text |
Opcional. Estos forman el flujo de entrada de texto en tiempo real. |
BidiGenerateContentServerContent
Actualización incremental del servidor que genera el modelo en respuesta a los mensajes del cliente.
El contenido se genera lo más rápido posible, no en tiempo real. Los clientes pueden optar por almacenar en búfer y reproducirlo en tiempo real.
Campos | |
---|---|
generationComplete |
Solo salida. Si es verdadero, indica que el modelo terminó de generarse. Cuando el modelo se interrumpa durante la generación, no habrá un mensaje "generation_complete" en el turno interrumpido, sino que pasará por "interrupted > turn_complete". Cuando el modelo asuma la reproducción en tiempo real, habrá una demora entre generation_complete y turn_complete, que se debe a que el modelo espera a que finalice la reproducción. |
turnComplete |
Solo salida. Si es verdadero, indica que el modelo completó su turno. La generación solo comenzará en respuesta a mensajes adicionales del cliente. |
interrupted |
Solo salida. Si es verdadero, indica que un mensaje del cliente interrumpió la generación de modelos actual. Si el cliente reproduce el contenido en tiempo real, esta es una buena señal para detener y vaciar la cola de reproducción actual. |
groundingMetadata |
Solo salida. Metadatos de origen para el contenido generado |
outputTranscription |
Solo salida. Genera una transcripción de audio de salida. La transcripción se envía independientemente de los otros mensajes del servidor y no hay un orden garantizado, en particular, no entre |
modelTurn |
Solo salida. Es el contenido que el modelo generó como parte de la conversación actual con el usuario. |
BidiGenerateContentServerMessage
Es el mensaje de respuesta para la llamada BidiGenerateContent.
Campos | |
---|---|
usageMetadata |
Solo salida. Son los metadatos de uso sobre las respuestas. |
Campo de unión messageType . Es el tipo de mensaje. Las direcciones (messageType ) solo pueden ser una de las siguientes opciones: |
|
setupComplete |
Solo salida. Se envía en respuesta a un mensaje |
serverContent |
Solo salida. Es el contenido que genera el modelo en respuesta a los mensajes de los clientes. |
toolCall |
Solo salida. Solicita al cliente que ejecute el |
toolCallCancellation |
Solo salida. Notificación para el cliente de que se debe cancelar un |
goAway |
Solo salida. Un aviso de que el servidor pronto se desconectará |
sessionResumptionUpdate |
Solo salida. Actualización del estado de reanudación de la sesión. |
BidiGenerateContentSetup
Es el mensaje que se enviará en el primer (y solo en el primer) BidiGenerateContentClientMessage
. Contiene la configuración que se aplicará durante la RPC de transmisión.
Los clientes deben esperar un mensaje BidiGenerateContentSetupComplete
antes de enviar cualquier mensaje adicional.
Campos | |
---|---|
model |
Obligatorio. Es el nombre del recurso del modelo. Este ID sirve como ID para que lo use el modelo. Formato: |
generationConfig |
Opcional. Configuración de generación No se admiten los siguientes campos:
|
systemInstruction |
Opcional. Las instrucciones del sistema que proporcionó el usuario para el modelo. Nota: Solo se debe usar texto en las partes y el contenido en cada parte debe encontrarse en un párrafo separado. |
tools[] |
Opcional. Es una lista de Un |
realtimeInputConfig |
Opcional. Configura el control de la entrada en tiempo real. |
sessionResumption |
Opcional. Configura el mecanismo de reanudación de la sesión. Si se incluye, el servidor enviará mensajes |
contextWindowCompression |
Opcional. Configura un mecanismo de compresión de ventana de contexto. Si se incluye, el servidor reducirá automáticamente el tamaño del contexto cuando supere la longitud configurada. |
outputAudioTranscription |
Opcional. Si se establece, habilita la transcripción de la salida de audio del modelo. La transcripción se alinea con el código de idioma especificado para el audio de salida, si está configurado. |
BidiGenerateContentSetupComplete
Este tipo no tiene campos.
Se envía en respuesta a un mensaje BidiGenerateContentSetup
del cliente.
BidiGenerateContentToolCall
Solicita al cliente que ejecute el functionCalls
y que devuelva las respuestas con los id
coincidentes.
Campos | |
---|---|
functionCalls[] |
Solo salida. La llamada a función que se ejecutará. |
BidiGenerateContentToolCallCancellation
Notificación para el cliente de que un ToolCallMessage
emitido anteriormente con los id
especificados no debería haberse ejecutado y debe cancelarse. Si hubo efectos secundarios en esas llamadas a la herramienta, los clientes pueden intentar deshacerlas. Este mensaje solo ocurre en los casos en que los clientes interrumpen los turnos del servidor.
Campos | |
---|---|
ids[] |
Solo salida. Los IDs de las llamadas a la herramienta que se cancelarán. |
BidiGenerateContentToolResponse
Respuesta generada por el cliente a un ToolCall
recibido del servidor. Los objetos FunctionResponse
individuales se corresponden con los objetos FunctionCall
respectivos mediante el campo id
.
Ten en cuenta que, en las APIs de GenerateContent uniaria y de transmisión del servidor, las llamadas a función se realizan intercambiando las partes Content
, mientras que, en las APIs de GenerateContent de transmisión bidireccional, las llamadas a función se realizan a través de este conjunto dedicado de mensajes.
Campos | |
---|---|
functionResponses[] |
Opcional. La respuesta a las llamadas a la función. |
BidiGenerateContentTranscription
Transcripción de audio (entrada o salida).
Campos | |
---|---|
text |
Texto de la transcripción. |
ContextWindowCompressionConfig
Habilita la compresión de la ventana de contexto, un mecanismo para administrar la ventana de contexto del modelo de modo que no exceda una longitud determinada.
Campos | |
---|---|
Campo de unión compressionMechanism . Es el mecanismo de compresión de la ventana de contexto que se usa. Las direcciones (compressionMechanism ) solo pueden ser una de las siguientes opciones: |
|
slidingWindow |
Un mecanismo de ventana deslizante |
triggerTokens |
Es la cantidad de tokens (antes de ejecutar un turno) necesarios para activar una compresión de ventana de contexto. Esto se puede usar para equilibrar la calidad con la latencia, ya que las ventanas de contexto más cortas pueden generar respuestas del modelo más rápidas. Sin embargo, cualquier operación de compresión provocará un aumento temporal de la latencia, por lo que no se deben activar con frecuencia. Si no se establece, el valor predeterminado es el 80% del límite de la ventana de contexto del modelo. Esto deja un 20% para la próxima solicitud del usuario o respuesta del modelo. |
EndSensitivity
Determina cómo se detecta el final de la voz.
Enumeraciones | |
---|---|
END_SENSITIVITY_UNSPECIFIED |
El valor predeterminado es END_SENSITIVITY_HIGH. |
END_SENSITIVITY_HIGH |
La detección automática finaliza la voz con más frecuencia. |
END_SENSITIVITY_LOW |
La detección automática finaliza la voz con menos frecuencia. |
GoAway
Un aviso de que el servidor pronto se desconectará
Campos | |
---|---|
timeLeft |
El tiempo restante antes de que se cierre la conexión se mostrará como ABORTED. Esta duración nunca será inferior a un mínimo específico del modelo, que se especificará junto con los límites de frecuencia del modelo. |
RealtimeInputConfig
Configura el comportamiento de entrada en tiempo real en BidiGenerateContent
.
Campos | |
---|---|
automaticActivityDetection |
Opcional. Si no se establece, la detección automática de actividades está habilitada de forma predeterminada. Si la detección de voz automática está inhabilitada, el cliente debe enviar indicadores de actividad. |
activityHandling |
Opcional. Define qué efecto tiene la actividad. |
turnCoverage |
Opcional. Define qué entrada se incluye en el turno del usuario. |
SessionResumptionConfig
Configuración de la reanudación de la sesión.
Este mensaje se incluye en la configuración de la sesión como BidiGenerateContentSetup.sessionResumption
. Si se configura, el servidor enviará mensajes SessionResumptionUpdate
.
Campos | |
---|---|
handle |
Es el identificador de una sesión anterior. Si no está presente, se crea una sesión nueva. Los identificadores de sesión provienen de los valores de |
SessionResumptionUpdate
Actualización del estado de reanudación de la sesión.
Solo se envía si se configuró BidiGenerateContentSetup.sessionResumption
.
Campos | |
---|---|
newHandle |
Es un identificador nuevo que representa un estado que se puede reanudar. Está vacío si |
resumable |
Es verdadero si la sesión actual se puede reanudar en este momento. No es posible reanudar la sesión en algunos puntos. Por ejemplo, cuando el modelo ejecuta llamadas a funciones o genera. Si se reanuda la sesión (con un token de sesión anterior) en ese estado, se perderán algunos datos. En estos casos, |
SlidingWindow
El método SlidingWindow funciona descartando el contenido al comienzo de la ventana de contexto. El contexto resultante siempre comenzará al comienzo de un turno de rol de USUARIO. Las instrucciones del sistema y cualquier BidiGenerateContentSetup.prefixTurns
siempre permanecerán al principio del resultado.
Campos | |
---|---|
targetTokens |
Es la cantidad objetivo de tokens que se deben conservar. El valor predeterminado es trigger_tokens/2. Si se descartan partes de la ventana de contexto, se produce un aumento temporal de latencia, por lo que este valor se debe calibrar para evitar operaciones de compresión frecuentes. |
StartSensitivity
Determina cómo se detecta el inicio de la voz.
Enumeraciones | |
---|---|
START_SENSITIVITY_UNSPECIFIED |
El valor predeterminado es START_SENSITIVITY_HIGH. |
START_SENSITIVITY_HIGH |
La detección automática detectará el inicio de la voz con mayor frecuencia. |
START_SENSITIVITY_LOW |
La detección automática detectará el inicio de la voz con menos frecuencia. |
TurnCoverage
Son opciones sobre qué entrada se incluye en el turno del usuario.
Enumeraciones | |
---|---|
TURN_COVERAGE_UNSPECIFIED |
Si no se especifica, el comportamiento predeterminado es TURN_INCLUDES_ONLY_ACTIVITY . |
TURN_INCLUDES_ONLY_ACTIVITY |
El turno del usuario solo incluye la actividad desde el último turno, sin incluir la inactividad (p.ej., silencio en la transmisión de audio). Este es el comportamiento predeterminado. |
TURN_INCLUDES_ALL_INPUT |
El turno del usuario incluye todas las entradas en tiempo real desde el último turno, incluida la inactividad (p.ej., silencio en la transmisión de audio). |
UsageMetadata
Son los metadatos de uso sobre las respuestas.
Campos | |
---|---|
promptTokenCount |
Solo salida. Cantidad de tokens en la instrucción. Cuando se establece |
cachedContentTokenCount |
Cantidad de tokens en la parte almacenada en caché de la instrucción (el contenido almacenado en caché) |
responseTokenCount |
Solo salida. Es la cantidad total de tokens de todos los candidatos de respuesta generados. |
toolUsePromptTokenCount |
Solo salida. Cantidad de tokens presentes en las instrucciones de uso de herramientas. |
thoughtsTokenCount |
Solo salida. Cantidad de tokens de pensamientos para los modelos de pensamiento. |
totalTokenCount |
Solo salida. Es el recuento total de tokens para la solicitud de generación (instrucción + candidatos de respuesta). |
promptTokensDetails[] |
Solo salida. Es la lista de modalidades que se procesaron en la entrada de la solicitud. |
cacheTokensDetails[] |
Solo salida. Es la lista de modalidades del contenido almacenado en caché en la entrada de la solicitud. |
responseTokensDetails[] |
Solo salida. Es la lista de modalidades que se mostraron en la respuesta. |
toolUsePromptTokensDetails[] |
Solo salida. Es la lista de modalidades que se procesaron para las entradas de solicitudes de uso de herramientas. |
Más información sobre los tipos comunes
Para obtener más información sobre los tipos de recursos de API de uso general Blob
, Content
, FunctionCall
, FunctionResponse
, GenerationConfig
, GroundingMetadata
, ModalityTokenCount
y Tool
, consulta Cómo generar contenido.