API de voz

Información general

La API de voz proporciona una comunicación de audio de extremo a extremo entre el usuario y el bot de texto:

• app.graphlogic.ai

La comunicación se realiza en los siguientes pasos generales:

1. El texto del usuario se reconoce a partir del audio del usuario mediante STT (Speech To Text technology; también ASR - Automatic Speech Recognition).

2. A continuación, el texto del usuario se pasa al sistema de bots (véase la plataforma de bots de chat).

3. El sistema de bots genera mensajes de texto en función del escenario (véase la plataforma de bots de chat).

4. A continuación, el audio del bot se sintetiza a partir de los mensajes de texto del bot mediante la tecnología TTS (Text To Speech).

Puede comprobar si la API de voz está disponible enviando una simple solicitud GET ahttps://{host}/api/voice/v1/user-stt-bot-tts/ping .

El streaming se basa en la conexión websocket (WS), que proporciona comunicación dúplex (se pueden enviar y recibir datos en paralelo).

La API v1 es totalmente compatible, pero puede quedar obsoleta en el futuro.

La nueva API v2 está en desarrollo activo.

v1 streaming

Work with streaming endpoint in the following steps:

1. abrir conexión WS a wss://{host}/api/voice/v1/user-stt-bot-tts/stream .

2. enviar trama abierta a WS una vez abierta la conexión.

3. enviar tramas de audio a WS (habla del usuario) después de abrir la trama.

4. recibir tramas de audio del WS (discurso / respuestas del bot) después de abrir la trama.

5. cerrar la conexión WS para finalizar el flujo de comunicación.

Si la trama abierta no es válida (por ejemplo, clave de API no válida) o se produce un error interno durante la transmisión, el endpoint cierra la conexión WS.

Marco abierto

