1. 为什么选择FunASR？聊聊本地部署的“真香”体验

大家好，我是老张，一个在AI和智能硬件圈子里摸爬滚打了十多年的“老码农”。今天想和大家掏心窝子聊聊一个最近让我眼前一亮的工具——FunASR，以及怎么把它用Docker搬到你自己的Windows电脑上。你可能听说过很多语音转文字的服务，像讯飞、百度云啥的，用起来是方便，但数据得上云，有时候网络一卡顿，或者涉及到一些内部会议录音、敏感音频的处理，心里总有点不踏实。这时候，本地部署的优势就出来了：数据不出本地、响应零延迟、完全自定义。FunASR就是阿里开源的这么一个“宝贝”，它把一流的语音识别模型打包好了，让你能在自己的机器上搭一个专属的“讯飞听见”。

我最初接触FunASR也是因为一个项目，客户要求所有语音数据处理必须在内网完成，绝对禁止上传到任何公有云。当时找了一圈方案，要么模型太大本地跑不动，要么精度不够理想。直到试了FunASR，特别是它的Paraformer-large模型，在中文场景下的准确率真的让我惊喜，接近甚至在某些场景下超过了我们之前采购的商用API。而且，用Docker部署，就像是把整个服务打包成了一个“绿色软件”，环境隔离得干干净净，不会把你电脑搞乱，卸载也简单。对于开发者、中小企业或者有隐私安全要求的团队来说，这简直就是“雪中送炭”。接下来，我就手把手带你，从零开始，在Windows上把这个强大的语音转写服务给跑起来。

2. 战前准备：搞定Windows下的Docker环境

万事开头难，但这一步走稳了，后面就一马平川。在Windows上玩Docker，和Linux、Mac有点不一样，因为它本身不是原生支持容器技术的。别担心，我们现在有非常成熟的方案。

2.1 安装Docker Desktop：选对版本很重要

首先，你得去Docker官网下载Docker Desktop for Windows。这里有个关键选择：是选WSL 2后端还是Hyper-V后端？ 我强烈推荐，甚至可以说是“必须”选择WSL 2后端。WSL 2是微软官方搞的Linux子系统，它让Docker在Windows上的运行效率几乎接近原生Linux，性能比老旧的Hyper-V模式好太多，而且资源占用也更友好。

安装过程基本就是一路“Next”，但安装完成后，重启电脑是必须的。重启后，你会在任务栏看到一个可爱的小鲸鱼图标。这时候，我建议你打开Windows自带的PowerShell（不是CMD，PowerShell更好用），输入命令 docker --version 和 docker run hello-world。如果第一个命令输出了Docker版本号，第二个命令下载了一个测试镜像并运行成功，打印出“Hello from Docker!”之类的信息，那么恭喜你，你的Docker环境已经妥了。这一步看似简单，但我见过不少新手卡在没开BIOS里的虚拟化支持（VT-x/AMD-V）上，如果你的hello-world跑不起来，先去BIOS里确认一下这个选项是Enabled状态。

2.2 规划你的工作目录：避免路径一团糟

Docker用起来爽，但管理和宿主机（也就是你的Windows）的文件交换，需要一点小规划。我们待会儿需要把本地的模型、音频文件映射到容器内部去。我个人的习惯是在D盘（或者你空间大的盘）创建一个清晰的工作目录。比如，我就建一个 D:\AI_Projects\FunASR。在这个目录下，我们再新建几个子文件夹，像 models（存放所有AI模型）、audios（存放待处理的音频）、configs（存放配置文件）。提前规划好，后面敲命令时心里有数，不会乱。特别是models文件夹，因为FunASR的模型动辄几百兆甚至上G，放在一个固定的、空间充足的位置非常有必要。

3. 核心实战：拉取镜像与启动容器

环境准备好了，咱们就正式开始“烹饪”FunASR这道大餐。整个过程就像用预制菜做大餐，Docker镜像是“预制菜包”，我们把它加热（运行）并配上自己的“调料”（模型和配置）。

