# 优谷雅言 SDK 文档

> 优谷雅言语音评测 SDK 的接入指南，接口参考与各端手册，覆盖 Java，安卓，iOS，网页，微信小程序与声通平替层。

## 指南

- [语音评测 SDK](https://open.shengzhiai.com/sdk/v2/index.md)：五端 SDK 与两个声通平替层，覆盖整段评测，实时评测，语音合成与报告查询，内置幂等，重试与断线重连。
- [快速开始](https://open.shengzhiai.com/sdk/v2/quickstart/index.md)：用沙箱密钥完成第一次评测，读出总分，维度分与逐字分数。
- [安装](https://open.shengzhiai.com/sdk/v2/installation/index.md)：各端制品的坐标，仓库地址与版本固定方式，制品仓库匿名只读。
- [鉴权](https://open.shengzhiai.com/sdk/v2/authentication/index.md)：appKey 签名与 token 两种鉴权方式，各端的配置写法与密钥存放位置。
- [沙箱环境](https://open.shengzhiai.com/sdk/v2/sandbox/index.md)：沙箱供接入方联调与 SDK 集成测试使用，与生产使用同一个基址，同一套评测引擎与同一份接口契约，区别只在密钥类型与额度。
- [SDK 架构](https://open.shengzhiai.com/sdk/v2/architecture/index.md)：SDK 的分层结构，各层职责与各端能力对照。
- [评测模式](https://open.shengzhiai.com/sdk/v2/core-types/index.md)：原生与声通兼容两套 coreType，语种，参考文本与各模式的取分字段。
- [整段评测](https://open.shengzhiai.com/sdk/v2/guides/evaluate/index.md)：录完一段音频后整段上传，一次请求拿到评测结果。
- [实时评测](https://open.shengzhiai.com/sdk/v2/guides/streaming/index.md)：边录边传的 WebSocket 会话，状态机，心跳，断线重连与音频缓冲策略。
- [语音合成与报告](https://open.shengzhiai.com/sdk/v2/guides/tts-report/index.md)：合成示范音，按 recordId 查询评测报告。
- [音频与录音](https://open.shengzhiai.com/sdk/v2/guides/audio/index.md)：音频格式要求，上传前预检，内置录音器与外部音频注入。
- [错误处理](https://open.shengzhiai.com/sdk/v2/guides/errors/index.md)：十六个错误类别，异常类型，可重试判定与各端的处理写法。
- [重试与幂等](https://open.shengzhiai.com/sdk/v2/guides/retries/index.md)：自动幂等键，重试策略，退避参数与总时限。
- [生命周期](https://open.shengzhiai.com/sdk/v2/guides/lifecycle/index.md)：客户端，实时会话与录音器的创建，释放与状态查询。
- [日志与指标](https://open.shengzhiai.com/sdk/v2/guides/observability/index.md)：日志级别，自定义日志输出与事件回调。
- [上线检查清单](https://open.shengzhiai.com/sdk/v2/guides/production/index.md)：从沙箱切到生产之前逐项核对的配置与行为。
- [从声通迁移](https://open.shengzhiai.com/sdk/v2/migrate/shengtong/index.md)：已经接入声通 SDK 的项目，换掉声通的依赖即可切换到优谷雅言服务，业务代码不改。安卓与 iOS 各有一个平替层，类名，方法签名，回调，常量值与回调里的结果 JSON 结构都与声通 SDK 一致。
- [升级到 2.0](https://open.shengzhiai.com/sdk/v2/migrate/v2/index.md)：SDK 2.0.0 统一了品牌，包名与仓库坐标，补齐幂等，重试，实时评测断线重连，错误分类，资源释放与状态查询。接口 v1 不变，1.x 版本 SDK 发出的请求在升级后的平台上照常工作。

## SDK

- [SDK 总览](https://open.shengzhiai.com/sdk/v2/sdks/index.md)：七个制品的坐标，运行环境与接口对照。
- [Java SDK](https://open.shengzhiai.com/sdk/v2/sdks/java/index.md)：服务端 Java SDK，封装优谷雅言开放平台的整段评测，声通兼容评测，语音合成，报告查询与实时流式评测。SDK 是推荐的接入方式，直连 REST 与 WebSocket 接口留给没有 SDK 的语言使用。
- [Java SDK 变更记录](https://open.shengzhiai.com/sdk/v2/sdks/java/changelog/index.md)：服务端 Java SDK com.shengzhiai.yugu:yugu-java-sdk 的版本记录。格式遵循 Keep a Changelog，见 https://keepachangelog.com/zh-CN/1.1.0/，版本号遵循语义化版本，见 https://semver.org/lang/zh-CN/。破坏性变更只在主版本号升级时出现，每个版本按新增，变更，修复，破坏性变更分类记录。
- [安卓 SDK](https://open.shengzhiai.com/sdk/v2/sdks/android/index.md)：优谷雅言语音评测的 Android 客户端，Kotlin 编写，Java 可直接调用。SDK 是接入平台的推荐方式，没有 SDK 的语言可按 CONTRACT.md 直连接口。
- [安卓 SDK 变更记录](https://open.shengzhiai.com/sdk/v2/sdks/android/changelog/index.md)：Android 核心 SDK com.shengzhiai.yugu:yugu-android-sdk 的版本记录，格式参照 Keep a Changelog，版本号遵循语义化版本。主版本号变化表示含破坏性变更。
- [iOS SDK](https://open.shengzhiai.com/sdk/v2/sdks/ios/index.md)：优谷雅言语音评测服务的 iOS 与 macOS SDK，提供整段评测，实时评测，语音合成，报告查询，自动重试，幂等键，断线重连，错误分类，音频预检与录音。
- [iOS SDK 变更记录](https://open.shengzhiai.com/sdk/v2/sdks/ios/changelog/index.md)：格式参照 Keep a Changelog，版本号规则见 SDK 总仓库的 COMPATIBILITY.md，由 1 版本升级的步骤见 MIGRATION-2.0.md。
- [网页 SDK](https://open.shengzhiai.com/sdk/v2/sdks/web/index.md)：@shengzhiai/yugu-web-sdk 是优谷雅言语音评测平台的浏览器端 SDK，版本 2.1.1，按 Apache-2.0 许可发布。SDK 是推荐的接入方式，REST 与 WebSocket 直连只作为没有 SDK 的语言的兜底方式。同一个包也可以在 Node.js 18 及以上版本中运行。
- [网页 SDK 变更记录](https://open.shengzhiai.com/sdk/v2/sdks/web/changelog/index.md)：@shengzhiai/yugu-web-sdk 的版本记录，格式参照 Keep a Changelog，版本号遵循语义化版本。每个版本按新增，变更，修复，破坏性变更分类。
- [微信小程序 SDK](https://open.shengzhiai.com/sdk/v2/sdks/miniprogram/index.md)：微信小程序端的优谷雅言语音评测 SDK，封装整段评测，声通兼容评测，实时评测，语音合成与报告查询，内置幂等键，自动重试，断线重连，录音器与音频预检。SDK 为零运行时依赖的 CommonJS 包，附完整 TypeScript 声明。
- [微信小程序 SDK 变更记录](https://open.shengzhiai.com/sdk/v2/sdks/miniprogram/changelog/index.md)：微信小程序 SDK @shengzhiai/yugu-miniprogram-sdk 的变更记录，格式参照 Keep a Changelog，版本号规则见仓库根目录的 COMPATIBILITY.md。
- [安卓声通平替](https://open.shengzhiai.com/sdk/v2/sdks/android-stcompat/index.md)：com.shengzhiai.yugu:stkouyu-compat:2.3.0 是声通 17kouyu_1.0.0.jar 的平替 AAR。com.stkouyu 包中的公共类，接口，方法，字段与常量都与声通 jar 一致，评测在优谷雅言云平台完成。接入方替换依赖，删除 .so 文件之后，原有代码不改动即可编译运行，需要更换的只有 appKey 与 secretKey，服务地址可选。
- [安卓声通平替变更记录](https://open.shengzhiai.com/sdk/v2/sdks/android-stcompat/changelog/index.md)：com.shengzhiai.yugu:stkouyu-compat 的版本记录。格式参照 Keep a Changelog，版本号遵循语义化版本，破坏性变更只在主版本号升级时出现。
- [iOS 声通平替](https://open.shengzhiai.com/sdk/v2/sdks/ios-stcompat/index.md)：STKouyuEngine 是优谷雅言语音评测 SDK 2.0 的 iOS 声通平替包。已经接入声通 STKouyuEngine.framework 的应用，用这个 SwiftPM 包替换声通的 framework 与 libskegn.a，换上优谷雅言的 appKey 与 secretKey，业务代码不改，评测改由优谷雅言云端完成。类名，属性，方法签名，枚举值，常量与代理协议都与声通公开头文件一致，回调里的结果 JSON 与错误 JSON 与安卓平替层一致。
- [iOS 声通平替变更记录](https://open.shengzhiai.com/sdk/v2/sdks/ios-stcompat/changelog/index.md)：STKouyuEngine 声通 iOS 平替包的版本记录。版本号遵循语义化版本，包地址 https://open.shengzhiai.com/git/stkouyu-ios-compat.git。

## 接口参考

- [接口概览](https://open.shengzhiai.com/sdk/v2/api/index.md)：基址，协议，限额与全部接口一览，SDK 与直连调用共用同一份契约。
- [签名与鉴权](https://open.shengzhiai.com/sdk/v2/api/authentication/index.md)：HMAC-SHA256 签名的拼接规则，各接口的被签名参数与跨端测试向量。
- [原生整段评测](https://open.shengzhiai.com/sdk/v2/api/evaluate/index.md)：上传音频与评测参数，返回总分，维度分与逐字逐句详情。
- [声通兼容整段评测](https://open.shengzhiai.com/sdk/v2/api/evaluate-compat/index.md)：路径与参数名沿用声通命名，返回声通风格的结果。
- [语音合成](https://open.shengzhiai.com/sdk/v2/api/tts/index.md)：文本合成为中文或英文语音，返回音频地址。
- [报告查询](https://open.shengzhiai.com/sdk/v2/api/report/index.md)：按 recordId 查询一次评测的报告。
- [原生实时评测](https://open.shengzhiai.com/sdk/v2/api/ws-evaluate/index.md)：一个 WebSocket 连接承载一轮或多轮评测，音频以二进制帧送入，结束后返回终评。
- [声通兼容实时评测](https://open.shengzhiai.com/sdk/v2/api/ws-compat/index.md)：路径与参数帧沿用声通命名，可开启朗读进度。
- [朗读进度](https://open.shengzhiai.com/sdk/v2/api/ws-progress/index.md)：实时评测过程中逐字或逐词返回参考文本是否已读，是否对上。
- [心跳与断线重连](https://open.shengzhiai.com/sdk/v2/api/ws-reconnect/index.md)：心跳方式，重连触发条件，退避与整段重放的语义。
- [幂等](https://open.shengzhiai.com/sdk/v2/api/idempotency/index.md)：幂等键的位置，格式与服务端语义，同一个键只评测一次，只计费一次。
- [重试](https://open.shengzhiai.com/sdk/v2/api/retries/index.md)：可重试的情形，退避公式与总时限。
- [音频要求](https://open.shengzhiai.com/sdk/v2/api/audio/index.md)：格式，时长与大小上限，SDK 上传前的预检项。
- [评测结果字段](https://open.shengzhiai.com/sdk/v2/api/results/index.md)：各评测模式的取分字段，字段名与 CONTRACT.md 和 spec/openapi.yaml 一致。样例为线上真实返回，存放在 spec/fixtures/platform/，五端 SDK 的解析测试逐一覆盖这些样例。分数默认为百分制，scale 参数改变分制后按比例换算。
- [错误码](https://open.shengzhiai.com/sdk/v2/api/errors/index.md)：服务端错误码，音频质量警告码，SDK 本地错误码与声通平替层 errId。
- [平替层回调 JSON](https://open.shengzhiai.com/sdk/v2/api/compat-layer/index.md)：安卓与 iOS 声通平替层在回调里给出的结果 JSON 与错误 JSON。
- [OpenAPI 描述](https://open.shengzhiai.com/sdk/v2/api/openapi/index.md)：用 spec/openapi.yaml 为没有 SDK 的服务端语言生成客户端。

## 资源

- [变更记录](https://open.shengzhiai.com/sdk/v2/changelog/index.md)：格式参照 Keep a Changelog，版本号规则见 COMPATIBILITY.md。各端的详细变更见各端目录下的 CHANGELOG.md。
- [版本兼容](https://open.shengzhiai.com/sdk/v2/compatibility/index.md)
- [制品与下载](https://open.shengzhiai.com/sdk/v2/downloads/index.md)：制品仓库，源码仓库，规范文件与校验和。
- [许可](https://open.shengzhiai.com/sdk/v2/license/index.md)：SDK 源码与文档按 Apache-2.0 许可发布。