Transcripción en tiempo real

Usa la transcripción en tiempo real cuando tu aplicación necesite convertir en texto el audio de un micrófono, una llamada u otra fuente de audio en vivo sin que el asistente responda por voz. El modelo recomendado devuelve fragmentos de la transcripción a medida que recibe el audio y la transcripción final de cada turno cuando tu aplicación lo confirma.

Empieza con gpt-live-transcribe. Si el audio ya está grabado, usa la transcripción de archivos. Para comparar los flujos de trabajo, consulta la guía general de transcripción.

Crear una sesión de transcripción

Para transcribir audio en el servidor mediante WebSocket con una clave de API estándar, conéctate a wss://api.openai.com/v1/realtime?intent=transcription. Usa el encabezado de autenticación de la guía de WebSocket, pero omite model en la URL. La URL de esa guía incluye el modelo y crea una sesión de conversación que no admite la actualización de transcripción que se muestra a continuación.

Una vez abierta la conexión, envía session.update con type: "transcription" y selecciona gpt-live-transcribe en la configuración de la sesión. Para trabajar con audio en el navegador, consulta la guía de WebRTC.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "gpt-live-transcribe"
        },
        "turn_detection": null
      }
    }
  }
}

Este ejemplo usa audio PCM a 24 kHz. En las sesiones de transcripción con gpt-live-transcribe, omite audio.input.turn_detection o asígnale el valor null. El modelo no admite server_vad ni semantic_vad. Para conocer todas las opciones de configuración de la sesión, consulta la referencia de sesiones de Realtime.

Transmitir audio

Envía fragmentos de audio con input_audio_buffer.append.

1
2
3
4
5
6ws.send(
  JSON.stringify({
    type: "input_audio_buffer.append",
    audio: base64Pcm16,
  })
);

Envía input_audio_buffer.commit al final de cada turno de audio para recibir la transcripción final.

1
2
3
4
5ws.send(
  JSON.stringify({
    type: "input_audio_buffer.commit",
  })
);

Usa la detección de actividad de voz (VAD) en el cliente para detectar cuándo termina de hablar la persona. Luego, envía input_audio_buffer.commit.

Procesar eventos de transcripción

Escucha los eventos que entregan fragmentos de la transcripción y los que indican que la transcripción terminó.

1
2
3
4
5
6
7
8
9
10
11ws.on("message", (data) => {
  const event = JSON.parse(data);

  if (event.type === "conversation.item.input_audio_transcription.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "conversation.item.input_audio_transcription.completed") {
    console.log("\nFinal transcript:", event.transcript);
  }
});

Cada evento delta contiene el nuevo fragmento de texto disponible.

123456{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "item_003",
  "content_index": 0,
  "delta": "Hello,"
}

El evento de finalización contiene la transcripción final del elemento confirmado.

123456{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "item_003",
  "content_index": 0,
  "transcript": "Hello, how are you?"
}

Los eventos de finalización pueden llegar en un orden distinto al de los turnos de voz. Usa item_id para asociar los eventos de transcripción con los elementos de entrada confirmados.

Después de configurar una sesión de transcripción, usa esta función de Go para enviar audio PCM16 mono a 24 kHz, confirmar el turno y asociar la transcripción final con el elemento confirmado.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43func transcribeTurn(ctx context.Context, conn *realtime.RealtimeConnection, audio []byte) error {
	for start := 0; start < len(audio); start += 9600 {
		end := min(start+9600, len(audio))
		if err := conn.Send(ctx, realtime.RealtimeClientEventParamOfInputAudioBufferAppend(base64.StdEncoding.EncodeToString(audio[start:end]))); err != nil {
			return err
		}
	}
	if err := conn.Send(ctx, realtime.RealtimeClientEventUnionParam{
		OfInputAudioBufferCommit: &realtime.InputAudioBufferCommitEventParam{},
	}); err != nil {
		return err
	}
	// Match the final transcript to the committed item, not event arrival order.
	var itemID string
	for {
		event, err := conn.Recv(ctx)
		if err != nil {
			return err
		}
		switch event.Type {
		case "input_audio_buffer.committed":
			itemID = event.OfInputAudioBufferCommittedEvent.ItemID
		case "conversation.item.input_audio_transcription.delta":
			delta := event.OfConversationItemInputAudioTranscriptionDeltaEvent
			if itemID != "" && delta.ItemID == itemID {
				fmt.Fprintf(os.Stderr, "Partial transcript (%s): %s\n", delta.ItemID, delta.Delta)
			}
		case "conversation.item.input_audio_transcription.completed":
			completed := event.OfConversationItemInputAudioTranscriptionCompletedEvent
			if itemID == "" || completed.ItemID != itemID {
				continue
			}
			fmt.Println("Final transcript:", completed.Transcript)
			return nil
		case "conversation.item.input_audio_transcription.failed":
			if itemID != "" && event.OfConversationItemInputAudioTranscriptionFailedEvent.ItemID == itemID {
				return fmt.Errorf("transcription failed")
			}
		case "error":
			return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
		}
	}
}

Agregar contexto a la transcripción