3.1 拉取FunASR官方镜像

打开你的PowerShell，确保当前工作目录在你刚才创建的项目文件夹里（比如D:\AI_Projects\FunASR），然后执行这条拉取镜像的命令。这步可能需要点时间，因为镜像本身也不小，请保持网络通畅。

docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13

我来解释一下这个镜像地址：registry.cn-hangzhou.aliyuncs.com 是阿里云的容器镜像服务地址，funasr_repo是项目仓库，funasr是镜像名，冒号后面的是标签（tag）funasr-runtime-sdk-online-cpu-0.1.13。这个标签很关键，它告诉我们这是FunASR的运行时环境，支持在线（流式）和离线（非流式）两种模式的SDK，并且是CPU版本。如果你的机器有NVIDIA显卡并且配置好了CUDA，可以去找带“cuda”标签的镜像，用GPU推理速度会快很多。但对于大多数初次尝试和开发测试，CPU版本完全够用。

下载完成后，可以用 docker images 命令查看一下，确认镜像已经安安静静地躺在你的本地镜像列表里了。

3.2 启动容器：参数详解与“避坑”指南

这是最关键的一步，命令稍微有点长，但别怕，我们拆开看。在PowerShell里执行下面这个命令：

docker run -p 10096:10095 -it --name my_funasr --privileged=true -v D:\AI_Projects\FunASR\models:/workspace/models registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13

咱们来逐段分析这个命令，理解了以后你就能举一反三：

• docker run： 创建并启动一个新容器。
• -p 10096:10095： 端口映射。这是容器内外通信的桥梁。容器内部FunASR服务默认监听10095端口，我们把它映射到宿主机的10096端口。意思是，你以后在Windows浏览器或者代码里，就访问 localhost:10096 或 127.0.0.1:10096，流量会自动转发到容器的10095端口。你可以把10096改成任何你喜欢的、没被占用的端口。
• -it： 这是两个参数-i（交互式）和-t（分配一个伪终端）的合并。加上它，容器启动后，你会直接进入容器的命令行界面，就像远程登录了一台Linux服务器一样，方便你后续操作。
• --name my_funasr： 给容器起个名字，这里叫my_funasr。有了名字，后续管理（如停止、重启、查看日志）就特别方便，不用去记那串复杂的容器ID。
• --privileged=true： 给容器“特权模式”。这主要是为了让容器有更大的权限去执行一些操作，比如可能涉及到的设备访问（虽然CPU版不太需要），有时候能避免一些莫名的权限错误。在本地开发测试环境可以加上，生产环境要谨慎。
• -v D:\AI_Projects\FunASR\models:/workspace/models： 目录挂载（卷映射）。这是Docker的精髓之一！把Windows本地的 D:\AI_Projects\FunASR\models 文件夹，映射到容器内部的 /workspace/models 路径。这样，容器里下载或生成的模型文件，实际上都保存在你的Windows硬盘上，即使容器被删除，模型还在。注意Windows路径的写法，可以用反斜杠\，但通常建议用正斜杠/或者双反斜杠\\，PowerShell和CMD对斜杠的处理有时不同，如果报路径错误，可以尝试把D:\...改成D:/...。
• 最后一行就是镜像名和标签，告诉Docker用哪个“预制菜包”来启动容器。

命令回车后，如果一切顺利，你会看到命令行前缀变成了类似 root@xxxxx:/workspace# 的样子，这说明你已经成功进入容器内部了！如果没进去，或者启动报错，最常见的原因就是端口冲突（换一个宿主机端口）或者路径不存在（检查你的 D:\AI_Projects\FunASR\models 文件夹是否已创建）。

4. 配置与启动：让语音服务“活”起来

现在我们已经在容器的“肚子”里了，眼前是一个干净的Linux环境。FunASR的所有家伙什儿都已经预装好了，我们只需要把它启动起来。

