AI Voice Platform 文档

onnx-platform ​

onnx-platform 是 AI Voice Platform 的本地纯 Rust 高性能语音与 AI 推理服务集合，包含基于 sherpa-onnx 与 FunASR 两个体系构建的统一 ASR、TTS 与通话情绪分析服务。全平台已全面消除 C++、CMake 与 MSVC 依赖，统一基于 Rust 2021 + Tokio 异步运行时与 Cargo 标准工具链构建。

模块总览 ​

模块目录服务 / 组件名称协议与端口底层框架 / 模型主要功能
sherpa-asr-server/Sherpa ASR 统一服务WS 10096 (/audio)；HTTP 10095 (/asr)sherpa-onnx + Zipformer + SenseVoice纯 Rust 统一重构，单进程双端口：流式 1-Pass Partial + Silero VAD 断句 + 2-Pass SenseVoice 终态重识别，以及 HTTP 离线转写与 Whisper 标准接口
funasr-asr-server/FunASR ASR 统一服务WS 10099 (/audio)；HTTP 10094 (/asr)FunASR + Paraformer + FSMN-VAD + CT-Punc纯 Rust 统一自研，单进程双端口：流式 2-Pass partial + 离线标点 final，以及 HTTP 离线转写与 Whisper 标准接口
sherpa-tts-server/本地 TTS 语音合成HTTP 9080 (/tts, /tts-stream)sherpa-onnx + VITS/Matcha/Kokoro纯 Rust 异步架构，离线 WAV 合成与实时 PCM/MP3 流式广播（audio_fork:// 原生 PCM 与 shout:// MP3），带 LRU 读租约保护、起播预缓冲门控与并发去重
emotion-analysis-server/通话情绪分析服务HTTP 9090 (/analyze, /health)ONNX Runtime + BERT/wav2vec2纯 Rust 多模态异步分析服务，自研轻量级 WordPiece 分词、多格式音频解码与静音裁剪，动态加载 ONNX Runtime
sherpa-demo/Rust 验证程序集本地 CLI 工具sherpa-onnx离线/流式 ASR/TTS/VAD 最小测试程序（纯 Rust 实现）
sherpa-onnx/sherpa-onnx 预编译 SDK跨平台二进制与库Win_x64, Linux_x64, Linux_aarch64, macOS arm64sherpa-onnx 官方预编译资产与 C-API 头文件
onnxruntime/ONNX Runtime 运行库预编译库与头文件Microsoft ONNX Runtime 1.29.0动态库与头文件，供 ort 运行时探测动态加载
models/模型资源根目录静态资产—各服务 config.toml 引用的模型与测试音频，不随源码打包分发
models/model-down/模型同步与下载工具CLI 工具 (Python)uv + ModelScope SDK本地 ONNX 全量模型库上传备份至 ModelScope，并在部署环境/新机器上一键并发断点续传拉取

构建与交付规范 ​

平台所有推理服务采用 Rust 官方标准构建规范，中间产物进入各工程自身的 target/ 目录，交付包装配至自包含的 dist/win_x64/（Windows）与 dist/linux_x64/（Linux）：

Windows x64 (PowerShell 7) ​

powershell
# 分别构建
pwsh onnx-platform/sherpa-asr-server/build.ps1
pwsh onnx-platform/sherpa-tts-server/build.ps1
pwsh onnx-platform/emotion-analysis-server/build.ps1
pwsh onnx-platform/funasr-asr-server/build.ps1

构建脚本将执行 cargo build --release，并自动将可执行文件、配置文件以及配套的动态链接库（onnxruntime.dll、sherpa-onnx-c-api.dll、sherpa-onnx-cxx-api.dll 等）装配至各工程的 dist/win_x64/。

Linux x64 (本地构建) ​

bash
# 根目录按服务构建（需本地或 WSL 环境具备 Rust 与构建依赖）
bun run build:native asr --linux      # sherpa-asr-server
bun run build:native funasr --linux   # funasr-asr-server
bun run build:native tts --linux      # sherpa-tts-server
bun run build:native emotion --linux  # emotion-analysis-server

# 或分别执行各自的构建脚本：
bash onnx-platform/sherpa-asr-server/build.sh
bash onnx-platform/sherpa-tts-server/build.sh
bash onnx-platform/emotion-analysis-server/build.sh
bash onnx-platform/funasr-asr-server/build.sh

Linux x64 跨环境 Docker 编译（推荐，环境完全隔离对齐） ​

为避免宿主机 WSL 系统 glibc 版本过高（例如高于生产容器运行环境）导致的动态链接符号冲突，或在未配置 Linux 编译工具链的开发机上一键出包，推荐使用统一的 Docker Builder：

