FunASR-Powered MCP Server (MCPServer)

FunASR 驱动的 MCP 服务（MCPServer）

概述

MCPServer 是一个基于 Python 的服务，通过 FastMCP 框架调用阿里巴巴的 FunASR 库提供语音处理服务。它提供以下工具：

• 音频验证： 检查音频文件是否有效且可读，并提供其属性。
• 语音转写： 使用 Paraformer 等先进 ASR 模型异步转写音频文件中的语音。支持管理转写任务并获取结果，包括详细的时间戳信息。
• 语音活动检测（VAD）： 识别音频文件中的语音片段。

该服务支持扩展，并允许动态加载和切换 ASR 与 VAD 模型。

功能

• 音频文件验证： 验证音频文件的完整性、可读性和格式。
• 异步语音转文字： 非阻塞式转写，适用于较长的音频文件。
• 转写任务管理： 启动任务、查询状态并获取结果。
• 详细的转写结果： 查看完整转写文本、片段级别的起止时间，以及词级时间戳（如果 ASR 模型提供）。
• 语音活动检测（VAD）： 返回音频文件中语音片段的精确起止时间戳。
• 多模型支持： 调用 FunASR 丰富的模型库，支持 ASR 和 VAD。
• 动态模型配置：
  • 为每次转写或 VAD 请求指定模型。
  • 显式加载或切换服务实例使用的默认 ASR 和 VAD 模型。
• 可配置的模型参数： 向 FunASR 模型传递特定的加载和生成参数。

前提条件

• Python： 3.8+
• Pip： 用于安装 Python 软件包。
• MODELSCOPE_API_TOKEN（可选）：
  • FunASR 会从 ModelScope 下载模型。如果遇到速率限制或需要访问私有模型，可能需要设置 MODELSCOPE_API_TOKEN 环境变量。
  • 可以从 ModelScope 网站获取令牌。
  • 在环境中设置：export MODELSCOPE_API_TOKEN="YOUR_TOKEN_HERE"

设置与安装

1. 克隆仓库（如适用）： 如果此服务属于更大的仓库，请克隆该仓库。否则，请确保拥有 MCPServer 目录及其内容。

2. 创建并激活虚拟环境（推荐）：

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 安装依赖项： 进入 MCPServer 目录（即包含此 README 和 server.py 的目录）。 安装所需的软件包：

   pip install -r requirements.txt
   

   这将安装 fastmcp、funasr 及其依赖项，包括 PyTorch（如果 FunASR 的直接依赖项未另行指定，默认安装 CPU 版本）。如果你对 PyTorch 有特定需求（例如 GPU 版本），建议在运行上述命令前手动安装 PyTorch，并参照 PyTorch 官方网站中的说明进行操作。

运行服务

1. 进入 MCPServer 目录。
2. 运行服务应用：

   uvicorn main:app --host 0.0.0.0 --port 9000
   

3. 服务将启动，你会看到表明服务正在运行的日志输出，通常地址为 http://0.0.0.0:9000。首次运行时，FunASR 将下载默认的 ASR 和 VAD 模型，这可能需要一些时间。

可用的 MCP 工具

MCPServer: http://0.0.0.0:9000/sse

你可以使用任何 MCP 客户端（例如 mcp_client 或通过 HTTP 请求）与这些工具交互。服务提供以下工具：

---

1. validate_audio_file

• **描述：**验证音频文件是否适合处理，并提供其属性。
• 参数：
  • file_path (str，必填)：音频文件的路径。
• 返回示例（成功）：

  {
    "status": "valid",
    "message": "Audio file is valid.",
    "details": {
      "samplerate": 16000,
      "channels": 1,
      "duration": 10.5,
      "formatted_duration": "00:10.500",
      "format": "WAV",
      "subtype": "PCM_16"
    }
  }
  

• 返回示例（错误 - 文件未找到）：

  {
     "status": "invalid",
     "message": "Error: File not found at 'path/to/non_existent_audio.wav'.",
     "details": null
  }
  

---

2. start_speech_transcription

• **描述：**为指定的音频文件启动异步语音转录任务。可指定 ASR 模型和生成参数。
• 参数：
  • audio_path (str，必填)：音频文件的路径。
  • model_name (str，可选)：此任务要使用的特定 ASR 模型（例如 ModelScope ID）。此参数会覆盖服务当前默认的 ASR 模型。如果指定的模型尚未以兼容的设置加载，服务将尝试使用该模型的默认加载参数或此实例的通用默认加载参数加载模型。
  • model_generate_kwargs (dict，可选)：ASR 模型 generate 方法的特定参数（例如 {"batch_size_s": 60, "hotword": "特定热词"}）。这些参数会覆盖服务为当前 ASR 模型设置的所有默认生成参数。
• 返回示例（成功）：

  {
    "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "processing_started",
    "message": "Transcription task started and is now processing."
  }
  

• 返回示例（错误 - 音频无效）：

  {
     "task_id": null,
     "status": "error",
     "message": "Error: File at '/path/to/your/bad_audio.wav' is not a valid audio file or is corrupted. Details: <error from soundfile>",
     "details": null
  }
  