4.1 进入核心目录并理解启动脚本

首先，切换到FunASR的运行时目录，这是所有操作的起点：

cd /FunASR/runtime

用 ls 命令看看，你会发现里面有好几个 run_server_*.sh 脚本。这里有个重要概念：2pass（两遍解码）模式。run_server_2pass.sh 这个脚本启动的服务，同时支持流式实时转写和非流式整句转写。简单来说，流式就是你说着，它同步转写着，延迟极低；非流式是你传整个音频文件，它给你最精准的全文结果。这个“2pass”服务把两者结合了，先用流式快速出中间结果，再用非流式整体优化一遍最终结果，兼顾速度和精度，是官方推荐的通用模式。所以我们接下来就用它。

4.2 启动服务：详解每个参数的含义

在 /FunASR/runtime 目录下，运行下面这条“长长长”的命令。别被吓到，我一行行给你解释：

nohup bash run_server_2pass.sh \
  --certfile 0 \
  --download-model-dir /workspace/models \
  --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
  --model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx \
  --online-model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online-onnx \
  --punc-dir damo/punc_ct-transformer_zh-cn-common-vad_realtime-vocab272727-onnx \
  --lm-dir damo/speech_ngram_lm_zh-cn-ai-wesp-fst \
  --itn-dir thuduj12/fst_itn_zh \
  --hotword /workspace/models/hotwords.txt > log.txt 2>&1 &

• nohup ... &： 让命令在后台运行，这样即使你退出容器的终端，服务也不会停止。
• --certfile 0： 禁用HTTPS，我们用HTTP测试，更简单。
• --download-model-dir /workspace/models： 指定模型下载目录。这是最重要的参数之一！所有模型都会下载到你之前挂载的 /workspace/models，也就是Windows上的 D:\AI_Projects\FunASR\models。
• --vad-dir： 指定**语音活动检测（VAD）**模型。VAD负责找出音频中哪些部分是人说话，哪些是静音或噪音。这里用的是达摩院开源的FSMN VAD模型，专门针对16kHz采样率的中文通用场景。
• --model-dir： 指定离线（非流式）ASR模型。这里用的是Paraformer-large大模型，并且是集成了VAD和标点恢复（punc）的版本，精度高。
• --online-model-dir： 指定在线（流式）ASR模型。这是用于实时转写的模型。
• --punc-dir： 指定标点恢复模型。流式转写时，实时给文本加上标点。
• --lm-dir： 指定语言模型（LM）。用于对识别结果进行纠错和优化，提升准确率，特别是对专有名词、领域术语。
• --itn-dir： 指定**逆文本归一化（ITN）**模型。负责把“一二三”转换成“123”，把“百分之五十”转换成“50%”等等。
• --hotword： 热词增强文件路径。这是FunASR一个超级实用的功能！你可以在Windows的 D:\AI_Projects\FunASR\models 目录下创建一个 hotwords.txt 文件，每行写一个你想提升识别率的词或短语（比如公司名、产品名、专业术语）。服务启动时会加载它，显著提升这些词的识别优先级和准确率。如果文件不存在，服务也能正常启动，只是没有热词增强功能。
• > log.txt 2>&1： 把服务的标准输出和错误输出都重定向到当前目录下的 log.txt 文件里，方便我们查看日志。

命令执行后，它会立刻返回一个进程ID。最关键的来了：第一次启动会自动下载模型。这时你需要赶紧用 tail -f log.txt 命令实时查看日志。你会看到一行行下载进度，从阿里云ModelScope平台拉取各个模型。因为模型比较大（总共可能好几个G），下载时间取决于你的网速，请耐心等待。当看到类似 “Started server process [1]” 和 “Uvicorn running on http://0.0.0.0:10095” 的日志时，就说明服务已经在容器内部的10095端口（对应我们宿主机的10096端口）成功启动了！

