# Fun‑ASR 语音识别服务配置说明

硬件参考：x86 + 16核 CPU / 32GB内存 / NVIDIA GeForce RTX 4090 24GB + 256GB磁盘

# 0. 快速部署（一键启动）

单GPU、2‑worker 默认配置，复制直接运行

# 1.拉取镜像
docker pull cdhx78.seeyon.com:5356/library/fun-asr:1.0.0
# 2.镜像重命名
docker tag cdhx78.seeyon.com:5356/library/fun-asr:1.0.0 fun-asr:latest

# 离线导入镜像（内网仓库不可用时二选一）
# docker load -i fun-asr-1.0.0.tar

# 3.启动服务（宿主机GPU 0，端口9914）
docker run -d \
  --gpus '"device=0"' \
  -p 9914:9914 \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_WORKERS=2 \
  -e FUNASR_WORKER_BASE_CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_GPU_MEMORY_UTILIZATION=0.35 \
  --name fun-asr \
  fun-asr:latest

访问地址：http://服务器IP:9914

# 1. 宿主机环境要求（Docker部署）

容器内部已自带 CUDA、cuDNN、Python、PyTorch，宿主机无需额外安装 基础镜像：nvidia/cuda:12.8.1-cudnn-runtime-ubuntu22.04

检查项	要求	校验命令
NVIDIA驱动	≥ 570（支持CUDA 12.8）	`nvidia-smi --query-gpu=driver_version --format=csv,noheader`
NVIDIA Container Toolkit	已安装	`dpkg -l \| grep nvidia-container-toolkit`

# 2. 配置方式说明

所有配置项均为环境变量，可通过 docker run -e 变量名=值 或 docker‑compose environment 段传入容器。

# 语法强制规则

-e 参数等号两侧不能带空格
- ✅ 正确：-e FUNASR_GPU_MEMORY_UTILIZATION=0.45
- ❌ 错误：-e FUNASR_GPU_MEMORY_UTILIZATION = 0.45
仅传入需要修改的配置项，其余自动使用默认值；
默认值来源标记：
- (镜像)：Dockerfile内预置，不传也生效
- (代码)：业务代码内置默认，镜像未预置

# 3. 环境变量完整参考表

# 3.1 GPU / 设备

变量名	默认值	来源	说明
CUDA_VISIBLE_DEVICES	0	镜像	容器内可见GPU编号，需与`--gpus`参数对应
FUNASR_DEVICE	cuda:0	镜像	ASR模型推理设备
FUNASR_WORKER_BASE_CUDA_VISIBLE_DEVICES	0	镜像	多worker模式下GPU分配基准，支持逗号分隔多卡号
NVIDIA_DRIVER_CAPABILITIES	compute,utility	镜像	驱动能力标记，一般无需修改
NVIDIA_VISIBLE_DEVICES	-	compose	docker‑compose部署时由`FUNASR_DOCKER_GPU_0`传入

# 3.2 服务 / 端口

变量名	默认值	来源	说明
FUNASR_HOST	0.0.0.0	镜像	服务监听地址
FUNASR_PORT	9914	镜像	容器内部服务端口
FUNASR_WORKERS	2	镜像	uvicorn worker进程数；多worker自动轮询绑定GPU
FUNASR_PRELOAD_STREAMING	1	代码	启动时预加载流式模型；1=开启，0=关闭（首次请求加载）
FUNASR_LOG_TO_STDOUT	0	代码	日志同时输出至控制台stdout；1=开启，0=关闭

# 3.3 模型路径

变量名	默认值	来源	说明
FUNASR_MODEL	/models/stream_asr/FunAudioLLM/Fun‑ASR‑Nano‑2512	镜像	ASR主模型路径
FUNASR_STREAMING_VAD_MODEL	/models/stream_asr/iic/speech_fsmn_vad_zh‑cn‑16k‑common‑pytorch	镜像	流式VAD模型路径
FUNASR_OFFLINE_VAD_MODEL	/models/stream_asr/iic/speech_fsmn_vad_zh‑cn‑16k‑common‑pytorch	镜像	非流式VAD模型路径
FUNASR_SPK_MODEL	/models/stream_asr/iic/speech_campplus_sv_zh‑cn_16k‑common	镜像	说话人识别模型路径
FUNASR_HUB	ms	代码	模型下载源；ms=ModelScope
FUNASR_HOTWORD_FILE	/app/热词列表	镜像	热词文件路径，每行一个热词
FUNASR_LANGUAGE	""	镜像	识别语言；代码默认值：中文

# 3.4 推理参数

变量名	默认值	来源	说明
FUNASR_DTYPE	bf16	镜像	推理精度；可选 bf16 / fp16 / fp32
FUNASR_TENSOR_PARALLEL_SIZE	1	代码	vLLM张量并行数
FUNASR_GPU_MEMORY_UTILIZATION	0.35	镜像	单worker vLLM显存占用上限比例
FUNASR_MAX_MODEL_LEN	2048	代码	模型最大上下文token长度
FUNASR_MAX_CONCURRENT_GENERATE	1	镜像	generate并发数，FunASR‑vLLM需串行，强制为1

# 3.5 流式识别参数

变量名	默认值	来源	说明
FUNASR_STREAM_ROLLBACK_CHARS	8	镜像	partial稳定回退字符数，避免末尾识别抖动
FUNASR_STREAM_CONTEXT_WARMUP_CHUNKS	10	镜像	上下文预热chunk数，超过后启用prev_text
FUNASR_STREAM_USE_CONTEXT	1	镜像	是否开启partial上下文稳定策略；1=开启，0=关闭
FUNASR_DECODE_INTERVAL	0.48	代码	无新锁定分句时最小解码间隔，单位：秒

