企业官网建设流程全解析

把一段录音变成一篇结构干净的 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 模块；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，则需要额外安装 PyTorch：

pip 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接口，就能接入。常见选项：

使用 OpenAI 官方 Python SDK 的另一个好处是：到任何兼容接口切换时，只需要修改api_base，不需要重写清理逻辑。

启动本地 Ollama 服务的命令：

ollama serve ollama run qwen2.5:7b

Ollama 默认监听 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(path="config.yaml"): with open(path, "r", encoding="utf-8") as f: data = yaml.safe_load(f) return SimpleNamespace( whisper=SimpleNamespace(**data.get("whisper", {})), llm=SimpleNamespace(**data.get("llm", {})), output=SimpleNamespace(**data.get("output", {})), log=SimpleNamespace(**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, check=True, capture_output=True) return str(output_path)

这里强制把音频统一转换为 16kHz 单声道 WAV，是 Whisper 预处理的推荐格式。多声道或高采样率的音频会让转写效果不稳定，也会增加计算量。

麦克风录制用sounddevice：

import sounddevice as sd import soundfile as sf def record(duration: float, sample_rate: int = 16000, output: str = "recordings/mic.wav"): print(f"Recording {duration} seconds...") audio = sd.rec(int(duration * sample_rate), samplerate=sample_rate, channels=1, dtype="int16") 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, device=cfg.device, compute_type=cfg.compute_type, ) def transcribe_audio(model, audio_path, cfg): segments, info = model.transcribe( audio_path, language=getattr(cfg, "language", None), initial_prompt=getattr(cfg, "initial_prompt", None), beam_size=getattr(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_url=cfg.api_base, api_key=cfg.api_key, timeout=120.0, ) def clean_transcript(client, transcript, cfg): response = client.chat.completions.create( model=cfg.model, temperature=cfg.temperature, max_tokens=cfg.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(parents=True, exist_ok=True) raw_path.write_text(raw_text, encoding="utf-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(parents=True, exist_ok=True) out_path.write_text(markdown_text, encoding="utf-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(description="Dictata local dictation") parser.add_argument("audio", help="audio file path") parser.add_argument("-o", "--output", default="demo", help="output name without extension") parser.add_argument("--config", default="config.yaml", help="config yaml path") args = parser.parse_args() logging.basicConfig(level=logging.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 模型怎么选

模型大小直接决定转写质量、延迟和资源占用。不同任务的选择建议如下：

如果第一次跑通流程，先用base或small。等到确认整个链路没有问题时，再换成medium或large-v3。注意显存只是经验值，实际占用受 beam size、batch size 和 compute type 影响。

5.2 转写阶段的重要参数

initial_prompt是一个容易忽略但效果明显的参数。比如会议记录场景下，可以写“以下是产品评审会的录音，会出现数据库、接口、缓存等术语。”模型会更倾向保留这些词的正确写法。

5.3 LLM 清理阶段的参数

做文本清理不是写文案，高温会导致模型擅自扩写。建议把 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, seconds=3.1, text_len=78 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.md

6.3 预期输出对比

用“今天想和大家说的是关于本地部署语音转写的问题”这段音频，转写后的原始文本可能长这样：

就是就是今天想和大家说的是关于那个本地部署语音转写的问题然后呢其实啊whisper它在中文上表现已经不错了但是呢它标点经常会没有然后还有那个语气词也很多嗯所以需要大模型来清理一下

LLM 清理后的 Markdown：

今天想和大家说的是关于本地部署语音转写的问题。其实 Whisper 在中文上表现已经不错了，但标点经常缺失，语气词也很多，所以需要大语言模型来清理一下。

这两个文件放在一起看，就能直观理解为什么“转写”后面还要接“清理”。

6.4 判断质量是否有提升的三个标准

清理后的文本不是“看起来通顺”就算合格，建议用三个标准自检：

如果三个标准都满足，说明 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 给新手的实践建议

如果你第一次接触这条链路，不要一开始就追求最大模型和完美输出。建议按这个顺序练习：

1. 先生成一段 10 秒中文测试音频，用 tiny 模型跑通整条链路。
2. 对比原始转写和清理后 Markdown，理解两个阶段的差异。
3. 换成 small 或 medium 模型，观察转写质量提升。
4. 用自己的真实会议录音测试，把问题收集起来，慢慢优化 prompt。
5. 保持 prompt 和配置文件的版本化，方便回退。

本地语音转写加 LLM 清理，本质上是把一段音频加工成一篇结构化了的知识内容。Whisper 负责把声音变成文字，LLM 负责把文字变成文章。这两个环节独立演进，又通过标准文本格式衔接，整体方案在隐私、成本和扩展性之间找到了一个很实用的平衡点。如果你的下一个项目是语音笔记、会议记录或播客整理，Dictata 的这套结构可以直接作为起点。