Antes de empezar a enviar y recibir datos de audio, debe enviar una trama abierta con su clave API(https://docs.graphlogic.ai/d/_dmiSwuik2Ar/_sulW_). Open frame es un mensaje de texto WS con una cadena JSON serializada.

También puede proporcionar información adicional para la conexión actual (por ejemplo, ID de usuario, información contextual, anulación de la configuración STT / TTS, véase la estructura de trama abierta más abajo).

Estructura JSON de marco abierto

{
  "kind": "open",
  // cadena obligatoria - proporciona la clave API para la autorización de la solicitud.
  "api_key": "XXX",
  // cadena opcional (cualquier formato, por ejemplo, número de teléfono o correo electrónico o uuid) - identificador de usuario, ayuda a los sistemas de bot de texto para obtener
  // saber qué usuario está enviando los mensajes y utilizarlo para mantener la memoria del contexto del chat.
  "user_id": "XXX",
  // objeto JSON opcional (las claves son cadenas, los valores son cualquier JSON válido) - proporciona información contextual adicional sobre el objeto
  // usuario, ayuda a los sistemas de bots de texto a utilizar esta información en el escenario (por ejemplo, recordar el número de teléfono o la fecha de nacimiento del usuario).
  "context": {
    "name": (any JSON value),
  },
  // optional STT config overrides - anula los ajustes de configuración de STT para esta conexión.
  "stt": {
    // El objeto JSON se fusiona con la configuración del canal base, por lo que sólo los valores proporcionados se tienen en cuenta en la configuración resultante.
    // para más información ver Voice box API config.
  },
  // optional text bot config overrides - anula los ajustes de configuración del bot de texto para esta conexión.
  "text_bot": {
    // El objeto JSON se fusiona con la configuración del canal base, por lo que sólo los valores proporcionados se tienen en cuenta en la configuración resultante.
    // Para más información, consulte Voice box API config.
  },
  // optional TTS config overrides - anula los ajustes de configuración TTS para esta conexión.
  "tts": {
    // El objeto JSON se fusiona con la configuración del canal base, por lo que sólo los valores proporcionados se tienen en cuenta en la configuración resultante.
    // Para más información, consulte Voice box API config.
  }
}

Ejemplos de marcos abiertos

Marco abierto simple para iniciar la comunicación utilizando la configuración predeterminada del canal del buzón de voz.

{  
"kind": "open",
  "api_key": "XXX"
 }

Abrir el marco con la configuración por defecto y el ID de usuario proporcionado y el contexto personalizado y desencadenar el escenario bot antes de que el usuario hable (la respuesta bot será la primera).

{
  "kind": "open",
  "api_key": "XXX",
  "user_id": "8b1609713e3c4cb49aa5be651c5959e1",
  "context": {
    "username": "John",
    "age": 30,
    "order_info": {
      "id": 42,
      "created_date": "2024-10-01"
  },
  "text_bot": {
    "trigger_bot": true
  }
}

Marco abierto con anulación de parámetros de audio de frecuencia de muestreo STT y TTS. La configuración final utilizará los mismos proveedores que en el canal del cuadro de voz correspondiente, pero con valores de frecuencia de muestreo específicos para STT y TTS.

{
  "kind": "open",
  "api_key": "XXX",
  "stt": {
    "sample_rate": 22000
  },
  "tts": {
    "sample_rate": 22000
  }
}

Marco abierto con anulación de bot de texto para activar el escenario bot antes del primer discurso del usuario.

{
  "kind": "open",
  "api_key": "XXX",
  "text_bot": {
    "trigger_bot": true
  }
}

Marco de audio

Después de abrir el marco, puede enviar y recibir datos de audio. El número de fotogramas es ilimitado (puedes enviar y recibir audio todo el tiempo que quieras).

La trama de audio es un mensaje binario WS con datos de audio. Los datos de audio deben codificarse en formato lineal 16.

v2 streaming

Trabaje con el punto final de streaming en los siguientes pasos:

1. abrir conexión WS con wss://{host}/api/voice/v2/user-stt-bot-tts/stream .

2. empezar a recibir tramas de respuesta de WS tras el envío de la trama abierta.

3. enviar trama abierta a WS una vez abierta la conexión.

4. enviar la trama de inicio de sesión de usuario al WS después de enviar la trama de apertura para iniciar la sesión de comunicación con un usuario específico.

5. enviar tramas de sesión de usuario (por ejemplo, audio) a WS después de que se envíe la trama de inicio de sesión de usuario para ese usuario.

6. enviar trama de fin de sesión de usuario a WS después de las tramas de sesión de usuario para finalizar la sesión de comunicación con un usuario específico.

7. se detiene para recibir tramas de respuesta de WS antes de que WS se cierre.

8. cerrar la conexión WS para finalizar todas las comunicaciones activas a la vez.

Si la trama abierta no es válida (por ejemplo, clave de API no válida) o se produce un error interno durante la transmisión, el punto final envía a WS la trama de error y puede cerrar la conexión WS si la conexión está interrumpida.

La API permite la comunicación con varios usuarios a través de una única conexión WS. Para ello, debe enviar el marco de inicio de sesión de usuario para cada usuario y proporcionar el user_id adecuado en cada marco de sesión de usuario.

marcos de transmisión v2

Cada mensaje WS es una cadena JSON serializada. Además, cada marco tiene un campo de tipo para especificar la estructura adecuada de todo el marco.

A continuación se muestra un archivo con el esquema JSON completo para el punto final WS. WSStreamRequest - estructura del mensaje WS entrante; WSStreamResponse - estructura del mensaje WS saliente.

66KB

schema.json

Los marcos pueden ser de dos tipos generales:

• request frame object - el cliente envía una solicitud al servidor

• response frame object - el servidor envía la respuesta al cliente

El punto final de la API acepta mensajes WS en un único objeto JSON de marco de solicitud o en una matriz JSON de objetos de marco de solicitud. El punto final de la API devuelve mensajes WS en una matriz JSON de objetos de marco de respuesta.

Ejemplos

• 1 objeto marco abierto en 1 mensaje de texto WS: {”kind”: “open”, “api_key”: “...”} .

• un array con 1 objeto marco abierto en 1 mensaje de texto WS: [{”kind”: “open”, “api_key”: “...”}] .

• 3 marcos de respuesta en 1 mensaje de texto WS: [{”kind”: “opened”}, {”kind”: “error”, “message”: “some error description”}, {”kind”: “closed”}] .

Marco de solicitud abierto

Una vez iniciada la conexión, debe enviar una trama abierta con su clave API(https://docs.graphlogic.ai/d/_dmiSwuik2Ar/_sulW_).

También puede proporcionar información adicional para la conexión actual (por ejemplo, anular la configuración de STT / bot de texto / TTS, véase la estructura de anulación más abajo). Esto anula la configuración sólo para la conexión actual.

Estructura

{
  "kind": "open",
  // proporcionar la clave API para la autorización de la solicitud.
  "api_key": (string),
  // opcional stt, text_bot, tts config overrides
  "stt": (optional object),
  "text_bot": (optional object),
  "tts": (optional object),
}

Ejemplos

Sencillo marco abierto para iniciar la comunicación utilizando la configuración predeterminada del canal del buzón de voz.

{
  "kind": "open",
  "api_key": "XXX"
}

Marco de respuesta abierto

Confirma que la solicitud abierta se ha procesado correctamente.

Estructura

{
  "kind": "opened"
}

Trama de respuesta a error

Si se produce algún error durante la transmisión, la API intentará enviar una trama de respuesta de error..

Estructura

{
  "kind": "error",
  // mensaje de descripción del error
  "message": (string)
}

Cerrar marco de solicitud

Pedir al endpoint que cierre el streaming con elegancia.

Estructura

{
  "kind": "close"
}

Marco de respuesta cerrado

Notifica que el flujo de comunicación está cerrado y que la conexión WS puede cerrarse.Estructura

{ 
  "kind": "closed",
  // mensaje de razón de flujo cerrado
   "reason": (optional string)
  }

Trama de solicitud de inicio de sesión de usuario

Antes de comenzar a enviar y recibir datos de audio del usuario, debe enviar el marco de inicio de sesión del usuario. También puede proporcionar información adicional para la conexión actual (por ejemplo, anular la configuración de STT / bot de texto / TTS, consulte la estructura de anulación a continuación). Esto anula la configuración para el usuario actual sólo dentro de la conexión actual.

Estructura

{
  "kind": "start_session",
  // identificador de usuario en cualquier formato (por ejemplo, número de teléfono o correo electrónico o uuid); ayuda a los sistemas de bots de texto a saber qué usuario está enviando los mensajes y a utilizarlo para mantener la memoria del contexto del chat.
  "user_id": (string),
  // información contextual opcional del usuario
  "context": (object),
  // opcional stt, text_bot, tts config overrides
  "stt": (optional object),
  "text_bot": (optional object),
  "tts": (optional object),
}

Trama de respuesta de sesión de usuario iniciada

Confirma que la sesión de usuario se ha iniciado correctamente.

Estructura

{
  "kind": "session_started",
  "user_id": (string, see user session start frame),
  // información de depuración sobre STT y TTS utilizados para la sesión de usuario
  "stt": (object),
  "tts": (object)
}

Trama de solicitud de fin de sesión de usuario

Finaliza la comunicación sólo con el usuario especificado.

Estructura

{
  "kind": "end_session",
  "user_id": (string, see user session start frame),
}

Trama de respuesta de sesión de usuario finalizada

Notifica que el flujo de comunicación con un usuario específico ha finalizado.

Estructura

{
  "kind": "session_ended",
  "user_id": (string, see user session start frame),
}

Trama de solicitud de audio de la sesión de usuario

Después del marco de inicio de sesión de usuario puede enviar datos de audio para ese usuario. La cantidad de fotogramas de audio es ilimitada (puedes enviar y recibir audio todo el tiempo que quieras).

Los datos de audio deben codificarse en formato de cadena lineal 16 base64.

Estructura

{
  "kind": "user_audio",
  "user_id": (string, see user session start frame),
  "audio": (string),
}

Marco de solicitud de texto de sesión de usuario

Una vez iniciada la sesión de usuario, puede enviar datos de texto para ese usuario. Este texto será reenviado al bot directamente, saltándose el sistema STT.

Estructura

{
  "kind": "user_text",
  "user_id": (string, see user session start frame),
  // el texto de un usuario se envía directamente al bot de texto (se omite el procesamiento ASR)
  "text": (string),
}

Marco de solicitud de contexto de actualización de sesión de usuario

Después del marco de inicio de sesión del usuario puede enviar información contextual sobre el usuario. Ver contexto.

Estructura

{
  "kind": "user_update_context",
  "user_id": (string, see user session start frame),
  "context": (object),
}

Fotograma de respuesta de audio de la sesión de bot

El mensaje de texto de un bot se procesará con TTS y el audio resultante se enviará al cliente.

Los datos de audio deben codificarse en formato de cadena lineal 16 base64.

Estructura

{
  "kind": "bot_audio",
  "user_id": (string, see user session start frame),
  "audio": (string),
  "subtitles": [
    {
      "text": (string),
      // inicio y fin del texto en audio (tiempo en milisegundos)
      "start": (number),
      "end": (number),
    }
  ]
}

Marco de respuesta de adjunto de sesión de bot

El mensaje adjunto de un bot (ver adjunto para más información).

Estructura

{
  "kind": "bot_attachment",
  "user_id": (string, see user session start frame),
  "attachment": (object)
}

Audio

IMPORTANTE: los datos de audio de usuario enviados deben grabarse con la misma frecuencia de muestreo especificada en los ajustes STT y los datos de audio de bot recibidos deben reproducirse con la misma frecuencia de muestreo especificada en los ajustes TTS.

Formato Lineal 16

En general, el contenido de los archivos de audio WAV se almacena en formato de audio PCM lineal. Para extraerlo se puede leer el archivo WAV y soltar metadatos WAV. Este es un ejemplo de archivo WAV de voz, codificado con frecuencia de muestreo (frecuencia de cuadro) = 16000, ancho de muestreo = 2, canales = 1

60KB

hello.wav

Ejemplo de datos de audio lineal 16

Puedes leer datos de audio de un archivo WAV usando la lib wave de python:

import wave

with wave.open("/my/audio/file.wav", "rb") as wf:
  assert wf.getnchannels() == 1
  assert wf.getsampwidth() == 2
  sample_rate = wf.getframerate()
  audio_data = wf.readframes(wf.getnframes())
  assert isinstance(audio_data, bytes)

También puedes escribir datos de audio en archivos WAV:

import wave

sample_rate = 16_000
audio_data = b"..."

with wave.open("/my/audio/file.wav", "wb") as wf:
  wf.setnchannels(1)
  wf.setsampwidth(2)
  wf.setframerate(sample_rate)
  assert isinstance(audio_data, bytes)
  wf.writeframes(audio_data)

Un enfoque similar se utiliza en echo bot python ejemplo v1.

Lineal 16 formato de cadena base64

El contenido binario del audio en formato lineal 16 se codifica en cadena base64.

ejemplo de codificación / descodificación de bytes base64

import base64

print(base64.b64encode(b"12345").decode())  # output: MTIzNDU=
print(base64.b64decode("MTIzNDU=".encode()))  # output: b'12345'

Anulaciones de configuración

El objeto de anulación proporcionado se fusiona con la configuración del canal base y, a continuación, el objeto final se valida y se utiliza dentro de la conexión o sesión de usuario.

Ejemplo

Suponga que tiene la siguiente configuración por defecto para su canal con la clave API XXX .

{
  "api_key": "XXX",
  "stt": {
    "kind": "internal",
    "sample_rate": 16000,
    "language_code": "en-US"
  },
  "text_bot": {},
  "tts": {
    "kind": "internal",
    "sample_rate": 16000,
    "voice_name": "EN_female"
  }
}

Puede anular la configuración de la frecuencia de muestreo para STT y TTS en el marco abierto de conexión.

{
  "kind": "open",
  "api_key": "XXX",
  "stt": {
    "sample_rate": 22000
  },
  "tts": {
    "sample_rate": 22000
  }
}

O anular el nombre de voz para TTS y habilitar los subtítulos en el marco de inicio de sesión de usuario para el usuario con id abcdef .

{
  "kind": "session_start",
  "user_id": "abcdef",
  "tts": {
    "voice_name": "RU_Ruslan",
    "subtitles": {
      "enabled": true
    }
  }
}

Todas las configuraciones anteriores utilizarán proveedores STT y TTS internos. Para anular el proveedor tiene que proporcionar una configuración completa. Por ejemplo, reemplazar STT interno por google STT para la conexión actual.

{
  "kind": "open",
  "api_key": "XXX",
  "stt": {
    "kind": "google",
    "service_account_info": {
      // objeto JSON de información de cuenta de servicio privado
    },
    "sample_rate": 16000,
    "name": "projects/my-project/locations/global/recognizers/_",
    "language_code": "en-US",
    "model": "long"
  }
}

Contexto

Proporcionar a bot información contextual adicional sobre el usuario (por ejemplo, fecha de nacimiento, número de teléfono, etc.). El bot de texto puede utilizar esta información en el escenario.

Estructura

// un objeto con claves de cadena y cualquier otro valor JSON válido
{
  (string): (any JSON value),
}

Example

{
  "username": "John",
  "age": 30,
  "order_info": {
    "id": 42,
    "created_date": "2024-10-01"
  }
}

Adjunto

El bot de texto puede enviar archivos adjuntos que no serán procesados por el TTS.

Texto adjunto

Proporcione un texto sencillo que no se utilizará en audio (síntesis). Por ejemplo, un código promocional.

{
  "kind": "text",
  "text": (string)
}

Enlace adjunto

Proporcionar una referencia a algún dato (por ejemplo, una URL a una imagen)

{
  "kind": "link",
  // name of the link
  "name": (optional string),
  // the link value
  "link": (string)
}

Ejemplo

{
  "kind": "link",
  "name": "welcome to google",
  "link": "https://google.com"
}

Accesorio binario

Facilite un anexo completo con su contenido.

{
  "kind": "binary",
  // el nombre del contenido binario (como el nombre del archivo)
  "name": (optional string),
  // el tipo MIME del contenido binario (por ejemplo, image/png), similar a la cabecera HTTP content-type
  "content_type": (string),
  // cuerpo binario
  "body": (string in base64 format),
}

Ejemplo de voz: bot eco con saludos

La siguiente configuración es un escenario de bot de texto simple (echo bot) con saludo de usuario en el inicio y respuesta echo.

734B

echo-bot.zip

archive

Para importar la configuración debes tener una cuenta registrada en nuestra plataforma. Importa la configuración del agente, luego entrena a tu agente, crea el canal API de voice box, activa el canal y publica el proyecto. Después podrás utilizar la clave API del canal voice box creado para comunicarte con el bot a través de la API de voz. (TODO: referencias a la importación del agente, entrenamiento del agente, creación del canal voice box, activación del canal)

IMPORTANTE: para comunicarte con el bot tienes que conectarte al mismo host donde se construyó tu bot.

Una vez completada la configuración y obtenida la clave API, estarás listo para comunicarte con el bot.

Aquí ejemplos de archivos WAV con el discurso del usuario y el discurso de respuesta del bot:

88KB

greetings-user.wav

56KB

greetings-bot-response.wav

Echo bot python ejemplo

El siguiente script utiliza la API v1

3KB

echo-bot-example.py

El siguiente script utiliza la API v2

5KB

echo-bot-example-v2.py

Requisitos:

• python 3.12

  • aiohttp 3.10.6 (puede instalarlo con pip install aiohttp==3.10.6)

Antes de ejecutar el script de ejemplo debe especificar los argumentos api_key y host para la llamada a la función principal.

Tras el inicio, el script leerá el archivo fuente y enviará su audio a la API de voz. Al mismo tiempo, el script recibirá los fotogramas WS entrantes y los escribirá en el archivo de salida.

Durante la ejecución el script mostrará algo como:

audio leído y enviado a WS
audio leído y enviado a WS
...
audio recibido de WS y guardado

Tras salir del script podrás reproducir el archivo de audio WAV dest.

Echo bot NodeJS ejemplo

El siguiente proyecto NodeJS utiliza la API v2.

12KB

echo-bot-typescript-example-v2.zip

archive

Compruebe README.md para preparar el proyecto para su ejecución.

Requisitos

• @types/node-wav@0.0.3

• @types/node@22.10.2

• @types/ws@8.5.13

• node-wav@0.0.2

• nodemon@3.1.9

• ts-node@10.9.2

• typescript@5.7.2

• uuid@11.0.3

• ws@8.18.0

Antes de ejecutar el proyecto de ejemplo debe especificar los argumentos api_key y host para la llamada a la función principal.

Tras el inicio, el script leerá el archivo fuente y enviará su audio a la API de voz. Al mismo tiempo, el script recibirá los fotogramas WS entrantes y los escribirá en el archivo de salida.

Durante la ejecución el script mostrará algo como:

WS frames received [ { kind: 'opened' } ]
WS frames received [
  {
    user_id: '0c27117f-7ab2-4c70-8cea-b2067d02c4c2',
    kind: 'session_started',
    stt: {
      kind: 'internal',
      language_code: 'en-US',
      sample_rate: 16000,
      automatic_punctuation: false
    },
    tts: {
      kind: 'internal',
      sample_rate: 16000,
      offline: false,
      speed: 1,
      pitch: 0,
      enable_normalization: false,
      volume: 0,
      voice_name: 'EN_female',
      language_code: 'en-US',
      subtitles: [Object]
    }
  }
]
Session started, streaming audio...
Audio chunk sent
Audio streaming complete. Starting session timeout...
Audio chunk sent
Audio chunk sent
Audio chunk sent
Audio chunk sent
Audio chunk sent
Audio chunk sent
Audio chunk sent
WS frames received [
  {
    user_id: '0c27117f-7ab2-4c70-8cea-b2067d02c4c2',
    kind: 'bot_audio',
    audio: '...' # string encoded audio data
  }
]
Saving audio to file...
Audio of length 29352 appended to response.wav
Audio frame received

Después de salir del script podrás reproducir el archivo WAV de audio dest.