# 3.6 日志 / 存储

变量名	默认值	来源	说明
FUNASR_LOG_DIR	/app/logs	镜像	日志存放目录
FUNASR_LOG_RETENTION_DAYS	7	镜像	日志保留天数，到期自动清理旧文件
FUNASR_TASK_STORE_DB	/app/logs/task_store.sqlite3	镜像	非流式任务SQLite数据库路径
TRANSCRIPTION_WORKERS	1	代码	非流式转写后台线程池大小

# 4. 接口说明

# 4.1 接口端点汇总

接口类型	请求方式	地址	用途
健康检查	GET	`http://服务器IP:9914/health`	服务存活探测
前端测试页	GET	`http://服务器IP:9914/client_mic.html`	浏览器麦克风测试页面
提交非流式任务	POST	`http://服务器IP:9914/comi_ai_service/transcription`	上传音频发起转写
查询任务状态	GET	`http://服务器IP:9914/comi_ai_service/transcription/status?uid={uid}&recordId={recordId}`	轮询任务进度
获取转写结果	GET	`http://服务器IP:9914/comi_ai_service/transcription/result?uid={uid}&recordId={recordId}`	取回识别结果，取完自动删除任务记录
流式实时转写	WebSocket	`ws://服务器IP:9914/comi_ai_service/transcription/stream`	长连接实时语音识别

# 4.2 非流式接口请求体示例

{
    "uid": "用户id",
    "recordId": "录音id",
    "recordUrl": "音频URL或本地路径",
    "hotword": "热词1,热词2"
}

任务状态流转：pending → processing → finished / failed

# 4.3 流式WebSocket协议流程

客户端连接成功，发送启动帧

{
    "type":"start",
    "uid":"用户id",
    "recordId":"录音id",
    "sampleRate":16000,
    "channels":1,
    "format":"pcm_s16le",
    "chunkMs":720,
    "enableSpeaker":true,
    "hotword":"热词",
    "language":"中文"
}

服务端应答：{"type":"started","ok":true,...}
客户端持续发送二进制PCM音频分片（16kHz mono s16le）
服务端持续推送 partial / segment / speech_end 识别事件
客户端发送停止帧 {"type":"stop"} 结束会话，服务端返回 completed + stopped
心跳保活：客户端发送 {"type":"ping"}，服务端返回 {"type":"pong"}

# 5. Docker‑Compose 部署示例

# 可通过环境变量控制参数（.env / export）

环境变量	默认值	说明
FUNASR_DOCKER_PORT	9914	宿主机映射端口
FUNASR_DOCKER_GPU_0	4	使用GPU卡号
FUNASR_DOCKER_WORKERS	2	worker进程数量
FUNASR_DOCKER_GPU_MEMORY_UTILIZATION	0.35	显存占用比例

# 示例1：默认启动（GPU 4，2 worker）

docker compose up -d

# 示例2：自定义端口、GPU、worker、显存比例

FUNASR_DOCKER_PORT=19914 \
FUNASR_DOCKER_GPU_0=6 \
docker compose up -d

# 示例3：双卡4、5 + 4 worker配置片段（docker‑compose.yml）

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ["4", "5"]
          capabilities: [gpu]
environment:
  NVIDIA_VISIBLE_DEVICES: "4,5"
  CUDA_VISIBLE_DEVICES: "0,1"
  FUNASR_WORKER_BASE_CUDA_VISIBLE_DEVICES: "0,1"
  FUNASR_WORKERS: "4"

多worker启动后自动按 worker_index % len(devices) 轮询分配GPU

# 6. docker run 启动示例

# 示例1：GPU 0，1 worker

docker run -d \
  --gpus '"device=0"' \
  -p 9914:9914 \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_WORKERS=1 \
  -e FUNASR_WORKER_BASE_CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_GPU_MEMORY_UTILIZATION=0.85 \
  --name fun-asr \
  fun-asr:latest

# 示例2：GPU 4，2 worker（默认推荐）

docker run -d \
  --gpus '"device=4"' \
  -p 9914:9914 \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_WORKERS=2 \
  -e FUNASR_WORKER_BASE_CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_GPU_MEMORY_UTILIZATION=0.35 \
  --name fun-asr \
  fun-asr:latest

# 示例3：双卡 4,5，4 worker

docker run -d \
  --gpus '"device=4,5"' \
  -p 9914:9914 \
  -e CUDA_VISIBLE_DEVICES=0,1 \
  -e FUNASR_WORKERS=4 \
  -e FUNASR_WORKER_BASE_CUDA_VISIBLE_DEVICES=0,1 \
  -e FUNASR_GPU_MEMORY_UTILIZATION=0.45 \
  --name fun-asr \
  fun-asr:latest

# 示例4：修改宿主机映射端口（宿主机19914 → 容器9914）

docker run -d \
  --gpus '"device=4"' \
  -p 19914:9914 \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_WORKERS=2 \
  --name fun-asr \
  fun-asr:latest

访问地址：http://服务器IP:19914

# 示例5：关闭启动预加载模型，首次请求加载

docker run -d \
  --gpus '"device=4"' \
  -p 9914:9914 \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e FUNASR_WORKERS=1 \
  -e FUNASR_PRELOAD_STREAMING=0 \
  --name fun-asr \
  fun-asr:latest

编撰人：jiangtw

快速跳转

Fun‑ASR 语音识别服务配置说明

← TTS docker部署文档 CoMi V2.0.2环境准备指导手册 →

# Fun‑ASR 语音识别服务 配置说明