一、Moonshine 部署安装指南

Moonshine 提供统一的 moonshine-voice 包，覆盖 Python、Android、iOS、Linux、Windows 和树莓派等平台，通过标准包管理器分发。

1.1 Python 环境（Windows / macOS / Linux）

环境要求：Python 3.8 及以上，依赖 numpy、sounddevice、requests、tqdm 等会自动安装。

安装步骤：

# 创建并激活虚拟环境（推荐）
python -m venv moonshine_env
source moonshine_env/bin/activate  # Linux/macOS
# moonshine_env\Scripts\activate   # Windows

# 安装核心库
pip install moonshine-voice

安装完成后，可通过命令行工具快速测试麦克风实时转录：

python -m moonshine_voice.mic_transcriber --language en

或在代码中调用：

from moonshine_voice import Transcriber, MicTranscriber, download_model

# 下载模型（首次运行自动触发）
download_model(language="en")

# 初始化转录器
transcriber = Transcriber(model_arch="base")

内置命令行工具还包括 moonshine-voice transcribe（转写 WAV 文件）、moonshine-voice tts（文本转语音）和 moonshine-voice download（下载模型资产）。

如果需要 ONNX 运行时后端（适合边缘设备，性能更优）：

uv pip install useful-moonshine-onnx@git+https://gitcode.com/GitHub_Trending/moonshine3/moonshine#subdirectory=moonshine-onnx

首次运行会自动下载约 150MB 的模型文件，默认存储在 ~/.moonshine/models。

1.2 Android 平台

环境要求：Android SDK 21（Android 5.0）及以上，Gradle 7.0+，支持 Kotlin 或 Java。

步骤 1：添加 Maven 依赖

在 gradle/libs.versions.toml 中添加：

[versions]
moonshineVoice = "0.0.49"

[libraries]
moonshine-voice = { group = "ai.moonshine", name = "moonshine-voice", version.ref = "moonshineVoice" }

在 app/build.gradle.kts 中引入：

dependencies {
    implementation(libs.moonshine.voice)
}

步骤 2：添加麦克风权限

在 AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.RECORD_AUDIO" />

步骤 3：添加模型文件

pip install moonshine-voice
python -m moonshine_voice.download --language en
# 将下载的模型文件夹复制到 app/src/main/assets/base-en
cp -r /path/to/downloaded/models app/src/main/assets/base-en

步骤 4：代码中加载模型

MicTranscriber transcriber = new MicTranscriber(this);
transcriber.loadFromAssets(this, "base-en", JNI.MOONSHINE_MODEL_ARCH_BASE);

1.3 iOS / macOS 平台

环境要求：iOS 14.0+，macOS 13.0+，Xcode 13.0+。

安装步骤：

在 Xcode 中，右键点击文件视图侧边栏，选择 “Add Package Dependencies…”，粘贴以下 URL：

https://github.com/moonshine-ai/moonshine-swift/

在 Package.swift 中声明依赖：

// swift-tools-version: 6.1
import PackageDescription

let package = Package(
    name: "YourPackage",
    platforms: [.iOS(.v14), .macOS(.v13)],
    dependencies: [
        .package(url: "https://github.com/moonshine-ai/moonshine-swift/", from: "0.0.49")
    ],
    targets: [
        .target(name: "YourTarget", dependencies: [
            .product(name: "MoonshineVoice", package: "moonshine-swift")
        ])
    ]
)

1.4 树莓派（Raspberry Pi）

环境要求：推荐 Raspberry Pi 4 或 5，内存 ≥ 512MB。

安装步骤：

# 安装 uv（现代 Python 包管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv
source .venv/bin/activate

# 安装 Moonshine
uv pip install moonshine-voice

# 下载模型
python -m moonshine_voice.download --language en

# 测试
python -m moonshine_voice.mic_transcriber --language en

如果在系统级 Python 上安装，可使用 sudo pip install --break-system-packages moonshine-voice。

性能参考：树莓派 4B 上实时转录延迟 < 200ms，tiny 模型约 40MB，base 模型约 120MB。

1.5 Windows C++ 环境

步骤 1：先安装 Python 包用于模型管理：

pip install moonshine-voice

步骤 2：下载 C++ 库和示例项目：

curl -L https://github.com/moonshine-ai/moonshine/releases/latest/download/windows-examples.tar.gz -o windows-examples.tar.gz
tar -xzf windows-examples.tar.gz
cd examples\windows\cli-transcriber
.\download-lib.bat

步骤 3：使用 MSBuild 构建：

msbuild cli-transcriber.sln /p:Configuration=Release /p:Platform=x64

1.6 Web / JavaScript（WASM）

通过 npm 安装 WebAssembly 包：

npm install @moonshine-ai/moonshine-wasm

或在浏览器中直接通过 CDN 引入：

import { MicTranscriber, ModelArch } from 'https://cdn.jsdelivr.net/npm/@moonshine-ai/moonshine-wasm/dist/index.js';

---

二、Vosk 部署安装指南

Vosk 基于 Kaldi 框架，支持 20+ 种语言，提供 Python、Java、C#、Go 等多语言 API。

2.1 Python 环境（Windows / macOS / Linux）

系统依赖：

• Linux：sudo apt-get install libasound2-dev portaudio19-dev python3-pip
• macOS：brew install portaudio
• Windows：下载 PortAudio 二进制文件并配置 PATH

安装步骤：

