Gummy实时语音识别、翻译Python SDK_大模型服务平台百炼(Model Studio)-阿里云帮助中心

本文介绍Gummy实时语音识别和翻译Python SDK的参数和接口细节。

用户指南：关于模型介绍和选型建议请参见实时语音识别和实时语音翻译。

在线体验：模型体验

前提条件

已开通服务并获得API-KEY：获取API Key。建议您配置API Key到环境变量，从而避免在代码里显示配置API Key，降低泄漏风险。
已安装最新版DashScope SDK：安装SDK。

模型列表

模型名

模型简介

gummy-realtime-v1

Gummy实时语音识别、翻译模型。默认进行标点符号预测和逆文本正则化（INT，Inverse Text Normalization）。支持定制热词。

模型使用VAD（Voice Activity Detection）断句。

快速开始

TranslationRecognizerRealtime类提供了语音识别/翻译的关键接口，支持以下几种调用方式：

流式调用：可直接对音频流进行识别或翻译，并实时输出结果。音频流可以来自外部设备（如麦克风）或从本地文件读取。适合需要即时反馈的场景。
同步调用：针对本地文件进行识别或翻译，并一次性返回完整的处理结果。适合处理录制好的音频。

流式调用

通过实现回调接口，实时流式输出识别结果。

启动流式语音识别/翻译
实例化TranslationRecognizerRealtime类绑定请求参数和回调接口（TranslationRecognizerCallback），调用start方法启动流式语音识别/翻译。
流式传输
循环调用TranslationRecognizerRealtime类的send_audio_frame方法，将从本地文件或设备（如麦克风）读取的二进制音频流分段发送至服务端。
在发送音频数据的过程中，服务端会通过回调接口（TranslationRecognizerCallback）的on_event方法，将识别结果实时返回给客户端。
建议每次发送的音频时长约为100毫秒，数据大小保持在1KB至16KB之间。
结束处理
调用TranslationRecognizerRealtime类的stop方法结束语音识别/翻译。
该方法会阻塞当前线程，直到回调接口（TranslationRecognizerCallback）的on_complete或者on_error回调触发后才会释放线程阻塞。

点击查看完整示例

识别传入麦克风的语音

import pyaudio
import dashscope
from dashscope.audio.asr import *


# 若没有将API Key配置到环境变量中，需将your-api-key替换为自己的API Key
# dashscope.api_key = "your-api-key"

mic = None
stream = None

class Callback(TranslationRecognizerCallback):
    def on_open(self) -> None:
        global mic
        global stream
        print("TranslationRecognizerCallback open.")
        mic = pyaudio.PyAudio()
        stream = mic.open(
            format=pyaudio.paInt16, channels=1, rate=16000, input=True
        )

    def on_close(self) -> None:
        global mic
        global stream
        print("TranslationRecognizerCallback close.")
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

    def on_event(
        self,
        request_id,
        transcription_result: TranscriptionResult,
        translation_result: TranslationResult,
        usage,
    ) -> None:
        print("request id: ", request_id)
        print("usage: ", usage)
        if translation_result is not None:
            print(
                "translation_languages: ",
                translation_result.get_language_list(),
            )
            english_translation = translation_result.get_translation("en")
            print("sentence id: ", english_translation.sentence_id)
            print("translate to english: ", english_translation.text)
        if transcription_result is not None:
            print("sentence id: ", transcription_result.sentence_id)
            print("transcription: ", transcription_result.text)


callback = Callback()


translator = TranslationRecognizerRealtime(
    model="gummy-realtime-v1",
    format="pcm",
    sample_rate=16000,
    transcription_enabled=True,
    translation_enabled=True,
    translation_target_languages=["en"],
    callback=callback,
)
translator.start()
print("请您通过麦克风讲话体验实时语音识别和翻译功能")
while True:
    if stream:
        data = stream.read(3200, exception_on_overflow=False)
        translator.send_audio_frame(data)
    else:
        break

translator.stop()

识别本地语音文件

import os
import requests
from http import HTTPStatus

import dashscope
from dashscope.audio.asr import *

# 若没有将API Key配置到环境变量中，需将your-api-key替换为自己的API Key
# dashscope.api_key = "your-api-key"

r = requests.get(
    "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
)
with open("asr_example.wav", "wb") as f:
    f.write(r.content)


