配置参考

配置

config.json 按域分组：server / concurrency / socket / logging / recording / asr / vad。各组字段如下（键名不带组前缀）。

server — 监听

字段	类型	默认值	说明
`host`	string	`"127.0.0.1"`	实际监听地址
`port`	uint16	`10096`	实际监听端口
`healthPath`	string	`"/health"`	HTTP 健康检查路径
`wsPath`	string	`"/audio"`	WebSocket 升级路径
`wsSubprotocol`	string	`"audio.drachtio.org"`	要求客户端声明的子协议；为空则不强制

concurrency — 并发

字段	类型	默认值	说明
`maxSessions`	int32	`16`	并发会话上限；超过后新连接返回 503
`ioWorkers`	int32	CPU 核心数	I/O 工作线程数；运行时会按 `FD_SETSIZE` 自动抬升下限
`sessionPoolSize`	int32	`16`	预热的 ASR session 数；超过 `maxSessions` 会被裁剪
`numThreads`	int32	`1`	ONNX 推理线程数
`acceptBacklog`	int32	`SOMAXCONN`	`listen(backlog)`
`workerPollTimeoutMs`	int32	`10`	工作线程单轮 `select` 超时；夹紧到 `[1, 1000]`

socket — 套接字缓冲

字段	类型	默认值	说明
`tcpNoDelay`	bool	`true`	启用 `TCP_NODELAY`
`maxFrameBytes`	int32	`4194304`	单个 WebSocket 帧最大字节数；超过即 1002 协议错误
`readBufferBytes`	int32	`65536`	每连接 recv 缓冲
`writeBufferBytes`	int32	`65536`	每连接 send 缓冲（预留）
`recvBufferBytes`	int32	`262144`	`SO_RCVBUF` 设置（0 表示不调整）
`sendBufferBytes`	int32	`262144`	`SO_SNDBUF` 设置（0 表示不调整）

logging — 日志

字段	类型	默认值	说明
`dir`	string	`"logs"`	日志目录；相对路径按运行目录解析，按天滚动
`debugTextFrames`	bool	`false`	打印每条 metadata 文本帧
`debugAudioFrames`	bool	`false`	每个二进制帧落一条识别状态日志
`debugRecognitionState`	bool	`false`	每次识别状态变化都落日志

recording — 录音

字段	类型	默认值	说明
`enabled`	bool	`false`	启用上行音频录制
`dir`	string	`"recordings"`	录制目录（相对路径按配置文件所在目录解析）

asr — 识别

字段	类型	默认值	说明
`activeModel`	string	`sherpa-onnx-streaming-zipformer-zh-int8-2025-06-30`	当前加载的 ASR profile ID；必须存在于 `models`
`models`	object	见默认 `config.json`	ASR profile 集合；服务启动时只加载 active profile
`provider`	string	`"cpu"`	ONNX 推理后端
`sampleRate`	int32	`16000`	上行采样率；当前只支持 16kHz
`debug`	bool	`false`	sherpa-onnx 内部 debug
`sendPartialResults`	bool	`true`	是否下发 partial 文本帧
`decodingMethod`	string	`greedy_search`	sherpa-onnx 解码方式；显式配置时原样使用。未配置且 `hotwordProfiles` 非空时自动改为 `modified_beam_search`
`hotwordsScore`	float	`1.5`	sherpa hotword boost 分数；对所有 hotword profile 生效
`defaultHotwordProfile`	string	空	metadata 未指定 `hotwordProfile` 时使用的 profile ID；为空则不启用 hotwords
`hotwordProfiles`	object	`{}`	静态 hotword profile 集合；连接建立后按 metadata 选择
`partialMinIntervalMs`	int32	`300`	同一句 partial 文本最小下发间隔
`decodeBatchMs`	int32	`80`	批量 decode 节奏
`idleFinalizeMs`	int32	`1200`	有未结算音频且已有 partial 时，若“最后一帧音频”空闲，或“最后一次 `speech_active=true` / partial 文本变化”空闲达到该时长，则主动 flush 并下发 `flushReason=audio-idle`；`speech_started` / `speech_segment_detected` 不刷新该空闲计时；`0` 表示关闭

vad — 语音活动检测（强制启用，无开关）

