端侧语音语义萃取引擎 | Whisper 离线语音解析专属技能定制手册

一、方案概述与原生能力短板

本项目基于 OpenAI Whisper 推理模型，打造适配 OpenClaw 生态的端侧语音语义萃取引擎，全程依托本地硬件完成运算，不依赖云端接口、不上传原始音视频数据。

原生 Whisper 仅为独立命令行工具，存在功能孤立、无法接入智能体调度体系、输出形式单一、缺少运行状态管控、实时拾音场景适配简陋、无本地化资源管理等问题。本次深度定制，将其封装为标准化技能模块，补齐硬件自适应调度、多格式结构化输出、本地资源缓存、实时语音捕获、跨技能协同、参数可视化管理等能力，构建集音频解析、语义提取、字幕生成、实时听写于一体的本地语音处理单元，适配会议录音、现场收音、影视素材转译、语音归档等多元使用场景。

二、定制化核心特性（原创功能体系）

纯本地离线推理：模型权重永久缓存至本地目录，断网环境下可正常工作，保障语音数据隐私安全
全域语种兼容识别：覆盖全球主流语种及汉语多地方言，针对口语化表达、嘈杂声场做识别优化
全载体格式兼容：支持 WAV、MP3、FLAC、M4A 等纯音频文件，同时解析 MP4、MKV 等视频内嵌音轨
多维度内容输出：可按需生成原生文本、标准时序字幕、带时间轴结构化数据，满足归档、剪辑、内容复盘需求
实时声场捕获转译：调用系统麦克风完成即时收音，一站式实现声音采集与文字萃取，无需第三方录制工具
算力智能适配：自动识别设备独显与 CPU 资源，动态切换加速模式，兼顾不同配置设备的运行效率
本地资源复用机制：对已完成解析的文件建立索引缓存，重复调用时跳过重复推理，实现秒级响应
生态联动能力：可对接文本凝练、集群运维、自主迭代类技能，形成「语音采集→语义萃取→内容梳理→运维监控」完整工作链路
自然语义交互：摒弃复杂命令行语法，使用中文场景化指令完成全功能操作，降低使用门槛

三、前置运行环境部署

1. 基础依赖组件安装

运行本引擎需提前部署 Python 运行环境与多媒体编解码工具 FFmpeg：

基础要求：Python 3.8 及以上稳定版本

FFmpeg 安装指令

bash

运行

# macOS（已安装 Homebrew）
brew install ffmpeg

# Debian / Ubuntu 系 Linux
sudo apt update && sudo apt install ffmpeg -y

# Windows 系统（管理员 PowerShell，需提前部署 Chocolatey）
choco install ffmpeg

2. 推理框架与模型库部署

使用国内镜像源加速安装，一次性部署语音推理核心依赖：

bash

运行

pip install openai-whisper torch torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 模型档位选型参考

结合设备硬件性能、解析速度与识别精度，区分不同使用档位：

轻量档位（tiny/base）：占用资源极低、推理速度快，适合低配设备、简单短句识别
均衡档位（small/medium）：速度与准确率平衡，日常办公、普通录音场景首选
旗舰档位（large-v3 /turbo）：识别精度拉满，擅长方言、复杂声场、长语音解析，建议大内存 + 独立显卡设备使用

四、技能目录规划

在 OpenClaw 自定义技能根目录下创建独立文件夹，区分不同操作系统路径：

macOS / Linux：~/.openclaw/skills/speech-extract-engine
Windows：C:\Users\你的系统用户名\.openclaw\skills\speech-extract-engine

目录内创建三份核心文件，各司其职：

meta.json：技能元数据、触发指令、系统权限配置
param.profile：运行参数、路径、硬件策略配置文件
service.js：核心业务逻辑，整合目录初始化、指令分发、语音解析、实时收音等功能

五、核心文件完整源码（可直接部署）

1. meta.json 技能注册配置文件

用于 OpenClaw 识别技能身份、监听触发指令、分配系统权限：

json

