Python SDK for short sentence recognition-Intelligent Speech Interaction(ISI)-阿里云帮助中心

Prerequisites

Prepare a Python 3 environment. Python 2 is not supported.
Obtain a project Appkey and an access token. For information about obtaining an Appkey and configuring a model, see Manage projects. For information about obtaining a token, see Obtain a token.

For the service protocol and audio requirements, see Short Sentence Recognition API reference.

Download and installation

Obtain the source code from GitHub, or download and extract the NLS Python SDK archive.
Install setuptools.
```
python -m pip install setuptools
```

Install the dependencies and SDK from the SDK root directory.

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

Import the SDK in the code.
```
import nls
```

Code example

This example uses Python 3.12 and SDK package version 1.1.0 to send the audio in tests/test1.pcm, included in the SDK package, to the Short Sentence Recognition service.

The audio is 16-bit, mono PCM sampled at 16000 Hz. Configure the General model for the project associated with the Appkey. For other audio, select a model that matches its language, sample rate, and scenario. For configuration instructions, see Manage projects.
Set the NLS_APP_KEY and NLS_TOKEN environment variables to the project Appkey and access token, respectively. These variables are read by the example code.
Set AUDIO_FILE to the local path of test1.pcm.

The example accesses the service over the Internet. To access the service over the internal network from an ECS instance in the China (Shanghai) region, set URL to 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)  # Disable SDK debug logging

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()

Key interfaces

The Short Sentence Recognition client is nls.NlsSpeechRecognizer. The following descriptions apply to SDK package version 1.1.0.

Initialization (init)

Create a client and configure its credentials, gateway, and callbacks.

Parameter	Type	Description
`url`	str	The gateway WebSocket URL. The default is `wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1`.
`appkey`	str	The project Appkey. For information about obtaining it, see Manage projects.
`token`	str	The access token. For information about obtaining it, see Obtain a token.
`on_start`	callable	Invoked when `RecognitionStarted` is received, indicating that recognition is ready.
`on_result_changed`	callable	Invoked when an intermediate recognition result is returned. Requires `enable_intermediate_result` to be enabled in `start`.
`on_completed`	callable	Invoked when recognition completes normally and the final result is returned.
`on_error`	callable	Invoked when a `TaskFailed` error message is received from the service.
`on_close`	callable	Invoked when the connection to the service closes.
`callback_args`	list	Custom callback arguments. The list elements are expanded in order and passed to each callback as `*args`.

All callbacks except on_close receive a JSON message string as their first argument, followed by the expanded callback_args. The on_close callback receives only the expanded custom arguments. For example, with callback_args=["example"], message callbacks receive callback(message, "example"), and the close callback receives on_close("example").

Client parameter validation errors, connection errors, and call timeouts may also be reported as exceptions. Handle these exceptions in the calling code.

start

Start recognition synchronously. During normal startup, the call blocks until the on_start callback returns. If the service rejects startup, on_error reports the failure. Send audio after recognition is ready.

Parameter	Type	Description
`aformat`	str	The audio format. The default is `pcm`. Formats such as `pcm`, `opus`, and `opu` are supported. For other formats and their audio requirements, see the API reference. The SDK does not automatically encode PCM as OPUS or OPU. Encode the audio before sending it in either format.
`sample_rate`	int	The audio sample rate in Hz. The default is 16000.
`ch`	int	The number of audio channels. The default is 1. Only mono audio is supported.
`enable_intermediate_result`	bool	Whether to return intermediate recognition results. The default is `False`.
`enable_punctuation_prediction`	bool	Whether to predict punctuation in recognition results. The default is `False`.
`enable_inverse_text_normalization`	bool	Whether to enable inverse text normalization (ITN). When set to `True`, Chinese numerals are converted to Arabic numerals in the output. The default is `False`.
`timeout`	int	The startup wait timeout in seconds. The default is 10.
`ping_interval`	int or None	The interval between Ping packets, in seconds. The default is 8. Set to `0` or `None` to disable Ping packets.
`ping_timeout`	int or None	The timeout for receiving a Pong, in seconds. The default is `None`, which disables Pong timeout checks. To enable checks, set a value greater than 0 and less than `ping_interval`.
`ex`	dict	Additional request parameters, merged as key-value pairs into the request `payload`. For parameter definitions, see Start recognition request parameters.

The normal return value is None. The on_start callback indicates that recognition is ready; on_error reports startup rejection by the service. A wait timeout raises an exception.

send_audio

Send binary audio after recognition is ready. The data format must match aformat in start. The SDK does not automatically encode PCM as OPUS or OPU.

Parameter	Type	Description
`pcm_data`	bytes	Non-empty binary audio data in the format specified by `aformat` in `start`.

The normal return value is None. An exception is raised if recognition has not started or the data is empty.

stop

End audio transmission and wait synchronously for the session to end. On normal completion, on_completed returns the final result. If the service task fails, on_error reports the error.

Parameter	Type	Description
`timeout`	int	The timeout for waiting for the session to end, in seconds. The default is 10.

The normal return value is None. A wait timeout raises an exception.

shutdown

Force-close a started request. Repeated calls have no side effects. This method takes no parameters and returns None.

Multi-threading and concurrency

In CPython environments with the Global Interpreter Lock (GIL) enabled, only one thread executes Python code at a time. Some performance-oriented libraries can release the GIL. To use multiple CPU cores, we recommend multiprocessing or concurrent.futures.ProcessPoolExecutor. Multi-threading remains suitable for running multiple I/O-bound tasks concurrently.

Too many threads in a single interpreter increase context-switching overhead and may cause SDK errors. We recommend using no more than 200 threads. Use multiprocessing or create multiple interpreters through scripts.