5. 测试与使用：让你的服务开口“说话”

服务跑起来了，怎么用呢？总不能一直看日志吧。我们有几种酷炫的方式来测试它。

5.1 网页Demo测试：最直观的视觉体验

FunASR官方提供了非常友好的Web测试界面。你需要把它下载到本地。另开一个Windows的PowerShell窗口（不要关闭之前容器的那个），在你之前的工作目录（比如D:\AI_Projects\FunASR）下，执行：

git clone https://github.com/alibaba-damo-academy/FunASR.git

或者，如果你没装Git，可以直接去GitHub项目页面（搜索 FunASR）下载ZIP包解压。找到解压后目录里的 FunASR/runtime/websocket 目录，这里就存放着网页Demo。

直接用浏览器打开 FunASR/runtime/websocket 目录下的 index.html 文件。页面很简单，中间有个连接地址的输入框。把地址改成 ws://localhost:10096（记住，这里填的是我们映射的宿主机端口10096，协议是ws代表WebSocket）。点击连接，如果显示“连接成功”，那就太棒了！

现在你可以点击“选择文件”，上传一个WAV格式的音频文件（建议16kHz采样率，单声道，效果最好）。点击发送，下方就会几乎实时地显示出语音转写的文字结果，并且是带标点的。你也可以直接点击“开始录音”，对着麦克风说话，体验流式实时转写的快感，你说完一句，文字马上就出来一句。这是我个人最喜欢的功能，用来做会议实时字幕辅助或者访谈记录，效率提升不是一点半点。

5.2 用Python脚本调用：集成到你的项目中

网页Demo是测试，真正要用起来，还得是API。FunASR服务提供了标准的WebSocket和HTTP接口。这里给你一个最简单的Python测试脚本，保存为 test_funasr.py，放在你的项目目录里运行：

import websocket
import json
import threading
import time

def on_message(ws, message):
    """收到服务器返回消息时的回调函数"""
    result = json.loads(message)
    # 打印转写结果
    if 'text' in result:
        print(f"识别结果: {result['text']}")
    if 'mode' in result and result['mode'] == '2pass':
        # 2pass模式下，final结果才是最终版
        print(f"最终结果: {result['text']}")

def on_error(ws, error):
    print(f"发生错误: {error}")

def on_close(ws, close_status_code, close_msg):
    print("连接关闭")

def on_open(ws):
    """连接建立后的回调函数"""
    print("连接成功，开始发送音频数据...")
    # 这里需要读取你的音频文件，并转换为base64或直接发送二进制帧
    # 以下是一个示例，实际需要根据音频格式处理
    def run(*args):
        # 模拟发送音频数据（实际应从文件读取）
        # 发送一个开始信号
        start_msg = {"mode": "2pass", "wav_name": "test.wav", "is_speaking": True}
        ws.send(json.dumps(start_msg))
        time.sleep(1)
        # 发送结束信号
        end_msg = {"is_speaking": False}
        ws.send(json.dumps(end_msg))
        time.sleep(5)
        ws.close()
    threading.Thread(target=run).start()

if __name__ == "__main__":
    # WebSocket连接地址，指向本地启动的服务
    ws_url = "ws://localhost:10096"
    ws = websocket.WebSocketApp(ws_url,
                                on_open=on_open,
                                on_message=on_message,
                                on_error=on_error,
                                on_close=on_close)
    ws.run_forever()

这个脚本使用了 websocket-client 库，你需要先用 pip install websocket-client 安装它。运行这个脚本，它会尝试连接你的本地服务。当然，这只是一个骨架，真正处理音频文件需要你添加读取WAV文件、分帧、发送二进制数据的逻辑。FunASR的GitHub仓库里有更完整的客户端示例代码，强烈建议你去参考。

5.3 服务管理：日常维护小贴士

服务跑起来了，总得知道怎么“照顾”它吧。