• 返回示例（错误 - 任务期间模型加载失败）：

  {
     "task_id": null,
     "status": "error",
     "message": "Failed to switch to model 'non_existent_model_id'. Error: Error loading model 'non_existent_model_id': <actual error>"
  }
  

---

3. get_transcription_task_status

• 描述： 查询先前启动的语音转写任务的状态。
• 参数：
  • task_id（str，必填）：转写任务的唯一 ID。
• 返回示例（处理中）：

  {
     "status": "processing",
     "audio_path": "/path/to/your/audio.wav",
     "model_used": "iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch",
     "submitted_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00",
     "details_from_validation": { /* ... audio details from validate_audio ... */ },
     "model_generate_kwargs": {"batch_size_s": 300, "hotword": "魔搭"},
     "processing_started_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
  }
  

- **返回示例（已完成）：**

 ```json
 {
    "status": "completed",
    "audio_path": "/path/to/your/audio.wav",
    "model_used": "iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch",
    "submitted_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00",
    "details_from_validation": { /* ... */ },
    "model_generate_kwargs": { /* ... */ },
    "processing_started_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00",
    "result": [ /* ... actual transcription result ... */ ],
    "completed_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
 }
 ```
- **返回示例（错误 - 未找到任务）：**
  ```json
  {
      "status": "error",
      "message": "Task ID not found."
  }
  ```

---

4. get_transcription_result

• 描述： 获取已完成的语音转写任务的结果。
• 参数：
  • task_id（str，必填）：转写任务的唯一 ID。
• 返回示例（成功/已完成）：

  {
    "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "completed",
    "result": [
      {
        "text": "这是 一段 测试 文本",
        "start": 120,
        "end": 2850,
        "timestamp": [[120, 300], [330, 500], [550, 900], [920, 1200]]
      }
    ],
    "completed_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
  }
  

• 返回示例（任务仍在处理中）：

  {
     "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
     "status": "processing",
     "message": "Transcription not yet completed or has failed."
  }
  

• 返回示例（任务失败）：

  {
     "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
     "status": "failed",
     "message": "Transcription failed.",
     "error_details": "Description of the error during transcription.",
     "failed_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
  }
  

---

5. load_asr_model

• 描述： 加载或重新加载指定的 ASR 模型，并将其设为后续任务的默认模型（除非另行指定）。返回操作状态。
• 参数：
  • model_name（str，必填）：要加载的 FunASR 模型标识符（例如 ModelScope ID）。
  • device（str，可选）：加载模型所用的设备（例如 "cpu"、"cuda:0"）。若为 None，则使用实例默认值。
  • model_load_kwargs（dict，可选）：加载 ASR 模型的特定参数（例如 {"ncpu": 2, "vad_model": "other-vad-id", "punc_model": "other-punc-id"}）。这些参数将传递给 funasr.AutoModel。
• 返回示例（成功）：

  {
    "status": "success",
    "message": "Model 'iic/speech_paraformer-large-en-16k-common-vocab10020' loaded successfully on cpu with load_kwargs: {'ncpu': 2, 'vad_model': 'fsmn-vad'}."
  }
  

• 返回示例（错误）：

  {
     "status": "error",
     "message": "Error loading model 'invalid-model-id': <FunASR or ModelScope error details>"
  }
  

---

6. get_voice_activity_segments

• 描述： 使用语音活动检测（VAD）模型检测音频文件中的语音片段。
• 参数：
  • audio_path（str，必填）：音频文件的路径。
  • vad_model_name（str，可选）：要使用的特定 VAD 模型。此参数会覆盖服务端当前的默认 VAD 模型。
  • model_load_kwargs（dict，可选）：当指定的 vad_model_name 与当前已加载的模型不同时，用于加载 VAD 模型的特定参数。
  • model_generate_kwargs（dict，可选）：VAD 模型 generate 方法的特定参数。
• 成功返回示例：

  {
    "status": "success",
    "segments": [ [100, 2500], [3000, 5500] ],
    "audio_path": "path/to/your/audio.wav",
    "vad_model_used": "damo/speech_fsmn_vad_zh-cn-16k-common-pytorch",
    "generate_kwargs_used": {},
    "audio_details": { /* ... audio properties ... */ }
  }
  

- **错误返回示例 - VAD 处理失败：**

 ```json
 {
    "status": "error",
    "message": "VAD processing failed for 'path/to/audio.wav': <FunASR error details>",
    "audio_path": "path/to/audio.wav",
    "vad_model_used": "damo/speech_fsmn_vad_zh-cn-16k-common-pytorch"
 }
 ```

---

7. load_vad_model

• 描述： 加载或重新加载特定 VAD 模型，并将其设为后续 VAD 任务的默认模型，除非被覆盖。返回操作状态。
• 参数：
  • model_name（str，必填）：要加载的 FunASR VAD 模型标识符。
  • device（str，可选）：加载模型所用的设备。若为 None，则使用实例默认值。
  • ncpu（int，可选）：当设备为 CPU 时使用的 CPU 线程数。若为 None，则使用实例默认值。
  • model_load_kwargs（dict，可选）：加载 VAD 模型的特定参数。