powershell
# Windows 宿主机（PowerShell 7 一键编译，支持 Docker Desktop 或自动桥接 WSL Docker）
pwsh onnx-platform/build-linux-docker.ps1                      # 全量编译 4 个语音服务
pwsh onnx-platform/build-linux-docker.ps1 -Service asr        # 单独编译 sherpa-asr-server
pwsh onnx-platform/build-linux-docker.ps1 -Service tts        # 单独编译 sherpa-tts-server
pwsh onnx-platform/build-linux-docker.ps1 -Service funasr     # 单独编译 funasr-asr-server
pwsh onnx-platform/build-linux-docker.ps1 -Service emotion    # 单独编译 emotion-analysis-server

# 或在根目录通过 bun 执行快捷命令：
bun run onnx:build:linux:docker
bash
# Linux / WSL 宿主机（Bash 一键编译，自动映射当前用户 UID/GID）
bash onnx-platform/build-linux-docker.sh                      # 全量编译
bash onnx-platform/build-linux-docker.sh asr                  # 单独编译

说明：

  • 基础镜像基于 debian:trixie（Dockerfile.builder），与生产运行环境版本严格一致；
  • 挂载 Docker 具名卷 ai-voice-cargo-registry 与 ai-voice-cargo-git，依赖无需重复下载，增量构建秒级完成；
  • 编译结果自动装配并输出到各工程的 dist/linux_x64/ 自包含交付目录。

运行与门禁 ​

本地启动 ​

各服务目录下均配备独立的自包含 run-server.ts，它会自动以交付目录（dist/<platform>）为工作目录启动编译好的二进制：

powershell
# 在根目录通过 bun run dev 启动全局服务，或单独启动特定服务：
bun run dev:asr       # 启动 sherpa-asr-server (10096 / 10095)
bun run dev:tts       # 启动 sherpa-tts-server (9080)
bun run dev:emotion   # 启动 emotion-analysis-server (9090)
bun run dev:funasr    # 启动 funasr-asr-server (10099 / 10094)

各服务测试入口 ​

联调、回归与压测统一使用各服务现有的 scripts/ 客户端。执行前需启动对应服务并准备脚本要求的音频或文本输入；详细用法见各服务 README 与脚本帮助。

下表的 10 个脚本均支持无参数启动，使用本机默认端口。ASR 客户端自动查找 models/ 下 SenseVoice 的 test_wavs/zh_vad.wav、zh.wav 或 Zipformer / Paraformer 的 test_wavs/0.wav、1.wav；样本路径相对脚本定位，不依赖启动目录。模型资产不随 Git 克隆提供，准备方式见模型同步工具。延迟压测和元数据回归需要 16kHz 单声道 PCM16 WAV。TTS 使用内置文本，情绪分析运行内置文本样本套件。

服务现有测试脚本（相对服务目录）用途
Sherpa ASRscripts/request-ws.ts、scripts/request-http.ts、scripts/bench-stream-latency.ts、scripts/test-metadata-parity.ts流式与离线识别、流式延迟及首帧元数据回归
FunASR ASRscripts/request-ws.ts、scripts/request-http.ts、scripts/bench-stream-latency.ts流式与离线识别及流式延迟
Sherpa TTSscripts/request-tts.ts、scripts/request-tts-stream.ts同步合成、流式并发、慢读与连接生命周期回归
情绪分析scripts/request-emotion.ts端到端多模态分析与样本套件验证

静态门禁与单元测试 ​

在根目录执行全量 Rust 门禁（包含所有服务的代码格式化校验、Clippy 零警告校验与内置单元测试）：

powershell
bun run check:rust

或针对单一服务运行门禁：

powershell
bun run check:rust tts
bun run check:rust emotion
bun run check:rust sherpa-asr
bun run check:rust funasr

模型管理与同步 (ModelScope & uv) ​

针对 models/ 下 4.3GB+ 的多模型资产（FunASR 系列、Sherpa-onnx Zipformer/SenseVoice、Kokoro/Matcha TTS、Silero VAD 等），仓库在 models/model-down/ 下提供了基于 uv 与 ModelScope 的同步与下载脚本：

  • 上传备份：将本地 models/ 递归同步至 ModelScope 模型仓库（支持分块多线程断点续传，自动排除缓存与虚拟环境）：
    bash
    cd onnx-platform/models/model-down
uv run upload.py --model-id wlf213/ai-voice-platform-models --token <access-token>
  • 部署机/新环境一键拉取：在 Debian 12 / Ubuntu / WSL 生产节点上一键高速拉取（支持断点续传与部分过滤）：
    bash
    cd onnx-platform/models/model-down
uv run download.py --model-id wlf213/ai-voice-platform-models --target-dir ../
# 或直接指定生产挂载目录：
# uv run download.py --model-id wlf213/ai-voice-platform-models --target-dir /data/ai-voice/models
  • 详细参数、环境变量配置与统一 CLI 入口见 models/model-down/README.md。

文档与代码在同一仓库维护，现有 Markdown 是唯一内容源。

AI Voice Platform