{
  "name": "speech-extract-engine",
  "version": "4.2.0-local-runtime",
  "author": "Independent Dev",
  "description": "端侧语音语义萃取引擎，基于Whisper实现本地音视频解析、实时收音、时序字幕生成，支持硬件加速与多技能协同",
  "trigger": [
    "解析语音素材",
    "即时声场听写",
    "生成时序脚本",
    "查看引擎运行参数",
    "切换推理模型档位"
  ],
  "permissions": [
    "system:shell",
    "file:access",
    "file:persist",
    "device:audio-input",
    "hardware:gpu-control",
    "config:read-param",
    "config:modify-param"
  ],
  "entry": "service.js",
  "disabled": false
}

2. param.profile 运行参数配置文件

统一管理推理模型、识别语种、存储路径、硬件模式，可手动编辑修改：

json

{
  "infer_model": "large-v3",
  "target_lang": "zh",
  "default_export_type": "txt",
  "gpu_accelerate": true,
  "local_cache_enable": true,
  "data_output_path": "~/SpeechExtract_Output",
  "model_storage_path": "~/.local/cache/speech-model"
}

3. service.js 核心逻辑主程序

实现目录初始化、配置加载、文件解析、实时收音、指令解析、异常捕获全流程：

javascript

运行

const fs = require('fs').promises;
const path = require('path');
const os = require('os');
const { exec, spawn } = require('child_process');

// 定义配置文件路径
const PROFILE_PATH = path.join(__dirname, 'param.profile');
let runtimeParam = {};

// 初始化全局工作目录
async function initWorkspaceDir() {
  const dirCollection = [
    os.homedir() + "/SpeechExtract_Output",
    os.homedir() + "/.local/cache/speech-model"
  ];
  for (const singleDir of dirCollection) {
    await fs.mkdir(singleDir, { recursive: true });
  }
}

// 加载运行参数配置
async function loadProfile() {
  const fileContent = await fs.readFile(PROFILE_PATH, 'utf8');
  runtimeParam = JSON.parse(fileContent);
}

// 执行音视频素材解析任务
function runMaterialParse(filePath, exportFormat) {
  return new Promise((resolve, reject) => {
    const modelTag = runtimeParam.infer_model;
    const langTag = runtimeParam.target_lang;
    const deviceArg = runtimeParam.gpu_accelerate ? "" : "--device cpu";
    const execCmd = `whisper "${filePath}" --model ${modelTag} --language ${langTag} --output_format ${exportFormat} ${deviceArg}`;

    exec(execCmd, (err, stdout, stderr) => {
      if (err) {
        reject({ error: err, log: stderr });
      } else {
        resolve(stdout);
      }
    });
  });
}

// 实时麦克风声场捕获与转译
function startRealTimeCapture() {
  return new Promise((resolve, reject) => {
    const tempAudioFile = path.join(os.tmpdir(), "temp_speech_capture.wav");
    // 预设录音时长，可按需调整数值
    const captureProcess = spawn("ffmpeg", [
      "-f", "dshow",
      "-i", "audio=麦克风",
      "-t", "6",
      tempAudioFile
    ]);

    captureProcess.on("close", async () => {
      const parseResult = await runMaterialParse(tempAudioFile, "txt");
      await fs.unlink(tempAudioFile).catch(() => {});
      resolve(parseResult);
    });

    captureProcess.on("error", (procErr) => {
      reject(procErr);
    });
  });
}

// 解析用户交互指令
function decodeUserCommand(inputContent) {
  if (inputContent.includes("解析语音素材")) {
    return { action: "parseFile", source: inputContent.replace("解析语音素材", "").trim() };
  }
  if (inputContent.includes("即时声场听写")) {
    return { action: "realTimeRecord" };
  }
  if (inputContent.includes("生成时序脚本")) {
    return { action: "genSubtitle", source: inputContent.replace("生成时序脚本", "").trim() };
  }
  if (inputContent.includes("查看引擎运行参数")) {
    return { action: "checkStatus" };
  }
  return { action: "unknown" };
}

