使用说明

FunASR供电的MCP服务器（MCPServer）

概述

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

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

该服务器设计为可扩展的，允许动态加载和切换ASR和VAD模型。

特性

音频文件验证： 验证音频文件的完整性、可读性和格式。
异步语音到文本转录： 适用于长音频文件的非阻塞转录。
转录任务管理： 启动任务、查询状态并检索结果。
详细转录结果： 访问完整转录文本、段级开始/结束时间和字级时间戳（如果由ASR模型提供）。
语音活动检测（VAD）： 返回音频文件中语音片段的精确开始和结束时间戳。
多模型支持： 利用FunASR的多样化模型动物园进行ASR和VAD。
动态模型配置：
- 根据转录或VAD请求指定模型。
- 显式加载/切换服务器实例使用的默认ASR和VAD模型。
可配置模型参数： 将特定的加载和生成参数传递给FunASR模型。

先决条件

python 3.8+
匹普： 用于安装Python包。
型号COPE_API_TOKEN（可选）：
- FunASR从ModelScope下载模型。如果遇到速率限制或需要访问私有模型，可能需要设置 MODELSCOPE_API_TOKEN 环境变量。
- 您可以从 ModelScope网站.
- 在您的环境中设置它： export MODELSCOPE_API_TOKEN="YOUR_TOKEN_HERE"

设置和安装

克隆存储库（如果适用）： 如果此服务器是更大存储库的一部分，请克隆它。否则，请确保您拥有 MCPServer 目录及其内容。

创建和激活虚拟环境（推荐）：

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

安装依赖关系： 导航到 MCPServer 目录（包含此README和 server.py). 安装所需的软件包：
```
pip install -r requirements.txt
```
这将安装 fastmcp, funasr，以及它们的依赖关系，包括PyTorch（如果FunASR的直接依赖关系没有另行指定，则默认为CPU版本）。如果您有特定的PyTorch需求（例如GPU版本），建议在运行上述命令之前按照以下说明手动安装PyTorch PyTorch官方网站.

运行服务器

导航到 MCPServer 目录。

运行服务器应用程序：

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

服务器将启动，您应该看到日志输出表明它正在运行，通常在 http://0.0.0.0:9000。在第一次运行时，FunASR将下载默认的ASR和VAD模型，这可能需要一些时间。

可用的MCP工具

MCP服务器：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"
}

- **Example Return (Completed):**
 ```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"
 }
 ```
- **Example Return (Error - Task Not Found):**
  ```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”）。如果为“无”，则使用实例默认值。
- 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模型的具体参数 vad_model_name 已指定，与当前加载的不同。
- 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 ... */ }
}

- **Example Return (Error - VAD Processing Failed):**
 ```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线程数。如果为“无”，则使用实例默认值。
- 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`

以下是您如何称呼 start_speech_transcription 工具使用 curl:

# 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"}}'

模型配置

默认型号： 服务器使用中指定的默认ASR和VAD模型进行初始化 MCPServer/server.py.
- 默认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 更改默认ASR模型的工具 SpeechTranscriber 例子
- 使用 load_vad_model 更改默认VAD模型的工具 VADProcessor 例子
- 这些工具还允许指定 device, ncpu （适用于VAD），以及 model_load_kwargs 为了对模型加载进行更精细的控制（例如， model_load_kwargs 可以包括VAD和标点模型ID）。
模型参数：
- model_load_kwargs：可以传递给 load_asr_model 和 load_vad_model 控制模型的加载方式（例如，为ASR管道指定VAD/标点符号等子模型，或指定其他特定于模型的加载参数，如 max_single_segment_time 如果负载时VAD模型支持）。
- model_generate_kwargs：可以传递给 start_speech_transcription 和 get_voice_activity_segments 以控制模型的推理/生成步骤的行为（例如。， batch_size_s, hotword ASR；VAD模型通常具有较少的生成时间参数）。

故障排除

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

使用说明

FunASR供电的MCP服务器（MCPServer）

概述

特性

先决条件

设置和安装

运行服务器

可用的MCP工具

1. validate_audio_file

2. start_speech_transcription

3. get_transcription_task_status

4. get_transcription_result

5. load_asr_model

6. get_voice_activity_segments

7. load_vad_model

示例用法 curl

模型配置

故障排除

相关 MCP

语音处理服务

LLM增强工具包

Ableton音乐制作辅助工具

音频接口服务器

语音合成服务器

音频转录处理服务

1. `validate_audio_file`

2. `start_speech_transcription`

3. `get_transcription_task_status`

4. `get_transcription_result`

5. `load_asr_model`

6. `get_voice_activity_segments`

7. `load_vad_model`

示例用法 `curl`