class Callback(TranslationRecognizerCallback):
    def on_open(self) -> None:
        print("TranslationRecognizerCallback open.")

    def on_close(self) -> None:
        print("TranslationRecognizerCallback close.")

    def on_event(
        self,
        request_id,
        transcription_result: TranscriptionResult,
        translation_result: TranslationResult,
        usage,
    ) -> None:
        print("request id: ", request_id)
        print("usage: ", usage)
        if translation_result is not None:
            print(
                "translation_languages: ",
                translation_result.get_language_list(),
            )
            english_translation = translation_result.get_translation("en")
            print("sentence id: ", english_translation.sentence_id)
            print("translate to english: ", english_translation.text)
        if transcription_result is not None:
            print("sentence id: ", transcription_result.sentence_id)
            print("transcription: ", transcription_result.text)
    
    def on_error(self, message) -> None:
        print('error: {}'.format(message))
    
    def on_complete(self) -> None:
        print('TranslationRecognizerCallback complete')


callback = Callback()


translator = TranslationRecognizerRealtime(
    model="gummy-realtime-v1",
    format="wav",
    sample_rate=16000,
    callback=callback,
)

translator.start()

try:
    audio_data: bytes = None
    f = open("asr_example.wav", 'rb')
    if os.path.getsize("asr_example.wav"):
        while True:
            audio_data = f.read(12800)
            if not audio_data:
                break
            else:
                translator.send_audio_frame(audio_data)
    else:
        raise Exception(
            'The supplied file was empty (zero bytes long)')
    f.close()
except Exception as e:
    raise e

translator.stop()

同步调用

通过传入本地文件路径，以同步阻塞方式获取识别或翻译结果。

实例化TranslationRecognizerRealtime类绑定请求参数，调用call进行识别/翻译并最终获取同步调用结果（TranslationRecognizerResultPack）。

点击查看完整示例

import requests
from http import HTTPStatus

import dashscope
from dashscope.audio.asr import *

# 若没有将API Key配置到环境变量中，需将your-api-key替换为自己的API Key
# dashscope.api_key = "your-api-key"

r = requests.get(
    "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
)
with open("asr_example.wav", "wb") as f:
    f.write(r.content)

translator = TranslationRecognizerRealtime(
    model="gummy-realtime-v1",
    format="wav",
    sample_rate=16000,
    translation_target_languages=["en"],
    translation_enabled=True,
    callback=None,
)
result = translator.call("asr_example.wav")
if not result.error_message:
    print("request id: ", result.request_id)
    print("transcription: ")
    for transcription_result in result.transcription_result_list:
        print(transcription_result.text)
    print("translation[en]: ")

    for translation_result in result.translation_result_list:
        print(translation_result.get_translation('en').text)
else:
    print("Error: ", result.error_message)

请求参数

语音识别需要设置模型、采样率、音频格式等参数，这些参数通过TranslationRecognizerRealtime类的构造方法（_init_）进行设置。

参数	类型	默认值	是否必须	说明
model	str	-	是	指定实时语音识别的模型。如需了解当前支持的模型，请参见模型列表。
sample_rate	int	-	是	设置待识别音频采样率（单位Hz）。支持16000Hz及以上采样率。
format	str	-	是	设置待识别音频格式。支持的音频格式：pcm、wav、mp3、opus、speex、aac、amr。重要 opus/speex：必须使用Ogg封装； wav：必须为PCM编码； amr：仅支持AMR-NB类型。
vocabulary_id	str	-	否	设置热词ID，若未设置则不生效。在本次语音识别中，将应用与该热词ID对应的热词信息。具体使用方法请参见定制热词。
source_language	str	auto	否	设置源语言（待识别/翻译语言）代码。如果无法提前确定语种，可不设置，默认为`auto`。目前支持的语言代码： zh: 中文 en: 英文 ja: 日语 yue: 粤语 ko: 韩语 de: 德语 fr: 法语 ru: 俄语 it: 意大利语 es: 西班牙语
transcription_enabled	bool	True	否	设置是否启用识别功能。模型支持单独开启识别或翻译功能，也可同时启用两种功能，但至少需要开启其中一种能力。
translation_enabled	bool	False	否	设置是否启用翻译功能。要正常输出翻译结果，需配置`translation_target_languages`参数。模型支持单独开启识别或翻译功能，也可同时启用两种功能，但至少需要开启其中一种能力。
translation_target_languages	list[str]	-	否	设置翻译目标语言代码。目标语言的代码与`source_language`参数一致。目前支持的翻译包括：中->英，中->日，中->韩，英->中，英->日，英->韩，（日、韩、粤、德、法、俄、意、西）->（中、英）。重要目前暂不支持同时翻译为多种语言，请仅设置一个目标语言以完成翻译。
max_end_silence	int	800	否	设置VAD（Voice Activity Detection，语音活动检测）断句的静音时长阈值（单位为ms）。当一段语音后的静音时长超过该阈值时，系统会判定该句子已结束。参数范围为200ms至6000ms，默认值为800ms。