// 技能统一入口
module.exports = async function (context, userInput) {
  try {
    await initWorkspaceDir();
    await loadProfile();
    const cmdInfo = decodeUserCommand(userInput);

    // 查看引擎当前运行参数
    if (cmdInfo.action === "checkStatus") {
      return {
        success: true,
        message: `📈 语音语义萃取引擎运行概况\n当前推理模型：${runtimeParam.infer_model}\n识别目标语种：${runtimeParam.target_lang}\n独显加速状态：${runtimeParam.gpu_accelerate ? "已启用" : "已关闭"}\n默认导出格式：${runtimeParam.default_export_type}`
      };
    }

    // 实时收音听写
    if (cmdInfo.action === "realTimeRecord") {
      const extractResult = await startRealTimeCapture();
      return {
        success: true,
        message: `🎙️ 即时声场听写结果：\n${extractResult}`
      };
    }

    // 解析本地音视频素材
    if (cmdInfo.action === "parseFile") {
      if (!cmdInfo.source) {
        return { success: false, message: "❌ 请补充待解析素材的完整路径" };
      }
      const parseRes = await runMaterialParse(cmdInfo.source, runtimeParam.default_export_type);
      return {
        success: true,
        message: `✅ 语音素材解析完成\n${parseRes}`
      };
    }

    // 生成时序字幕脚本
    if (cmdInfo.action === "genSubtitle") {
      if (!cmdInfo.source) {
        return { success: false, message: "❌ 请补充音视频素材的完整路径" };
      }
      const subRes = await runMaterialParse(cmdInfo.source, "srt");
      return {
        success: true,
        message: `✅ 时序脚本生成完成\n${subRes}`
      };
    }

    // 无法识别指令
    return {
      success: false,
      message: "❌ 未匹配到可用操作指令，请使用标准交互话术"
    };

  } catch (error) {
    return {
      success: false,
      message: `❌ 语音萃取引擎运行异常：${error.message}`
    };
  }
};

六、技能加载与上线验证

1. 配置全局技能目录

编辑 OpenClaw 主配置文件 ~/.openclaw/openclaw.json，确保本地自定义技能可被正常加载：

json

{
  "skills": {
    "localPaths": ["~/.openclaw/skills"]
  }
}

2. 重载技能并校验状态

在终端执行以下命令，完成部署校验：

bash

运行

openclaw reload
openclaw doctor

终端技能列表中出现 speech-extract-engine 4.2.0-local-runtime，即代表部署完成。

七、全功能交互指令（直接使用）

查看引擎全部运行参数 查看引擎运行参数
解析本地音频 / 视频文件，输出纯文本内容 解析语音素材 D:\archive\meeting_record.mp3
基于音视频素材生成标准时序字幕脚本 生成时序脚本 /home/user/media/short_video.mp4
调用麦克风，完成即时收音与文字转译 即时声场听写

八、常见异常排查方案

系统提示 FFmpeg 工具缺失 检查工具安装是否完整，将 FFmpeg 可执行文件所在目录添加至系统环境变量。
模型文件下载进度缓慢 手动将模型权重文件拷贝至 param.profile 内 model_storage_path 对应的目录，跳过在线下载流程。
独立显卡无法开启硬件加速 核对显卡驱动、CUDA 运行环境完整性，确认当前 PyTorch 版本为 GPU 适配版。
实时收音无采集到声音 Windows 检查麦克风设备名称与系统音频设置；Linux /macOS 确认应用拥有麦克风调用权限。
方言、低音质音频识别效果差 切换至 large-v3 高精度推理模型，同时保证录音素材声场清晰。

九、功能拓展延伸方向

联动文本凝练类技能：长语音萃取完成后，自动提炼核心观点、精简内容摘要
接入集群运维单元：将本语音引擎纳入 MCP 集群管控，实现进程监控、异常告警、自动重启
拓展批量解析能力：支持批量读取文件夹内所有音视频文件，一键完成全域解析
新增语种快速切换指令：通过交互指令直接修改识别语种，无需手动编辑配置文件
结合自主迭代技能：根据识别错误案例，动态优化推理参数与语种配置