Gummy一句话识别、翻译Python API

更新时间:2025-04-21 10:01:18

本文介绍Gummy一句话识别和翻译Python API的使用,能够直接对一分钟内的音频流(无论是从外部设备如麦克风获取的音频流,还是从本地文件读取的音频流)进行识别或翻译,并实时输出结果。在识别或翻译一句话后将停止识别或翻译任务。

说明
  • 音频时长不能超过一分钟,否则将报错断连。

  • 一句话的结束,通过静音时长来判断,当语音后面出现的静音时长超过预设的静音时长(默认为700ms,可通过请求参数max_end_silence设置),系统会认为当前的一句话已结束。如果语音时长超过了一分钟,则认为这一分钟内的语音是一句话。

前提条件

模型列表

模型名

模型简介

gummy-chat-v1

Gummy一句话识别、翻译模型,在识别、翻译出一句话后会结束任务。默认进行标点符号预测和逆文本正则化(INT,Inverse Text Normalization)。支持定制热词

快速开始

TranslationRecognizerChat提供了一句话识别/翻译的关键接口,支持流式调用模式。

流式调用

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

image
  1. 启动流式语音识别/翻译

    实例化TranslationRecognizerChat绑定请求参数回调接口(TranslationRecognizerCallback),调用start方法启动流式语音识别/翻译。

  2. 流式传输

    循环调用TranslationRecognizerChatsend_audio_frame方法,将从本地文件或设备(如麦克风)读取的二进制音频流分段发送至服务端。

    在发送音频数据的过程中,服务端会通过回调接口(TranslationRecognizerCallback)on_event方法,将识别结果实时返回给客户端。

    建议每次发送的音频时长约为100毫秒,数据大小保持在1KB16KB之间。

    当识别到一句话后,send_audio_frame方法返回false,音频数据无法再继续上传。此时请终止循环。

  3. 结束处理

    调用TranslationRecognizerChatstop方法结束语音识别/翻译。

    该方法会阻塞当前线程,直到回调接口(TranslationRecognizerCallback)on_complete或者on_error回调触发后才会释放线程阻塞。

点击查看完整示例

识别传入麦克风的语音
识别本地语音文件
# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/xxxxx.html

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 english_translation.vad_pre_end:
                print("vad pre end {}, {}, {}".format(transcription_result.pre_end_start_time, transcription_result.pre_end_end_time, transcription_result.pre_end_timemillis))
        if transcription_result is not None:
            print("sentence id: ", transcription_result.sentence_id)
            print("transcription: ", transcription_result.text)


callback = Callback()


translator = TranslationRecognizerChat(
    model="gummy-chat-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)
        if not translator.send_audio_frame(data):
            print("sentence end, stop sending")
            break
    else:
        break

translator.stop()
# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/xxxxx.html

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 = TranslationRecognizerChat(
    model="gummy-chat-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:
                if translator.send_audio_frame(audio_data):
                    print("send audio frame success")
                else:
                    print("sentence end, stop sending")
                    break
    else:
        raise Exception(
            'The supplied file was empty (zero bytes long)')
    f.close()
except Exception as e:
    raise e

translator.stop()

请求参数

语音识别需要对模型、采样率、音频格式等参数进行设置。请求参数通过TranslationRecognizerChat的构造方法(_init_)进行设置。

参数

类型

默认值

是否必须

说明

参数

类型

默认值

是否必须

说明

model

str

-

设置一句话识别/翻译的模型。如需了解当前支持的模型,请参见模型列表

sample_rate

int

-

设置待识别音频采样率(单位Hz)。只支持16000Hz。

format

str

-

设置待识别音频格式。

支持的音频格式:pcm、pcm编码的wav、mp3、ogg封装的opus、ogg封装的speex、aac、amr。

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

700

设置最大结束静音时长,单位为毫秒(ms),取值范围为200ms6000ms。

若语音结束后静音时长超过该预设值,系统将判定当前语句已结束。

关键接口

TranslationRecognizerChat

TranslationRecognizerChat通过“from dashscope.audio.asr import *”方式引入,提供一句话识别/翻译的关键接口。

成员方法

方法签名

说明

成员方法

方法签名

说明

start

def start(self)

启动一句话识别/翻译。

详细的调用流程和参考示例请参见流式调用

send_audio_frame

def send_audio_frame(self, buffer: bytes) -> bool

推送音频,每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。

当已经识别到一句话后,调用send_audio_frame会返回False,并且音频不会被继续上传。请停止发送并且结束调用。

识别结果通过回调接口(TranslationRecognizerCallback)on_event方法获取。

详细的调用流程和参考示例请参见流式调用

stop

def stop(self)

结束一句话识别/翻译。该方法会阻塞当前线程直到回调的on_complete或者on_error返回。

详细的调用流程和参考示例请参见流式调用

回调接口(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

当服务有回复时会被回调。

def on_complete(self) -> None

当所有数据全部返回后进行回调。

def on_error(self, result: RecognitionResult) -> None

result:异常信息

发生异常时该方法被回调。

def on_close(self) -> None

当服务已经关闭连接后进行回调。

响应结果

实时识别结果(TranscriptionResult

TranscriptionResult代表一次实时识别的结果,包含了时间戳和文本信息等。

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

成员变量

类型

说明

成员变量

类型

说明

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指定的所有语种的翻译结果。

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

成员方法

方法签名

说明

成员方法

方法签名

说明

get_language_list

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

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

get_translation

def get_translation(self, language) -> Translation

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

成员变量

类型

说明

成员变量

类型

说明

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>

字时间戳信息。

is_sentence_end

Bool

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

  • True:当前文本构成完整句子,已结束,翻译结果为最终结果。

  • False:当前文本未构成完整句子,仍在继续,翻译结果可能会更新。

字时间戳信息(Word

参数

类型

说明

参数

类型

说明

beginTime

long

字开始时间,单位为ms。

endTime

long

字结束时间,单位为ms。

text

String

字。

错误码

在使用API过程中,如果调用失败并返回错误信息,请参见错误信息进行解决。

更多示例

更多示例,请参见GitHub

常见问题

请参见GitHub QA

  • 本页导读 (1)
  • 前提条件
  • 模型列表
  • 快速开始
  • 流式调用
  • 请求参数
  • 关键接口
  • TranslationRecognizerChat类
  • 回调接口(TranslationRecognizerCallback)
  • 响应结果
  • 实时识别结果(TranscriptionResult)
  • 实时翻译结果(TranslationResult)
  • 某语种对应的翻译结果(Translation)
  • 字时间戳信息(Word)
  • 错误码
  • 更多示例
  • 常见问题
AI助理

点击开启售前

在线咨询服务

你好,我是AI助理

可以解答问题、推荐解决方案等