STARWARCLOUD STARWAR.AI
返回市场
本地转写-MCP--鹦鹉-实时转写-0.6b-v2--

本地转写-MCP--鹦鹉-实时转写-0.6b-v2--

作者：MiguelsPizza11 星标更新：2025-07-07
安装使用来源：spider==github.com

项目介绍

MseeP.ai 安全评估徽章

Parakeet 转录 MCP 服务器

版本: 0.1.0

这是一个使用 NVIDIA 强大的 Parakeet TDT 0.6B V2 模型将音频和视频文件转录成文本的 MCP（模型上下文协议）服务器。它还提供了获取模型详细信息的工具。

该服务器基于 FastMCP 构建，依赖于 pydub（需要 FFmpeg）来处理音频转换，并依赖于 nemo_toolkit[asr] 来实现核心转录功能。

重要提示： 必须在系统路径中安装并可访问 FFmpeg。提供给服务器工具的所有文件路径必须是绝对路径。

快速开始

以下是启动服务器的简要步骤：

  1. 安装前置条件： 确保已安装 mise、uv 和 FFmpeg 并且它们在系统路径中可访问。详情见 前置条件 部分。
  2. 克隆仓库： 如果还没有，克隆此仓库并导航到项目目录。
  3. 设置环境： 使用 mise 安装正确的 Python 版本并激活环境： 
    mise install
  4. 安装依赖项： 使用 uv 安装所需的 Python 包： 
    uv pip install -r requirements.txt
  5. 运行服务器： 使用 fastmcp 启动 MCP 服务器： 
    fastmcp run server.py
    服务器通常会使用 STDIO 运输方式启动。有关其他选项如 HTTP，请参阅 运行服务器。

一旦服务器运行起来，您就可以使用兼容 MCP 的客户端与其交互。有关示例，请参阅 与服务器交互（客户端用法）。

关于 ASR 模型：NVIDIA Parakeet TDT 0.6B V2 (En)

此服务器利用 NVIDIA Parakeet TDT 0.6B V2 模型，这是一种具有 6 亿参数的 FastConformer 架构。它优化了高质量的英文转录，包括准确的单词级时间戳、自动标点符号和大写以及对口语数字和歌词的强大性能。它可以高效地一次性转录音频片段长达 24 分钟。

  • 输入： 16kHz 音频（WAV 或 FLAC），单声道。
  • 输出： 文本，可选带有标点符号、大写和时间戳。
  • 许可证： CC-BY-4.0。
  • 演示及更多信息： Hugging Face Spaces

虽然优化用于 NVIDIA GPU，但如果未检测到兼容的 GPU，模型将回退到 CPU（注意：CPU 性能可能显著较慢）。

功能

  • 转录各种音频/视频格式。
  • 自动将输入音频转换为所需的 16kHz 单声道 WAV 或 FLAC 格式。
  • 可选择包含详细的单词和段落时间戳。
  • 当包含时间戳时，格式化转录输出，可自定义行断开。
  • 获取加载的 ASR 模型的信息。
  • 获取系统硬件规格（操作系统、CPU、RAM、GPU）。

前置条件

  1. Python： 版本 3.12（如 .tool-versions 和 mise.toml 中所指定）。

  2. mise： 用于管理 Python 版本（及其他工具）。按照 官方 mise 文档中的说明安装 mise。

  3. uv： 极其快速的 Python 包安装器和解析器。按照 Astral uv 文档中的说明安装 uv。

  4. FFmpeg： 由 pydub 所需，用于音频和视频文件格式转换。FFmpeg 必须安装并在系统路径中可访问。

    • macOS（使用 Homebrew）： 
      brew install ffmpeg
    • Linux（使用 apt - Debian/Ubuntu）： 
      sudo apt update && sudo apt install ffmpeg
    • Linux（使用 yum - CentOS/RHEL/Fedora）： 
      sudo yum install ffmpeg  # 或对于新 Fedora：sudo dnf install ffmpeg
    • Windows： 从 官方 FFmpeg 网站下载 FFmpeg。解压存档并将包含 ffmpeg.exe 的 bin 目录添加到系统的 PATH 环境变量中。
    • 验证 FFmpeg 安装： 在新的终端/命令提示符中键入： 
      ffmpeg -version
      如果正确安装，您应该能看到版本信息。

设置和安装

  1. 克隆仓库（如果尚未完成）：

    # git clone https://github.com/MiguelsPizza/local-transcription-mcp--parakeet-tdt-0.6b-v2--.git
