sherpa-onnx 基于 Gradle Kotlin DSL（KTS）的 Java 示例构建与运行指南

sherpa-onnx 基于 Gradle Kotlin DSLKTS的 Java 示例构建与运行指南【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx本指南围绕 sherpa-onnx 仓库中的 gradle-kts-examples 目录 展开讲解如何用 Gradle Kotlin DSLbuild.gradle.kts在 macOS、Linux、Windows 上构建并运行 sherpa-onnx 的 Java API 示例。读完本文你将掌握构建脚本如何在构建时自动探测操作系统与 CPU 架构并拉取对应平台的 native 库、如何通过 JitPack 声明 JVM 核心 API 与平台 native 库两类依赖、如何用 Gradle Wrapper 一键build/run以及底层版本查询 API 的实现原理。前置条件运行本示例需要满足以下环境要求JDK 8 或以上构建脚本通过java { sourceCompatibility JavaVersion.VERSION_1_8; targetCompatibility JavaVersion.VERSION_1_8 }将编译目标锁定为 Java 8因此使用 JDK 8 均可正常编译运行仓库根目录的 jitpack.yml 中 CI 使用 OpenJDK 17 构建发布物。Gradle 8.x 以上推荐直接使用目录内自带的 Gradle Wrapper./gradlew无需在系统上单独安装 Gradle。仓库内 gradle-wrapper.properties 锁定的分发版本为gradle-9.6.1-bin.zipgradlew会自动下载对应版本。示例项目结构java-api-examples/gradle-kts-examples/ ├── build.gradle.kts # Kotlin DSL 构建脚本核心 ├── settings.gradle.kts # rootProject.name sherpa-onnx-gradle-kts-example ├── gradlew / gradlew.bat # Gradle Wrapper 启动脚本Unix / Windows ├── gradle/wrapper/ # Wrapper 配置与 jar └── src/main/java/com/k2fsa/sherpa/onnx/example/ └── VersionTest.java # 示例入口打印 sherpa-onnx 版本信息其中 settings.gradle.kts 仅声明了项目名sherpa-onnx-gradle-kts-examplebuild.gradle.kts 承担了平台探测、依赖声明、应用入口与 fat jar 打包的全部逻辑。核心机制构建期自动探测 OS 与架构这是整个示例最具实用价值的部分——无需手动指定平台构建脚本会在配置阶段读取 JVM 系统属性自动选择对应的 native 库 artifact。build.gradle.kts 中的探测逻辑如下// Auto-detect current OS and architecture val osName System.getProperty(os.name).lowercase() val osArch System.getProperty(os.arch).lowercase() val targetNativeClassifier when { osName.contains(mac) || osName.contains(darwin) - { if (osArch aarch64 || osArch arm64) osx-aarch64 else osx-x64 } osName.contains(linux) - { if (osArch aarch64 || osArch arm64) linux-aarch64 else linux-x64 } osName.contains(win) - { if (osArch aarch64 || osArch arm64) win-arm64 else win-x64 } else - throw GradleException(Unsupported OS: $osName, Arch: $osArch) }要点解读System.getProperty(os.name)与System.getProperty(os.arch)是 JVM 标准系统属性Gradle 守护进程运行在哪个平台就能探测到哪个平台的取值macOS 同时兼容mac与darwin两种命名ARM 架构同时兼容aarch64与arm64两种写法Apple Silicon 与 Linux/Windows ARM 环境的实际取值可能不同六种组合分别映射到六个 native classifierosx-aarch64、osx-x64、linux-x64、linux-aarch64、win-x64、win-arm64无法识别的平台直接抛出GradleException(Unsupported OS: ...)避免后续下载错误 artifact。探测完成后脚本通过logger.lifecycle(-- Auto-detected platform native lib: $targetNativeClassifier)在构建日志中打印结果。这带来了三个实际收益零手工配置./gradlew build一条命令即可不需要按平台修改脚本跨平台可移植同一份build.gradle.kts在 macOS、Linux、Windows x64 / ARM64 上行为一致无需维护 CI 脚本平台相关的分支全部收敛在构建文件内部不同 CI 机器拉取的是各自平台对应的 native 库。依赖管理JitPack 双模块设计项目通过JitPack仓库获取 sherpa-onnx 的预编译 Java 发布物。仓库声明如下build.gradle.ktsrepositories { mavenCentral() maven { url uri(https://jitpack.io) } }依赖采用JVM 核心 API 平台 native 库的双模块拆分方式build.gradle.ktsdependencies { // 1. JVM core API implementation(com.github.k2-fsa.sherpa-onnx:sherpa-onnx-jvm:v1.13.7) // 2. Platform native lib (auto-detected) implementation(com.github.k2-fsa.sherpa-onnx:sherpa-onnx-native-lib-$targetNativeClassifier:v1.13.7) }这种拆分的意义在于sherpa-onnx-jvm只包含纯 Java/JNI 绑定代码即 sherpa-onnx/java-api 目录下的 Java 类sherpa-onnx-native-lib-*按平台拆分每个 artifact 只携带一个平台的动态库.so/.dylib/.dll配合上文的自动探测变量$targetNativeClassifier精确命中当前平台。仓库根目录的 jitpack.yml 从侧面印证了这套发布结构JitPack 构建时会将sherpa-onnx-jvm-1.13.7.jar与sherpa-onnx-native-lib-{linux-aarch64, linux-x64, osx-aarch64, osx-x64, win-x64, win-arm64}-1.13.7.jar共 6 个平台包逐一安装到本地 Maven 仓库之后 Gradle 即可通过com.github.k2-fsa.sherpa-onnx坐标解析到它们。与之对比gradle-examples 目录 中的 Groovy 版还介绍了单依赖写法implementation com.github.k2-fsa:sherpa-onnx:v1.13.7一个 AAR 包含全部平台 native 库其 README 给出了实测差异单依赖打出的 fat jar 压缩后约 95 MB而双模块按平台拆分后仅约 9 MB体积相差约 10 倍。本 KTS 示例采用的就是这种更轻量的双模块方案。构建与运行进入示例目录后使用 Gradle Wrapper推荐或系统 Gradle 均可cd java-api-examples/gradle-kts-examples # 使用 Gradle Wrapper推荐 ./gradlew build # 或使用系统安装的 Gradle gradle build构建过程中日志会打印自动探测到的平台例如-- Auto-detected platform native lib: osx-aarch64运行示例同样支持 Wrapper 与系统 Gradle 两种方式# 使用 Gradle Wrapper推荐 ./gradlew run # 或使用系统安装的 Gradle gradle runapplication插件已通过mainClass.set(com.k2fsa.sherpa.onnx.example.VersionTest)指定了启动类build.gradle.kts因此run任务会直接执行示例程序。预期输出sherpa-onnx version: x.y.z sherpa-onnx gitSha1: ... sherpa-onnx gitDate: ...示例代码与底层版本 API示例入口是 VersionTest.java它通过com.k2fsa.sherpa.onnx.VersionInfo打印四条版本信息public class VersionTest { public static void main(String[] args) { System.out.printf(sherpa-onnx version: %s\n, VersionInfo.getVersion()); System.out.printf(sherpa-onnx gitSha1: %s\n, VersionInfo.getGitSha1()); System.out.printf(sherpa-onnx gitDate: %s\n, VersionInfo.getGitDate()); System.out.printf(onnxruntime version: %s\n, VersionInfo.getOnnxruntimeVersion()); } }对应地VersionInfo.java 是 Java 侧的薄封装每个静态方法首先调用LibraryLoader.maybeLoad()触发 JNI 本地库的按需加载再委托给private static native方法getVersionStr2()、getGitSha12()、getGitDate2()、getOnnxruntimeVersionStr2()最终由 C 层返回字符串。这也解释了为何该示例必须同时依赖 JVM 核心 API 与平台 native 库——run一旦调用VersionInfoJNI 动态库就必须已经通过sherpa-onnx-native-lib-*依赖进入 classpath。可独立分发的 fat jar 打包除了runbuild.gradle.kts 还定义了jar任务将运行时 classpath 中的全部依赖含 native 库解包合并进单个可执行 jartasks.jar { manifest { attributes(Main-Class to com.k2fsa.sherpa.onnx.example.VersionTest) } duplicatesStrategy DuplicatesStrategy.EXCLUDE from(configurations.runtimeClasspath.get().map { if (it.isDirectory) it else zipTree(it) }) }要点manifest 中写入Main-Class与application.mainClass保持一致使产物可直接java -jar运行duplicatesStrategy DuplicatesStrategy.EXCLUDE用于规避多个依赖 jar 解包后可能出现的资源冲突例如META-INF下的签名文件、服务描述文件由于依赖只包含当前平台的 native 库打包出的 fat jar 只携带当前平台的.so/.dylib/.dll体积更小。支持平台与 artifact 对照自动探测机制覆盖以下六种平台组合平台架构对应 native artifactmacOSARM64Apple Siliconsherpa-onnx-native-lib-osx-aarch64macOSx64Intelsherpa-onnx-native-lib-osx-x64Linuxx64sherpa-onnx-native-lib-linux-x64LinuxARM64sherpa-onnx-native-lib-linux-aarch64Windowsx64sherpa-onnx-native-lib-win-x64WindowsARM64sherpa-onnx-native-lib-win-arm64版本号v1.13.7与这些 artifact 的对应关系可以从 jitpack.yml 中得到验证——该文件中每个平台包均以1.13.7版本发布到 JitPack 坐标体系。Groovy 与 Kotlin DSL 对比同一套逻辑在仓库内还存在 gradle-examplesGroovybuild.gradle与本目录Kotlin DSLbuild.gradle.kts两个版本核心差异如下特性Groovybuild.gradleKotlin DSLbuild.gradle.kts语法动态、简洁静态、类型安全IDE 支持一般优秀自动补全、重构支持字符串单引号...或双引号...仅双引号...方法调用implementation ...implementation(...)属性赋值mainClass ...mainClass.set(...)适用场景遗留项目新项目对新建项目而言Kotlin DSL 的类型检查能在配置阶段尽早暴露拼写错误配合 IDE 补全体验更好这也是本示例选择build.gradle.kts的原因。进一步阅读java-api-examples 总览 README仓库内全部 Java 示例的索引ASR、TTS、VAD、说话人识别、音频打标等可参照本指南的依赖方式运行其他示例gradle-examples/README.mdGroovy 版构建说明包含单依赖与双模块两种方案的 fat jar 体积对比数据maven-examples使用 Maven 而非 Gradle 的等效示例适合 Maven 项目参考VersionInfo.java版本查询 API 的 Java/JNI 封装源码jitpack.ymlJitPack 侧构建配置说明sherpa-onnx-jvm与六个平台 native 包如何被发布与消费。以上文件均位于当前仓库内可对照阅读以完整理解 sherpa-onnx 的 Java 构建链路。【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考