把一段录音变成一篇结构干净的 Markdown 笔记这件事的完整链路是很多人在搭本地语音工作流时想实现的目标。Dictata 就是这样一个轻量工具先用 Whisper 在本地完成语音识别再用大语言模型对转写文本做清理和结构化。相比直接使用在线语音转写这种本地优先的做法更适合对隐私有要求、需要长期保存原始音频、或者希望自由调整输出风格的场景。很多人初次接触 Whisper 时会有一种“识别出来就结束了”的错觉。实际用过就会发现Whisper 输出的原始文本里经常混着语气词、无标点长句、口语重复、甚至识别错误。它更接近“语音听写稿”而不是“可读文章”。这也是 LLM cleanup 存在的意义让大模型把听写稿整理成能直接放进 Obsidian、Notion 或博客后台的 Markdown 文本。这篇文章会从零实现一个最小可运行的 Dictata 流程覆盖架构设计、环境配置、核心代码、参数选择、运行验证和常见问题排查。项目正文比较零散因此下面会按真实项目常用的方式补全工程细节。如果你准备把录音变成笔记、会议纪要、采访稿或博客草稿这套思路可以直接落成脚本。1. 先想清楚 Dictata 到底要解决什么问题1.1 听写和整理是两个阶段不应该混在一起语音输入链路里最容易犯的错是把“识别”和“整理”当成同一件事。Whisper 本身是自动语音识别模型它负责把音频转成文字。至于这段文字里是否去掉“嗯”“啊”是否给长句加标点是否需要把口语语序调整为书面语这已经超出了 ASR 的能力边界。Dictata 的设计核心是把这条链路拆成两个独立阶段阶段一用 Whisper 做本地语音转写得到带时间戳的原始文本。阶段二用 LLM 对原始文本做清理、标点补全、段落合并和 Markdown 格式化。拆开的好处是每一步都能独立验证、独立替换。比如 Whisper 识别质量不好可以换更大的模型或者换 faster-whisper 后端LLM 整理风格不满意只需要改 prompt不需要重新跑音频转写。1.2 Whisper 原始输出为什么不能直接读我用中文音频做过大量测试Whisper 的识别准确率在常见模型下已经很不错但输出风格距离“可读”相差很远。典型问题包括没有标点或标点位置不稳定。口语填充词原样保留例如“嗯”“然后”“那个”“就是”。同一句话被拆成多个片段重新拼接后逻辑断裂。专有名词、英文术语、数字单位可能被写成同音字。说话人切换没有标记多人会议转录后像一个人独白。这些问题不是 Whisper 的缺陷而是 ASR 的设计目标决定的。Whisper 要做的是“把声音变成文字”不是“把话变成文章”。因此后续的 LLM cleanup 环节不只是锦上添花而是整个链路能否进入生产使用的关键。1.3 本地优先的取舍Dictata 强调 Local是指录音文件、Whisper 模型和清理过程都可以在本地完成。这样做有几个实际收益隐私可控音频不离开设备适合访谈、医疗、法务、企业内部会议等场景。成本稳定语音转写按分钟计费的服务在长音频场景下成本不低本地推理只消耗电力。离线可用没有网络也能转录和整理。可复现模型版本固定后同一段音频的转写结果是稳定的方便调试。代价是环境配置成本更高尤其是 GPU 不是默认就有的。后续会给出 CPU 与 GPU 两种运行路径。注意本地优先不等于完全不联网。如果选择使用 OpenAI API、DeepSeek API 或其他远程 LLM音频仍然是本地的只有转写文本会被发送到模型服务端。要完全离线需要替换成本地 Ollama 模型。2. 整体架构与数据流2.1 四个核心模块Dictata 的最小架构可以分成四个模块每一个都只负责一件事模块职责输入输出audio读取音频文件或录制麦克风声音mp3/wav/m4aWAV 文件或路径transcribe调用 Whisper 模型转写音频路径原始文本、片段列表cleanup调用 LLM 清理与格式化原始文本Markdown 文本pipeline cli串联整个流程一条命令输出 Markdown 文件这种分层方式不是过度设计。音频处理、转写和清理各自的依赖差异很大写在一个文件里会很难调试。比如某个音频解码失败你希望能单独验证 audio 模块LLM 清理结果不满意你希望不需要重跑 Whisper。2.2 数据流的实际样子一次完整运行的数据流如下recordings/demo.wav | v [audio.decode] - 16kHz 单声道 WAV | v [transcribe] - raw transcript segments | v [cleanup] - markdown string | v [write output] - outputs/demo.md转写结果不直接进入输出而是先落到一个字符串变量里方便写入日志也方便在调试时对比原始文本和清理后文本。2.3 为什么要保留原始转写文本清理后的 Markdown 是最终交付物但原始转写文本同样重要。原因有两点排查 LLM 幻觉时需要对照原文。如果清理模型擅自改写了原意你需要知道是哪一步造成的。后续可以调整 prompt对同一份原始文本反复做多轮清理而不需要重新转写音频。因此pipeline 执行完成后建议同时在日志里输出原始文本长度和清理后文本长度并把原始转写保存为.txt文件。这个体积不大却能让调试成本大幅降低。3. 环境准备与项目结构3.1 Python 版本与核心依赖建议使用 Python 3.10 或更高版本。下面这套依赖组合在 Windows、macOS 和常见 Linux 发行版上都跑得通pip install faster-whisper openai sounddevice pydub pyyaml如果使用 OpenAI 官方 Whisper 而不是 faster-whisper则需要额外安装 PyTorchpip install faster-whisper pip install openai pip install sounddevice pydub pyyaml这里优先选择 faster-whisper 作为转写后端。它使用 CTranslate2 推理不强制依赖完整 PyTorch在 CPU 和 GPU 上都有性能优势API 与 Whisper 模型基本兼容。如果你对 openai-whisper 更熟悉也可以替换成它核心流程不需要改动。3.2 LLM 接入方式Dictata 的清理阶段使用 OpenAI 兼容接口。这意味着只要模型服务提供/v1/chat/completions接口就能接入。常见选项场景LLM 服务地址api_key本地离线http://localhost:11434/v1随便填如 ollama在线 API按服务商文档配置你的密钥使用 OpenAI 官方 Python SDK 的另一个好处是到任何兼容接口切换时只需要修改api_base不需要重写清理逻辑。启动本地 Ollama 服务的命令ollama serve ollama run qwen2.5:7bOllama 默认监听 11434 端口并对外提供 OpenAI 兼容端点。3.3 项目目录结构dictata/ ├── config.yaml ├── requirements.txt ├── recordings/ │ └── demo.wav ├── outputs/ └── dictata/ ├── __init__.py ├── cli.py ├── config.py ├── audio.py ├── transcribe.py ├── cleanup.py └── pipeline.py这个结构与本文的模块划分一一对应。后续要加说话人分离、音频降噪、格式模板等功能时也有明确的位置可以放。3.4 配置文件示例config.yaml里放的是运行期可变参数不应该把 API 密钥等敏感信息写死在代码里。whisper: model: small device: cpu compute_type: int8 language: zh initial_prompt: 以下是普通话的会议记录请使用中文标点。 beam_size: 5 llm: api_base: http://localhost:11434/v1 api_key: ollama model: qwen2.5:7b temperature: 0.2 max_tokens: 2000 output: dir: outputs save_raw: true log: level: INFO这里的language: zh表示默认按中文识别。如果你的音频是英文可以改成en或删除该字段让 Whisper 自动判断。4. 核心代码实现4.1 配置加载config.py负责读取 YAML 文件并提供接近对象属性的访问方式。这里不引入 pydantic只用一个简单类避免额外依赖import yaml from types import SimpleNamespace def load_config(pathconfig.yaml): with open(path, r, encodingutf-8) as f: data yaml.safe_load(f) return SimpleNamespace( whisperSimpleNamespace(**data.get(whisper, {})), llmSimpleNamespace(**data.get(llm, {})), outputSimpleNamespace(**data.get(output, {})), logSimpleNamespace(**data.get(log, {})), )使用SimpleNamespace的好处是可以在代码里写cfg.whisper.model可读性比字典更好。配置文件缺字段时代码用get方法给默认值避免启动即崩溃。4.2 音频输入模块audio.py提供两个能力从已有音频文件读取以及从麦克风录制一段声音。文件读取只需要返回最终可用于 Whisper 的 WAV 路径import subprocess from pathlib import Path def decode_to_wav(input_path: str, target_sr: int 16000) - str: input_path Path(input_path) output_path input_path.with_suffix(.wav) if input_path.suffix.lower() .wav: return str(input_path) cmd [ ffmpeg, -y, -i, str(input_path), -ar, str(target_sr), -ac, 1, str(output_path), ] subprocess.run(cmd, checkTrue, capture_outputTrue) return str(output_path)这里强制把音频统一转换为 16kHz 单声道 WAV是 Whisper 预处理的推荐格式。多声道或高采样率的音频会让转写效果不稳定也会增加计算量。麦克风录制用sounddeviceimport sounddevice as sd import soundfile as sf def record(duration: float, sample_rate: int 16000, output: str recordings/mic.wav): print(fRecording {duration} seconds...) audio sd.rec(int(duration * sample_rate), sampleratesample_rate, channels1, dtypeint16) sd.wait() sf.write(output, audio, sample_rate) return output实际使用中建议用按键停止录制而不是固定时长这是后话。最小版本先按秒数录制。4.3 Whisper 转写模块transcribe.py封装 faster-whisper 的调用from faster_whisper import WhisperModel def load_model(cfg): return WhisperModel( cfg.model, devicecfg.device, compute_typecfg.compute_type, ) def transcribe_audio(model, audio_path, cfg): segments, info model.transcribe( audio_path, languagegetattr(cfg, language, None), initial_promptgetattr(cfg, initial_prompt, None), beam_sizegetattr(cfg, beam_size, 5), ) segment_list [] for seg in segments: segment_list.append(seg.text.strip()) raw_text .join(segment_list) return raw_text, segment_list注意model.transcribe返回的是一个生成器segments。如果直接执行len(segments)会报错必须先遍历列表。这也是初学者最容易踩坑的地方。4.4 LLM 清理模块cleanup.py是整个 Dictata 的“文字后期处理车间”。核心是 prompt 设计和 OpenAI 客户端调用from openai import OpenAI SYSTEM_PROMPT 你是一个录音文本整理助手。用户会给你一段语音转写文本它可能包含口语词、重复词、语气词、断句错误和缺少标点的问题。 请把这段文本整理成适合阅读的 Markdown 1. 去掉“嗯”“啊”“然后”“那个”“就是”等不影响语义的口语填充词。 2. 补充正确的标点符号。 3. 将语义相近的短句合并为完整段落。 4. 不要改写原意不要补充原文没有的事实。 5. 如果内容出现明显的主题切换可以使用 Markdown 二级标题作为分隔。 6. 保留数字、日期、人名、公司名和专有名词的原始信息。 7. 只输出整理后的 Markdown 正文不要输出任何解释或开头语。 def build_client(cfg): return OpenAI( base_urlcfg.api_base, api_keycfg.api_key, timeout120.0, ) def clean_transcript(client, transcript, cfg): response client.chat.completions.create( modelcfg.model, temperaturecfg.temperature, max_tokenscfg.max_tokens, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: f转写文本\n{transcript}}, ], ) content response.choices[0].message.content return content.strip()这个 prompt 的细节值得解释。第 1 条处理口语词是听写稿最常见的噪音第 3 条负责合并短句第 4 条是防幻觉边界避免大模型自动补出原文没有的内容第 7 条保证 Markdown 输出干净不出现“好的以下是整理后的文本”这类多余开头。4.5 输出与保存pipeline.py把各步骤串联起来import logging import time from pathlib import Path from dictata.audio import decode_to_wav from dictata.transcribe import load_model, transcribe_audio from dictata.cleanup import build_client, clean_transcript def run(audio_path, cfg, output_name: str): logger logging.getLogger(dictata) logger.info(audio decode start) wav_path decode_to_wav(audio_path) logger.info(whisper load model) model load_model(cfg.whisper) logger.info(transcribe start) t0 time.time() raw_text, segments transcribe_audio(model, wav_path, cfg.whisper) logger.info(transcribe done, seconds%.1f, text_len%d, time.time() - t0, len(raw_text)) if getattr(cfg.output, save_raw, True): raw_path Path(cfg.output.dir) / f{output_name}.raw.txt raw_path.parent.mkdir(parentsTrue, exist_okTrue) raw_path.write_text(raw_text, encodingutf-8) logger.info(raw transcript saved: %s, raw_path) client build_client(cfg.llm) logger.info(llm cleanup start) markdown_text clean_transcript(client, raw_text, cfg.llm) out_path Path(cfg.output.dir) / f{output_name}.md out_path.parent.mkdir(parentsTrue, exist_okTrue) out_path.write_text(markdown_text, encodingutf-8) logger.info(markdown saved: %s, out_path) return str(out_path)注意这里把原始文本先保存了一次然后再清理。前面说过这是为了日后调试 prompt 的时候不重跑 Whisper。4.6 命令行入口cli.py提供最简单的一条命令入口import argparse import logging from dictata.config import load_config from dictata.pipeline import run def main(): parser argparse.ArgumentParser(descriptionDictata local dictation) parser.add_argument(audio, helpaudio file path) parser.add_argument(-o, --output, defaultdemo, helpoutput name without extension) parser.add_argument(--config, defaultconfig.yaml, helpconfig yaml path) args parser.parse_args() logging.basicConfig(levellogging.INFO, format%(asctime)s %(name)s %(levelname)s %(message)s) cfg load_config(args.config) result run(args.audio, cfg, args.output) print(result) if __name__ __main__: main()运行方式python -m dictata.cli recordings/demo.wav -o demo输出结果会在终端打印 Markdown 文件路径。5. 关键参数详解5.1 Whisper 模型怎么选模型大小直接决定转写质量、延迟和资源占用。不同任务的选择建议如下模型参数量CPU 相对速度GPU 显存经验值适用场景中文转写质量tiny39M很快1GB测试流程、低要求速记一般base74M快约1GB短语音、简单命令中等small244M中等约2GB通用听写、日常笔记良好medium769M慢约5GB中文长音频、会议记录优秀large-v31550M很慢约10GB高质量转写、广播级最好如果第一次跑通流程先用base或small。等到确认整个链路没有问题时再换成medium或large-v3。注意显存只是经验值实际占用受 beam size、batch size 和 compute type 影响。5.2 转写阶段的重要参数参数默认值作用调大/调小影响languageNone指定音频语言指定后可避免语言自动检测误差initial_promptNone给模型一个文本风格提示可引导专有名词和标点习惯beam_size5搜索宽度调大质量略好速度明显变慢compute_typefast精度类型CPU 推荐 int8GPU 可用 float16fp16Trueopenai-whisper 特有GPU 开启CPU 必须关闭initial_prompt是一个容易忽略但效果明显的参数。比如会议记录场景下可以写“以下是产品评审会的录音会出现数据库、接口、缓存等术语。”模型会更倾向保留这些词的正确写法。5.3 LLM 清理阶段的参数参数推荐值说明temperature0.1 到 0.3越低越稳定清理任务不需要创造性max_tokens2000 左右中文转写按字数和 token 守恒按输入长度的 1.5 倍预留timeout120 秒本地模型首次加载或思考较慢时不容易误报超时做文本清理不是写文案高温会导致模型擅自扩写。建议把 temperature 稳定在 0.2 以下。如果模型仍然在改写原文可以再往 prompt 里加一条“只能删减和调整语序不能新增内容”。5.4 Prompt 设计是 LLM cleanup 的核心资产prompt 不是写一次就结束的。不同用途需要不同清理规则建议把 system prompt 按模板拆开放到配置文件或单独目录里meeting.md会议纪要保留决策、待办、参与人。blog.md博客草稿优化语句流畅度保留口语气口。general.md通用笔记只去除填充词和补标点。把规则外置后命令行可以增加一个--preset meeting参数运行时加载不同的 system prompt。这样 Dictata 就不再只是“转写工具”而是一个可配置的语音笔记处理器。6. 运行与验证6.1 准备一段测试音频在 Linux 上可以用 espeak-ng 生成一段中文测试音频前提是系统已安装中文语音包espeak-ng -v cmn -z -w recordings/demo.wav 今天想和大家说的是关于本地部署语音转写的问题。Whisper 在中文上表现不错但是标点经常缺失语气词也很多所以需要大语言模型来清理一下。macOS 上可以用系统 say 命令say -o recordings/demo.aiff 今天想和大家说的是关于本地部署语音转写的问题。 ffmpeg -y -i recordings/demo.aiff -ar 16000 -ac 1 recordings/demo.wav如果没有 TTS直接用手机录音文件也可以但要注意文件格式。Whisper 对 mp3 也可以解码但底层还是转换成统一采样率更稳妥。6.2 执行转写与清理python -m dictata.cli recordings/demo.wav -o demo --config config.yaml预期日志类似2025-01-06 12:00:01 dictata INFO audio decode start 2025-01-06 12:00:02 dictata INFO whisper load model 2025-01-06 12:00:05 dictata INFO transcribe start 2025-01-06 12:00:08 dictata INFO transcribe done, seconds3.1, text_len78 2025-01-06 12:00:10 dictata INFO raw transcript saved: outputs/demo.raw.txt 2025-01-06 12:00:22 dictata INFO markdown saved: outputs/demo.md6.3 预期输出对比用“今天想和大家说的是关于本地部署语音转写的问题”这段音频转写后的原始文本可能长这样就是就是今天想和大家说的是关于那个本地部署语音转写的问题然后呢其实啊whisper它在中文上表现已经不错了但是呢它标点经常会没有然后还有那个语气词也很多嗯所以需要大模型来清理一下LLM 清理后的 Markdown今天想和大家说的是关于本地部署语音转写的问题。其实 Whisper 在中文上表现已经不错了但标点经常缺失语气词也很多所以需要大语言模型来清理一下。这两个文件放在一起看就能直观理解为什么“转写”后面还要接“清理”。6.4 判断质量是否有提升的三个标准清理后的文本不是“看起来通顺”就算合格建议用三个标准自检检查维度通过标准信息保真清理后没有新增原文不存在的数字、结论、人名格式正确Markdown 标题层级不跳跃锚点和引用块没有乱套段落合理同一主题的句子没有被拆到不同段落语义连续如果三个标准都满足说明 prompt 和参数组合是有效的。任意一个不满足优先调整 prompt而不是盲目升级模型。7. 常见问题排查7.1 转写结果为空现象pipeline 跑完原始文本长度接近 0。可能原因音频实际是静音或音量极低。音频采样率太高多声道没有预处理。Whisper 语言参数与真实音频不匹配。检查方式用播放器打开音频确认内容。用 ffprobe 查看音频信息。ffprobe recordings/demo.wav用 Python 直接打印分段结果确认是否走了循环。处理建议统一转成 16kHz 单声道 WAV。去掉language参数让模型自动检测。检查麦克风输入音量。7.2 CUDA out of memory现象GPU 模式启动后转写过程中抛出CUDA out of memory。可能原因显存不足以加载当前模型。compute_type 使用了显存占用过高的 float32。长时间运行后显存碎片累积。检查方式观察报错输出的显存占用数据。用nvidia-smi查看当前显存占用。nvidia-smi处理建议换成更小的模型例如从medium降到small。显存较小使用compute_type: float16。显存不足时直接退回 CPU 和int8。7.3 中文识别出现拼音或英文乱码现象输出文本中出现不应该存在的拼音或者中文被识别成英文单词。可能原因语言参数缺失导致 Whisper 自动检测出错。音频本身混有较多英文术语。使用过老的 Whisper 版本中文能力较弱。处理建议在配置里固定language: zh。在initial_prompt中写出预期包含的中文关键词。升级到medium或large-v3模型。如果项目基于 openai-whisper可以切换到 faster-whisper 再测试同一模型下转写表现会略有不同。7.4 LLM 请求超时现象日志卡在llm cleanup start然后报llm request timed out。可能原因本地 Ollama 模型没有启动或未下载。本地推理速度太慢超过客户端 timeout。远程 API 服务端网络波动或排队。检查方式先单独测试 LLM 服务是否可用。curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:7b,messages:[{role:user,content:hi}],max_tokens:10}确认 Ollama 日志中是否显示正在加载模型。处理建议将timeout从 120 调整到 300 秒本地首轮加载慢是正常现象。或者清理前先把模型拉入内存避免首轮冷启动。7.5 LLM 擅自补充原文没有的内容现象清理后的文本比原始转写多了结论、建议或其他内容。可能原因temperature 设置过高。system prompt 没有明确禁止扩写。上下文里没有提醒模型“只能整理不能创作”。处理建议temperature 降到 0.1。prompt 增加硬性规则不要补充原文不存在的信息。输出前做一次 diff逐句核对清理文本是否与原文语义一致。注意LLM 清理阶段是整条链路里最“不可控”的环节。只要发现一次内容被篡改就应该把禁止扩写写进 system prompt而不能指望换一个更大的模型自动解决。7.6 本地 Ollama 模型加载慢或内存不足现象首次启动时等待很久或者直接 OOM 退出。可能原因模型参数太大内存不足。没有做模型量化。系统 swap 空间过小。处理建议使用量化版本例如qwen2.5:7b-instruct-q4_K_M。关闭并行多任务避免内存争抢。如果硬件有限用 7B 或更小的 3B 模型。8. 最佳实践与扩展方向8.1 可以沉淀成一套个人语音笔记工作流Dictata 的最小实现跑通后可以把它放进日常使用手机录音后传到recordings/目录一条命令生成 Markdown。会议录音转写后直接输入到 Obsidian 或个人 wiki 库。采访稿先用 Whisper 转写再用 LLM 整理成通顺文章。博客选题用口述录音清理后作为初稿。因为输出是标准 Markdown所以下游可以接任何笔记系统。这也是标题里“LLM cleanup”最有价值的地方不是做字幕而是生成可以直接进入知识库的文本。8.2 生产化之前要补充的能力从“自己能用”到“稳定服务”至少还要补这几项日志记录音频路径、模型版本、prompt 版本、耗时、原始文本长度和清理后长度。失败重试LLM 请求失败时对生成器结果做退避重试。队列化长音频不是一次同步请求就能结束的要改成任务队列。格式校验清理后的 Markdown 需要校验标题层级和代码块是否闭合。敏感信息保护如果音频包含手机号、地址、身份证要提前做脱敏。术语表把项目里的专有名词写成术语 JSON注入 prompt减少同音字错误。8.3 扩展方向说话人分离与加标签用 pyannote 或其他 VAD 工具切分说话人然后在 LLM 清理时输出对话体 Markdown。RAG 增强清理如果录音内容涉及特定项目可以把历史文档、技术资料作为上下文注入 LLM让清理结果更符合团队表达习惯。预设风格模板把博客、会议纪要、待办清单、日记等输出格式做成模板列表。增量术语热更新将 Whisper 识别后出现的高频陌生词自动加入 glossary下一轮调用时生效。桌面端封装把 Python 脚本包装成带录制按钮的桌面小程序避免每次都在终端敲命令。8.4 给新手的实践建议如果你第一次接触这条链路不要一开始就追求最大模型和完美输出。建议按这个顺序练习先生成一段 10 秒中文测试音频用 tiny 模型跑通整条链路。对比原始转写和清理后 Markdown理解两个阶段的差异。换成 small 或 medium 模型观察转写质量提升。用自己的真实会议录音测试把问题收集起来慢慢优化 prompt。保持 prompt 和配置文件的版本化方便回退。本地语音转写加 LLM 清理本质上是把一段音频加工成一篇结构化了的知识内容。Whisper 负责把声音变成文字LLM 负责把文字变成文章。这两个环节独立演进又通过标准文本格式衔接整体方案在隐私、成本和扩展性之间找到了一个很实用的平衡点。如果你的下一个项目是语音笔记、会议记录或播客整理Dictata 的这套结构可以直接作为起点。