hzeng412 Claude Fable 5 commited on
Commit
040114b
·
1 Parent(s): 2e4bd5d

README: fix model-download instructions for clone install

Browse files

The repo no longer bundles the ASR model: Qwen3-ASR is now the default
and is downloaded from HuggingFace on first launch. The old README
claimed 'all models bundled via Git LFS, no download needed', which
contradicted the auto-download step and left fresh-clone users stuck.

- Split models into 'bundled via LFS (~12GB)' vs 'Qwen3-ASR auto-
downloaded (~4.4GB) on first run'
- Require + verify Git LFS (clone yields pointer files otherwise)
- Correct first-launch note (4.4GB, prints progress, needs network)
- Add a DMG section for the fully-offline prebuilt installer

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Files changed (1) hide show
  1. README.md +34 -6
README.md CHANGED
@@ -54,27 +54,40 @@ VoiceDialogue 是一个基于 Python 的完整语音对话系统,实现了端
54
 
55
  ### 1. 克隆并安装
56
 
57
- > 仓库已通过 **Git LFS** 内置所需模型(约 12GB),克隆后即可直接运行,无需另外下载。
58
- > 请先确认已安装 [Git LFS](https://git-lfs.com)`git lfs install`)。
 
 
 
59
 
60
  ```bash
61
- # 克隆项目已包含模型,体积较大,请耐心等待
 
 
 
 
62
  git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
63
  cd VoiceDialogue
64
 
65
- # 安装依赖推荐使用 uv
 
 
 
 
66
  pip install uv
67
  uv venv
68
  source .venv/bin/activate
69
 
70
  WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync
71
 
72
- # 安装额外依赖
73
  uv pip install kokoro-onnx # kokoro-onnx(英文 TTS)
74
  uv pip install numpy==1.26.4 # 固定 numpy 版本
75
  ```
76
 
77
  > 📖 需要更详细的步骤?请查阅 [安装指南](docs/installation.md),其中包含系统要求和常见问题。
 
 
78
 
79
  ### 2. 启动图形界面(推荐)
80
 
@@ -89,7 +102,8 @@ python main.py --mode api
89
  - 点击右下角 **⚙️ 设置**,选择**麦克风、回音消除、识别语言、音色**,也可切换**中 / 英界面语言**;
90
  - 点击 **「开始对话」**,即可与 AI 实时语音对话,**字幕会实时显示**。
91
 
92
- > 首次启动会自动下载 Qwen3-ASR 模型(约 3.4GB)并转换 TTS 权重格式 1 分钟)之后每次启动只需数十秒,请稍候
 
93
 
94
  ### 3. 命令行模式(CLI)
95
 
@@ -111,6 +125,20 @@ python main.py --input-device <设备索引>
111
 
112
  > 详细使用方法请参考 [配置指南](docs/configuration.md) 和 [API 服务指南](docs/api-guide.md)。
113
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
114
  ## 📚 文档导航
115
 
116
  - 📖 **[安装指南](docs/installation.md)**: 详细的安装步骤和系统要求。
 
54
 
55
  ### 1. 克隆并安装
56
 
57
+ > **模型分两部分**:
58
+ > - **随仓库下载 12GB,Git LFS**:大语言模型、语音合成、参考音色等
59
+ > - **首次启动自动下载(约 4.4GB)**:语音识别引擎 **Qwen3-ASR**,由程序在第一次运行时从 HuggingFace 拉取并缓存到 `~/.cache/huggingface`,之后无需重复下载。
60
+ >
61
+ > ⚠️ **必须先安装 [Git LFS](https://git-lfs.com)**,否则克隆下来的模型只是几百字节的占位指针,应用无法启动。
62
 
63
  ```bash
64
+ # 1) 安装并初始化 Git LFS只需一次
65
+ brew install git-lfs # 如未安装 Homebrew,见 https://git-lfs.com
66
+ git lfs install
67
+
68
+ # 2) 克隆项目(包含约 12GB 模型,体积较大,请耐心等待)
69
  git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
70
  cd VoiceDialogue
71
 
72
+ # 3) 校验模型确实拉取成功应显示 GB 级大小,而非 100+ 字节
73
+ # 若显示很小,说明 Git LFS 未生效,执行:git lfs pull
74
+ ls -lh assets/models/llm/qwen/Qwen3-8B-Q6_K.gguf
75
+
76
+ # 4) 安装依赖(推荐使用 uv)
77
  pip install uv
78
  uv venv
79
  source .venv/bin/activate
80
 
81
  WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync
82
 
83
+ # 5) 安装额外依赖
84
  uv pip install kokoro-onnx # kokoro-onnx(英文 TTS)
85
  uv pip install numpy==1.26.4 # 固定 numpy 版本
86
  ```
87
 
88
  > 📖 需要更详细的步骤?请查阅 [安装指南](docs/installation.md),其中包含系统要求和常见问题。
89
+ >
90
+ > 💡 想免去克隆与下载?直接下载打包好的 **DMG 安装包**(已内置全部模型,完全离线即开即用),见下方[「直接安装(DMG)」](#-直接安装dmg)。
91
 
92
  ### 2. 启动图形界面(推荐)
93
 
 
102
  - 点击右下角 **⚙️ 设置**,选择**麦克风、回音消除、识别语言、音色**,也可切换**中 / 英界面语言**;
103
  - 点击 **「开始对话」**,即可与 AI 实时语音对话,**字幕会实时显示**。
104
 
105
+ > **首次启动较慢,属正常现象**:程序会自动下载 Qwen3-ASR 模型(约 4.4GB,需联网,下载进度会打印在终端)并转换一次 TTS 权重格式。全部完成后才会就绪,整个过程分钟(取决于网速之后每次启动只需数十秒。
106
+ > 若终端长时间停在下载步骤,请检查网络是否能访问 `huggingface.co`。
107
 
108
  ### 3. 命令行模式(CLI)
109
 
 
125
 
126
  > 详细使用方法请参考 [配置指南](docs/configuration.md) 和 [API 服务指南](docs/api-guide.md)。
127
 
128
+ ## 💾 直接安装(DMG)
129
+
130
+ 不想克隆仓库、配置环境的用户,可以直接使用打包好的 **DMG 安装包**:**全部模型已内置(含 Qwen3-ASR),完全离线、即开即用,无需任何下载**。
131
+
132
+ - 适用机型:**仅 Apple Silicon(M 系列芯片)**,约 14GB。
133
+ - 安装包请向团队获取(暂未放到公开 Releases)。
134
+
135
+ 安装步骤:
136
+
137
+ 1. 双击打开 DMG,将 **Voice Dialogue** 拖入 **Applications**。
138
+ 2. 首次打开因安装包**未签名**,会被 macOS 拦截。请**右键点击应用图标 → 选择「打开」**,在弹窗中再次点击「打开」即可(直接双击只会提示“已损坏/无法验证”,属正常现象)。
139
+ - 也可在 **系统设置 → 隐私与安全性** 中点击「仍要打开」。
140
+ 3. 启动后等待模型加载(约 1 分钟),随后浏览器会自动进入对话界面。
141
+
142
  ## 📚 文档导航
143
 
144
  - 📖 **[安装指南](docs/installation.md)**: 详细的安装步骤和系统要求。