Este tema describe los parámetros y los detalles de la interfaz del SDK de Java para reconocimiento de voz no en tiempo real de Paraformer.
Requisitos previos
Inicio rápido
La clase Core (Transcription) proporciona interfaces para enviar tareas de forma asíncrona, esperar sincrónicamente a que se completen las tareas y consultar resultados de tareas de forma asíncrona. Puede utilizar los siguientes dos métodos de llamada para el reconocimiento de voz no en tiempo real:
- Envío asíncrono + espera síncrona: Después de enviar una tarea, el hilo actual se bloquea hasta que la tarea finaliza y se obtiene el resultado de reconocimiento.
- Envío asíncrono + consulta asíncrona: Después de enviar una tarea, puede consultar el resultado de la tarea en cualquier momento llamando a la interfaz de consulta.
Envío asíncrono + espera síncrona
- Configure los Parámetros de solicitud.
- Instancie la Clase principal (Transcription).
-
Llame al método
asyncCallde la clase Core (Transcription) para enviar una tarea de forma asíncrona.- El servicio de transcripción de archivos procesa las tareas enviadas a través de la API sobre la base del mejor esfuerzo. Después del envío, una tarea entra en el estado de espera (
PENDING). El tiempo de espera depende de la longitud de la cola y la duración del archivo, y no se puede estimar con precisión, pero generalmente se completa en unos pocos minutos. Una vez que comienza el procesamiento, el reconocimiento de voz se completa a varios cientos de veces la velocidad en tiempo real. - Después de que cada tarea se completa, el resultado de reconocimiento y el enlace de descarga de la URL son válidos durante 24 horas. Después de la expiración, no puede consultar la tarea ni descargar resultados a través de la URL proporcionada anteriormente.
- El servicio de transcripción de archivos procesa las tareas enviadas a través de la API sobre la base del mejor esfuerzo. Después del envío, una tarea entra en el estado de espera (
-
Llame al método
waitde la clase Core (Transcription) para esperar sincrónicamente a que finalice la tarea. Los estados de la tarea incluyenPENDING,RUNNING,SUCCEEDEDyFAILED. Cuando la tarea está en estadoPENDINGoRUNNING, la interfazwaitse bloquea. Cuando la tarea está en estadoSUCCEEDEDoFAILED, la interfazwaitdeja de estar bloqueada y devuelve el resultado de la tarea.waitdevuelve el Resultado de la tarea (TranscriptionResult).
Haga clic para ver el ejemplo completo
Haga clic para ver el ejemplo completo
Envío asíncrono + consulta asíncrona
- Configure los Parámetros de solicitud.
- Instancie la Clase principal (Transcription).
-
Llame al método
asyncCallde la clase Core (Transcription) para enviar una tarea de forma asíncrona.- El servicio de transcripción de archivos procesa las tareas enviadas a través de la API sobre la base del mejor esfuerzo. Después del envío, una tarea entra en el estado de espera (
PENDING). El tiempo de espera depende de la longitud de la cola y la duración del archivo, y no se puede estimar con precisión, pero generalmente se completa en unos pocos minutos. Una vez que comienza el procesamiento, el reconocimiento de voz se completa a varios cientos de veces la velocidad en tiempo real. - Después de que cada tarea se completa, el resultado de reconocimiento y el enlace de descarga de la URL son válidos durante 24 horas. Después de la expiración, no puede consultar la tarea ni descargar resultados a través de la URL proporcionada anteriormente.
- El servicio de transcripción de archivos procesa las tareas enviadas a través de la API sobre la base del mejor esfuerzo. Después del envío, una tarea entra en el estado de espera (
-
Llame en bucle al método
fetchde la clase Core (Transcription) hasta obtener el resultado final de la tarea. Cuando el estado de la tarea seaSUCCEEDEDoFAILED, detenga el sondeo y procese el resultado.fetchdevuelve el Resultado de la tarea (TranscriptionResult).
Haga clic para ver el ejemplo completo
Haga clic para ver el ejemplo completo
Parámetros de solicitud
Los parámetros de solicitud se configuran mediante los métodos encadenados de TranscriptionParam.
Haga clic para ver el ejemplo
Haga clic para ver el ejemplo
| Parámetro | Tipo | Predeterminado | Obligatorio | Descripción |
|---|---|---|---|---|
| model | String | Sí | Especifica el nombre del modelo Paraformer para la transcripción de archivos de audio/video. Consulte Modelos admitidos. | |
| fileUrls | List<String> | Sí | La lista de URL de archivos de audio/video para transcripción. Admite protocolos HTTP/HTTPS. Solo se admite una URL por solicitud.Si los archivos de audio están almacenados en Alibaba Cloud OSS, el SDK no admite URL temporales con el prefijo oss://. | |
| vocabularyId | String | No | El ID de palabras clave más reciente. Admite los últimos modelos de la serie v2 con configuración de idioma. Las palabras clave asociadas con este ID surten efecto para este reconocimiento de voz. Deshabilitado por defecto. Para instrucciones de uso, consulte Palabras clave personalizadas. | |
| channelId | List<Integer> | [0] | No | Especifica los índices de pista de audio a reconocer en un archivo de audio multipista. Los índices comienzan desde 0. Por ejemplo, [0] significa reconocer la primera pista, y [0, 1] significa reconocer tanto la primera como la segunda pista simultáneamente. Si se omite este parámetro, solo se procesa la primera pista por defecto. |
| disfluencyRemovalEnabled | Boolean | false | No | Filtra palabras de relleno. Deshabilitado de forma predeterminada. |
| timestampAlignmentEnabled | Boolean | false | No | Indica si se debe habilitar la función de alineación de marcas de tiempo. Deshabilitada de forma predeterminada. |
| specialWordFilter | String | No | Especifica las palabras sensibles que se deben procesar durante el reconocimiento de voz y permite configurar diferentes métodos de procesamiento para distintas palabras sensibles.Si no se proporciona este parámetro, el sistema utiliza la lógica de filtrado de palabras sensibles incorporada, y las palabras que coincidan con la lista de palabras sensibles de Alibaba Cloud Model Studio en los resultados de reconocimiento se reemplazarán con * de igual longitud.Si se proporciona este parámetro, se pueden implementar las siguientes estrategias de procesamiento de palabras sensibles:
| |
| language_hints | String[] | ["zh", "en"] | No | Especifica los códigos de idioma del habla que se va a reconocer.Este parámetro solo es aplicable al modelo paraformer-v2.Códigos de idioma admitidos:
language_hints debe establecerse a través del método parameter o del método parameters de la instancia de TranscriptionParam: |
| diarizationEnabled | Boolean | false | No | Diarización automática de hablantes. Deshabilitada de forma predeterminada.Solo aplicable a audio mono. El audio multicanal no admite la diarización de hablantes.Cuando esta función está habilitada, los resultados de reconocimiento incluirán un campo speaker_id para distinguir a los diferentes hablantes.Si la diarización de hablantes está habilitada, se recomienda que la duración del audio no exceda 2 horas; de lo contrario, el reconocimiento podría fallar o agotar el tiempo de espera. speaker_id, consulte Descripción del resultado de reconocimiento. |
| speakerCount | Integer | No | Un valor de referencia para el número de hablantes. Valores válidos: enteros de 2 a 100 (inclusive).Surte efecto cuando la diarización de hablantes está habilitada (diarizationEnabled establecido en true).Por defecto, el sistema determina automáticamente el número de hablantes. Si este parámetro está configurado, solo sirve como sugerencia al algoritmo para intentar generar el número especificado de hablantes, pero no se garantiza la cantidad exacta. | |
| apiKey | String | No | La API Key. Si la API Key ya está configurada en una variable de entorno, no necesita establecerla en el código. De lo contrario, debe establecerla en el código. |
Respuesta
Resultado de la tarea (TranscriptionResult)
TranscriptionResult encapsula el resultado de la tarea actual.
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
| None | requestId | Obtiene el requestId. | |
| None | taskId | Obtiene el taskId. | |
| None | TaskStatus, el estado de la tarea | Obtiene el estado de la tarea.TaskStatus es una clase de enumeración. Solo necesita prestar atención a los siguientes cuatro estados: PENDING, RUNNING, SUCCEEDED y FAILED.Cuando una tarea contiene múltiples subtareas, siempre que cualquier subtarea tenga éxito, el estado general de la tarea se marca como SUCCEEDED. Necesita verificar el campo subtask_status para determinar el resultado de cada subtarea. | |
| None | Resultado de subtarea (TranscriptionTaskResult) | Obtiene el Resultado de subtarea (TranscriptionTaskResult).Cada tarea reconoce uno o más archivos de audio. Los diferentes archivos de audio se procesan en distintas subtareas, por lo que cada tarea corresponde a una o más subtareas. | |
| None | Resultado de la tarea en formato JSON | Obtiene el resultado de la tarea.El resultado está en formato JSON. Si utiliza la interfaz getOutput para obtener el resultado de la tarea, deberá analizarlo usted mismo.
Haga clic para ver el ejemplo JSON Ejemplo normal code" es el código de error y "message" es el mensaje de error. Estos dos campos solo aparecen en escenarios de error. Puede usarlos para solucionar problemas consultando Códigos de error. |
Resultado de subtarea (TranscriptionTaskResult)
TranscriptionTaskResult encapsula el resultado de la subtarea. Una subtarea reconoce un único archivo de audio.
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
| None | URL del archivo de audio reconocido | Obtiene la URL del archivo de audio reconocido. | |
| None | URL del resultado de reconocimiento | Obtiene la URL del resultado de reconocimiento. Esta URL es válida durante 24 horas. Después de la expiración, no puede consultar la tarea ni descargar resultados a través de la URL proporcionada anteriormente.El resultado de reconocimiento se guarda como un archivo JSON. Puede descargar el archivo a través de la URL anterior o leer directamente su contenido mediante una solicitud HTTP.Para conocer el significado de cada campo en los datos JSON, consulte Descripción del resultado de reconocimiento. | |
| None | TaskStatus, el estado de la subtarea | Obtiene el estado de la subtarea.TaskStatus es una clase de enumeración. Solo necesita prestar atención a los siguientes cuatro estados: PENDING, RUNNING, SUCCEEDED y FAILED. | |
| None | Información clave durante la ejecución de la tarea, que puede estar vacía | Obtiene información clave durante la ejecución de la tarea.Cuando una tarea falla, puede revisar este contenido para analizar la causa. |
Descripción del resultado de reconocimiento
El resultado del reconocimiento se guarda como un archivo JSON.
Haga clic para ver el ejemplo de resultado de reconocimiento
Haga clic para ver el ejemplo de resultado de reconocimiento
Parámetro | Tipo | Descripción |
|---|---|---|
audio_format | string | El formato de audio del archivo fuente. |
channels | array[integer] | La información del índice de pistas de audio del archivo fuente. Devuelve [0] para audio mono, [0, 1] para audio de doble pista, y así sucesivamente. |
original_sampling_rate | integer | La frecuencia de muestreo (Hz) del audio en el archivo fuente. |
original_duration | integer | La duración original del audio (ms) del archivo fuente. |
channel_id | integer | El índice de la pista de audio del resultado de transcripción, comenzando desde 0. |
content_duration | integer | La duración (ms) del contenido identificado como habla en la pista de audio. El servicio de modelo de reconocimiento de voz Paraformer solo transcribe y mide el contenido identificado como voz en la pista de audio, y factura en consecuencia. El contenido que no es voz no se mide ni se factura. Normalmente, la duración del contenido de voz es menor que la duración del audio original. Dado que la determinación de si existe contenido de voz la realiza un modelo de IA, puede haber alguna desviación respecto a la situación real. |
transcript | string | El resultado de la transcripción de voz a nivel de párrafo. |
sentences | array | El resultado de la transcripción de voz a nivel de oración. |
words | array | El resultado de la transcripción de voz a nivel de palabra. |
begin_time | integer | La marca de tiempo de inicio (ms). |
end_time | integer | La marca de tiempo de finalización (ms). |
text | string | El resultado de la transcripción de voz. |
speaker_id | integer | El índice del hablante actual, comenzando desde 0, utilizado para distinguir a los diferentes hablantes. Este campo solo se muestra en los resultados de reconocimiento cuando la diarización de hablantes está habilitada. |
punctuation | string | La puntuación predicha después de la palabra (si la hay). |
Interfaces clave
Clase de parámetros de consulta de tarea (TranscriptionQueryParam)
TranscriptionQueryParam se utiliza al esperar a que se complete una tarea (llamando al método Transcription wait) o al consultar el resultado de la tarea (llamando al método Transcription fetch).
Cree una instancia de TranscriptionQueryParam mediante el método estático FromTranscriptionParam.
Haga clic para ver el ejemplo
Haga clic para ver el ejemplo
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
| Una instancia de TranscriptionQueryParam | Crea una instancia de TranscriptionQueryParam. |
Clase principal (Transcription)
Transcription se puede importar con "import com.alibaba.dashscope.audio.asr.transcription.*;". Sus interfaces clave son las siguientes:
| Interfaz/Método | Parámetro | Valor de retorno | Descripción |
|---|---|---|---|
param: Parámetros de reconocimiento de voz, una instancia de TranscriptionParam | Resultado de la tarea (TranscriptionResult) | Envía una tarea de reconocimiento de voz de forma asíncrona. | |
queryParam: Una instancia de TranscriptionQueryParam | Resultado de la tarea (TranscriptionResult) | Bloquea el hilo actual hasta que finaliza la tarea asíncrona (el estado de la tarea es SUCCEEDED o FAILED). | |
queryParam: Una instancia de TranscriptionQueryParam | Resultado de la tarea (TranscriptionResult) | Consulta de forma asíncrona el resultado de la tarea actual. |
Otras interfaces: Consulta por lotes del estado de tareas / Cancelar tarea
Para más detalles, consulte Gestionar tareas asíncronas: Admite la consulta por lotes de tareas de reconocimiento de voz no en tiempo real enviadas en las últimas 24 horas, y también admite cancelar tareas en estado PENDING (en cola).
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 para reportar el incidente y proporcione el Request ID para una investigación adicional.
Cuando una tarea contiene múltiples subtareas, siempre que cualquier subtarea tenga éxito, el estado general de la tarea se marca como SUCCEEDED. Necesita verificar el campo subtask_status para determinar el resultado de cada subtarea.
Ejemplo de respuesta de error:
Más ejemplos
Para más ejemplos, consulte GitHub.
FAQ
Preguntas sobre funciones
P: ¿Admite audio codificado en Base64?
No. No se admite audio codificado en Base64. Solo se admite audio accesible a través de URLs de acceso público. No se admiten flujos binarios ni el reconocimiento directo de archivos locales.
P: ¿Cómo proporcionar archivos de audio como URL de acceso público?
Generalmente, siga estos pasos (esto proporciona un enfoque general; los detalles varían según el producto de almacenamiento. Recomendamos cargar el audio en Alibaba Cloud OSS):
1. Elegir un método de almacenamiento y alojamiento
1. Elegir un método de almacenamiento y alojamiento
-
Object Storage Service (recomendado):
- Utilice un servicio de almacenamiento de objetos de un proveedor de nube (como Alibaba Cloud OSS) para cargar archivos de audio en un bucket y configurarlos para acceso público.
- Ventajas: Alta disponibilidad, soporte de aceleración CDN, gestión sencilla.
-
Servidor web:
- Coloque archivos de audio en un servidor web que admita acceso HTTP/HTTPS (como Nginx o Apache).
- Ventajas: Adecuado para proyectos pequeños o pruebas locales.
-
Content Delivery Network (CDN):
- Aloje archivos de audio en una CDN y acceda a ellos a través de la URL proporcionada por la CDN.
- Ventajas: Entrega acelerada de archivos, adecuada para escenarios de alta concurrencia.
2. Cargar archivos de audio
2. Cargar archivos de audio
-
Object Storage Service:
- Inicie sesión en la consola del proveedor de servicios en la nube y cree un bucket.
- Cargue archivos de audio y configure los permisos del archivo como "lectura pública" o genere enlaces de acceso temporal.
-
Servidor web:
- Coloque los archivos de audio en el directorio designado del servidor (como
/var/www/html/audio/). - Asegúrese de que los archivos sean accesibles mediante HTTP/HTTPS.
- Coloque los archivos de audio en el directorio designado del servidor (como
3. Generar una URL de acceso público
3. Generar una URL de acceso público
-
Object Storage Service:
- Después de la carga, el sistema genera automáticamente una URL de acceso público (generalmente en el formato
https://<bucket-name>.<region>.aliyuncs.com/<file-name>). - Si necesita un dominio más amigable, puede vincular un dominio personalizado y habilitar HTTPS.
- Después de la carga, el sistema genera automáticamente una URL de acceso público (generalmente en el formato
-
Servidor web:
- La URL de acceso al archivo suele ser la dirección del servidor más la ruta del archivo (como
https://your-domain.com/audio/file.mp3).
- La URL de acceso al archivo suele ser la dirección del servidor más la ruta del archivo (como
-
CDN:
- Después de configurar la aceleración CDN, utilice la URL proporcionada por la CDN (como
https://cdn.your-domain.com/audio/file.mp3).
- Después de configurar la aceleración CDN, utilice la URL proporcionada por la CDN (como
4. Verificar la accesibilidad de la URL
4. Verificar la accesibilidad de la URL
- Abra la URL en un navegador y verifique si el archivo de audio se puede reproducir.
- Utilice herramientas (como
curlo Postman) para verificar si la URL devuelve una respuesta HTTP correcta (código de estado 200).
oss://.
Al utilizar la API RESTful, si los archivos de audio están almacenados en Alibaba Cloud OSS, se admiten URLs temporales con el prefijo oss://:
- La URL temporal es válida durante 48 horas y no se puede utilizar después de su caducidad. No la utilice en un entorno de producción.
- La API para obtener una credencial de carga está limitada a 100 QPS y no admite escalado horizontal. No la utilice en entornos de producción, escenarios de alta concurrencia o escenarios de pruebas de estrés.
- Para entornos de producción, utilice un servicio de almacenamiento estable como OSS para garantizar la disponibilidad de archivos a largo plazo y evitar problemas de limitación de tasa.
P: ¿Cuánto tiempo toma obtener los resultados de reconocimiento?
Después del envío, la tarea entra en un estado de espera (PENDING). El tiempo de espera depende de la longitud de la cola y la duración del archivo, y no se puede estimar con precisión, pero generalmente se completa en unos pocos minutos. Por favor, espere pacientemente. Los archivos de audio más largos requieren más tiempo de procesamiento.
Solución de problemas
Si encuentra errores de código, resuelva el problema basándose en la información de Códigos de error.
P: ¿Qué hacer si el resultado de reconocimiento y la reproducción de audio no están sincronizados?
Establezca los Parámetros de solicitud timestampAlignmentEnabled en true para habilitar la función de alineación de marcas de tiempo, que sincroniza el resultado de reconocimiento con la reproducción de audio.
P: ¿No se pueden obtener resultados tras realizar sondeos continuos?
Esto puede deberse a limitaciones de tasa. Por favor, espere pacientemente. Si necesita ampliación de capacidad, únase a la comunidad de desarrolladores para solicitarla.
P: ¿Por qué no hay resultado de reconocimiento (incapaz de reconocer el habla)?
- Verifique si el audio cumple con los requisitos (formato, tasa de muestreo).
- Si está utilizando el modelo
paraformer-v2, verifique si la configuración delanguage_hintses correcta. - Si none de lo anterior resuelve el problema, puede personalizar palabras clave para mejorar el reconocimiento de términos específicos.