• 成功返回示例：

  {
    "status": "success",
    "message": "VAD Model 'damo/speech_fsmn_vad_zh-cn-16k-common-pytorch' loaded successfully on cpu with load_kwargs: {'ncpu': 2}."
  }
  

---

使用 curl 的示例

以下示例展示了如何使用 curl 调用 start_speech_transcription 工具：

# Ensure the audio_path is accessible by the server.
# For paths with spaces or special characters, ensure proper JSON escaping if needed.
curl -X POST http://localhost:8000/mcp/start_speech_transcription \
     -H "Content-Type: application/json" \
     -d '{"params": {"audio_path": "/path/to/your/audio_sample.wav"}}'

响应：

{
  "jsonrpc": "2.0",
  "id": "some_client_generated_id",
  "result": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "processing_started",
    "message": "Transcription task started and is now processing."
  }
}

若要稍后获取结果，请使用响应中的 task_id：

curl -X POST http://localhost:8000/mcp/get_transcription_result \
     -H "Content-Type: application/json" \
     -d '{"params": {"task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}}'

模型配置

• 默认模型： 服务会使用 MCPServer/server.py 中指定的默认 ASR 和 VAD 模型进行初始化。
  • 默认 ASR：iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch（预配置了 VAD damo/speech_fsmn_vad_zh-cn-16k-common-pytorch 和标点模型 damo/punc_ct-transformer_zh-cn-common-vocab272727-pytorch）。
  • 默认 VAD：damo/speech_fsmn_vad_zh-cn-16k-common-pytorch。
• 按请求指定模型：
  • 对于 start_speech_transcription，使用 model_name 参数为该特定任务指定其他 ASR 模型。
  • 对于 get_voice_activity_segments，使用 vad_model_name 参数为特定任务指定 VAD 模型。
  • 如果按请求指定的模型与当前已加载的模型不同，服务会尝试加载该模型。如果成功加载，这个新模型会成为相应处理器类型（ASR 或 VAD）的当前默认模型，供后续未指定模型的请求使用。
• 全局模型加载：
  • 使用 load_asr_model 工具更改 SpeechTranscriber 实例的默认 ASR 模型。
  • 使用 load_vad_model 工具更改 VADProcessor 实例的默认 VAD 模型。
  • 这些工具还允许指定 device、ncpu（用于 VAD）和 model_load_kwargs，以便更精细地控制模型加载（例如，对于 ASR，model_load_kwargs 可包含 VAD 和标点模型 ID）。
• 模型参数：
  • model_load_kwargs：可传递给 load_asr_model 和 load_vad_model，用于控制模型的加载方式（例如，为 ASR 流水线指定 VAD/标点等子模型，或设置其他特定于模型的加载参数，例如在加载时设置 VAD 模型支持的 max_single_segment_time）。
  • model_generate_kwargs：可传递给 start_speech_transcription 和 get_voice_activity_segments，用于控制模型推理/生成步骤的行为（例如，ASR 的 batch_size_s、hotword；VAD 模型通常在生成时可用的参数较少）。

故障排除

• 模型下载问题：
  • 确保服务可以访问互联网，以便从 ModelScope（hub.modelscope.cn）下载模型。
  • 如果持续遇到下载错误或身份验证问题（例如 HTTP 401/403），请设置 MODELSCOPE_API_TOKEN 环境变量。
  • 检查 ModelScope 缓存目录中的可用磁盘空间（通常为 ~/.cache/modelscope/hub/）。
• 依赖冲突：
  • 强烈建议使用 Python 虚拟环境，以避免与系统级软件包或其他项目发生冲突。
• PyTorch 版本：
  • FunASR 需要特定范围内的 PyTorch 版本。如果 requirements.txt 未安装兼容版本，或已有的 PyTorch 安装与之冲突，则可能需要手动安装兼容的 PyTorch 版本。请参阅 FunASR 文档，了解兼容的 PyTorch 版本。
• 资源限制：
  • ASR 模型，尤其是 Paraformer 等较大的模型，可能会占用大量内存和 CPU。请确保服务有足够的资源。对于 CPU 推理，性能与 ncpu（CPU 线程数，可在 SpeechTranscriber 和 VADProcessor 中配置）以及 CPU 的性能密切相关。
• 文件路径：
  • 确保传递给工具的 audio_path 是绝对路径，或相对于运行 server.py 脚本的位置的路径，并且服务进程可以访问该路径。
• CUDA/GPU 问题（如果使用 GPU）：
  • 如果使用 GPU（device="cuda:X"），请确保已正确安装兼容的 NVIDIA 驱动程序、CUDA Toolkit 和支持 GPU 的 PyTorch 版本。可使用 nvidia-smi 和 torch.cuda.is_available() 等工具进行诊断。