# cd <仓库目录>

  2. 使用 mise 设置 Python 版本： 导航到项目的终端目录并运行：

    mise install

    这将确保您使用的是 .tool-versions 中指定的 Python 3.12。

  3. 使用 uv 安装 Python 依赖项： 确保您的 mise 环境处于活动状态（如果您在 mise install 后 cd 到目录中，它应该是活动的）。然后运行：

    uv pip install -r requirements.txt

    这将安装 fastmcp、pydub、nemo_toolkit[asr]、psutil 及其他必要包。

运行服务器

MCP 服务器

fastmcp dev server.py

要在生产环境中运行：

fastmcp run server.py

FastAPI 服务器（用于 REST API）

要使用 REST API，首先需要安装额外的依赖项（这包括 fastapi、uvicorn 和 python-multipart）：

# 确保您的 mise 环境处于活动状态
uv pip install -r requirements.txt

然后，从项目根目录使用 Uvicorn 运行 FastAPI 应用程序：

# 从项目根目录（transcription-mcp）
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
  • api.main:app 告诉 Uvicorn 在 api 目录下的 main.py 文件中查找名为 app 的对象。
  • --host 0.0.0.0 使服务器可以从网络上的其他设备访问。
  • --port 8000 指定运行的端口。
  • --reload 当代码更改时启用自动重新加载，这对于开发非常有用。

一旦运行，API 将在 http://localhost:8000（或您机器的 IP 地址在端口 8000 上）可用。交互式 API 文档（Swagger UI）将在 http://localhost:8000/docs 可用。

可用组件（API）

服务器通过两个接口公开功能：模型上下文协议（MCP）和 RESTful HTTP API。

MCP 服务器组件

以下组件可通过 MCP 服务器（server.py）获得：

工具

1. transcribe_audio

  • 描述： 使用 Parakeet TDT 0.6B V2 模型将音频/视频文件转录成文本。
  • 参数：
    • audio_file_path（字符串，绝对路径，必需）：要转录的音频或视频文件的绝对路径。
    • output_format（字符串，可选，默认值："wav"）：在转录前将输入文件转换为的中间音频格式。支持的值："wav"，"flac"。
    • include_timestamps（布尔值，可选，默认值：True）：是否在转录输出中包含单词和段落级别的时间戳。
    • line_character_limit（整数，可选，默认值：80，最小值：40，最大值：200）：当包含时间戳时，格式化转录输出每行的字符限制。
    • segment_length_minutes（整数，可选，默认值：5，最小值：1，最大值：24）：音频片段的最大长度（分钟）。超过此长度的音频将被分割。
  • 返回： 包含以下内容的 JSON 对象：
    • message（字符串）：指示转录结果的状态消息。
    • file_processed（字符串）：已处理的原始 audio_file_path。
    • transcription（字符串）：转录文本，可能带有时间戳。

2. 系统硬件规格

  • URI： info://system_hardware_specs
  • 名称： system_hardware_specifications
  • 描述： 获取与性能估算相关的系统硬件规格，例如操作系统、CPU、RAM 和 GPU 细节。
  • 返回： 包含系统硬件细节的 JSON 对象（详见 server.py 的完整结构）。

REST API 端点（FastAPI）

以下端点可通过 FastAPI 服务器（api/main.py）获得，通常运行在 http://localhost:8000：

1. 转录音频

  • 端点： POST /transcribe/
  • 描述： 转录上传的音频或视频文件。
  • 请求类型： multipart/form-data
  • 表单字段：
    • file（文件，必需）：要转录的音频或视频文件。
    • output_format（字符串，可选，默认值："wav"）：中间音频格式（"wav" 或 "flac"）。
    • include_timestamps（布尔值，可选，默认值：True）：是否包含单词/段落时间戳。
    • line_character_limit（整数，可选，默认值：80，最小值：40，最大值：200）：带时间戳输出的每行字符限制。
    • segment_length_minutes（整数，可选，默认值：5，最小值：1，最大值：24）：最大音频片段长度（分钟）。
  • 成功响应（200 OK）： 
    {
  "message": "转录成功，带有格式化的时间戳。",
  "file_processed": "your_audio_file.mp3",
  "transcription": "转录文本..."
}
  • 错误响应（例如，400，422，500）： 描述错误的 JSON 对象，其中包含一个 detail 字段。

2. ASR 模型信息

  • 端点： GET /info/asr-model/
  • 描述： 提供关于 ASR 模型的详细信息。
  • 成功响应（200 OK）： 
    {
  "model_name": "NVIDIA Parakeet TDT 0.6B V2 (En)",
  "status": "已加载",
  "input_requirements": "16kHz 音频（.wav 或 .flac），单声道",
  "output_type": "文本，可选带有标点符号、大写和时间戳。",
  "license": "CC-BY-4.0",
  "note": "此模型针对 NVIDIA GPU 加速系统进行了优化。"
}

