前一阵子需要给团队搭一套语音识别服务对比了几个开源方案之后最后还是选了阿里达摩院的FunASR。这框架本身的识别效果确实能打尤其是中文场景下扛住了不少实际业务的折腾。但真正让我印象深刻的反而是部署这一步——如果你打算从源码开始编译安装那恭喜你光依赖就能磨掉你小半天torch、torchaudio、modelscope、各种runtime库一个一个来版本稍微一抖就能让你怀疑人生。所以这次我直接用docker来部署整个过程比预想中顺畅太多。这篇文章就从头到尾记录一下我用Docker部署FunASR的完整过程包括环境准备、镜像拉取、容器启动、服务调用、GPU加速、常见坑和排查思路基本属于一篇可以直接照着抄的作业。不管你是第一次接触语音识别还是已经在其他地方踩过源码安装的坑跟着这篇文章走大概率能少走不少弯路。1. 部署前先搞清楚FunASR是什么为什么偏要用Docker1.1 FunASR能干什么FunASR是阿里达摩院开源的一个语音识别工具包底层核心模型是Paraformer同时配套了标点恢复、时间戳、VAD语音活动检测、说话人分离等一系列能力。它不只支持离线音频文件的批量识别也支持流式语音识别也就是边说边出结果。这个特性在语音输入法、会议转写、客服质检、智能硬件交互这类场景里非常实用。它的模型体系比较完整中文普通话识别精度在开源方案里属于第一梯队而且支持中文方言和一些英文场景的混合识别。更友好的是FunASR官方提供了runtime版本的Docker镜像镜像里已经预装好了模型推理所需的环境和依赖你只需要处理音频输入和结果解析不用关心模型加载、资源调度这些底层逻辑。1.2 为什么推荐Docker部署很多人第一反应是我直接在服务器上pip install funasr然后跑Python脚本不就行了对于简单的离线识别、自己开发调试来说这条路确实可以。但如果你要做的是服务化部署考虑并发、长期稳定性、多模型切换源码部署会有一堆问题等着你。最头疼的是环境依赖。FunASR不仅有Python层的依赖还有C runtime依赖比如ffmpeg、gcc、各种音频解码库以及不同CUDA版本的适配。你在一台机器上好不容易配好了换一台机器又得重新来一遍。版本一旦升级我见过有人直接把整个Python环境搞崩的。Docker的优势就在这里镜像把操作系统、CUDA、Python库、模型文件、服务代码全打成一个黑盒你拉下来就能跑。团队协作也方便开发环境、测试环境、生产环境用同一个镜像行为完全一致。加上docker-compose编排扩缩容也简单。1.3 部署形态选择CPU版还是GPU版FunASR的runtime Docker镜像分CPU和GPU两个版本。CPU版本门槛低几乎所有x86服务器都能跑缺点是识别速度受限于CPU算力。GPU版本需要NVIDIA显卡和nvidia-container-toolkit支持速度快得多适合并发要求高的场景。我的建议如果只是自己测试、小流量内部工具先上CPU版。把整个流程跑通再切GPU版本优化性能也不迟。如果一开始就直接上GPU遇到环境问题反而容易分不清是CUDA的问题还是FunASR本身的问题。我先在这台机器上用的是CPU版后面拿到带GPU的机器又切了一次两个都验证过了。2. 环境准备与基础检查2.1 Docker环境安装既然要用Docker部署第一步当然是准备Docker环境。系统环境是CentOS 7.9内核3.10那套老古董。说实话CentOS 7自带的yum源里Docker版本很老建议用官方源或者国内镜像源安装新版。安装过程我建议直接用阿里云的镜像源sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo sudo yum install -y docker-ce docker-ce-cli containerd.io sudo systemctl start docker sudo systemctl enable docker docker version如果你用的是Ubuntu过程也类似把repo换一下就行。Windows系统的话装Docker Desktop即可但需要注意硬件虚拟化必须开启这个后面在常见问题里详细说。这里有个小细节装完Docker之后先跑一下sudo docker run hello-world确认整个链路是通的。很多问题都出在Docker本身没装好却跑去排查FunASR这是典型的排查顺序错误。2.2 Docker权限、网络与加速配置装好Docker后的第一个坑就是权限普通用户跑docker ps直接报permission denied while trying to connect to the docker api at unix:///var/run/docker.sock。这是因为docker.sock的所有者是root普通用户没权限。解决方案有两个# 方案一把当前用户加入docker组 sudo usermod -aG docker $USER newgrp docker # 方案二如果公司环境不允许改组使用时加sudo sudo docker ps方案一更好用但是注意加入docker组之后一定要重新登录或者执行newgrp否则当前会话不会生效。另外从安全角度说docker组内的用户等同于拥有root权限生产环境要谨慎。再说网络。国内拉官方镜像仓库的速度真的很感人所以必须配置registry mirror。修改/etc/docker/daemon.json没有这个文件就创建一个{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com ] }改完重启Dockersudo systemctl restart docker。如果镜像源本身不稳定直接访问阿里云容器镜像服务的专属加速地址也行每个用户有一个独立的加速URL。2.3 确认端口和存储空间FunASR runtime服务默认监听10095端口部署前先确认这个端口没有被占用sudo lsof -i:10095 sudo netstat -tlnp | grep 10095如果被占用了后面启动容器时可以用-p 10096:10095这种形式做端口映射。磁盘空间也要注意。FunASR的镜像本身大约3到5个G模型的体积取决于你的选择Paraformer大模型大概1G多如果还有标点模型、VAD模型加起来可能超过3个G。建议预留20G以上空间避免模型下载到一半硬盘满了。3. 完整实操从拉取镜像到跑通第一个识别任务3.1 拉取镜像FunASR官方把镜像放在阿里云的容器镜像服务上共用镜像地址是registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasrCPU版本对应的tag是funasr-runtime-sdk-cpu-0.1.0。docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.1.0这一步如果很慢除了依赖前面说的mirror配置还可以试试直接在阿里云服务器上操作走内网拉取。我在本地开发机上用公网拉这个镜像1到2个G的数据大概花了几分钟还在可接受范围内。拉取完成后用docker images确认一下镜像已经存在。3.2 启动容器镜像拿到手接下来就是启动容器。这里有一个关键点你最好把模型目录挂载出来这样以后模型升级、替换或者容器重建的时候不需要重新下载模型文件。启动命令docker run -it \ --name funasr \ -p 10095:10095 \ -v /data/funasr/models:/workspace/models \ registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.1.0解释一下参数--name funasr容器名称后面管理容器方便。-p 10095:10095宿主机10095端口映射到容器内的10095端口。-v /data/funasr/models:/workspace/models宿主机models目录挂载到容器内。这是整个操作里我最推荐保留的一步。启动后你会直接进入到容器内的bash环境因为镜像默认的启动命令就是/bin/bash。如果不想交互式进入容器可以用-d参数后台运行但第一次部署我还是建议交互式跑方便在前台看日志。3.3 启动服务与模型下载进入容器后我们需要在容器内启动FunASR服务。先看一下目录结构cd /workspace/FunASR/runtime ls -l这里面有server.sh这个启动脚本。但直接跑之前要先想好模型从哪来。官方镜像默认带了一些模型配置但我在实际部署中遇到的情况是镜像里的模型文件不完整首次启动时脚本会自动从ModelScope下载这个下载过程在网络不好的时候极其折磨。我的做法是先启动一次服务让它尝试下载模型同时观察日志里模型下载到了哪个目录。等模型下载完成把对应的目录整个复制出来。下次重建容器的时候用-v挂载宿主机上已经准备好的模型目录就不会再触发下载。具体到启动服务直接在容器内执行cd /workspace/FunASR/runtime nohup bash server.sh server.log 21 启动之后立即跟踪日志tail -f server.log等日志中出现类似listening on 0.0.0.0:10095的输出说明服务已经起来了。这时候在宿主机上测试端口连通性curl http://127.0.0.1:10095如果返回错误信息但连接没被拒说明服务确实在监听只是没有带正确的参数。3.4 测试识别效果验证服务是否可用简单的方式是直接在浏览器访问http://服务器IP:10095你会看到一个简单的测试页面。或者用curl构造一个上传音频的请求curl -F audio/path/to/test.wav -F languagezh-cn http://127.0.0.1:10095这个接口需要16kHz采样率、16bit编码、单声道的wav文件。如果你的音频是44.1kHz的MP3需要先转一下ffmpeg -i source.mp3 -ar 16000 -ac 1 -sample_fmt s16 test.wav我第一次测试时直接用了原声频道的MP3接口返回了一堆乱码后来才发现是采样率不对。这个细节务必注意。返回结果是一个JSON里面包含识别文本和关键信息。如果识别结果乱码或者为空多半是音频格式问题。另外语言参数要正确中文用zh-cn英文用en。3.5 docker-compose部署方式如果希望整个部署流程更规范还可以用docker-compose来管理。下面这个compose文件可以参考version: 3 services: funasr: image: registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.1.0 container_name: funasr ports: - 10095:10095 volumes: - /data/funasr/models:/workspace/models environment: - TZAsia/Shanghai restart: always command: bash /workspace/FunASR/runtime/server.sh注意这个compose文件的写法省略了-it交互参数所以需要把启动命令直接写在command里让服务以前台方式运行。否则容器会因为没有主进程而直接退出。4. 进阶玩法GPU加速、模型切换与性能调优4.1 GPU容器部署如果识别量大、时延要求高CPU版可能撑不住。FunASR官方也提供了GPU版本镜像tag是funasr-runtime-sdk-gpu-0.1.0。启动GPU容器需要先在宿主机装好NVIDIA驱动和nvidia-container-toolkit。检查驱动的命令nvidia-smi如果命令可用说明驱动正常。接着安装nvidia-container-toolkitdistribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker之后启动容器加--gpus all参数docker run -it \ --name funasr-gpu \ --gpus all \ -p 10095:10095 \ -v /data/funasr/models:/workspace/models \ registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-gpu-0.1.0进入容器后先用nvidia-smi确认GPU在容器内可见。如果命令不存在说明镜像没装GPU工具如果命令存在但显示无GPU说明toolkit没配置好。这两种情况分别处理。GPU模式下识别速度提升非常明显。以一段5分钟的音频为例CPU版可能需要几十秒GPU版在普通显卡上只需要几秒。但要注意GPU版对显存有要求模型默认会占用2到4个G的显存如果显存不够需要调整模型参数。4.2 更换和自定义模型FunASR最灵活的地方在于模型可替换。默认的Paraformer模型可能不是最优选择比如方言场景、英文场景都有专门的模型。在runtime环境中模型是通过配置文件指定的。在容器内查看ls /workspace/FunASR/runtime/resources/不同模型对应不同的配置目录。如果你想切换模型思路是把新的模型文件手动放到/workspace/models对应目录然后修改server.sh里的模型路径参数重启服务。这里有一个实用技巧可以用modelscope的命令行直接下载模型。比如下载一个指定模型# 在容器内执行先安装modelscope镜像里已预装 python -c from modelscope.hub.snapshot_download import snapshot_download; snapshot_download(模型ID, cache_dir/workspace/models)具体下载哪个模型去ModelScope官网搜索即可。注意模型ID一定要对应runtime版本支持的范围否则会出现版本不匹配的报错。4.3 并发性能调优FunASR服务默认基于Gunicorn或类似机制支持并发但默认参数未必适合你的场景。服务启动脚本里通常有worker数量、线程数等参数可以按需要调整。一个比较经典的调优方向是如果请求平均耗时为T秒系统需要支撑的QPS是Q那么并发数至少需要T×Q。比如平均耗时2秒预期并发场景需要同时处理20个请求就要把并发数调到40左右。不过调高并发数之前要确认机器CPU核数和内存够不够。我在4核8G的机器上跑默认配置同时处理10个请求已经到了CPU瓶颈。如果CPU持续100%调并发数只会让请求排队时间更久识别更慢所以调参要配合监控。另一个需要注意的点是模型的内存占用。每个worker都会加载一份模型副本worker数量过多会导致内存爆炸。经验值是内存大小除以单个worker的模型占用得到的数值再乘以0.7作为安全阈值。5. 常见问题与排查实录5.1 Docker环境层面的问题问题一docker服务启动失败宿主机上执行sudo systemctl start docker报Failed to start Docker Application Container Engine。这种问题先看系统日志sudo journalctl -u docker --no-pager | tail -50 sudo tail -100 /var/log/messages | grep docker常见原因是iptables配置冲突。Docker默认需要操作iptables来配置网络如果系统里有其他防火墙软件管理了iptables规则Docker启动就挂。临时解决办法是sudo systemctl stop firewalld sudo systemctl restart docker如果是内网环境有安全策略不能关防火墙就要配置Docker使用特定的iptables链这个偏复杂建议找运维协助。问题二Windows下Docker Desktop起不来报virtualization support not detected这类问题基本是硬件虚拟化没开。重启进BIOS找到Intel VT-x或者AMD SVM选项开启后在Windows功能里启用“虚拟机平台”和“Windows虚拟机监控程序平台”然后再启动Docker Desktop。如果BIOS里没有虚拟化选项那就是CPU太老或者机器被虚拟化了Docker Desktop基本没法用建议改用Linux服务器。问题三permission denied前面提过当前用户不在docker组里。执行sudo usermod -aG docker $USER后重新登录即可。问题四拉取镜像特别慢甚至失败配置了registry mirror还是慢可以试试直接拉取时指定镜像源的完整URL或者用代理方式。如果在内网环境建议让运维提前把镜像导出为tar包然后在外网机器上拉取后传输到内网docker save和docker load两个命令配合使用这个方法很实用。5.2 FunASR服务层面的问题问题一容器内服务启动后立刻退出检查server.log最常见的是端口被占用。容器内10095端口被其他进程占用改端口或者杀掉占用进程。另外如果你的容器用了-it参数退出容器bash时服务也会被关闭注意用nohup和重定向。问题二首次启动长时间卡在模型下载镜像内的模型可能不完整服务第一次启动会下载。这个等待时间取决于网速有时候看起来卡住了其实是在下载大文件。用du -sh看模型目录大小变化如果一直不变可能是下载进程挂了考虑手动下载模型并挂载进去。问题三接口返回500错误服务能访问但返回500一般是音频处理失败。先确认音频格式我记得最常见的坑就是采样率不是16k。另外检查音频文件是否损坏用ffprobe验证一下。问题四识别结果全为空或者乱码服务调用成功返回了JSON但文本为空。这往往是VAD把整段音频当成静音过滤掉了或者音频音量太低。可以先关闭VAD或者调整VAD阈值再试试音量正常的音频。我遇到过一次是录音文件是静音起头VAD一上来就裁掉了实际内容。问题五内存不足OOM容器运行一段时间内存占用持续上升最终OOM被杀。这是大模型服务常见问题。检查并发配置降低worker数量另外确认是否每个worker加载了整个模型。生产环境建议给容器设置内存上限比如-m 8g避免内存泄漏拖垮宿主机。5.3 网络连通性问题问题一宿主机能访问其他机器不能访问检查防火墙sudo firewall-cmd --list-ports没有10095就添加sudo firewall-cmd --add-port10095/tcp --permanent sudo firewall-cmd --reload如果是云服务器还要检查安全组是否放行了10095端口。这个问题我栽过一次服务明明起来了同事就是访问不了最后发现是云安全组规则没加。问题二容器内外部网络不通Docker容器默认通过bridge网络访问外网。如果容器内curl外网不通检查宿主机的ip_forwardsysctl net.ipv4.ip_forward如果值是0改成1echo net.ipv4.ip_forward 1 /etc/sysctl.conf sysctl -p5.4 一个典型的排查链路案例前面讲了一堆零散的问题这里串一个完整案例。某次同事反馈识别服务响应超时我按顺序排查先看服务进程还在不在在容器内ps aux | grep server.sh。进程还在。再看端口监听netstat -tlnp | grep 10095。端口在监听。接着用curl测试本机调用curl -F audio/test.wav ...。等了大概30秒都没返回。这时候我怀疑是并发打满。宿主机上top一看CPU接近100%KiB Mem明显紧张。再查并发连接数发现确实有大量请求堆积。定位到原因是上游系统调用频率过高每个请求都是整段音频的离线识别耗时又长导致服务排队。最终通过限制上游单次调用时长、增加一个简单的请求队列、把模型切到GPU总算把服务稳定住了。这个过程其实谈不上高明但我想说的是排查问题一定要有顺序从进程、端口、日志、资源这四个维度去查比东猜一个西猜一个高效得多。6. 写在最后的一点心得这次用Docker部署FunASR的整体感受是官方镜像解决了最麻烦的环境问题但真正的工程化工作比如模型管理、并发调优、日志监控、异常恢复这些还是得自己动手。Docker只是把地基打好了楼怎么盖还得靠自己的需求分析。我个人体会比较深的几个点再强调一下第一模型目录务必挂载到宿主机否则容器一删模型就得重新下载第二生产环境不要前台跑服务nohup或者systemd方式管理进程容器重启策略也要配好第三GPU部署之前一定要先把CPU版流程走通不要在还没学会走的时候想着跑那样出了错你很难分清是哪一层的问题第四日志要尽早采集出来FunASR的服务日志里有很多有价值的信息别等出了问题再去翻。最后分享一个小技巧如果你想快速判断一套环境能不能跑FunASR不用等到拉完镜像可以先在目标机器上装好Docker并跑通hello-world然后直接跑官方镜像的容器测试一下GPU是否可见如果这几个环节都顺利后面基本就是一马平川。语音识别这类服务的部署调试成本不低把前置检查做扎实比事后救火有用得多。希望这篇实操记录能帮你省下一些时间。