# 创建虚拟环境
python -m venv vosk_env
source vosk_env/bin/activate  # Linux/macOS
# vosk_env\Scripts\activate   # Windows

# 安装 Vosk
pip install vosk
# 可选：安装音频采集和数值计算库
pip install sounddevice numpy

源码编译安装（适用于模型定制）：

git clone https://github.com/alphacep/vosk-api.git
cd vosk-api/python
python setup.py install

模型下载：Vosk 需要针对目标语言的预训练模型，从官网 https://alphacephei.com/vosk/models 下载。中文模型约 1.2GB，树莓派等嵌入式设备建议使用 small 版本（约 50MB）。

实时识别示例代码：

from vosk import Model, KaldiRecognizer
import pyaudio

model = Model("vosk-model-zh-cn-0.22")
recognizer = KaldiRecognizer(model, 16000)

p = pyaudio.PyAudio()
stream = p.open(format=pyaudio.paInt16, channels=1, rate=16000,
                input=True, frames_per_buffer=4096)

while True:
    data = stream.read(4096)
    if recognizer.AcceptWaveform(data):
        result = recognizer.Result()
        print("识别结果:", result)

音频文件识别示例：

import wave, json
from vosk import Model, KaldiRecognizer

model = Model("vosk-model-cn-0.22")
wf = wave.open("test.wav", "rb")
rec = KaldiRecognizer(model, wf.getframerate())

while True:
    data = wf.readframes(4096)
    if not data:
        break
    if rec.AcceptWaveform(data):
        print(json.loads(rec.Result())["text"])

2.2 Android 平台

环境要求：Android Studio 最新稳定版，NDK（推荐 r25b），最低 API 21。

步骤 1：添加依赖

在 app/build.gradle 中：

dependencies {
    implementation 'com.alphacephei:vosk-android:0.3.45'
}

步骤 2：添加模型文件

从 Vosk 官网下载模型（如 vosk-model-small-cn-0.3），解压后将整个模型文件夹放入 src/main/assets/ 目录。

步骤 3：初始化识别器

import org.vosk.Model;
import org.vosk.Recognizer;

public void initRecognizer(Context context) throws IOException {
    File modelDir = new File(context.getCacheDir(), "vosk-model");
    // 从 assets 复制模型到缓存目录
    Model model = new Model(modelDir.getAbsolutePath());
    Recognizer recognizer = new Recognizer(model, 16000);
}

2.3 iOS 平台

Vosk 在 iOS 上需要手动提供原生框架 LibVosk.xcframework。从官方发布页下载或自行构建后，将 LibVosk.xcframework 放入 ios/Frameworks 目录，并在 Info.plist 中添加麦克风使用描述。

如果使用 Flutter，可通过 vosk_flutter_service 或 vosk_flutter_fixed 插件简化集成：

dart run vosk_flutter_service install -t ios

2.4 树莓派（Raspberry Pi）

Vosk 在树莓派上运行流畅，内存占用低于 200MB，推荐使用 vosk-model-small 系列模型（约 45-50MB）。

安装步骤：

sudo apt update
sudo apt install python3 python3-pip ffmpeg
pip3 install vosk sounddevice

# 下载轻量级英文模型
wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
unzip vosk-model-small-en-us-0.15.zip

2.5 Docker 部署

Vosk 官方提供 Docker 镜像，可一键启动语音识别服务：

docker run -d -p 2700:2700 alphacep/kaldi-vosk-server:latest

也可拉取 alphacep/vosk-api 镜像用于 Python 环境。

---

三、部署优化建议

3.1 模型选择策略

设备类型	Moonshine 模型	Vosk 模型
树莓派 / 嵌入式	tiny（40MB）	small 系列（45-50MB）
移动端（Android/iOS）	base（120MB）	small 系列
PC / 服务器	base 或更大	完整模型（1.2GB+）

3.2 通用优化技巧

• 使用虚拟环境：两个项目都强烈建议在 venv 或 uv 创建的隔离环境中安装，避免依赖冲突。
• 音频采样率一致：初始化识别器时，采样率必须与音频源一致（通常为 16000Hz），否则识别精度会显著下降。
• 缓冲区大小调优：frames_per_buffer 影响实时性与 CPU 占用，建议在树莓派上使用 4096，在 PC 上可适当增大。
• 模型路径管理：Vosk 模型需与代码同目录或指定绝对路径；Moonshine 默认将模型存储在 ~/.moonshine/models，可通过环境变量调整。

3.3 选型

场景	推荐方案	理由
极低延迟实时交互	Moonshine	树莓派上延迟 < 200ms
多语言且模型丰富	Vosk	20+ 语言，模型可定制
端侧移动应用	两者均可	Moonshine 通过 Maven/SPM 集成更简洁
已有 Kaldi 生态	Vosk	基于 Kaldi，可复用现有模型和工具链
快速原型验证	Moonshine	pip install 后即可用命令行测试

---

四、部署路径

Moonshine 和 Vosk 都是优秀的离线 ASR 方案，但部署路径差异明显：Moonshine 通过统一的 moonshine-voice 包覆盖所有平台，安装体验更现代化；Vosk 则依赖 Kaldi 生态，模型资源更丰富，且官方提供 Docker 镜像，适合已有 Kaldi 技术栈的团队。在资源受限的嵌入式场景中，两者都能在树莓派上流畅运行，Moonshine 在延迟方面略有优势，Vosk 在多语言和模型定制方面更为成熟。