离线部署与模型配置说明
更新于 2026 年 6 月 · 适用 macOS 13+
一句话：Vlow 的语音识别本来就在你的电脑上离线运行（说话→文字这一步永不联网、永不上传录音）。是否联网只取决于「润色后端」这一个设置——选「免润色」或「本地 Ollama」就是 100% 全离线；想要云端最佳质量再选 DeepSeek / Claude（需自带 API Key）。本页把每个参数、每一步都讲清楚。
① 先理清：哪一步本来就离线
Vlow 把「说话」变成「可用文字」分两段，离线与否完全不同：
| 环节 | 是否联网 | 说明 |
|---|---|---|
| 语音 → 文字（识别 / ASR） | 否，本来就全离线 | 本机用开源 FireRedASR（Apache-2.0）+ sherpa-onnx 运行。首次下载约 1GB 模型后，永久离线，录音永不上传。 |
| 文字 → 润色 / 结构化 | 看「润色后端」 | 本地后端不联网、不要 Key；云端后端要联网 + 自带 Key。只处理文本，不碰录音。 |
所以：只要不想联网，把润色后端设成「免润色」或「本地 Ollama」即可，识别永远是离线的。
② 润色后端：四选一
在 设置 → 润色后端 里选其一（对应配置文件里的 backend 值）：
| 后端（设置项） | 联网 / Key | 质量 / 速度 | 适合谁 |
|---|---|---|---|
| 免润色（原文直出） | 不联网 · 免 Key | 瞬时；识别已自带标点 | 只想要干净原文、极致离线 |
本地 Ollama local | 不联网 · 免 Key | AI 整理；约 1–4 秒 | 断网也要 AI 整理 |
DeepSeek deepseek | 需联网 · 需 Key | 质量很好；约 1–2 秒 | 国内、要最佳中文质量 |
Claude anthropic | 需联网 · 需 Key | 质量顶级；约 1–3 秒 | 已有 Anthropic 账号 |
BYO-Key（自带密钥）：云端两档绝不内置开发者的 Key，用的是你自己的账号和额度，文本只走你自己的 API。改设置后需重启 Vlow 生效。
③ 方案一：100% 全离线（推荐隐私/断网场景）
A. 免润色 —— 零配置，开箱即用
- 打开 设置 → 润色后端，选 「免润色（原文直出）」。
- 保存并重启 Vlow。完成——说话即出干净文字（识别模型已自带标点），全程不联网。
B. 本地 Ollama —— 离线也能 AI 整理（一次性 3 步）
- 安装 Ollama：到 ollama.com 下载安装（菜单栏常驻、开机自启）；或终端
brew install ollama && ollama serve。 - 拉一个模型（中文强、低配 Mac 友好）：
ollama pull qwen2.5:3b - 在 Vlow 设置 → 润色后端 选 「本地 Ollama（离线）」。设置页会实时显示「✅ 已就绪 / ⚠️ 未运行 / ⚠️ 模型未拉取」。就绪后断网也能 AI 整理。
Vlow 默认连本机
http://127.0.0.1:11434、默认模型 qwen2.5:3b。想换模型：启动前设环境变量 OLLAMA_MODEL=qwen2.5:1.5b（见 §⑤）。机型怎么选模型见 §⑥。Ollama 是独立的后台程序，不在 Vlow 安装包内，需按上面装一次。没启动时 Vlow 不会静默——会在菜单栏/胶囊提示「⚠️ 本地 Ollama 未运行…已用原文」。
④ 方案二：云端润色（BYO-Key）+ 如何获取 API Key
A. 获取 DeepSeek API Key（国内推荐，支付方便）
- 打开 platform.deepseek.com（DeepSeek 开放平台），用手机号/邮箱注册并登录。
- 左侧 「充值 / 余额」 充值：按量计费，充 ¥10 起即可用很久（每次润色仅几百 token，单价极低）。
- 左侧 「API keys」→「创建 API key」，起个名字 → 创建。
- 复制以
sk-开头的密钥。⚠️ 它只显示这一次，立刻复制保存。 - 把它填进 Vlow（见下面「C. 怎么填 Key」），再把润色后端设为 DeepSeek。
B. 获取 Anthropic（Claude）API Key
- 打开 console.anthropic.com，注册并登录。
- 「Billing / Plans」 充值（信用卡、按量计费、美元）。⚠️ 大陆银行卡支付可能受限——这也是国内默认推荐 DeepSeek 或本地 Ollama 的原因。
- 「API keys」→「Create Key」，命名 → 创建。
- 复制以
sk-ant-开头的密钥（同样只显示一次）。 - 填进 Vlow（见下），把润色后端设为 Claude。Vlow 默认用
claude-opus-4-8（可改，见 §⑤）。
C. 怎么把 Key 填进 Vlow（三选一）
- 方式一 · 推荐（有界面）：打开 Vlow 的 「设置 DeepSeek API Key」 小窗，粘贴 → 保存。它只写入你本机的
secret.json，不会外发。 - 方式二 · 手动编辑：在数据目录（见 §⑤）编辑
secret.json：
只填你要用的那一个即可。{ "deepseek_api_key": "sk-你的DeepSeek密钥", "anthropic_api_key": "sk-ant-你的Claude密钥" } - 方式三 · 环境变量（高级/临时）：启动前在终端导出，优先级高于 secret.json：
export DEEPSEEK_API_KEY=sk-你的密钥 export ANTHROPIC_API_KEY=sk-ant-你的密钥
安全：API Key 等同你的账号额度，只存在本机
secret.json，请勿截图外发、勿提交到 git。怀疑泄露就到对应平台吊销重置。⑤ 每个参数详解
设置项（写在 vlow_settings.json）
| 参数 | 取值 | 含义 / 怎么设 |
|---|---|---|
backend | 免润色 / local / deepseek / anthropic | 润色后端，见 §②。在「设置 → 润色后端」选。 |
hotkey | f2（默认）/ f3 / f4 / f8 / f9 / right ctrl / caps lock … | 触发键：按一下开始说话，再按一下结束。建议 F2（不分左右、不和 Ctrl+C/V 冲突）。 |
mode | clean（默认）/ prompt / commit / task / doc | 输出结构：清理口语 / AI 指令 / Git 提交信息 / 任务清单 / 技术文档。也可在菜单栏随时切。 |
hotwords | 逗号分隔字符串 | 热词，提升专有名词/人名准确率。例：佛山站,黄主任,中控室 |
prompt | 一段文字 | 自定义润色提示词，仅对 clean 模式生效（其它结构化模式用各自内置模板）。 |
环境变量（高级，启动前设置）
| 变量 | 默认值 | 作用 |
|---|---|---|
VLOW_ASR_ACCURACY | 视构建 | 识别精度档：CTC（更快）/ AED（更准）。 |
OLLAMA_MODEL | qwen2.5:3b | 本地 Ollama 用哪个模型，见 §⑥。 |
DEEPSEEK_MODEL | deepseek-chat | DeepSeek 模型名。 |
ANTHROPIC_MODEL | claude-opus-4-8 | Claude 模型名。 |
DEEPSEEK_API_KEY / ANTHROPIC_API_KEY | 无 | 对应云端 Key，优先级高于 secret.json。 |
VLOW_DATA_DIR | 见下 | 覆盖数据目录位置（测试/自定义用）。 |
文件位置（Key 和设置存在哪）
- 安装版（.app）：
~/Library/Application Support/Vlow/ - 源码运行（开发）：项目目录本身。
- 该目录下有两个文件：
secret.json（API Key）、vlow_settings.json（上面的设置项）。识别模型首次下载后也缓存在本机。
⑥ 按硬件选本地模型
润色是「短文本整理」，不需要大模型，1.5B–3B 足矣，Qwen2.5 中文最稳。
| 设备 | 推荐模型 | 体积 | 单次润色（预期） |
|---|---|---|---|
| Mac mini M4 / M1~M3（16GB） | qwen2.5:3b | 1.9GB | 约 1–2 秒 ✅ |
| 入门 Apple 芯片（8GB） | qwen2.5:3b（紧）或 qwen2.5:1.5b（稳） | 1.9 / 1.0GB | 约 2–4 秒 |
| 想更快 / 内存吃紧 | qwen2.5:1.5b | 1.0GB | 约 1–2 秒，质量略降 |
| Intel Mac（无 Metal） | qwen2.5:1.5b 或直接「免润色」 | — | 较慢，建议免润色 |
本地模型常驻内存约等于「模型体积」（3b≈2GB）。8GB 机器同时开大应用时选
qwen2.5:1.5b 更稳，或用免润色。⑦ 常见问题
完全断网能用吗？
能。识别永远本地；润色后端选「免润色」或「本地 Ollama」即 100% 离线，不需要联网、不需要任何 Key。
菜单栏提示「本地 Ollama 未运行」怎么办？
说明 Ollama 后台没启动。打开 Ollama 应用（或终端 ollama serve）；若提示「模型未拉取」，执行 ollama pull qwen2.5:3b。Vlow 设置页会显示实时就绪状态。
DeepSeek/Claude 提示「未设置 API Key」？
说明对应 Key 没填好。按 §④C 填入 secret.json 或环境变量；确认 Key 完整（DeepSeek 以 sk-、Claude 以 sk-ant- 开头），并已重启 Vlow。
用云端润色，我的录音会上传吗？
不会。任何后端下，录音都不离开你的电脑——识别永远在本机。云端后端只把识别出的文本发到你自己的 API 账号做整理。
改了设置不生效？
设置改动需重启 Vlow 生效（退出后重新启动）。