SenseVoice ASR（语音转写）

SenseVoice ASR 是基于 SenseVoice.cpp 封装的语音转文本服务，算力舱中的服务域名为 asr-ai。它提供一个 OpenAI Audio API 风格的转写入口，适合后端服务、前端应用或脚本通过 HTTP 上传音频文件并获得转写文本。

服务入口

• API 文档：
• 服务地址：
• 健康检查：
• 转写接口：

部署到算力舱后的访问形式：

• 服务地址：https://asr-ai.${LAZYCAT_BOX_DOMAIN}
• API 文档：https://asr-ai.${LAZYCAT_BOX_DOMAIN}/docs
• 健康检查：https://asr-ai.${LAZYCAT_BOX_DOMAIN}/health
• 转写接口：https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions

健康检查

GET /health

该接口用于确认 ASR HTTP 服务可用。

请求：

curl https://asr-ai.${LAZYCAT_BOX_DOMAIN}/health

响应示例：

{
  "status": "ok"
}

转写接口

POST /v1/audio/transcriptions

该接口接收一个音频文件并返回转写结果。请求必须使用 multipart/form-data。

服务会先用 ffmpeg 将上传音频转换为 16 kHz、单声道 wav，再执行 SenseVoice 推理。因此实际可用格式取决于镜像内 ffmpeg 可解码的音频格式，常见的 wav、mp3、m4a、mp4、webm、flac、ogg 通常都可以直接上传。

请求参数

参数	类型	必填	说明
file	file	是	待转写音频文件
language	string	否	语音语言，默认 auto。支持 auto / zh / en / ja / ko / yue，非法值会按 auto 处理
response_format	string	否	默认 json。传 text 返回纯文本；传其他值时返回 JSON
token_timestamps	string	否	传 true 时在分段结果中包含 words 时间戳信息
split_on_word	string	否	传 true 时同样包含 words 时间戳信息

当前服务不提供 srt / vtt 字幕输出，也不提供 progress / progress_format 进度事件流。需要字幕时建议拿 JSON 中的 segments 自行生成。

输出格式

response_format	Content-Type	说明
json	application/json	默认格式，包含 text 和 segments
verbose_json	application/json	兼容常见调用习惯，实际返回同一类 JSON 结构
text	text/plain; charset=utf-8	只返回转写文本

JSON 响应示例：

{
  "text": "欢迎使用算力舱语音转写服务。",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 2.4,
      "text": "欢迎使用算力舱语音转写服务。"
    }
  ]
}

开启 token_timestamps=true 或 split_on_word=true 后，segments 中会额外包含 words：

{
  "id": 0,
  "start": 0.0,
  "end": 2.4,
  "text": "欢迎使用算力舱语音转写服务。",
  "words": [
    {
      "word": "欢迎",
      "text": "欢迎",
      "start": 0.12,
      "end": 0.42,
      "probability": 0.98
    }
  ]
}

错误响应示例：

{
  "error": "multipart field 'file' is required"
}

常见错误：

HTTP 状态码	场景
400	未使用 multipart/form-data、缺少 file 字段，或 ffmpeg 无法转换上传音频
500	临时文件写入失败

调用示例

JSON 转写

curl -fsS -X POST "https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "language=auto" \
  -F "response_format=json"

纯文本转写

curl -fsS -X POST "https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "response_format=text"

带时间戳转写

curl -fsS -X POST "https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "language=zh" \
  -F "token_timestamps=true"

推荐调用流程

1. 准备音频文件，视频文件建议先抽取音频再上传。
2. 以 multipart/form-data 上传到 /v1/audio/transcriptions。
3. language 不确定时传 auto；已知语言时传 zh / en / ja / ko / yue。
4. 需要程序处理分段时使用默认 JSON；只需要展示文本时使用 response_format=text。
5. 需要词级时间戳时传 token_timestamps=true 或 split_on_word=true。

后端环境变量

在依赖 ASR 的业务服务中，可以将 ASR 基地址配置为：

services:
  convert:
    environment:
      - ASR_URL=https://asr-ai.${LAZYCAT_BOX_DOMAIN}
      - HOMEDIR=/lzcapp/run/mnt/home

• ASR_URL：ASR 服务基地址，业务代码再拼接 /v1/audio/transcriptions。
• HOMEDIR：业务文件读写根路径，按应用需要配置。

前端匹配 asr-ai 域名

const asrUrl = (path = "/v1/audio/transcriptions") => {
  const currentHost = window.location.host;
  const protocol = window.location.protocol;
  const host = currentHost.replace(/^([^.]+)/, "asr-ai");

  return `${protocol}//${host}${path}`;
};

单独部署使用

根据设备选择对应镜像。AGX Orin 使用 -agxorin 镜像，Thor T5000 使用 -thor 镜像。

AGX Orin

services:
  asr:
    image: registry.lazycat.cloud/catdogai/lzc-aipod-sensevoiceasr:0.2.0-sensevoice-small-q4k-agxorin
    ports:
      - 3000:3000
    environment:
      - PORT=3000
      - SENSEVOICE_MODEL=/opt/sensevoice-models/sense-voice-small-q4_k.gguf
      - SENSEVOICE_LANGUAGE=auto
      - SENSEVOICE_THREADS=4
      - SENSEVOICE_USE_ITN=true
      - OMP_NUM_THREADS=1
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 30s
      retries: 100
      start_period: 30s

Thor T5000

services:
  asr:
    image: registry.lazycat.cloud/catdogai/lzc-aipod-sensevoiceasr:0.2.0-sensevoice-small-q4k-thor
    ports:
      - 3000:3000
    environment:
      - PORT=3000
      - SENSEVOICE_MODEL=/opt/sensevoice-models/sense-voice-small-q4_k.gguf
      - SENSEVOICE_LANGUAGE=auto
      - SENSEVOICE_THREADS=4
      - SENSEVOICE_USE_ITN=true
      - OMP_NUM_THREADS=1
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 30s
      retries: 100
      start_period: 30s

启动：

docker compose up -d
curl http://127.0.0.1:3000/health

启动后可访问 http://127.0.0.1:3000/docs 查看服务内置 API 文档。

服务环境变量

变量	默认值	说明
PORT	3000	HTTP 监听端口
SENSEVOICE_MODEL	/opt/sensevoice-models/sense-voice-small-q4_k.gguf	SenseVoice GGUF 模型路径
SENSEVOICE_LANGUAGE	auto	默认识别语言
SENSEVOICE_THREADS	4	推理线程数
SENSEVOICE_USE_GPU	true	是否启用 GPU
SENSEVOICE_USE_ITN	true	是否启用逆文本正则化，包含标点处理
SENSEVOICE_USE_PREFIX	false	是否输出 SenseVoice 前缀信息
OMP_NUM_THREADS	1	OpenMP 线程数

相关服务

• SenseVoice ASR 默认启用 SENSEVOICE_USE_ITN=true，会进行文本规范化和标点处理。