• 查看日志：在容器内部，随时可以用 tail -f log.txt 或 tail -100f log.txt（查看最后100行并实时更新）来监控服务状态和识别详情。
• 停止服务：在容器内部，找到运行服务的进程ID（可以用 ps aux | grep run_server 查看），然后用 kill [PID] 命令停止。或者更粗暴一点，直接退出容器（exit），然后在宿主机PowerShell里用 docker stop my_funasr 停止整个容器。
• 重启服务：如果修改了配置（比如更新了hotwords.txt），需要重启服务。可以先在容器内停止服务进程，然后重新执行一遍那个长长的 nohup bash run_server_2pass.sh ... 命令。
• 容器自启动：如果你希望电脑一开机，这个服务就自动运行，可以在当初 docker run 的时候加上 --restart always 参数，或者用 docker update --restart always my_funasr 来更新现有容器。

6. 进阶调优与问题排查

部署成功只是第一步，要想用得顺手，还得懂点“调优”和“排错”的手艺。

6.1 性能调优：让转写更快更准

CPU版本的性能主要吃CPU核心数和内存。你可以在启动Docker容器时，通过参数限制资源使用，比如 --cpus 2 限制使用2个CPU核心，-m 4g 限制使用4GB内存，避免它吃掉你所有资源。 对于识别精度，热词（Hotword）功能是你最好的朋友。我有个项目是做医疗访谈转录，里面有很多药品名和疾病名。我把这些专业词汇做成一个热词列表，准确率提升了超过20%。热词文件的格式就是每行一个词，也可以加权重，比如 “冠状动脉粥样硬化性心脏病 10”，权重越高，提升效果越明显。 另外，音频质量是输入的天花板。尽量提供背景噪音小、说话人清晰的16kHz/16bit单声道WAV音频。如果原始音频质量差，可以考虑先用一些开源音频降噪工具（比如noisereduce）预处理一下，再送给FunASR，效果会有改善。

6.2 常见问题与解决方案

1. 模型下载失败或极慢：因为模型是从ModelScope下载，国内网络通常没问题。如果失败，可以检查容器内网络（ping www.baidu.com），或者尝试在宿主机用其他工具先下载模型，然后手动放到 D:\AI_Projects\FunASR\models 目录下对应的子文件夹里（需要根据日志看它期望的路径）。
2. 服务启动后，网页或客户端连接不上：首先确认服务日志是否真的显示启动在10095端口。然后，在宿主机（Windows）上打开浏览器，访问 http://localhost:10096（注意是HTTP），如果返回“WebSocket endpoint”之类的提示，说明服务端口映射是通的。检查防火墙是否阻止了10096端口。
3. 识别结果为空或乱码：首先检查音频格式是否符合要求（16kHz, mono, WAV）。用 ffmpeg 工具转换一下最保险：ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav。其次，查看日志 log.txt，看是否有解码错误信息。
4. 容器退出后，再次启动如何保留状态：这就是我们使用 -v 参数挂载模型目录的意义所在。只要 D:\AI_Projects\FunASR\models 目录还在，模型就不需要重新下载。重新运行 docker run 命令（使用相同的挂载路径和容器名），它会复用之前的模型文件，快速启动。

最后，再分享一个我踩过的坑：早期版本在Windows路径挂载时，因为文件系统权限问题，容器内可能无法写入模型文件。如果你遇到类似“Permission denied”的错误，可以尝试在Windows上确保该文件夹有足够的读写权限，或者使用Docker Desktop设置中的“Shared Drives”功能，明确把D盘共享给Docker。折腾本地部署就是这样，会遇到各种小问题，但每解决一个，你对整个系统的理解就加深一层。FunASR这个项目还在活跃更新，社区也很热闹，遇到解决不了的问题，去GitHub上提个Issue，往往能得到开发者的快速响应。希望这篇超详细的指南能帮你顺利搭起自己的语音转写服务器，开启离线语音处理的新世界大门。