3. 系统硬件规格

  • 端点： GET /info/system-hardware/
  • 描述： 获取系统硬件规格。
  • 成功响应（200 OK）： 包含系统硬件细节的 JSON 对象（详见 api/main.py 中的 SystemHardwareResponse 模型的完整结构）。 
    // 示例结构（字段可能因系统而异）
{
  "os_platform": "Darwin",
  "os_version": "...",
  "cpu_model": "Apple M1 Pro",
  "ram_total_gb": 16.0,
  "cuda_available": false,
  "gpus": [
    {
      "name": "Apple Metal Performance Shaders (MPS)",
      "memory_total_gb": "N/A (与系统内存共享)",
      "notes": "MPS 在此 Mac 上可用于 PyTorch。"
    }
  ]
  // ... 其他字段 ...
}

推荐的转录工作流程

此工作流程适用于 MCP 和 REST API 的使用，根据需要调整组件名称/调用。

  1. 读取硬件规格： 使用 info://system_hardware_specs（MCP）或 GET /info/system-hardware/（API）获取硬件详情。
  2. 确定段落长度： 根据硬件选择最优的 segment_length_minutes。
  3. 转录音频： 调用 transcribe_audio（MCP）或 POST /transcribe/（API），带上音频文件和选定的参数。
  4. （可选）获取模型信息： 使用 info://asr_model（MCP）或 GET /info/asr-model/（API）获取模型详情。

添加到 MCP 客户端主机

您可以配置 MCP 客户端（如 Claude Desktop 或其他支持自定义 MCP 服务器定义的工具）以使用此服务器。

手动 JSON 配置

对于使用 JSON 配置文件（如 cline_mcp_settings.json 或类似文件）定义 MCP 服务器的客户端，您可以为此转录服务器添加一个条目。确保已完成上述“设置和安装”步骤，以便 Python 3.12 和所有依赖项在客户端尝试运行服务器时在您的环境中可用。

这里是一个配置片段示例：

{
  "mcpServers": {
    "transcription-mcp": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 600,
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "nemo_toolkit[asr]",
        "--with",
        "pydub",
        "psutil",
        "fastmcp",
        "run",
        "/绝对路径/到此文件/server.py"
      ],
      "env": {},
      "transportType": "stdio"
    }
    // ... 其他服务器配置 ...
  }
}

使用 fastmcp install（对于支持的客户端）

一些 MCP 客户端，如 Claude Desktop App 的最新版本，集成了 fastmcp install 命令。这可以通过创建服务器的隔离环境来简化设置。如果您的客户端支持此功能，可以从该项目的根目录使用以下命令安装服务器：

fastmcp install server.py -e . -n "Parakeet 转录服务器"
  • -e .：以可编辑模式安装当前目录（应包含 pyproject.toml）。pyproject.toml 文件列出了核心依赖项（fastmcp、pydub、nemo_toolkit[asr]、psutil），fastmcp install 应该能够识别这些依赖项。
  • -n "Parakeet 转录服务器"：在客户端应用程序中为服务器设置自定义名称。

此命令通常会处理打包服务器及其指定的依赖项，以便客户端使用。

与服务器交互（客户端用法）

您可以使用任何兼容 FastMCP 的客户端与此 MCP 服务器进行交互。这里是一个使用 fastmcp 库的基本 Python 示例：

import asyncio
from fastmcp import Client

# 如果使用 'fastmcp run server.py' 运行 MCP 服务器（默认为 STDIO）：
client = Client("server.py")

# 如果使用 HTTP 运行服务器，例如 'fastmcp run server.py --transport streamable-http --port 8000'：
# client = Client("http://localhost:8000/mcp")

# 如果您已在客户端主机配置中添加了它（例如 Claude Desktop）
# 并且客户端库允许按名称/ID 引用：
# client = Client(mcp_server_id="parakeet-transcription-server-local") # 语法取决于客户端库

async def main():
    async with client:
        print(f"客户端连接：{client.is_connected()}")

        # 示例 1：获取 ASR 模型信息
        try:
            print("\n获取 ASR 模型信息...")
            model_info_result = await client.call_tool("get_asr_model_info")
            # 假设结果是第一个 TextContent 部分中的 JSON 字符串
            model_info_dict = model_info_result[0].text_content_as_json_dict()
            print("ASR 模型信息：")
            for key, value in model_info_dict.items():
                 print(f"  {key}: {value}")
        except Exception as e:
            print(f"调用 get_asr_model_info 出错：{e}")