关键接口

`TranslationRecognizerRealtime`类

TranslationRecognizerRealtime通过“from dashscope.audio.asr import *”方式引入，提供语音识别/翻译的关键接口。

成员方法	方法签名	说明
start	`def start(self)`	启动流式语音识别/翻译。 `start`、`send_audio_frame`和`stop`方法在流式语音识别/翻译时配合使用。适合需要即时反馈的场景。详细的调用流程和参考示例请参见流式调用。
send_audio_frame	`def send_audio_frame(self, buffer: bytes)`	推送音频，每次推送的音频流不宜过大或过小，建议每包音频时长为100ms左右，大小在1KB~16KB之间。识别/翻译结果通过回调接口（TranslationRecognizerCallback）的`on_event`方法实时获取。 `start`、`send_audio_frame`和`stop`方法在流式语音识别/翻译时配合使用。适合需要即时反馈的场景。详细的调用流程和参考示例请参见流式调用。
stop	`def stop(self)`	结束流式语音识别/翻译。该方法会阻塞当前线程，直至回调接口（TranslationRecognizerCallback）的`on_complete`或者`on_error`方法被调用后，才会解除对当前线程的阻塞。 `start`、`send_audio_frame`和`stop`方法在流式语音识别/翻译时配合使用。适合需要即时反馈的场景。详细的调用流程和参考示例请参见流式调用。
call	`def call(self, file: str, phrase_id: str = None, **kwargs) -> TranslationRecognizerResultPack`	基于本地文件的同步调用，该方法最终返回同步调用结果（TranslationRecognizerResultPack）。要求待识别文件具有可读权限。适合处理录制好的音频。详细的调用流程和参考示例请参见同步调用。

回调接口（`TranslationRecognizerCallback`）

TranslationRecognizerCallback通过“from dashscope.audio.asr import *”方式引入。

使用流式调用模式时，服务端会通过回调的方式，将关键流程信息和数据返回给客户端。您需要实现回调方法，处理服务端返回的信息或者数据。

点击查看示例

class Callback(TranslationRecognizerCallback):
    def on_open(self) -> None:
        print('连接成功')

    def on_event(self, request_id, transcription_result: TranscriptionResult, translation_result: TranslationResult, usage) -> None:
        #实现接收识别结果的逻辑

    def on_complete(self) -> None:
        print('识别完成')

    def on_error(self, result: RecognitionResult) -> None:
        print('出现异常')

    def on_close(self) -> None:
        print('连接关闭')


callback = Callback()

方法	参数	返回值	描述
`def on_open(self) -> None`	无	无	当和服务端建立连接完成后，该方法立刻被回调。
`def on_event( self, request_id, transcription_result: TranscriptionResult, translation_result: TranslationResult, usage, ) -> None`	`request_id`：本次任务的请求ID `transcription_result`：识别结果（TranscriptionResult），当没有开启识别功能时为None `translation_result`：翻译结果（TranslationResult），当没有开启翻译功能时为None `usage`：计费相关信息，只在sentenceEnd时出现	无	当服务有回复时会被回调。
`def on_complete(self) -> None`	无	无	当所有数据全部返回后进行回调。
`def on_error(self, result: RecognitionResult) -> None`	`result`：异常信息	无	发生异常时该方法被回调。
`def on_close(self) -> None`	无	无	当服务已经关闭连接后进行回调。

响应结果

识别结果（`TranscriptionResult`）

TranscriptionResult封装了识别结果，包含时间戳、文本信息以及文本是否构成完整句子等信息。

由于语言间的词汇差异，识别和翻译的中间结果可能不会同时返回，因此某些情况下结果可能仅包含识别或翻译的部分。识别与翻译的进度会在is_sentence_end为True时同步完成。

成员变量	类型	说明
sentence_id	Int	句子ID。
begin_time	Long	句子开始时间，单位为ms。
end_time	Long	句子结束时间，单位为ms。
text	String	识别文本。
words	List<Word>	字时间戳信息。 `Word`的详细信息，请参见字时间戳信息（Word）。
is_sentence_end	Bool	当前文本是否构成完整的句子。 True：当前文本构成完整句子，识别结果为最终结果。 False：当前文本未构成完整句子，识别结果可能会更新。

