配置参考

配置

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 生效
hotwordsFile	string	"hotword.json"	独立热词配置文件路径（默认 hotword.json）
defaultHotwordProfile	string	"default"	metadata 未指定 hotwordProfile 时默认生效的 profile ID；为空则不启用热词
hotwordProfiles	object	{}	静态 hotword profile 集合（推荐在 hotword.json 中配置，也兼容内嵌于 config.json）
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

切换到中英双语模型：

{
  "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 时服务会启动失败。

热词配置与独立 hotword.json

热词配置已独立为单文件（默认 hotword.json），config.json 中只需通过 asr.hotwordsFile 与 asr.defaultHotwordProfile 指定：

{
  "asr": {
    "decodingMethod": "modified_beam_search",
    "hotwordsScore": 1.5,
    "hotwordsFile": "hotword.json",
    "defaultHotwordProfile": "default"
  }
}

hotword.json 结构示例：

{
  "defaultHotwordProfile": "default",
  "hotwordProfiles": {
    "default": {
      "words": [
        "接收whatsapp验证码",
        "微信",
        "WhatsApp",
        "白班值",
        "华法林"
      ]
    },
    "sales": {
      "words": ["智能客服", "FreeSWITCH", "sherpa-onnx"]
    }
  }
}

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

twoPass — 句尾 2-pass 二次离线精修识别（可选）

当开启 twoPass.enabled: true 时，服务端在流式推流期间由 Pass 1（流式 Zipformer）输出实时 partial 增量字幕；当 VAD 判定句尾静音或推流结束时，自动调度离线大模型重算整句音频并输出 final 纠错终态文本。

字段	类型	默认值	说明
enabled	bool	true	是否启用 2-pass 句尾精修识别
activeModel	string	"sherpa-onnx-zipformer-multi-zh-hans-2023-9-2"	当前加载的 2-pass 离线模型 Profile ID；必须存在于 twoPass.models
models	object	见 config.json	2-pass 离线模型 Profile 集合
recognizerPoolSize	int32	4	离线识别器实例池容量，并发支撑 final 句级精修
numThreads	int32	1	每个离线识别实例计算线程数
provider	string	"cpu"	ONNX 推理后端（"cpu"）
hotwordsScore	float	1.5	离线热词加权分数
fallbackToFirstPass	bool	true	当 2-pass 识别异常或返回空时，是否自动回退 Pass 1 的识别文本
debug	bool	false	是否打印 2-pass 内部调试日志

twoPass.models 支持 Transducer 离线大模型 与 SenseVoice / Paraformer 离线模型 两类配置：

1. Transducer 架构（离线 Zipformer 大模型）

字段	类型	说明
modelDir	string	离线模型目录；相对 onnx-platform/models/ 解析
encoder / decoder / joiner / tokens	string	必填模型文件与词表；相对 modelDir 解析
bpeVocab	string	可选 BPE 词表（如 bpe.model 或 bbpe.model）；相对 modelDir 解析
modelType	string	固定为 "transducer"（或留空自动探测）
modelingUnit	string	建模单元（如 "cjkchar" 或 "bpe"）

2. SenseVoice / Paraformer 架构

字段	类型	说明
modelDir	string	离线模型目录；相对 onnx-platform/models/ 解析
model	string	离线模型文件名（如 model.int8.onnx）；相对 modelDir 解析
tokens	string	词表文件名（如 tokens.txt）；相对 modelDir 解析
modelType	string	模型架构类型："sense_voice" 或 "paraformer"
language	string	目标识别语种（"zh"、"en"、"auto" 等，仅 SenseVoice 生效）
useItn	bool	是否启用逆文本归一化（ITN，仅 SenseVoice 生效）

预配置离线模型选型对比

1. sherpa-onnx-zipformer-multi-zh-hans-2023-9-2（默认推荐）：
   • 中文多数据集离线 Zipformer 大模型（Transducer 架构），高准确率，与流式中文模型语种对齐。
2. sherpa-onnx-zipformer-zh-en-2023-11-22：
   • 中英双语离线 Zipformer 大模型（Transducer 架构 + BPE 建模），适合中英混合通话场景。
3. sherpa-onnx-sense-voice：
   • SenseVoice 多语种离线大模型，自带 ITN 逆文本归一化与情绪/事件检测能力。
4. sherpa-onnx-paraformer-zh：
   • 阿里 Paraformer 高精度纯中文离线模型。

吞吐建议

调优时优先调整：

• 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：默认关闭；只在排查问题时打开