Este tema describe los parámetros e interfaces del SDK de Java para el reconocimiento de voz en tiempo real de Qwen-Audio-ASR-Streaming.
Requisitos previos
- El servicio está activado y Obtenga una clave API. Para protegerse contra riesgos de seguridad causados por fugas de código, Configure la clave API como una variable de entorno, en lugar de codificarla directamente en su código.
- Instale el SDK de DashScope más reciente.
Inicio rápido
La clase Recognition proporciona interfaces tanto para llamadas síncronas como para llamadas de streaming bidireccionales. Elija el enfoque que mejor se adapte a sus necesidades:
- Llamada síncrona: reconoce un archivo local y devuelve el resultado completo de una vez. Ideal para procesar audio pregrabado.
- Llamada de transmisión bidireccional: reconoce un flujo de audio directamente y devuelve resultados en tiempo real. El flujo de audio puede provenir de un dispositivo externo, como un micrófono, o leerse desde un archivo local. Ideal para escenarios que requieren retroalimentación inmediata.
- Llamada síncrona
- Llamada de transmisión bidireccional: basada en callbacks
- Llamada de transmisión bidireccional: basada en Flowable
Envíe una única tarea de reconocimiento de voz en tiempo real y obtenga el resultado del reconocimiento de forma síncrona pasando un archivo local. La llamada se bloquea hasta que se devuelve el resultado.Instancie la clase Recognition y llame al método
call para vincular los Parámetros de solicitud y el archivo a reconocer. El método realiza el reconocimiento y devuelve el resultado final.Llamadas de alta concurrencia
El SDK de Java de DashScope utiliza el agrupamiento de conexiones de OkHttp3 para reducir la sobrecarga de establecer conexiones repetidamente. Para más detalles, consulte Mejores prácticas de alta concurrencia.
Parámetros de solicitud
Utilice los métodos encadenados de RecognitionParam para configurar el modelo, la frecuencia de muestreo, el formato de audio y otros parámetros. Pase el objeto de parámetros configurado al método call/streamCall de la clase Recognition.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
model | String | Sí | El nombre del modelo. |
sampleRate | Integer | Sí | La frecuencia de muestreo en Hz. Se admite cualquier frecuencia de muestreo. |
format | String | Sí | El formato de audio.Valores válidos:
|
keep_dialect | boolean | No | Admitido solo por qwen-audio-3.1-asr-flash-streaming. El valor predeterminado es false, que transcribe dialectos al chino estándar. Establezca en true para conservar las expresiones dialectales. Configure con .parameter("keep_dialect", value). Consulte Eventos del cliente para obtener más detalles. |
vad_model | String | No | Admitido solo por qwen-audio-3.1-asr-flash-streaming. Establezca en near_meeting_16k (campo cercano) o far_field_meeting_16k (campo lejano, predeterminado). Configure con .parameter("vad_model", value). Consulte Eventos del cliente para obtener más detalles. |
vocabularyId | String | No | El ID de una lista de palabras calientes precompilada.Genere este ID con antelación llamando a la API de creación de lista de palabras clave. Pase el ID durante el reconocimiento para usar las palabras clave de la lista.Adecuado para escenarios donde el vocabulario es conocido y relativamente estable, y donde necesita reutilizar la misma lista de palabras en distintas solicitudes.Para obtener detalles sobre el uso, consulte Palabras clave precompiladas. |
vocabulary | Map<String, Integer> | No | Palabras clave instantáneas.Se pasan como pares clave-valor, donde la clave es el texto de la palabra clave (string) y el valor es el peso de la palabra clave (integer). No es necesario crear una lista de palabras clave con antelación. El peso oscila entre [1, 5] o se establece en 50: un valor en [1, 5] hace que el modelo tenga más probabilidades de generar la palabra a medida que aumenta el valor; un valor de 50 designa una súper palabra clave, lo que mejora enormemente la recuperación, pero el número de súper palabras clave no puede exceder 50.Adecuado para la optimización temporal de palabras clave a nivel de sesión.Cuando las palabras clave instantáneas y precompiladas se configuran juntas, el sistema fusiona ambos conjuntos. Si el conjunto fusionado contiene más de 2000 palabras clave, el sistema selecciona aleatoriamente 2000 para usar. Para detalles de uso, consulte Palabras clave instantáneas.Configure vocabulary mediante el método parameter o el método parameters de la instancia RecognitionParam: |
max_sentence_silence | Integer | No | El umbral de silencio del VAD para la segmentación, en ms. Cuando el silencio posterior a un segmento de voz supera este umbral, el sistema determina que la oración ha finalizado.Valor predeterminado: 800.Valores válidos: [200, 6000].Configure max_sentence_silence mediante el método parameter o el método parameters de la instancia RecognitionParam: |
multi_threshold_mode_enabled | boolean | No | Si se debe habilitar el modo de umbral múltiple. Cuando está habilitado, esto evita que los segmentos VAD sean demasiado largos.Valor predeterminado: false.Configure multi_threshold_mode_enabled mediante el método parameter o el método parameters de la instancia RecognitionParam: |
punctuation_prediction_enabled | boolean | No | Define si se agrega puntuación automáticamente a los resultados del reconocimiento:
punctuation_prediction_enabled mediante el método parameter o el método parameters de la instancia RecognitionParam: |
heartbeat | boolean | No | Si se habilitan los paquetes de latido.Valor predeterminado: false.
Para usar este campo, la versión del SDK debe ser 2.19.1 o posterior. heartbeat mediante el método parameter o el método parameters de la instancia RecognitionParam: |
language_hints | String[] | No | El idioma del audio a reconocer. No hay valor predeterminado; si no se establece, el modelo detecta el idioma automáticamente.Puede configurar hasta 4 valores. Si configura más, solo los primeros 4 surten efecto.
Haga clic para ver los códigos de idioma admitidos
language_hints mediante el método parameter o el método parameters de la instancia RecognitionParam: |
speech_noise_threshold | float | No | El umbral para distinguir el habla del ruido, utilizado para ajustar la sensibilidad de la Detección de Actividad de Voz (VAD).Valores válidos: [-1.0, 1.0].Descripciones de valores:
speech_noise_threshold mediante el método parameter o el método parameters de la instancia RecognitionParam: |
special_word_filter | String | No | Especifica las palabras sensibles que se deben procesar durante el reconocimiento de voz y permite configurar diferentes métodos de procesamiento para cada una. Para más detalles, consulte Filtrado de palabras sensibles.Configure special_word_filter mediante el método parameter o el método parameters de la instancia RecognitionParam: |
input | Map<String, Object> | No | Objeto de entrada que pasa el contexto de la conversación. El contexto ayuda al reconocimiento y mejora la precisión de términos específicos. Para su uso, consulte Inicio rápido.El Map debe contener una clave context cuyo valor sea una matriz de mensajes de tipo List<Map<String, Object>>. Cada mensaje contiene los siguientes campos:
Para usar este campo, la versión del SDK debe ser 2.22.23 o posterior. input mediante el método input de la instancia RecognitionParam: |
apiKey | String | No | Su clave API. |
Interfaces clave
La clase Recognition
Importe Recognition con import com.alibaba.dashscope.audio.asr.recognition.Recognition;. Sus interfaces principales son las siguientes:
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
| None | Reconocimiento en tiempo real por streaming basado en callbacks. Este método no bloquea el hilo actual. | |
| El resultado del reconocimiento. | Reconocimiento no streaming de un archivo local. Este método bloquea el hilo actual hasta que se lee todo el archivo de audio. El archivo debe ser legible. | |
| Flowable<RecognitionResult> | Reconocimiento en tiempo real por streaming basado en Flowable. | |
| None | Envía audio. Mantenga cada fragmento de audio enviado dentro de un tamaño razonable. Se recomienda que un fragmento contenga aproximadamente 100 ms de audio y tenga un tamaño de 1 KB a 16 KB.Los resultados del reconocimiento se entregan a través del método onEvent de la interfaz de callback (ResultCallback). | |
None | None | Detiene el reconocimiento en tiempo real.Este método bloquea el hilo actual hasta que se llama a onComplete o onError del callback ResultCallback. | |
| code: El código de cierre de WebSocket.reason: El motivo del cierre.Para obtener orientación sobre cómo configurar estos dos parámetros, consulte El protocolo WebSocket. | true | Después de que finalice una tarea, cierre siempre la conexión WebSocket, haya ocurrido o no una excepción, para evitar fugas de conexiones. Para reutilizar conexiones y mejorar la eficiencia, consulte Mejores prácticas de alta concurrencia. | |
None | requestId | Obtiene el requestId de la tarea actual. Disponible después de que se inicia una nueva tarea con call o streamingCall.Este método está disponible solo en la versión 2.18.0 del SDK y posteriores. | |
None | La latencia del primer paquete. | Obtiene la latencia del primer paquete, es decir, el retraso desde el envío del primer paquete de audio hasta la recepción del primer resultado de reconocimiento. Úselo después de que se complete la tarea. Este método está disponible solo en la versión 2.18.0 del SDK y posteriores. | |
None | La latencia del último paquete. | Obtiene la latencia del último paquete, es decir, el tiempo transcurrido desde el envío del comando stop hasta la recepción del resultado final del reconocimiento. Úselo después de que se complete la tarea.Este método está disponible solo en la versión 2.18.0 del SDK y posteriores. |
La interfaz de callback (ResultCallback)
Durante las llamadas de streaming bidireccionales, el servidor devuelve información clave del proceso y datos al cliente a través de callbacks. Implemente los métodos de callback para manejar la información o los datos devueltos por el servidor.
Implemente los métodos de callback extendiendo la clase abstracta ResultCallback. Cuando extienda esta clase, puede establecer el tipo genérico en RecognitionResult. RecognitionResult encapsula la estructura de datos devuelta por el servidor.
Dado que Java admite la reutilización de conexiones, no hay onClose ni onOpen.
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
result: Resultado de reconocimiento en tiempo real (RecognitionResult) | None | Se llama cuando el servidor envía una respuesta. | |
None | None | Se llama después de que se completa la tarea. | |
e: La información de la excepción. | None | Se llama cuando ocurre una excepción. |
Respuesta
Resultado de reconocimiento en tiempo real (RecognitionResult)
RecognitionResult representa el resultado de un único reconocimiento en tiempo real.
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
None | requestId | Obtiene el requestId. | |
None | Si se ha formado una oración completa, es decir, si se detectó un límite de oración. | Determina si la oración dada ha terminado. | |
None | Información de la oración (Sentence) | Obtiene la información de la oración, incluidas las marcas de tiempo y el texto. |
Información de la oración (Sentence)
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
None | La hora de inicio de la oración, en ms. | Devuelve la hora de inicio de la oración. | |
None | La hora de finalización de la oración, en ms. | Devuelve la hora de finalización de la oración. | |
None | El texto reconocido. | Devuelve el texto reconocido. | |
None | Una lista de objetos de Información de marcas de tiempo a nivel de palabra (Word). | Devuelve información de marcas de tiempo a nivel de palabra. |
Información de marcas de tiempo a nivel de palabra (Word)
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
None | El tiempo de inicio de la palabra, en ms. | Devuelve el tiempo de inicio de la palabra. | |
None | El tiempo de finalización de la palabra, en ms. | Devuelve el tiempo de finalización de la palabra. | |
None | La palabra. | Devuelve la palabra reconocida. | |
None | La puntuación. | Devuelve la puntuación. |
Códigos de error
Si encuentra errores, consulte Códigos de error para solucionar problemas.
Si el problema persiste, únase a la comunidad de desarrolladores que aparece en el repositorio de muestras del SDK de voz para informar su problema y proporcionar el ID de solicitud para una investigación más detallada.
FAQ
Funcionalidades
P: ¿Cómo mantengo activa la conexión con el servidor durante largos períodos de silencio?
Establezca el parámetro de solicitud heartbeat en true y continúe enviando audio silencioso al servidor.
El audio silencioso es aquel que no contiene señal de sonido en el archivo o flujo de datos. Puede generar audio silencioso de varias maneras, por ejemplo, utilizando software de edición de audio como Audacity o Adobe Audition, o una herramienta de línea de comandos como FFmpeg.
P: ¿Cómo convierto el audio a un formato compatible?
Utilice la herramienta FFmpeg. Para más información sobre su uso, consulte el sitio web oficial de FFmpeg.
P: ¿Cómo reconozco un archivo local (una grabación)?
Hay dos formas de reconocer un archivo local:
-
Pase la ruta del archivo local directamente: este enfoque devuelve el resultado completo del reconocimiento solo después de que finaliza el reconocimiento, por lo que no es adecuado para escenarios que necesitan retroalimentación inmediata.
Consulte Llamada síncrona y pase la ruta del archivo al método
callde la clase Recognition para reconocer la grabación directamente. -
Convierta el archivo local en un flujo binario para el reconocimiento: este enfoque reconoce el archivo y transmite los resultados al mismo tiempo, lo cual es adecuado para escenarios que requieren retroalimentación inmediata.
- Consulte Llamada de streaming bidireccional: basada en callbacks, y envíe el flujo binario al servidor para su reconocimiento mediante el método
sendAudioFramede la clase Recognition. - Consulte Llamada de streaming bidireccional: basada en Flowable, y envíe el flujo binario al servidor para su reconocimiento mediante el método
streamCallde la clase Recognition.
- Consulte Llamada de streaming bidireccional: basada en callbacks, y envíe el flujo binario al servidor para su reconocimiento mediante el método
Solución de problemas
P: ¿Por qué no se puede reconocer el habla (sin resultado de reconocimiento)?
-
Verifique que el formato de audio (
format) y la frecuencia de muestreo (sampleRate/sample_rate) en los parámetros de solicitud sean correctos y cumplan con las restricciones de parámetros. Los errores comunes incluyen:- El archivo de audio tiene extensión .wav pero en realidad está en formato MP3, mientras que el parámetro de solicitud
formatestá configurado en mp3 (configuración de parámetro incorrecta). - La frecuencia de muestreo del audio es de 3600 Hz, pero el parámetro de solicitud
sampleRate/sample_rateestá configurado en 48000 (configuración de parámetro incorrecta).
- El archivo de audio tiene extensión .wav pero en realidad está en formato MP3, mientras que el parámetro de solicitud
-
Verifique que el idioma configurado en
language_hintscoincida con el idioma real del audio. Por ejemplo, el audio está realmente en chino, perolanguage_hintsestá configurado comoen(inglés). - Si none de las verificaciones anteriores revela un problema, configure palabras clave personalizadas para mejorar el reconocimiento de términos específicos.