翻译结果（`TranslationResult`）

TranslationResult封装了翻译结果，包含请求参数translation_target_languages对应的所有语种的翻译结果。

成员方法

方法签名

说明

get_language_list

def get_language_list(self, ) -> List[str]

返回翻译结果中的所有语种列表。

get_translation

def get_translation(self, language) -> Translation

输入语种，返回该语种的翻译结果。

方法参数language要和请求参数translation_target_languages相匹配。

成员变量

类型

说明

is_sentence_end

Bool

当前文本是否构成完整的句子。

True：当前文本构成完整句子，翻译结果为最终结果。
False：当前文本未构成完整句子，翻译结果可能会更新。

某语种对应的翻译结果（`Translation`）

Translation代表翻译结果中一种语言的结果，包含时间戳、文本信息以及文本是否构成完整句子等信息。

成员变量	类型	说明
sentence_id	Int	句子ID。
language	String	翻译语种。
begin_time	Long	句子开始时间，单位为ms。
end_time	Long	句子结束时间，单位为ms。
text	String	识别文本。
words	List<Word>	字时间戳信息。 `Word`的详细信息，请参见字时间戳信息（Word）。
is_sentence_end	Bool	当前文本是否构成完整的句子。 True：当前文本构成完整句子，翻译结果为最终结果 False：当前文本未构成完整句子，翻译结果可能会更新。

字时间戳信息（`Word`）

参数	类型	说明
beginTime	long	字开始时间，单位为ms。
endTime	long	字结束时间，单位为ms。
text	String	字。

同步调用结果（`TranslationRecognizerResultPack`）

在同步调用中，返回结果会将流式结果中所有成句（is_sentence_end为true）的结果打包到列表中返回。

参数	类型	说明
request_id	String	requestId 为本次任务的请求ID。
transcription_result_list	List[TranscriptionResult]	语音识别结果（TranscriptionResult）。
translation_result_list	List[TranslationResult]	语音翻译结果（TranslationResult）。
usage_list	List[]	计费信息。
error_message	String	如果没有错误则为None，否则为错误信息。

错误码

如遇报错问题，请参见错误信息进行排查。

若问题仍未解决，请加入开发者群反馈遇到的问题，并提供Request ID，以便进一步排查问题。

常见问题

故障排查

如遇代码报错问题，请根据错误信息进行排查。

Q：为什么没有输出翻译结果？

请求参数配置要正确。
1. 需将参数translation_enabled设置为True。
2. 需通过参数translation_target_languages指定翻译目标语言。注意，该参数类型为列表而非字符串。
获取翻译结果（TranslationResult）时，方法get_translation的入参要和翻译目标语言（即参数translation_target_languages的值）相匹配。
比如translation_target_languages为["en"]，却get_translation("zh")就无法获取翻译结果。

Gummy实时语音识别、翻译Python SDK

前提条件

模型列表

快速开始

流式调用

识别传入麦克风的语音

识别本地语音文件

同步调用

请求参数

关键接口

`TranslationRecognizerRealtime`类

回调接口（`TranslationRecognizerCallback`）

响应结果

识别结果（`TranscriptionResult`）

翻译结果（`TranslationResult`）

某语种对应的翻译结果（`Translation`）

字时间戳信息（`Word`）

同步调用结果（`TranslationRecognizerResultPack`）

错误码

更多示例

常见问题

故障排查

Q：为什么没有输出翻译结果？

更多问题

前提条件

模型列表

快速开始

流式调用

识别传入麦克风的语音

识别本地语音文件

同步调用

请求参数

关键接口

TranslationRecognizerRealtime类

回调接口（TranslationRecognizerCallback）

响应结果

识别结果（TranscriptionResult）

翻译结果（TranslationResult）

某语种对应的翻译结果（Translation）

字时间戳信息（Word）

同步调用结果（TranslationRecognizerResultPack）

错误码

更多示例

常见问题

故障排查

Q：为什么没有输出翻译结果？

更多问题

`TranslationRecognizerRealtime`类

回调接口（`TranslationRecognizerCallback`）

识别结果（`TranscriptionResult`）

翻译结果（`TranslationResult`）

某语种对应的翻译结果（`Translation`）

字时间戳信息（`Word`）

同步调用结果（`TranslationRecognizerResultPack`）