字段	类型	默认值	说明
`model`	string	`silero_vad.onnx`	silero-vad onnx
`bufferSizeSeconds`	float	`30.0`	silero-vad ring buffer
`threshold`	float	`0.5`	VAD 置信度阈值
`minSilenceDuration`	float	`0.5`	触发段尾的最小静音时长
`minSpeechDuration`	float	`0.25`	视为有效语音的最小时长
`windowSize`	int32	`512`	VAD 窗大小（采样点）
`maxSpeechDuration`	float	`20.0`	单段最大语音时长，超过强制切段

asr.models 每个 profile 的字段：

字段	类型	说明
`modelDir`	string	模型目录；相对 `onnx-platform/models/` 解析，绝对路径原样使用
`encoder` / `decoder` / `joiner` / `tokens`	string	必填模型文件名或路径；相对 `modelDir` 解析
`bpeVocab`	string	可选 BPE 词表；相对 `modelDir` 解析
`modelType`	string	sherpa-onnx 模型类型提示，例如 `zipformer`；空字符串表示交给模型 metadata 自动识别
`modelingUnit`	string	建模单元，例如 `cjkchar`

默认配置包含两个 profile：

sherpa-onnx-streaming-zipformer-zh-int8-2025-06-30：默认中文 int8 streaming zipformer，文件为 encoder.int8.onnx / decoder.onnx / joiner.int8.onnx / tokens.txt，modelType 默认为空以使用 metadata 自动识别
sherpa-onnx-streaming-zipformer-bilingual-zh-en：中英双语 streaming zipformer，文件为 encoder-epoch-99-avg-1.onnx / decoder-epoch-99-avg-1.onnx / joiner-epoch-99-avg-1.onnx / tokens.txt，modelType 为 zipformer

切换到中英双语模型：

json

{
  "asr": {
    "activeModel": "sherpa-onnx-streaming-zipformer-bilingual-zh-en"
  }
}

如果需要加载其他模型，请在 asr.models 中新增 profile，并把 asr.activeModel 改为对应 ID。旧的 asrModelName / asrEncoder / asrDecoder / asrJoiner / asrTokens / asrBpeVocab / asrModelType / asrModelingUnit 字段不再兼容；缺少 asr.activeModel 或找不到对应 profile 时服务会启动失败。

asr.hotwordProfiles 每个 profile 必须且只能定义 file 或 words 其中一个字段：

json

{
  "asr": {
    "decodingMethod": "modified_beam_search",
    "hotwordsScore": 1.5,
    "defaultHotwordProfile": "default",
    "hotwordProfiles": {
      "default": {
        "file": "hotwords/default.txt"
      },
      "sales": {
        "words": ["智能客服", "FreeSWITCH", "sherpa-onnx"]
      }
    }
  }
}

file：UTF-8 hotword 文本文件，路径相对 config.json 所在目录解析；文件不存在会导致服务启动失败
words：字符串数组，启动时用 \n 拼接为 sherpa-compatible UTF-8 hotword lines
profile 同时定义 file 与 words、或两者都未定义，都会导致服务启动失败
hotword 文本不会写入 OnlineRecognizerConfig.hotwords_file；服务会在每个 WebSocket session 选定 profile 后调用 CreateStream(hotwords)
sherpa-onnx 要求通过 CreateStream(hotwords) 使用 session 级 hotwords 时， decodingMethod 必须为 modified_beam_search。如果未显式配置 asr.decodingMethod，服务会在 hotwordProfiles 非空时自动切换；如果显式配成 greedy_search，后续启用 hotwords 的连接仍可能在创建 stream 时失败或崩溃
修改 hotword profile 或文件后需要重启服务，不支持运行时热加载

吞吐建议

调优时优先调整：

concurrency.ioWorkers：与并发连接数匹配，每个工作线程受 FD_SETSIZE 约束（Windows 默认 1024，本进程编译期强制设到 1024，单工作线程上限约 992 连接）
concurrency.sessionPoolSize：建议接近或等于 concurrency.maxSessions，避免连接抖动反复冷启动 recognizer / VAD
concurrency.numThreads：ONNX 推理线程，配合 CPU 调整
asr.partialMinIntervalMs、asr.decodeBatchMs：影响 partial 实时性与 CPU 占用
recording.enabled：默认关闭；只在排查问题时打开

配置参考 ​

配置 ​

server — 监听 ​

concurrency — 并发 ​

socket — 套接字缓冲 ​

logging — 日志 ​

recording — 录音 ​

asr — 识别 ​

vad — 语音活动检测（强制启用，无开关） ​

吞吐建议 ​