一句话识别 Python SDK 使用说明-智能语音交互(ISI)-阿里云帮助中心

前提条件

已准备 Python 3 环境。SDK 不支持 Python 2。
已获取项目 Appkey 和访问 Token。Appkey 的获取和模型配置请参见项目管理，Token 的获取请参见获取 Token。

下载安装

从GitHub获取源码，或下载NLS Python SDK 压缩包并解压。
安装 setuptools。
```
python -m pip install setuptools
```

在 SDK 根目录安装依赖和 SDK。

python -m pip install -r requirements.txt
python -m pip install .

在代码中导入 SDK。
```
import nls
```

代码示例

示例使用 Python 3.12 和 SDK 包版本 1.1.0，将 SDK 包内 tests/test1.pcm 的音频发送到一句话识别服务。

音频为 16000 Hz、16 位、单声道 PCM。为 Appkey 对应的项目配置通用模型；使用其他音频时，选择与其语种、采样率和场景匹配的模型。配置方法请参见项目管理。
配置环境变量 NLS_APP_KEY 和 NLS_TOKEN，分别填入项目 Appkey 和访问 Token。这两个变量由示例代码读取。
将 AUDIO_FILE 设置为 test1.pcm 的本地路径。

示例通过外网地址访问服务。使用上海地域 ECS 并需要内网访问时，将 URL 改为 ws://nls-gateway-cn-shanghai-internal.aliyuncs.com/ws/v1。

import json
import os
import threading
import time

import nls

APPKEY = os.environ["NLS_APP_KEY"]
TOKEN = os.environ["NLS_TOKEN"]
URL = "wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1"
AUDIO_FILE = "tests/test1.pcm"

ready = threading.Event()
finished = threading.Event()


def on_start(message, *args):
    ready.set()


def on_completed(message, *args):
    result = json.loads(message)
    print("Recognition result:", result["payload"]["result"])
    finished.set()


def on_error(message, *args):
    print("Recognition failed:", message)
    finished.set()


def on_close(*args):
    finished.set()


nls.enableTrace(False)  # 关闭 SDK 调试日志

with open(AUDIO_FILE, "rb") as audio:
    recognizer = nls.NlsSpeechRecognizer(
        url=URL,
        appkey=APPKEY,
        token=TOKEN,
        on_start=on_start,
        on_completed=on_completed,
        on_error=on_error,
        on_close=on_close,
    )
    try:
        recognizer.start(aformat="pcm", sample_rate=16000)
        if ready.is_set() and not finished.is_set():
            while not finished.is_set():
                chunk = audio.read(640)
                if not chunk:
                    break
                recognizer.send_audio(chunk)
                time.sleep(0.02)
            if not finished.is_set():
                recognizer.stop()
    finally:
        recognizer.shutdown()

关键接口

一句话识别客户端为 nls.NlsSpeechRecognizer。以下说明对应 SDK 包版本 1.1.0。

初始化（init）

创建客户端，设置凭证、网关和回调。

参数	类型	说明
`url`	str	网关 WebSocket 地址。默认值为 `wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1`。
`appkey`	str	项目 Appkey。获取方法请参见项目管理。
`token`	str	访问 Token。获取方法请参见获取 Token。
`on_start`	callable	收到 `RecognitionStarted` 时调用，表示识别已就绪。
`on_result_changed`	callable	返回中间识别结果时调用。需要在 `start` 中开启 `enable_intermediate_result`。
`on_completed`	callable	正常完成识别、返回最终识别结果时调用。
`on_error`	callable	收到服务端 `TaskFailed` 错误消息时调用。
`on_close`	callable	与服务端的连接关闭时调用。
`callback_args`	list	自定义参数列表。列表元素按顺序展开，传给各回调的 `*args`。

除 on_close 外，回调的第一个参数为 JSON 格式的消息字符串，其后为展开的 callback_args。on_close 只接收展开的自定义参数。例如，callback_args=["example"] 时，消息回调接收 callback(message, "example")，关闭回调接收 on_close("example")。

客户端参数校验、连接或调用超时等错误还可能通过异常报告，应在调用代码中处理。

start

同步启动识别。正常启动时，阻塞至 on_start 回调返回；服务端拒绝启动时，通过 on_error 报告失败。识别就绪后再发送音频。

参数	类型	说明
`aformat`	str	音频格式，默认值为 `pcm`。支持 `pcm`、`opus`、`opu` 等，其他格式及其音频要求请参见接口说明。SDK 不会将 PCM 自动编码为 OPUS 或 OPU，使用这两种格式时需自行编码。
`sample_rate`	int	音频采样率，默认值为 16000，单位为 Hz。
`ch`	int	声道数。默认值为 1，仅支持单声道。
`enable_intermediate_result`	bool	是否返回中间识别结果，默认值为 `False`。
`enable_punctuation_prediction`	bool	是否预测识别结果的标点，默认值为 `False`。
`enable_inverse_text_normalization`	bool	是否开启逆文本规整（ITN）。设置为 `True` 时，将中文数字转换为阿拉伯数字输出。默认值为 `False`。
`timeout`	int	等待启动的超时时间，默认值为 10，单位为秒。
`ping_interval`	int 或 None	发送 Ping 的间隔，默认值为 8，单位为秒。设置为 `0` 或 `None` 时，不发送 Ping。
`ping_timeout`	int 或 None	等待 Pong 的超时时间，单位为秒。默认值为 `None`，不检查 Pong 超时。启用检查时，值须大于 0，且小于 `ping_interval`。
`ex`	dict	额外请求参数，按键值对合并到请求的 `payload` 中。参数定义请参见开始识别的请求参数。

正常返回值为 None。识别就绪通过 on_start 通知，服务端拒绝启动通过 on_error 报告；等待超时会抛出异常。

send_audio

发送二进制音频。识别须已就绪，数据格式与start 的 aformat 一致。SDK 不进行 PCM 到 OPUS 或 OPU 的自动编码。

参数	类型	说明
`pcm_data`	bytes	要发送的非空二进制音频数据，格式与 `start` 的 `aformat` 一致。

正常返回值为 None。未启动识别或数据为空时，会抛出异常。

stop

结束音频发送，并同步等待会话结束。正常完成时通过 on_completed 返回最终结果；服务端任务失败时通过 on_error 报告错误。

参数	类型	说明
`timeout`	int	等待会话结束的超时时间，默认值为 10，单位为秒。

正常返回值为 None。等待超时会抛出异常。

shutdown

强制关闭已启动的请求，重复调用无副作用。无参数，返回值为 None。

多线程和多并发

在启用全局解释器锁（GIL）的 CPython 环境中，同一时刻只有一个线程执行 Python 代码，部分性能库可以释放 GIL。需要利用多核计算资源时，推荐使用multiprocessing 或concurrent.futures.ProcessPoolExecutor。同时运行多个 I/O 密集型任务时，多线程仍是合适的方式。

单个解释器的线程过多，会增加线程切换开销，也可能导致 SDK 出错。不建议使用超过 200 个线程，推荐使用multiprocessing，或通过脚本创建多个解释器。