Agrega contexto cuando el audio contenga vocabulario especializado o cuando esperes escuchar más de un idioma. Envía otro evento session.update para cambiar la configuración de transcripción durante una sesión en curso.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "gpt-live-transcribe",
          "prompt": "A customer support call about a premium plan and account AC-42.",
          "keywords": ["premium plan", "AC-42", "billing"],
          "languages": ["en", "fr"],
          "delay": "low"
        },
        "turn_detection": null
      }
    }
  }
}

• Usa prompt para describir la grabación o el contexto en que se realizó.
• Usa keywords para indicar nombres de productos, siglas y otros términos que puedan aparecer tal cual en el audio.
• Usa languages para indicar los idiomas que esperas recibir.

Puedes usar los siguientes formatos de códigos de idioma.

• Códigos ISO 639-1, como en, es y fr.
• Algunos códigos ISO 639-3, como eng, spa, yue y cmn.
• Códigos de configuración regional de zh, como zh-cn, zh-tw y zh-hk.

La Realtime API rechaza los códigos de idioma que no admite o que tienen un formato incorrecto.

Las palabras clave orientan al modelo, pero no tienen que aparecer en la transcripción. Escribe cada palabra clave en una sola línea y no incluyas <, >, retornos de carro ni saltos de línea. La Realtime API rechaza la actualización de la sesión si alguna palabra clave contiene uno de estos caracteres o si prompt supera el límite de longitud del modelo.

gpt-live-transcribe usa languages en lugar del campo en singular language. No envíes ambos campos.

Transcribir un turno confirmado

Usa gpt-transcribe en una sesión de Realtime solo si necesitas que la transcripción comience después de confirmar un turno de audio o que el resultado indique el idioma detectado. Este flujo de trabajo especializado requiere una conexión WebSocket.

Cuando gpt-transcribe transcribe el audio de entrada en una sesión de la Realtime API o se ejecuta en una sesión dedicada a la transcripción, usa automáticamente como contexto los turnos anteriores que ya se transcribieron.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "gpt-transcribe"
        },
        "turn_detection": null
      }
    }
  }
}

Agrega audio al búfer y envía input_audio_buffer.commit. A partir de ese momento, el modelo puede emitir fragmentos de la transcripción antes del evento de finalización. Ese evento también incluye los idiomas detectados.

1234567{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "item_003",
  "content_index": 0,
  "transcript": "Bonjour, pouvez-vous m'entendre ?",
  "languages": [{ "code": "fr" }]
}

Si gpt-transcribe no puede identificar el idioma con suficiente certeza, el valor de languages es un arreglo vacío. gpt-live-transcribe no devuelve predicciones sobre el idioma detectado.

Ajustar la latencia y la precisión

En la transcripción en tiempo real, el retardo influye tanto en la latencia como en la calidad de la transcripción. Con un retardo menor, el texto parcial puede aparecer antes. Un retardo mayor permite que el modelo reciba más audio como contexto antes de emitir texto y puede reducir la tasa de error por palabra.

Empieza por configurar audio.input.transcription.delay y haz pruebas con audio real de tu aplicación. Puedes usar estos valores como punto de partida.

• minimal para las interacciones más sensibles a la latencia.
• low para subtítulos en vivo de baja latencia.
• medium para equilibrar la latencia y la precisión.
• high cuando la precisión sea más importante que mostrar el texto de inmediato.
• xhigh cuando tu flujo de trabajo tolere el retardo máximo para que el modelo tenga más contexto.

El retardo exacto en milisegundos puede variar según la configuración del modelo. Mídelo con audio representativo en lugar de suponer que cada nivel tiene un retardo fijo.

Evita elegir un valor basándote únicamente en audio sintético. Haz pruebas con micrófonos representativos, audio de llamadas telefónicas, distintos acentos, ruido de fondo, alternancia de idiomas, vocabulario especializado y sesiones largas.

Manejar puntuaciones de confianza, marcas de tiempo y etiquetas de hablante

gpt-live-transcribe no devuelve marcas de tiempo por palabra, etiquetas de hablante ni puntuaciones de confianza de la transcripción. Si tu aplicación requiere marcas de tiempo o etiquetas de hablante, usa un modelo compatible de transcripción de archivos o implementa una alternativa en tu aplicación.

Lista de verificación para producción

• Define la latencia objetivo y el umbral de precisión antes de ajustar la configuración.
• Haz pruebas con audio real de producción, además de muestras sin ruido.
• Prueba cada idioma que quieras admitir.
• Incluye números, fechas, importes en distintas monedas, direcciones de correo electrónico, nombres de productos y términos especializados en tu conjunto de evaluación.
• Registra las transcripciones vacías, truncadas o tardías por separado de la tasa de error por palabra.
• Define cómo debe actualizar la interfaz el texto parcial cuando un fragmento posterior corrija texto anterior.
• Usa item_id para ordenar y conciliar las transcripciones finales.
• Ten una alternativa para los casos en que el modelo no admita marcas de tiempo, etiquetas de hablante o campos de confianza.

Guías relacionadas