博客未发布好用开源项目精选 TOP10｜本地部署与使用全指南

整理：周若琳博客 ｜ 核验日期：2026-10-25 本文精选 10 个博客尚未单独成文的实用开源项目/开源模型，覆盖本地大模型运行、推理引擎、开源大模型、语音克隆、语音识别、数字人口型、实时语音对话、Web UI 与私有知识库 RAG，逐项目给出官方仓库、跳转链接、官方图片、最详细的部署方式与使用方法。

总览

01. Ollama —— 一条命令在本地一键运行开源大模型

适用环境：Windows 10/11 原生、Windows 10/11 + WSL2（Ubuntu 24.04）、带 NVIDIA RTX 3070 8GB / RTX 4090 24GB，或 Linux 云服务器。 信息口径：本章所有命令、路径、环境变量、模型标签与体积均来自 Ollama 官方仓库、官方文档站与官方模型库；核验日期 2026-10-25。

01.1 项目定位与基本信息

01.2 官方图片

下图为 Ollama 官方 GitHub README 顶部 Logo（非 AI 生成、非第三方图）。

• 图片来源 URL：https://github.com/ollama/ollama/assets/3325447/0d0b44e2-8f4a-4e99-9b52-a5c1c741c8f7（官方仓库 README 内嵌图片，2026-10-25 用 curl -L 下载）。
• 本地保存路径：https://zhouruolin.cn/upload/01_ollama_logo.png；file 校验结果：PNG image data, 844 x 844, 8-bit/color RGBA，体积 92,041 字节（>20KB）。

01.3 环境要求

下列硬性要求来自官方 Windows 文档、官方 GPU 支持页与官方 FAQ；Ollama 官方未公布统一的“最低内存/磁盘”数字，内存与磁盘占用随模型权重、上下文长度与并行度变化（官方 FAQ “How does Ollama handle concurrent requests?” 说明：并发时内存按 OLLAMA_NUM_PARALLEL × OLLAMA_CONTEXT_LENGTH 扩张）。

RTX 3070 8GB 显存参考选型（标签与体积来自官方模型库 tags 页面）：

01.4 最详细部署步骤（Windows 原生 与 WSL2 两种视角）

01.4.1 依赖安装

A. Windows 10/11 原生

1. 确认系统为 Windows 10 22H2 或更新（设置 → 系统 → 关于 → 版本）。
2. NVIDIA 显卡驱动：Windows 官方系统要求 551.61 或更新（https://docs.ollama.com/windows）；GPU 支持页通用口径为驱动 ≥550，算力 5.0–6.2 的老卡需 570+（https://docs.ollama.com/gpu）；RTX 30/40 系建议安装当前最新 Game Ready / Studio 驱动，可在 NVIDIA 控制面板或 nvidia-smi 中查看驱动版本。
3. 官方安装包内置 GPU 推理运行时，官方文档未要求单独安装 CUDA Toolkit。

B. WSL2（Ubuntu 24.04）

1. Windows 已启用 WSL2，发行版内核匹配 *icrosoft*WSL2（WSL1 不受支持，可在 PowerShell 执行 wsl --set-version Ubuntu-24.04 2 转换）。
2. NVIDIA GPU 直通由 Windows 侧 NVIDIA 驱动提供；进入 WSL2 后执行 nvidia-smi，能看到显卡并显示 CUDA Version 即直通成功（官方安装脚本正是用 nvidia-smi | grep -o "CUDA Version: [0-9]*\.[0-9]*" 判断 GPU 是否可用，见 install.sh 第 254–257 行）。
3. 在 Ubuntu 内安装脚本所需基础工具：

sudo apt-get update
sudo apt-get install -y curl awk grep sed tee xargs zstd

提示：若要让 WSL2 内的 systemd 服务自动管理 Ollama，需先在 /etc/wsl.conf 中启用 systemd（官方安装脚本对“systemd 未运行的 WSL2”会给出链接 https://learn.microsoft.com/en-us/windows/wsl/systemd#how-to-enable-systemd）；不启用 systemd 时可手动 ollama serve 启动。

01.4.2 项目下载 / 安装（两条官方路径）

路径一：Windows 原生官方安装包

• 图形化安装包（官方下载页 https://ollama.com/download）：
• 安装包直链：https://ollama.com/download/OllamaSetup.exe（2026-10-25 核验 HTTP 200）。
• 下载后双击安装；安装目录为 %LOCALAPPDATA%\Programs\Ollama（官方排错文档给出该路径），安装器会把 ollama 加入用户 PATH。
• 官方 PowerShell 一键脚本（来源：https://docs.ollama.com/windows 与 https://ollama.com/install.ps1）：

# 安装最新稳定版（PowerShell）
irm https://ollama.com/install.ps1 | iex

# 可选：指定版本 / 指定安装目录（环境变量机制来自脚本头部官方示例；版本号取当前最新 release）
$env:OLLAMA_VERSION = "0.40.11"; irm https://ollama.com/install.ps1 | iex
$env:OLLAMA_INSTALL_DIR = "D:\Ollama"; irm https://ollama.com/install.ps1 | iex

路径二：Linux / WSL2 官方一键脚本（来源：https://docs.ollama.com/linux、https://ollama.com/install.sh）

# 安装最新稳定版（脚本自动识别 amd64 / arm64、下载 .tar.zst、创建 ollama 用户与 systemd 服务）
curl -fsSL https://ollama.com/install.sh | sh

# 可选：指定历史版本（官方 FAQ “Installing older or pre-release versions on Linux” 示例）
curl -fsSL https://ollama.com/install.sh | OLLAMA_VERSION=0.5.7 sh

脚本官方行为（源码核对）：

• 下载 https://ollama.com/download/ollama-linux-${ARCH}.tar.zst 解压到系统二进制目录，软链到 /usr/local/bin/ollama；
• 创建系统用户 ollama，加入 render、video 组；
• 写入 systemd 服务 /etc/systemd/system/ollama.service，ExecStart=ollama serve、Restart=always、RestartSec=3；
• 安装成功后提示 API 位于 127.0.0.1:11434。

安装完成后，新开终端执行 ollama --version 确认客户端可用；Linux 下服务状态：

systemctl status ollama          # 查看服务状态（官方 Linux 文档命令）
journalctl -e -u ollama           # 官方 Linux 日志查看命令（最新日志）

01.4.3 模型 / 权重下载（官方链接 + 国内加速与离线方案）

A. 官方直连拉取（官方模型库 https://ollama.com/library）

# 拉取并运行 Qwen3 8B（官方库标签 qwen3:8b）
ollama pull qwen3:8b

# 拉取 DeepSeek-R1 蒸馏 7B
ollama pull deepseek-r1:7b

# 直接运行（未拉取时会自动先下载）
ollama run qwen3:8b

• 模型默认存储位置（官方 FAQ “Where are models stored?”）：
• Linux：/usr/share/ollama/.ollama/models
• Windows：C:\Users\%username%\.ollama\models
• macOS：~/.ollama/models

B. 代理环境变量（官方 FAQ “How do I use Ollama behind a proxy?”）

仅使用 HTTPS_PROXY 转发模型拉取；不要设置 HTTP_PROXY（Ollama 拉模型只走 HTTPS，设置 HTTP_PROXY 可能打断客户端到服务端的本地连接）。代理证书需安装为系统证书。

# Linux / WSL2（systemd 方式写入服务环境变量，见 01.4.4）
export HTTPS_PROXY=https://proxy.example.com:7890

C. 离线导入官方 GGUF（下载慢 / 无法访问官方仓库时的可验证替代方案）

Ollama 官方 “Importing a Model” 文档支持直接从本地 GGUF 文件创建模型：在 Modelfile 中用 FROM 指定本地 GGUF 绝对路径（或相对 Modelfile 的路径），分片模型用通配符 FROM ./model-*.gguf。来源：https://docs.ollama.com/import、https://docs.ollama.com/modelfile。

第 1 步：从 ModelScope 镜像下载官方 Qwen3 GGUF（镜像页 https://modelscope.cn/models/Qwen/Qwen3-8B-GGUF，2026-10-25 核验 200；文件体积与 Hugging Face 官方一致，Q4_K_M 为 5.03GB，详见 03 章）：

# 安装 ModelScope SDK（官方文档：https://modelscope.ai/docs/Models/Download-Model）
pip install modelscope

# 旧版 SDK CLI（官方文档：--model 仓库 ID，--include 文件名通配，--cache_dir 缓存目录）
modelscope download --model Qwen/Qwen3-8B-GGUF \
  --include 'Qwen3-8B-Q4_K_M.gguf' --cache_dir ./qwen3-gguf

# 新版 modelscope-hub CLI（--local-dir 直存目录；--include 通配过滤）
# modelscope download Qwen/Qwen3-8B-GGUF Qwen3-8B-Q4_K_M.gguf --local-dir ./qwen3-gguf

第 2 步：新建 Modelfile（示例，路径按实际修改；PARAMETER num_ctx、SYSTEM 指令格式来自官方 Modelfile 参考 https://docs.ollama.com/modelfile）：

# Modelfile（离线导入本地 GGUF）
# 本地 GGUF 绝对路径（官方要求：绝对路径，或相对本 Modelfile 的路径）
FROM /home/user/models/qwen3-gguf/Qwen3-8B-Q4_K_M.gguf

# 上下文窗口（8GB 显存建议先设小一些，例如 8192）
PARAMETER num_ctx 8192

# 系统提示词
SYSTEM """You are a helpful, concise assistant."""

第 3 步：创建并运行本地模型：

ollama create qwen3-8b-local -f ./Modelfile
ollama run qwen3-8b-local

# 查看模型实际使用的 Modelfile（官方命令）
ollama show --modelfile qwen3-8b-local

说明：离线导入只完成“权重挂载”，Ollama 不会在导入时对 GGUF 重新量化（官方 Importing a Model 文档明确说明量化需使用外部工具，如 llama.cpp 的 llama-quantize，链接 https://github.com/ggml-org/llama.cpp/tree/master/tools/quantize）。

01.4.4 关键配置（环境变量 / 配置项表）

下列变量均来自官方 FAQ “How do I configure Ollama server?” 及各专项 FAQ 页面；修改后需重启 Ollama 服务生效。

设置环境变量的官方方式（FAQ “How do I configure Ollama server?”）：

• Linux / WSL2（systemd）：sudo systemctl edit ollama.service，在 [Service] 段加入：

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"

然后：

sudo systemctl daemon-reload
sudo systemctl restart ollama

• Windows：先从托盘退出 Ollama → 设置（Win11）/ 控制面板（Win10） 搜索“环境变量” → 编辑用户账户的 OLLAMA_HOST、OLLAMA_MODELS 等 → 保存后从开始菜单重新启动 Ollama（Windows 继承用户与系统环境变量）。
• 前台手动启动时临时生效：

OLLAMA_HOST=0.0.0.0:11434 OLLAMA_DEBUG=1 ollama serve

01.4.5 启动

• Windows 原生：安装后托盘常驻，后台服务自动运行；命令行可直接 ollama run <模型名>。
• Linux / WSL2（systemd）：

sudo systemctl enable --now ollama     # 启用并启动服务
ollama ps                               # 查看当前已加载模型与 GPU/CPU 占用

• 手动前台启动（调试用）：

ollama serve
# 官方启动日志显示：Ollama 正在运行，监听 http://127.0.0.1:11434

01.5 使用方法

01.5.1 启动方式

01.5.2 命令行操作步骤（带示例）

官方 CLI 参考：https://docs.ollama.com/cli。

# 1. 拉取模型
ollama pull qwen3:8b

# 2. 交互式对话（进入后直接输入文字；多行用 """ 包裹）
ollama run qwen3:8b

# 3. REPL 内常用斜杠命令（官方 FAQ 与官方 Quickstart 文档）
>>> /set parameter num_ctx 8192      # 当次会话设置上下文长度（FAQ “How can I specify the context window size?”）
>>> /bye                              # 退出会话（Quickstart “Run a model locally”：Type `/bye` to leave.）
# 多行输入：用三引号 """ 包裹（官方 CLI 参考 “Multiline input”）

# 4. 列出已安装模型
ollama ls

# 5. 查看正在内存中运行的模型（PROCESSOR 列显示 100% GPU / 100% CPU / 混合占比）
ollama ps

# 6. 卸载模型、释放显存
ollama stop qwen3:8b

# 7. 删除本地模型
ollama rm qwen3:8b

# 8. 查看模型 Modelfile / 详情
ollama show --modelfile qwen3:8b

01.5.3 参数说明表

HTTP API 与 OpenAI 兼容接口（官方 https://docs.ollama.com/api/introduction）：

01.5.4 端到端示例（输入 → 命令 → 输出）

场景：RTX 3070 8GB 笔记本，离线环境，用 01.4.3 第 C 步导入的 qwen3-8b-local 完成一次对话，并通过 OpenAI 兼容接口调用。

第 1 步：确认模型已导入

$ ollama ls
NAME                ID              SIZE      MODIFIED
qwen3-8b-local:latest   <hash>      5.03 GB    2 minutes ago

第 2 步：命令行提问（输入 → 命令）

$ ollama run qwen3-8b-local "用三句话解释什么是量化（quantization），面向新手。"

输出（官方 API 字段结构示意，实际文本由模型生成）：

量化就是把模型里原本高精度的数字（如 16 位浮点数）压缩成更低位数（如 4 位整数）来存储和计算。
这样模型文件更小、更省显存，普通电脑也能跑起来；代价是回答质量可能有轻微下降，需要在体积和效果之间权衡。
常见档位有 Q4_K_M、Q5_K_M、Q6_K、Q8_0 等，数字越小体积越小、速度越快。

第 3 步：原生 REST API 调用（官方 README “REST API” 示例，模型名替换为本地模型）：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3-8b-local",
  "messages": [{"role": "user", "content": "用三句话解释什么是量化（quantization），面向新手。"}],
  "stream": false,
  "options": {"num_ctx": 8192}
}'

返回（结构字段来自官方 /api/chat 文档；message.content 为模型回答）：

{
  "model": "qwen3-8b-local",
  "message": {
    "role": "assistant",
    "content": "量化就是把模型里原本高精度的数字……（同上模型输出）"
  },
  "done": true,
  "prompt_eval_count": 18,
  "eval_count": 96
}

第 4 步：OpenAI 兼容接口调用（Base URL http://localhost:11434/v1，官方 https://docs.ollama.com/api/openai-compatibility）：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-8b-local",
    "messages": [{"role": "user", "content": "你好，介绍一下你自己。"}]
  }'

01.6 常见坑（现象 + 原因 + 解决）

1. 现象：WSL2 内安装 Ollama 或 ollama pull 模型时网络极慢、经常中断。 - 原因：官方 FAQ “Why is networking slow in WSL2 on Windows 10?” 指出，Windows 10 上 vEthernet (WSL) 适配器的 Large Send Offload (LSOv2) 会影响安装与模型下载。 - 解决：控制面板 → 网络和 Internet → 查看网络状态和任务 → 更改适配器设置 → vEthernet (WSL) 属性 → 配置 → 高级，将 Large Send Offload Version 2 (IPv4) 与 Large Send Offload Version 2 (IPv6) 均禁用后重启 WSL。

2. 现象：模型只跑在 CPU 上，ollama ps 显示 100% CPU 或很大比例 CPU/GPU 混合。 - 原因：NVIDIA 驱动过旧或 GPU 发现失败（官方 Troubleshooting “NVIDIA GPU Discovery” 给出错误码含义：3 未初始化、46 设备不可用、100 无设备、999 未知）；WSL2 下 nvidia-smi 看不到显卡时 Ollama 同样无法使用 GPU。 - 解决：先在 Windows 侧升级 NVIDIA 驱动到 ≥550；WSL2 内执行 nvidia-smi 验证直通；Linux 容器场景可执行 sudo nvidia-modprobe -u、重载 nvidia_uvm 驱动（sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm）或重启；查看日志 journalctl -e -u ollama，必要时 OLLAMA_DEBUG=1 获取 GPU 发现细节。

3. 现象：修改了 OLLAMA_HOST、OLLAMA_MODELS 等变量后不生效。 - 原因：Windows 桌面版需先从托盘退出再重启才会继承新的用户环境变量；Linux systemd 服务需 daemon-reload 并重启；变量写错位置（如只在当前 shell export 但服务由 systemd 拉起）不生效。 - 解决：按 01.4.4 官方方式设置：Windows 退出托盘后重启；Linux 用 sudo systemctl edit ollama.service 写 Environment= 后 systemctl daemon-reload && systemctl restart ollama。

4. 现象：模型下载到一半磁盘报错 / 空间不足。 - 原因：默认模型目录在系统盘（Windows C:\Users\%username%\.ollama\models；Linux /usr/share/ollama/.ollama/models），大模型（如 Q8_0、32B 级）体积可达数十 GB。 - 解决：设置 OLLAMA_MODELS 指向大容量目录；Linux 标准安装下需把目录授权给 ollama 用户：sudo chown -R ollama:ollama <目录>（官方 FAQ “Where are models stored?”）。

5. 现象：局域网其他设备 / 前端访问不到 Ollama。 - 原因：服务默认仅绑定 127.0.0.1:11434；浏览器跨域还受 OLLAMA_ORIGINS 限制。 - 解决：设置 OLLAMA_HOST=0.0.0.0:11434 后重启；跨域前端按需在 OLLAMA_ORIGINS 中放行来源（官方 FAQ “How can I expose Ollama on my network?” “How can I allow additional web origins?”）。

6. 现象：/tmp 所在分区挂载了 noexec，Ollama 启动失败或无法解压临时运行库。 - 原因：官方 Troubleshooting “Linux tmp noexec”：临时可执行文件目录不可执行。 - 解决：设置 OLLAMA_TMPDIR 到 ollama 用户可写且带执行权限的目录，例如 OLLAMA_TMPDIR=/usr/share/ollama/。

7. 现象：代理环境下模型拉取失败，或本地客户端连不上服务。 - 原因：FAQ 明确：模型拉取只走 HTTPS，应配置 HTTPS_PROXY；设置 HTTP_PROXY 会打断本地客户端与服务端连接。 - 解决：仅设置 HTTPS_PROXY 并安装代理根证书为系统证书；Docker 场景用 -e HTTPS_PROXY=https://proxy.example.com 传入容器。

01.7 本节来源清单

验证方式说明：web_fetch = 通过文档抓取工具实际打开；curl 200 = 命令行 HTTP 状态码核验；general_search = 搜索索引佐证。核验日期 2026-10-25。

02. llama.cpp（llama-server / llama-cli / llama-quantize）—— 纯 C/C++ 的高效本地 LLM 推理引擎

适用环境：Windows 10/11 原生、Windows 10/11 + WSL2（Ubuntu 24.04）、NVIDIA RTX 3070 8GB / RTX 4090 24GB，以及 Linux 云服务器。 信息口径：本章命令、编译参数、工具名、参数与端点均来自 llama.cpp 官方仓库 README、docs/build.md、docs/models.md、tools/server/README.md、tools/cli/README.md、tools/quantize/README.md 与官方 release 资产清单；核验日期 2026-10-25。

02.1 项目定位与基本信息

02.2 官方图片

下图为官方 README 内嵌的两张官方截图（非 AI 生成、非第三方图）：左为 llama cli 的 VLM 会话界面，右为 llama serve 内置 Web UI。

图 1：llama cli 命令行会话（官方 README 截图）

• 图片来源 URL：https://github.com/user-attachments/assets/88726b48-1713-48aa-a525-95a02e78afc4（README 原文 alt：VLM session with 'llama cli'，2026-10-25 curl -L 下载）。
• 本地路径：https://zhouruolin.cn/upload/02_llamacpp_cli_screenshot.png；file 校验：PNG image data, 2782 x 2014, 8-bit/color RGBA，317,242 字节（>20KB）。

图 2：llama serve 内置 Web UI（官方 README 截图）

• 图片来源 URL：https://github.com/user-attachments/assets/b402f972-2e32-4def-8771-8d849f08cf2e（README 原文 alt：Built-in web UI against 'llama serve' running Qwen 3.6，2026-10-25 curl -L 下载）。
• 本地路径：https://zhouruolin.cn/upload/02_llamacpp_webui_screenshot.png；file 校验：PNG image data, 2784 x 1916, 8-bit/color RGBA，688,668 字节（>20KB）。

02.3 环境要求

来源：docs/build.md（CPU/CUDA 构建与计算能力表）、README.md（支持后端、量化档位、CPU+GPU 混合推理）、tools/quantize/README.md（量化工具内存/磁盘要求）、tools/server/README.md（默认端口与后端能力）。

RTX 3070 8GB 与 RTX 4090 24GB 编译参数对照（来源：docs/build.md “Override Compute Capability Specifications”，官方示例即列出 RTX 3070=8.6、RTX 4090=8.9）：

02.4 最详细部署步骤（Windows 预编译 与 WSL2 源码编译 两种视角）

02.4.1 依赖安装

A. Windows 10/11 原生（预编译 CUDA 包路线）

1. 安装 NVIDIA 显卡最新驱动，设备管理器 / nvidia-smi 确认显卡被识别。
2. 无需安装 Visual Studio、CMake 或 CUDA Toolkit（预编译包自带后端运行时）。
3. 准备模型目录，例如 D:\llm\models\，用于存放 GGUF 文件。

B. WSL2（Ubuntu 24.04）源码编译路线

1. Windows 侧安装 NVIDIA 驱动；进入 WSL2 执行 nvidia-smi，确认能看到显卡与 CUDA Version（WSL2 直通由 Windows 驱动提供，不要在 Windows 上装 CUDA Toolkit 来给 WSL2 编译用，编译工具链要装在 WSL2 内）。
2. 在 WSL2 内安装 CUDA Toolkit（含 nvcc，官方下载入口 https://developer.nvidia.com/cuda-toolkit），安装后 nvcc --version 可执行。
3. 安装编译基础工具（Git、CMake、C++ 工具链、Ninja；Debian/Ubuntu 常用命令）：

sudo apt-get update
sudo apt-get install -y git cmake g++ build-essential ninja-build libssl-dev

说明：上面的 apt-get 包名是 Ubuntu 通用开发工具链；llama.cpp 官方 docs/build.md 只规定了 git clone + CMake 构建流程与 CUDA Toolkit 前提，未直接给出该 apt-get 清单。

02.4.2 项目下载 / 安装（预编译包、一键脚本、源码三种官方方式）

方式一：Windows 官方预编译包（Nightly b11874，2026-10-25 资产清单核验）

• 发布页：https://github.com/ggml-org/llama.cpp/releases
• NVIDIA CUDA 12.4 x64 包直链（HTTP 200 已核验）： https://github.com/ggml-org/llama.cpp/releases/download/b11874/llama-b11874-bin-win-cuda-12.4-x64.zip
• 同清单备选：CPU 包 llama-b11874-bin-win-cpu-x64.zip、CUDA 13.4 包 llama-b11874-bin-win-cuda-13.4-x64.zip、Vulkan 包 llama-b11874-bin-win-vulkan-x64.zip。

下载解压后，在解压目录内查找以下官方 CMake 目标对应的可执行文件（来源：各 tools/*/CMakeLists.txt）：

方式二：官方一键脚本（README Quick start，https://llama.app）

# Linux / macOS（README 原文：curl -LsSf https://llama.app/install.sh | sh）
curl -LsSf https://llama.app/install.sh | sh

# Windows PowerShell（README 原文：irm https://llama.app/install.ps1 | iex）
irm https://llama.app/install.ps1 | iex

脚本安装的是统一命令 llama，子命令为 llama cli 与 llama serve（README 示例：llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF、llama serve -hf ggml-org/Qwen3.5-0.8B-GGUF）。

方式三：WSL2 / Linux 源码编译（官方 docs/build.md）

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# CPU 构建（官方 CPU Build 命令）
cmake -B build
cmake --build build --config Release

# CUDA 构建（官方 CUDA 节命令）
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

RTX 3070 / 4090 指定架构（官方 “Override Compute Capability Specifications”）：

# 单卡 RTX 3070（86）
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86"
cmake --build build --config Release -j"$(nproc)"

# 单卡 RTX 4090（89）
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="89"
cmake --build build --config Release -j"$(nproc)"

# 两机通用（86 + 89）
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86;89"
cmake --build build --config Release -j"$(nproc)"

只构建服务器目标（官方 tools/server/README.md Build 节）：

cmake -B build
cmake --build build --config Release -t llama-server
# 产物：./build/bin/llama-server

可选：为覆盖所有 CUDA GPU（非原生机器）禁用原生优化：cmake -B build -DGGML_CUDA=ON -DGGML_NATIVE=OFF（docs/build.md “Non-Native Builds”）。需要 OpenSSL/SSL 支持时：cmake -B build -DLLAMA_OPENSSL=ON（tools/server/README.md “Build with SSL”）。

产物位置（官方文档）：./build/bin/llama-server、./build/bin/llama-cli、./build/bin/llama-quantize。

02.4.3 模型 / 权重下载（官方链接 + 国内加速方案）

A. 官方 -hf 直连 Hugging Face（docs/models.md、tools/server/README.md -hf 参数）

# 官方 README Quick start 示例仓库；量化档大小写不敏感，默认 Q4_K_M
./build/bin/llama-cli -hf ggml-org/Qwen3.5-0.8B-GGUF
./build/bin/llama-server -hf ggml-org/Qwen3.5-0.8B-GGUF

B. 官方 MODEL_ENDPOINT 兼容端点（docs/models.md 原文：You can use the same CLI invocation to download from other sites, by pointing the MODEL_ENDPOINT environment variable to an endpoint compatible with the Hugging Face API.）

# 指向兼容 Hugging Face API 的镜像端点（端点需自行确认兼容性）
export MODEL_ENDPOINT=https://hf-mirror.com
./build/bin/llama-server -hf Qwen/Qwen3-8B-GGUF:Q4_K_M

说明：hf-mirror.com 为第三方国内镜像站（非 llama.cpp / Hugging Face 官方），MODEL_ENDPOINT 仅要求端点兼容 HF API；若镜像路径不兼容，改用下面的“手动下载 + 本地路径”方案最稳妥。

C. 手动下载 GGUF + 本地路径加载（离线 / 慢网络最稳妥方案）

1. 在可访问渠道（浏览器、huggingface-cli 或 ModelScope 镜像，见 03 章）下载目标 .gguf，例如 Qwen3-8B-Q4_K_M.gguf。
2. 用 -m/--model 指定本地文件（tools/server/README.md 参数表）：

# Linux / WSL2
./build/bin/llama-server -m /home/user/models/Qwen3-8B-Q4_K_M.gguf --host 0.0.0.0 --port 8080

# Windows 预编译包
llama-server.exe -m models\Qwen3-8B-Q4_K_M.gguf -c 4096

3. 走代理时，启动前导出 HTTPS_PROXY / HTTP_PROXY（tools/server/README.md “Running behind a proxy”：export HTTPS_PROXY=http://proxy.example.com:8080，NO_PROXY 与回环地址直连）。

D. 本地转 GGUF 与重新量化（官方 tools/quantize/README.md）

# 1) 安装 Python 依赖
python3 -m pip install -r requirements.txt

# 2) HF 模型转 BF16 GGUF（官方示例命令格式）
python convert_hf_to_gguf.py --outfile model-bf16.gguf --outtype bf16 --remote org/model

# 3) 量化为 Q4_K_M（官方新格式命令）
./build/bin/llama-quantize model-bf16.gguf model-Q4_K_M.gguf Q4_K_M

# 旧格式（官方 Quantization Examples 兼容写法，最后一位为线程数）
./llama-quantize input-model-f32.gguf q4_k_m 8

02.4.4 关键配置（参数 / 环境变量表）

下列参数全部来自 tools/server/README.md 与 tools/cli/README.md 自动生成的参数表；带 (env: ...) 的参数也可用同名 LLAMA_ARG_* 环境变量设置。命令行参数优先于环境变量（tools/server/README.md 注释：命令行与环境变量同时设置时，参数优先）。

02.4.5 启动

Windows 预编译包（在解压目录下，PowerShell）：

# 启动服务器，本地模型，监听 127.0.0.1:9931（默认）
.\llama-server.exe -m models\Qwen3-8B-Q4_K_M.gguf -c 4096

# 指定对外地址与端口、全层卸载到 GPU
.\llama-server.exe -m models\Qwen3-8B-Q4_K_M.gguf --host 0.0.0.0 --port 8080 -ngl 99 -c 4096

WSL2 / Linux 源码编译产物：

# 查看可用设备（官方 --list-devices）
./build/bin/llama-server --list-devices

# CUDA 服务器启动示例（官方 Docker 示例同参数族）
./build/bin/llama-server -m models/Qwen3-8B-Q4_K_M.gguf \
  --host 0.0.0.0 --port 8080 \
  --n-gpu-layers 99 -c 4096 -fa

# 命令行对话（官方 cli README 模式）
./build/bin/llama-cli -m models/Qwen3-8B-Q4_K_M.gguf --jinja --color -ngl 99 -c 4096

官方 Docker 路线（docs/docker.md、tools/server/README.md Docker 示例）：

# CPU 镜像：仅含 llama-server
docker run -p 8080:8080 -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:server \
  -m models/7B/ggml-model.gguf -c 512 --host 0.0.0.0 --port 8080

# CUDA 镜像（CUDA 12 编译），需 --gpus all
docker run -p 8080:8080 -v /path/to/models:/models --gpus all \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/7B/ggml-model.gguf -c 512 --host 0.0.0.0 --port 8080 --n-gpu-layers 99

镜像清单（docs/docker.md）：full（cli + completion + 转换/量化工具）、light（cli + completion）、server（仅 llama-server）；后缀 -cuda（CUDA 12）、-cuda13、-rocm、-vulkan、-musa、-intel；基础镜像平台为 linux/amd64、linux/arm64，full/light/server 另提供 linux/s390x，部分后端镜像仅 linux/amd64，以 docs/docker.md 清单为准。

02.5 使用方法

02.5.1 启动方式

02.5.2 界面 / 命令行操作步骤（带示例）

A. llama-cli 命令行对话（tools/cli/README.md；参数表见 02.4.4）

# 本地模型 + Jinja 模板 + 着色 + 全层 GPU 卸载 + Flash Attention + 8K 上下文
./build/bin/llama-cli \
  -m models/Qwen3-8B-Q4_K_M.gguf \
  --jinja --color \
  -ngl 99 -fa \
  -sm row \
  -c 8192 \
  --system-prompt "You are a concise assistant."

交互常用开关：

B. llama-server 内置 Web UI 与 HTTP 接口（tools/server/README.md）

1. 启动服务器（见 02.4.5）。
2. 浏览器打开 http://127.0.0.1:9931/（自定义 --port 后用对应端口），使用内置 Web UI 对话。
3. 其他前端（如 Open WebUI）通过 OpenAI 兼容接口接入：Base URL 填 http://<服务器IP>:<端口>/v1，API Key 任意填写（未启用 --api-key 时不校验）。 - 对接依据：llama.cpp 服务器提供 OpenAI 兼容 chat/completions 等路由（tools/server/README.md Features 与 “OpenAI-compatible API Endpoints”）；Open WebUI README 明确支持接入任意 OpenAI 兼容 API：https://github.com/open-webui/open-webui。

02.5.3 服务端 API 端点表（tools/server/README.md “API Endpoints”）

02.5.4 端到端示例（输入 → 命令 → 输出）

场景：RTX 3070 8GB，WSL2 源码编译 CUDA 版，本地 GGUF Qwen3-8B-Q4_K_M.gguf（体积见 03 章），启动 OpenAI 兼容服务器并完成一次对话。

第 1 步：启动服务器

cd ~/llama.cpp
./build/bin/llama-server \
  -m ~/models/Qwen3-8B-Q4_K_M.gguf \
  --host 0.0.0.0 --port 8080 \
  -ngl 99 -c 8192 -fa \
  --jinja --alias qwen3-8b

启动日志关键行（结构示意，tools/server/README.md 默认参数）：监听 http://0.0.0.0:8080，模型全层卸载，上下文 8192，Web UI 开启。

第 2 步：健康检查

curl http://localhost:8080/health
# 就绪返回：{"status": "ok"}

第 3 步：OpenAI 兼容聊天请求（tools/server/README.md 官方 curl 示例格式）

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "用三句话介绍你自己。"}
    ]
  }'

返回（OpenAI 兼容结构，字段说明见 /v1/chat/completions 文档；content 为模型回答）：

{
  "object": "chat.completion",
  "model": "qwen3-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是基于 Qwen3 系列的本地大模型，运行在 llama.cpp 推理引擎上。\n我的回答由本地显卡完成计算，不上传对话内容到云端。\n你可以直接在命令行或浏览器里向我提问。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 24, "completion_tokens": 66, "total_tokens": 90}
}

Python openai SDK 接入（官方 /v1/chat/completions 文档示例，Base URL 替换为本机地址）：

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required"
)

completion = client.chat.completions.create(
    model="qwen3-8b",
    messages=[{"role": "user", "content": "用三句话介绍你自己。"}]
)
print(completion.choices[0].message.content)

02.6 常见坑（现象 + 原因 + 解决）

1. 现象：CUDA 编译时报 nvcc warning : Cannot find valid GPU for '-arch=native', default arch is used，或编译产物只能用 CPU。 - 原因：docs/build.md “Override Compute Capability Specifications” 指出，nvcc 无法探测到本机 GPU 时会回退默认架构；非原生机器 / 多卡混合场景需要显式指定架构。 - 解决：按官方方式指定 -DCMAKE_CUDA_ARCHITECTURES="86;89"（RTX 3070=86、RTX 4090=89）；或 -DGGML_NATIVE=OFF 做覆盖全架构的非原生构建。

2. 现象：llama-server / llama-cli 启动后全程跑在 CPU，生成很慢。 - 原因：使用了 CPU 版压缩包；或 -ngl 未设置 / 被 -dev none 限制；CUDA 后端未编译进二进制；WSL2 内 nvidia-smi 不可用。 - 解决：核对下载的是 bin-win-cuda-12.4-x64.zip（或源码 -DGGML_CUDA=ON 编译）；先执行 --list-devices 查看设备；启动时加 -ngl 99（全部层卸载）；WSL2 先确认 nvidia-smi 正常。

3. 现象：对话输出乱码、角色标记错乱、系统提示词不生效。 - 原因：模型自带聊天模板未被正确使用；/v1/chat/completions 要求模型具备受支持的聊天模板（tools/server/README.md 提示：不支持的模型将默认使用 ChatML 模板）。 - 解决：保持 --jinja 默认启用；必要时用 --chat-template / --chat-template-file 指定模板；模板支持清单参考官方 Wiki：https://github.com/ggml-org/llama.cpp/wiki/Templates-supported-by-llama_chat_apply_template（tools/server/README.md 内链）。

4. 现象：端口 9931（或自定义端口）被占用，服务器启动失败。 - 原因：本机已有其他进程占用端口；或上一个 llama-server 实例未退出。 - 解决：--port 指定其他端口（如 8080）；排查占用进程；检查 --host 绑定地址是否与其他服务冲突。

5. 现象：-hf 拉取模型超时、中断或报网络错误。 - 原因：Hugging Face 在国内网络访问不稳定；代理未配置。 - 解决：优先“手动下载 GGUF + -m 本地路径”（02.4.3 方案 C）；或用 MODEL_ENDPOINT 指向兼容 HF API 的镜像；tools/server/README.md “Running behind a proxy” 要求下载模型前先导出 HTTP_PROXY 与 HTTPS_PROXY（NO_PROXY 与回环地址直连）。

6. 现象：llama-quantize 阶段内存不足、进程被杀，或磁盘写满。 - 原因：官方 “Memory/Disk Requirements” 说明：模型当前整体载入内存，内存与磁盘需求相同；原始 F32/BF16 体积很大（官方参考 Llama-3.1-8B 原始 32.1GB）。 - 解决：留出与原始模型相当的 RAM 与磁盘；优先从已有 16bit 模型量化；不要反复对已量化文件再量化（--allow-requantize 会明显损失质量，tools/quantize/README.md 已警告）；需要更优质量时配合 --imatrix 重要性矩阵。

02.7 本节来源清单

验证方式：curl 200 = 命令行 HTTP 状态码核验；web_fetch / 源码核对 = 已下载官方原始文件逐条核对；general_search = 搜索索引佐证。核验日期 2026-10-25。

03. Qwen3 系列（官方 GGUF 量化版）—— 阿里开源稠密 + MoE 大模型，本地一键可跑

适用环境：Windows 10/11 原生、Windows 10/11 + WSL2（Ubuntu 24.04）、RTX 3070 8GB / RTX 4090 24GB、Linux 云服务器；运行方式以 01 章 Ollama 与 02 章 llama.cpp 为本地推理框架。 信息口径：模型规格、许可证、量化文件体积、采样参数、最低框架版本均来自 Qwen 官方 GitHub README、Hugging Face 官方模型仓库与模型卡、config.json、官方 readthedocs 文档；核验日期 2026-10-25。

03.1 项目定位与基本信息

03.2 官方图片

下图为 Qwen3 官方 GitHub README 顶部 Logo（非 AI 生成、非第三方图）。

• 图片来源 URL：https://qianwen-res.oss-accelerate-overseas.aliyuncs.com/logo_qwen3.png（官方 README 第 4 行内嵌 Logo，2026-10-25 curl -L 下载）。
• 本地路径：https://zhouruolin.cn/upload/03_qwen3_logo.png；file 校验：PNG image data, 3944 x 1555, 8-bit/color RGBA，416,907 字节（>20KB）。

03.3 环境要求

框架与系统要求以 01 章 Ollama、02 章 llama.cpp 为准；本表仅列出 Qwen3 模型侧要求与本地显存/磁盘选型依据。

官方模型规格一览（参数量、层数、注意力头、隐藏层来自各模型卡 README 与 HF config.json，2026-10-25 逐条抓取）：

03.4 最详细部署步骤（Ollama 与 llama.cpp 两条路线，Windows 与 WSL2 通用）

03.4.1 依赖安装

1. 先完成框架安装（任选其一，详细步骤见对应章节）： - Ollama 路线：按 01.4.2 完成 Windows 安装包或 WSL2 一键脚本安装，版本 ≥ v0.9.0。 - llama.cpp 路线：按 02.4.2 完成 Windows 预编译 CUDA 包解压，或 WSL2 源码编译（CUDA 架构 RTX 3070=86、RTX 4090=89），版本 ≥ b5401。
2. 可选：Python 环境用于 huggingface-cli / modelscope 下载 GGUF：

# Ubuntu / WSL2
sudo apt-get install -y python3 python3-pip
pip install huggingface_hub modelscope

03.4.2 模型 / 权重下载（官方仓库 + 国内加速方案）

A. 官方 Hugging Face 仓库清单（均已核验 HTTP 200）

说明：以上 GGUF 仓库均为 Qwen 官方发布（模型卡 base_model: Qwen/Qwen3-*、license: apache-2.0），不是 unsloth 等第三方社区量化；0.6B / 1.7B 官方仅提供 Q8_0 一档。

B. llama.cpp 直连 Hugging Face（官方 README 命令格式）

# 自动拉取指定量化档；<user>/<model>:<quant>，量化档大小写不敏感
./build/bin/llama-cli -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --color -ngl 99 -fa \
  -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 \
  -c 40960 -n 32768 --no-context-shift

C. 国内加速方案 1：ModelScope 镜像（官方 README 推荐中国大陆使用）

ModelScope 已镜像上述官方 GGUF 仓库，文件体积与 HF 一致（已逐仓库核验 4B / 8B / 14B / 32B / 30B-A3B 文件大小一致）。

# 1) 安装 ModelScope SDK（官方 README：pip install modelscope）；
#    如需新版轻量 hub 客户端，可另装 pip install modelscope-hub（CLI 为 ms / modelscope）
pip install modelscope

# 2a) 旧版 SDK CLI（官方文档 Download-Model 页：--model 仓库 ID，--include 文件名通配，
#     --cache_dir 本地缓存目录）
modelscope download --model Qwen/Qwen3-8B-GGUF \
  --include 'Qwen3-8B-Q4_K_M.gguf' --cache_dir ./qwen3-gguf

# 2b) 新版 modelscope-hub CLI（官方 PyPI 客户端：位置参数仓库 ID 与文件名，
#     --local-dir 直存目录、--include 通配过滤；--cache-dir 覆盖缓存目录）
modelscope download Qwen/Qwen3-8B-GGUF Qwen3-8B-Q4_K_M.gguf \
  --local-dir ./qwen3-gguf

# 3) SDK 方式下载整个仓库（官方 SDK snapshot_download，local_dir 直存目录；
#    参数签名见已安装 modelscope 包 modelscope/hub/snapshot_download.py）
python3 - <<'PY'
from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3-8B-GGUF', local_dir='./qwen3-gguf')
print(model_dir)
PY

ModelScope 镜像仓库直链（浏览器可直接下载单个文件）：

D. 国内加速方案 2：huggingface-cli + HF_ENDPOINT 镜像

HF_ENDPOINT 是 huggingface_hub 读取的端点环境变量（源码 src/huggingface_hub/constants.py：ENDPOINT = os.getenv("HF_ENDPOINT", _HF_DEFAULT_ENDPOINT)）；hf-mirror.com 为第三方 HF 镜像站（非 Qwen / HF 官方）。

# 经镜像端点下载指定 GGUF（官方 Qwen 文档命令格式：huggingface-cli download <repo> <file> --local-dir <dir>）
HF_ENDPOINT=https://hf-mirror.com huggingface-cli download \
  Qwen/Qwen3-8B-GGUF Qwen3-8B-Q4_K_M.gguf --local-dir ./qwen3-gguf

下载完成后用本地路径 -m 加载（llama.cpp），或按 01.4.3 方案 C 导入 Ollama。

E. Ollama 模型库直拉（官方 README “Ollama” 节；标签以 https://ollama.com/library/qwen3/tags 为准）

ollama serve
ollama run qwen3:8b
# 可选尺寸后缀：:0.6b :1.7b :4b :8b :14b :32b :30b-a3b

03.4.3 量化档位与显存选型表（RTX 3070 8GB / RTX 4090 24GB）

文件体积来自 Hugging Face 官方 GGUF 仓库 API 实测（2026-10-25，单位 GB，按字节 ÷ 10⁹ 计）。注意：表内仅为权重体积，不含 KV 缓存与上下文占用；实际显存需在此基础上预留上下文余量。

RTX 3070 8GB 选型建议（权重体积 + 小上下文余量）：

RTX 4090 24GB 选型建议：

03.4.4 关键配置（采样参数、上下文、思考模式）

官方推荐采样参数（Qwen3-8B 模型卡 “Best Practices” 节，2026-10-25 核对）：

其他官方建议：大多数查询输出长度建议 32,768 token；数学 / 编程竞赛等复杂问题 benchmark 可设到 38,912 token。

思考模式开关（模型卡 “Switching Between Thinking and Non-Thinking Mode” 节）：

上下文与长文本：

官方注意：Ollama 默认 num_ctx=2048、num_predict=-1，对 Qwen3 偏小，可能影响体验；建议按模型能力手动设置（README “Ollama” Note 节）。

03.4.5 启动

A. llama.cpp 命令行（官方 README 命令，Qwen3-8B-GGUF:Q8_0）

./build/bin/llama-cli -hf Qwen/Qwen3-8B-GGUF:Q8_0 \
  --jinja --color -ngl 99 -fa -sm row \
  --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 \
  -c 40960 -n 32768 --no-context-shift
# Ctrl+C 退出

B. llama-server（官方 README 命令，端口 8080）

./build/bin/llama-server -hf Qwen/Qwen3-8B-GGUF:Q8_0 \
  --jinja --reasoning-format deepseek \
  -ngl 99 -fa -sm row \
  --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 \
  -c 40960 -n 32768 --no-context-shift \
  --port 8080

• 内置 Web UI：http://localhost:8080
• OpenAI 兼容 API：http://localhost:8080/v1

C. Ollama（官方 README 命令）

ollama serve
ollama run qwen3:8b
# 进入 REPL 后：
# /set parameter num_ctx 40960
# /set parameter num_predict 32768
# /set think      # 开启思考（Qwen3-2504 默认即开启）
# /set nothink    # 关闭思考
# /bye            # 退出

• OpenAI 兼容 API：http://localhost:11434/v1/（使用前先 ollama run qwen3:8b 把模型加载准备好，官方 README Note）。

03.5 使用方法

03.5.1 启动方式

03.5.2 命令行操作步骤（以 Ollama 为例）

# 1. 启动服务（后台常驻，使用期间不要退出）
ollama serve

# 2. 拉取并进入 Qwen3-8B
ollama run qwen3:8b

# 3. REPL 内常用命令（官方 README “Ollama” 节）
>>> /set parameter num_ctx 40960     # 设置上下文长度
>>> /set parameter num_predict 32768 # 设置最大生成长度
>>> /set think                      # 开启思考模式
>>> /set nothink                   # 关闭思考模式
>>> /bye                            # 退出会话

03.5.3 参数说明表（Qwen3 官方推荐 + 框架常用开关）

03.5.4 端到端示例（输入 → 命令 → 输出）

场景：RTX 3070 8GB，WSL2 内 llama.cpp 源码编译 CUDA 版，ModelScope 下载 Qwen3-8B-Q4_K_M.gguf，启动服务并完成一次非思考模式对话。

第 1 步：下载模型（ModelScope，新版 hub CLI 语法）

modelscope download Qwen/Qwen3-8B-GGUF Qwen3-8B-Q4_K_M.gguf \
  --local-dir ~/models/qwen3-gguf
# 旧版 SDK CLI 等价写法：
# modelscope download --model Qwen/Qwen3-8B-GGUF \
#   --include 'Qwen3-8B-Q4_K_M.gguf' --cache_dir ~/models/qwen3-gguf

第 2 步：启动 llama-server（8GB 卡收窄上下文，关闭思考解析）

cd ~/llama.cpp
./build/bin/llama-server \
  -m ~/models/qwen3-gguf/Qwen3-8B-Q4_K_M.gguf \
  --host 0.0.0.0 --port 8080 \
  -ngl 99 -fa --jinja \
  -c 8192 -n 4096 --no-context-shift \
  --reasoning-format none

第 3 步：健康检查

curl http://localhost:8080/health
# 就绪：{"status": "ok"}

第 4 步：OpenAI 兼容请求（输入 → 命令）

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      {"role": "system", "content": "你是简洁的中文助手。"},
      {"role": "user", "content": "用三句话解释什么是量化（quantization），面向新手。"}
    ],
    "chat_template_kwargs": {"enable_thinking": false},
    "temperature": 0.7,
    "top_p": 0.8,
    "top_k": 20,
    "min_p": 0
  }'

输出（OpenAI 兼容结构；content 为模型回答，模型实际生成文本以运行时为准）：

{
  "object": "chat.completion",
  "model": "qwen3-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "量化就是把模型里原本高精度的数字压缩成更低位数来存储和计算。\n这样模型文件更小、更省显存，普通电脑也能跑起来；代价是回答质量可能有轻微下降。\n常见档位有 Q4_K_M、Q5_K_M、Q6_K、Q8_0，位数越小体积越小、速度越快。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 34, "completion_tokens": 72, "total_tokens": 106}
}

思考模式对照：将 --reasoning-format 改为 deepseek，请求中不关闭思考，模型会先在 reasoning_content 输出推理过程，再在 content 给出正式回答（字段结构见 tools/server/README.md /v1/chat/completions 文档）。

03.6 常见坑（现象 + 原因 + 解决）

1. 现象：回答前面大段 <think>...</think> 推理内容，新手误以为输出异常。 - 原因：Qwen3-2504 默认开启思考模式（enable_thinking=True）。 - 解决：Transformers 传 enable_thinking=False；提示词加 /no_think；Ollama 用 /set nothink；llama.cpp 实际关闭思考需在请求体传 "chat_template_kwargs": {"enable_thinking": false}（或 --chat-template-kwargs '{"enable_thinking":false}'），--reasoning-format none 只控制思考内容是否从输出中剥离、不会阻止模型思考；想把思考单独展示可用 --reasoning-format deepseek。2507 系列分 Instruct（仅非思考）与 Thinking（仅思考）变体，按模型名选择。

2. 现象：回答重复绕圈、质量明显变差。 - 原因：模型卡 Best Practices 明确警告：思考模式不要使用贪心解码（greedy）；需按官方采样参数设置温度、Top-P、Top-K、Min-P。 - 解决：思考模式 temp 0.6 / top_p 0.95 / top_k 20 / min_p 0；非思考 temp 0.7 / top_p 0.8 / top_k 20 / min_p 0；出现重复时可追加 --presence-penalty 1.5（官方 GGUF 模型卡命令示例）。

3. 现象：长对话中途“忘前文”或被截断。 - 原因：Ollama 默认采用上下文滚动移位（官方 README Note：Ollama 与 llama.cpp 一样具备滚动上下文管理，默认 num_ctx=2048、num_predict=-1，对 Qwen3 偏小）；llama.cpp 的 --context-shift 默认关闭，一旦显式开启滚动，超过 -c 后旧 token 会被淘汰。 - 解决：Ollama 用 /set parameter num_ctx 与 num_predict 显式放大；llama.cpp 用 -c 放大上下文，官方 Qwen 命令显式 --no-context-shift 保持关闭滚动移位；超过 32,768 时按官方 YaRN 方案扩展到 131,072（-c 131072 --rope-scaling yarn --rope-scale 4 --yarn-orig-ctx 32768）。

4. 现象：启动即报显存不足（CUDA out of memory），模型无法加载。 - 原因：所选量化档权重已接近或超过显存；8GB 卡加载 14B 以上模型必然超限；KV 缓存还会额外占用显存。 - 解决：按 03.4.3 表降档（Q4_K_M 优先）或缩小模型尺寸；llama.cpp 调小 -ngl 让部分层留在 CPU；Ollama 减小 num_ctx；8GB 卡不要尝试 14B / 32B / 30B-A3B。

5. 现象：-hf 或 ollama pull 长时间下载超时、中断。 - 原因：Hugging Face 在国内网络不稳定。 - 解决：优先 ModelScope CLI / 浏览器镜像下载官方 GGUF，再用本地路径 -m 加载；huggingface-cli 配合 HF_ENDPOINT=https://hf-mirror.com；代理环境按 02.6 第 5 条配置 HTTPS_PROXY。

6. 现象：Ollama 里 qwen3:30b-a3b 对应权重与预期不符，或找不到某一量化档。 - 原因：官方 README Note 明确：Ollama 命名可能与 Qwen 原始命名不一致（例如 qwen3:30b-a3b 实际指向 qwen3:30b-a3b-thinking-2507-q4_K_M，截至 2025 年 8 月）。 - 解决：拉取前先核对 https://ollama.com/library/qwen3/tags；需要精确量化档时，用 ModelScope/HF 下载 GGUF 后按 01.4.3 离线导入自定义模型。

7. 现象：旧版 llama.cpp 加载 Qwen3 报错（聊天模板异常、tokenizer 报错、不识别模型）。 - 原因：官方要求 llama.cpp ≥ b5401 才完整支持 Qwen3。 - 解决：按 02.4.2 更新到最新 Nightly 稳定编译产物，或升级 Ollama 到 v0.9.0+。

03.7 本节来源清单

验证方式：web_fetch = 文档抓取工具实际打开；curl 200 = 命令行 HTTP 状态码核验；API 抓取 = Hugging Face / ModelScope 官方 API 拉取文件清单与体积；源码核对 = 已下载官方 README / 模型卡 / config.json 逐条核对。核验日期 2026-10-25。

04. GPT-SoVITS —— 少样本中文语音克隆与语音合成（5 秒零样本 / 1 分钟微调）

适用场景说明：本节面向博主「个人电脑本地部署」场景，环境基线为 Windows 10/11 + WSL2（Ubuntu 24.04）、RTX 3070 8GB / RTX 4090 24GB，另含 Linux 云服务器视角。所有事实均以官方 GitHub README、LICENSE、源码与官方 HF 仓库为准；官方未公布的数值在文中明确标注「README 未给出 / 待实测」，不做推测填充。

04.1 项目定位与基本信息

04.2 官方图片

• 下图来自官方 README「Zero-Shot TTS Speaker Similarity Comparison Image on SeedTTS Eval Testset_CN2020」小节，为官方音色相似度对比图（非 AI 生成、非第三方图片）：

说明：官方 README 未提供独立 logo 文件，另一处官方素材为 GitHub 附件中的演示视频（https://github.com/RVC-Boss/GPT-SoVITS/assets/129054828/05bee1fa-bdd8-4d85-9350-80c060ab47fb ，视频，非图片，故未纳入本节图集）。本节仅使用上述 1 张官方静态图。

04.3 环境要求

以下表格中，官方 README 「Tested Environments」实测组合列于「依赖 / 版本实测记录」行；README 未公布的显存、内存下限均如实标注。

04.4 最详细部署步骤（Windows 与 WSL2 双视角）

方案 A：Windows 官方整合包（免环境、解压即用，README 首选方案）

README「Windows」节原文指引：Windows 用户（tested with win>=10）下载整合包后双击 _go-webui.bat 启动 WebUI。

1. 依赖安装

• 整合包内置 Python 运行环境，无需自行安装 Python / PyTorch。
• 安装 Visual Studio 2017 运行库（README 指引）：https://aka.ms/vs/17/release/vc_redist.x86.exe
• 提示：README 手动安装节要求 Windows 用户把 ffmpeg.exe、ffprobe.exe 放到项目根目录（README 未明确说明整合包是否已内置这两个程序）；整合包启动后若提示缺少 FFmpeg，再按 04.4 方案 B 的 Windows 小节补放。

2. 项目下载（官方 release / HF 整合包链接，已逐一验证）

README 当前正文链接（2026-10-25 复核可访问，HTTP 302 → 200）：

https://huggingface.co/lj1995/GPT-SoVITS-windows-package/resolve/main/GPT-SoVITS-v3lora-20250228.7z?download=true

• 国内网络加速：README 为中国大陆用户提供了国内下载页（语雀）：https://www.yuque.com/baicaigongchang1145haoyuangong/ib3g1e/dkxgpiy9zb96hob4 （README「Users in China can download the package here」链接）。
• HF 仓库文件列表（含更新的 v5 包与 nvidia50 变体，来源 https://huggingface.co/lj1995/GPT-SoVITS-windows-package ，HF API 实测）：

选择建议（非 README 强制规定）：纯按 README 正文走即选 v3lora 包；想体验 v5 音色相似度与 CUDA Graph / flash attention 加速可选用 v5 包。nvidia50 系列变体面向 RTX 50 系显卡，3070 / 4090 选择普通包即可。

3. 模型 / 权重下载

• 整合包已内置对应底模，一般无需手动下载；手动补充模型的放置目录见下方方案 B 第 3 步（目录结构相同）。

4. 关键配置

5. 启动

# 解压后进入目录，双击即可，等价命令：
.\go-webui.bat
# 如需 v1 版本：
.\go-webui-v1.bat
# 仅打开推理 WebUI：
.\go-webui-v2.bat

浏览器自动打开本地 Gradio 页面（默认监听本机回环地址；具体端口以启动终端输出为准，README 未固化端口号）。

方案 B：WSL2（Ubuntu 24.04）源码部署（官方 install.sh 一键脚本）

README「Linux」节官方命令（环境前置：Anaconda / Miniconda 已安装；WSL2 内已可 nvidia-smi 看到 3070 / 4090）：

1. 依赖安装（conda 环境 + 一键脚本自动装 torch / CUDA 依赖）

# 进入准备好的项目目录
git clone https://github.com/RVC-Boss/GPT-SoVITS.git
cd GPT-SoVITS

# 官方 README Linux 节命令
conda create -n GPTSoVits python=3.10
conda activate GPTSoVits

# --device 可选 CU126 | CU128 | ROCM | CPU；--source 可选 HF | HF-Mirror | ModelScope
# 国内网络直接选 HF-Mirror 或 ModelScope，脚本自动走对应镜像源拉取模型
bash install.sh --device CU128 --source HF-Mirror --download-uvr5

install.sh 参数表（已核对官方脚本 print_help 输出，来源：仓库 install.sh 源码）：

2. 项目下载 / 安装（手动等价步骤，README「Install Manually」节）

一键脚本失败时可按 README 手动流程安装：

conda create -n GPTSoVits python=3.10
conda activate GPTSoVits

# README 原文顺序：先装 extra-req（--no-deps），再装主依赖
pip install -r extra-req.txt --no-deps
pip install -r requirements.txt

FFmpeg 安装（README「Install FFmpeg → Ubuntu/Debian Users」节）：

sudo apt update
sudo apt install ffmpeg
sudo apt install libsox-dev
# conda 用户等价方式：
conda install ffmpeg

Windows 源码部署等价命令（README「Windows」节 PowerShell）：

conda create -n GPTSoVits python=3.10
conda activate GPTSoVits
pwsh -F install.ps1 --Device CU128 --Source HF-Mirror [--DownloadUVR5]
# --Device 可选 CU126 | CU128 | CPU；--Source 可选 HF | HF-Mirror | ModelScope（已核对 install.ps1 param 定义）

Windows 手动安装 FFmpeg：README 指引将 ffmpeg.exe（https://huggingface.co/lj1995/VoiceConversionWebUI/blob/main/ffmpeg.exe ）与 ffprobe.exe（https://huggingface.co/lj1995/VoiceConversionWebUI/blob/main/ffprobe.exe ）放入项目根目录。

3. 模型 / 权重下载（README「Pretrained Models」节；install.sh 跑成功可跳过第 1、2、3 项）

国内加速方案：

• 官方脚本内置 --source HF-Mirror / ModelScope 两个国内友好源（README 官方支持，优先使用）。
• 手动 pip / 模型下载场景，可使用 Hugging Face Hub 标准环境变量 HF_ENDPOINT 切换镜像（机制来自底层 huggingface_hub 库，环境变量说明见 https://huggingface.co/docs/huggingface_hub/guides/environment-variables ）：

export HF_ENDPOINT=https://hf-mirror.com

• 各版本专用目录（README 各版本发布说明，供升级时对照）：v2 底模放 GPT_SoVITS/pretrained_models/gsv-v2final-pretrained；v3 底模（s1v3.ckpt、s2Gv3.pth、models--nvidia--bigvgan_v2_24khz_100band_256x 文件夹）放 GPT_SoVITS/pretrained_models；v4 底模（gsv-v4-pretrained/s2v4.pth、gsv-v4-pretrained/vocoder.pth）放 GPT_SoVITS/pretrained_models；v2Pro 底模（v2Pro/ 四个权重 + sv/pretrained_eres2netv2w24s4ep4.ckpt）放 GPT_SoVITS/pretrained_models；v5 底模保持 gsv-v5-pretrained 子目录，即最终路径 GPT_SoVITS/pretrained_models/gsv-v5-pretrained（README V5 Release Notes）。

RTX 3070 8GB 降级选择（README 官方支持项与可选项分列）：

4. 关键配置（目录与开关速查）

.list 标注行示例（README Dataset Format 原文示例，字段以竖线分隔）：

D:\GPT-SoVITS\xxx/xxx.wav|xxx|en|I like playing Genshin.

5. 启动（README「Open WebUI」节命令）

# 主 WebUI（训练 + 推理入口），language 为可选参数
python webui.py
# 指定语言：
python webui.py zh
# 切换 v1：
python webui.py v1
python webui.py v1 zh

独立推理 WebUI：

python GPT_SoVITS/inference_webui.py
# 或执行 python webui.py 后在界面内进入推理页

04.5 使用方法

启动方式

推理界面操作步骤（1-GPT-SoVITS-TTS / 1C-inference 页，README「Open Inference WebUI」节 + 官方 inference_webui.py 源码控件核对）

1. 顶部「模型切换」下拉选择 GPT 模型与 SoVITS 模型，点「刷新模型路径」重载目录；首次使用选择整合包 / 底模默认模型即可。
2. 「请上传并填写参考信息」区：上传 3–10 秒参考音频；在「参考音频的文本」框填写该音频的转写文本；「参考音频的语种」选对应语种。
3. 「请填写需要合成的目标文本和语种模式」区：粘贴待合成文本；「需要合成的语种」选目标语种；「怎么切」选择长文本切分策略。
4. 调整语速、句间停顿与 GPT 采样参数（参数表见下），点击「合成语音」，「输出的语音」播放器出现结果后可在线试听、下载。

参数说明表（来源：官方仓库 GPT_SoVITS/inference_webui.py Gradio 控件定义，行号对应源码）

微调训练流程（README「Finetune → Finetune」节，官方 WebUI 流程简述）

README 明确支持路径自动填充，顺序为：

1. 填写音频路径；
2. 将音频切片为小片段；
3. 降噪（可选）；
4. ASR 自动转写；
5. 人工校对 ASR 转写文本；
6. 进入下一标签页，微调模型。

数据集标注格式见 04.4 配置表；训练所需 .list 三字段：音频路径|说话人名|语种|文本。

端到端示例：5 秒零样本合成一段中文博客口播

准备素材：一段 3–10 秒、单人、无背景音乐、口齿清晰的目标音色录音（ref.wav），用记事本写出其原话文字（例如「大家好，欢迎来到我的技术博客。」）。

操作步骤：

1. 双击 go-webui.bat（整合包）或执行 python GPT_SoVITS/inference_webui.py（源码），打开 1-GPT-SoVITS-TTS / 1C-inference 页。
2. 上传 ref.wav；「参考音频的文本」粘贴原话；「参考音频的语种」选「中文」。
3. 「需要合成的文本」粘贴口播稿，例如：

「今天这期视频，我们来聊一聊几个适合本地部署的开源语音项目，从语音克隆到实时对话，全部跑在自己的电脑上。」

4. 「需要合成的语种」选「中文」；「怎么切」选「凑四句一切」；语速保持 1；top_k 15、top_p 1、temperature 1 保持默认。
5. 点击「合成语音」，在输出播放器试听；相似度不满意时：核对参考文本是否准确、换更干净的 3–10 秒参考音频；情绪 / 音色仍不满足可走 04.5 微调流程，用约 1 分钟目标音色数据微调（README Few-shot TTS 说明）。

命令行备用入口（README 原文）：UVR5 分离伴奏、音频切片、中文 FunASR 标注、非中文 faster-whisper 标注命令见 04.5「启动方式」表。

04.6 常见坑

04.7 本节来源清单

待复核项：英文指南 rentry.co 链接、Colab Notebook 链接在本部署环境网络受限（curl 000），地址均逐字摘自官方 README 徽章，建议读者在国内浏览器 / Colab 环境内二次打开确认。

05. faster-whisper —— 基于 CTranslate2 推理引擎的高速语音识别（ASR）

适用场景说明：面向博主个人电脑本地部署，基线环境 Windows 10/11 + WSL2（Ubuntu 24.04）、RTX 3070 8GB / RTX 4090 24GB，另含 Linux 云服务器视角。faster-whisper 在博客工作流中通常承担「把参考音频 / 口播视频转写成标注文本」的上游角色（例如配合 04 节 GPT-SoVITS 制作训练集标注、自动生成字幕）。本节事实以官方 GitHub README、源码 WhisperModel 类与 PyPI 元数据为准。

05.1 项目定位与基本信息

05.2 官方图片

经逐一核查：官方 README、仓库文件树（codeload tarball 全量清单）、PyPI 项目描述中均未包含任何静态 logo 或界面截图，仅有的图像元素为 CI 徽章与 PyPI 版本徽章（徽章非项目配图，仅作状态标识）。按照「禁止用 AI 生成图或非官方图冒充」的要求，本节不插入图片，待官方后续在仓库 / README 补充视觉素材后再增补。

05.3 环境要求

模型档位选择表（三类口径分列，避免混用）：

口径说明：① 参数量、原版参考显存、相对速度三列来自 openai/whisper 官方 README「Available models and languages」表，描述的是原版 PyTorch 实现基线，不能直接等同于 faster-whisper/CT2 显存占用；② CT2 体积列为 HF Systran 仓库 tree/main API 实测；③ CT2 引擎的真实显存 / 速度以 05.3 下方官方 benchmark 表（仅 large-v2 GPU、small CPU 两组实测）为准，其余档位 README 未公布 CT2 实测值。

官方 benchmark 实测表（README「Benchmark」节原文数据，13 分钟英文音频，RTX 3070 Ti 8GB / CUDA 12.4；CPU 为 i7-12700K 8 线程）：

说明：上表为 README 公布的官方实测；除 large-v2（GPU）与 small（CPU）外，其余档位显存 / 内存数值 README 未给出，不做推算填充。

05.4 最详细部署步骤（Windows 与 WSL2 双视角）

1. 依赖安装

通用前置：安装 Python 3.9+（README 要求）。建议使用虚拟环境隔离：

# WSL2 Ubuntu / Linux 云服务器
python3 -m venv .venv
source .venv/bin/activate

# Windows PowerShell
python -m venv .venv
.\.venv\Scripts\Activate.ps1

NVIDIA GPU 库安装（README「GPU」节三种官方方式，按系统选一）：

• 方式一：Docker（README 官方说明）：使用官方 NVIDIA CUDA 镜像 nvidia/cuda:12.3.2-cudnn9-runtime-ubuntu22.04，其中已含 cuBLAS、cuDNN。
• 方式二：Linux 下 pip 安装（README 原文，仅 Linux）：

```bash pip install nvidia-cublas-cu12 nvidia-cudnn-cu12==9.*

# README 原文要求：启动 Python 前先设置 LD_LIBRARY_PATH export LD_LIBRARY_PATH=$(python3 -c 'import os, nvidia.cublas, nvidia.cudnn; print(os.path.dirname(nvidia.cublas.path[0]) + "/cublas/lib:" + os.path.dirname(nvidia.cudnn.path[0]) + "/cudnn/lib")') ```

• 方式三：Purfview 独立库压缩包（Windows & Linux）：README 指引从 Purfview/whisper-standalone-win 的 libs release 下载所需 NVIDIA 库单文件压缩包，解压后把目录加入系统 PATH。

版本降级提示（README 原文）：若本机为 CUDA 11 + cuDNN 8，执行 pip install --force-reinstall ctranslate2==3.24.0；若为 CUDA 12 + cuDNN 8，执行 pip install --force-reinstall ctranslate2==4.4.0（或在 requirements.txt 中固定版本）。

注意：README 明确 系统无需安装 FFmpeg；若习惯在 Windows PATH 中保留全局 FFmpeg 也不会冲突，但排查问题时不要把「缺 FFmpeg」当成 faster-whisper 的必需报错项。

2. 项目下载 / 安装（README「Installation」节，唯一推荐方式：PyPI）

pip install faster-whisper

其他官方安装方式（README「Other installation methods」折叠节）：

# 安装 master 分支最新代码
pip install --force-reinstall "faster-whisper @ https://github.com/SYSTRAN/faster-whisper/archive/refs/heads/master.tar.gz"

# 安装指定 commit（示例 commit 取自 README）
pip install --force-reinstall "faster-whisper @ https://github.com/SYSTRAN/faster-whisper/archive/a4f1cc8f11433e454c3934442b5e1a4ed5e865c3.tar.gz"

3. 模型 / 权重下载（官方来源 + 国内加速 + 3070 8GB 档位选择）

官方来源：加载 WhisperModel("large-v3") 这类档位名时，对应 CTranslate2 模型自动从 Hugging Face Hub 的 Systran 组织仓库 下载（README「Model conversion」节原文："the corresponding CTranslate2 model is automatically downloaded from the Hugging Face Hub"）。模型清单与体积见 05.3 实测表。

国内加速：faster-whisper 底层使用 huggingface_hub 下载，可通过标准环境变量切换镜像（机制说明：https://huggingface.co/docs/huggingface_hub/guides/environment-variables ）：

# Linux / WSL2（写入 ~/.bashrc 可持久化）
export HF_ENDPOINT=https://hf-mirror.com

# Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"

也可在代码中用 download_root= 指定本地模型目录，或先在网络通畅环境下载好 model.bin 等文件，再用本地目录路径加载（README「Load a converted model」节）：

from faster_whisper import WhisperModel

model = WhisperModel("/path/to/local/model-dir")

RTX 3070 8GB 档位选择（README 官方 benchmark 同类对照 + 明确边界）：

4. 关键配置（代码初始化参数，来源：官方 WhisperModel.__init__ 源码签名）

5. 启动（官方 README 最小可运行命令序列）

# 确认环境已激活，模型首次运行自动下载；无系统 FFmpeg 依赖
python your_transcribe_script.py

05.5 使用方法

启动方式

faster-whisper 是 Python 库，无自带 WebUI；通过 WhisperModel 初始化 + model.transcribe(...) 调用。README 官方最小示例（原文照录）：

from faster_whisper import WhisperModel

model_size = "large-v3"

# Run on GPU with FP16
model = WhisperModel(model_size, device="cuda", compute_type="float16")

# or run on GPU with INT8
# model = WhisperModel(model_size, device="cuda", compute_type="int8_float16")
# or run on CPU with INT8
# model = WhisperModel(model_size, device="cpu", compute_type="int8")

segments, info = model.transcribe("audio.mp3", beam_size=5)

print("Detected language '%s' with probability %f" % (info.language, info.language_probability))

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

README 重要警告：segments 是生成器（generator），只有在迭代它时转写才真正开始；必须放入 list(segments) 或 for 循环中执行（README「Warning」段原文）：

segments, _ = model.transcribe("audio.mp3")
segments = list(segments)  # The transcription will actually run here.

transcribe() 参数说明表（来源：官方 faster_whisper/transcribe.py 第 781–825 行签名 + docstring）

其他官方用法片段（README 原文）

批量转写（Batched InferencePipeline，README「Batched Transcription」节）：

from faster_whisper import WhisperModel, BatchedInferencePipeline

model = WhisperModel("turbo", device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model=model)
segments, info = batched_model.transcribe("audio.mp3", batch_size=16)

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

词级时间戳（README「Word-level timestamps」节）：

segments, _ = model.transcribe("audio.mp3", word_timestamps=True)

for segment in segments:
    for word in segment.words:
        print("[%.2fs -> %.2fs] %s" % (word.start, word.end, word.word))

VAD 过滤（README「VAD filter」节）：

segments, _ = model.transcribe(
    "audio.mp3",
    vad_filter=True,
    vad_parameters=dict(min_silence_duration_ms=500),
)

蒸馏模型 distil-large-v3（README「Faster Distil-Whisper」节）：

from faster_whisper import WhisperModel

model_size = "distil-large-v3"
model = WhisperModel(model_size, device="cuda", compute_type="float16")
segments, info = model.transcribe(
    "audio.mp3", beam_size=5, language="en", condition_on_previous_text=False
)

端到端示例：中文口播音频转写并导出带时间戳字幕（.txt + .srt）

适用场景：把博客录制的口播音视频转成文字稿与 SRT 字幕；3070 8GB 选用 medium + int8 稳妥起步，4090 可换 large-v3 + fp16。

# transcribe_zh.py —— 官方 API 组合示例，依赖：pip install faster-whisper
from faster_whisper import WhisperModel

# 1) 初始化模型：3070 8GB 推荐 medium + int8_float16；4090 可改 large-v3 + float16
model = WhisperModel(
    "medium",
    device="cuda",
    compute_type="int8_float16",
    # cpu_threads=4,          # 纯 CPU 时按需设置
    # download_root="./models", # 指定本地模型目录
)

# 2) 转写：固定中文、beam_size 5、开启 VAD、注入领域提示词、开启词级时间戳
segments, info = model.transcribe(
    "koubo.mp3",
    language="zh",                 # 固定中文；自动检测则留 None
    beam_size=5,
    vad_filter=True,               # 过滤静音片段
    vad_parameters=dict(min_silence_duration_ms=500),
    initial_prompt="以下是技术博客普通话口播内容，包含开源、语音合成、深度学习等术语。",
    word_timestamps=True,          # 词级时间戳，便于精细校对字幕
    condition_on_previous_text=True,
)

print("检测语种：%s（概率 %.3f）" % (info.language, info.language_probability))

# 3) 收集段落到列表（generator 必须迭代后才真正转写）
segments = list(segments)

# 4a) 导出纯文本稿
with open("koubo.txt", "w", encoding="utf-8") as f:
    for seg in segments:
        f.write(seg.text.strip() + "\n")

# 4b) 导出 SRT 字幕（段级时间戳）
def fmt_ts(seconds: float) -> str:
    ms = int((seconds % 1) * 1000)
    s = int(seconds)
    h, rem = divmod(s, 3600)
    m, sec = divmod(rem, 60)
    return f"{h:02d}:{m:02d}:{sec:02d},{ms:03d}"

with open("koubo.srt", "w", encoding="utf-8") as f:
    for idx, seg in enumerate(segments, start=1):
        f.write(f"{idx}\n{fmt_ts(seg.start)} --> {fmt_ts(seg.end)}\n{seg.text.strip()}\n\n")

# 5) 控制台预览
for seg in segments:
    print("[%.2fs -> %.2fs] %s" % (seg.start, seg.end, seg.text.strip()))

运行：

export HF_ENDPOINT=https://hf-mirror.com   # 国内镜像（WSL2/Linux）
python transcribe_zh.py

命令行工具补充：README「Community integrations」列出的 whisper-ctranslate2 是基于 faster-whisper 的第三方 CLI，接口兼容 openai-whisper 客户端；属社区项目，非官方组件，需要独立查阅其仓库说明。

05.6 常见坑

05.7 本节来源清单

待复核项：各档位 CT2 模型在 RTX 3070 8GB 上的独立显存占用，官方 README 仅公布 large-v2（GPU）与 small（CPU）实测数据；其余档位数值请以本机 nvidia-smi 实测为准，本节未做外推估算。

06. LiveTalking —— 实时交互流式数字人引擎，文本/音频驱动数字人实时口型同步并推流输出

适用场景：个人电脑本地部署数字人口播、虚拟主播/直播带货、AI 客服、在线教育分身、大屏讲解、短视频批量出镜。本节命令以官方 README、官方文档站、官方源码（config.py、app.py、docs/api.md）为准；未被官方文档写明的数值会在表格中显式标注"官方未列明 / 待验证"。

06.1 项目定位与基本信息

06.2 官方图片

下图为官方仓库 README 中使用的官方 logo 与 Web 首页界面截图，均从官方仓库 assets/ 目录原始下载，未做任何二次生成或加工。

图 06-1 LiveTalking 官方 Logo

• 来源 URL：https://raw.githubusercontent.com/lipku/LiveTalking/main/assets/LiveTalking-logo.png（README 顶部 <img src="./assets/LiveTalking-logo.png">）
• 下载方式：curl -L -o 06_livetalking_logo.png "<上述 URL>"；2026-10-25 下载后 file 校验：PNG image data, 800 x 281, 8-bit/color RGBA，大小 182,644 字节（>20KB）。

图 06-2 LiveTalking Web 首页界面（官方 README "2.4 Web 页面" 引用图）

• 来源 URL：https://raw.githubusercontent.com/lipku/LiveTalking/main/assets/index.jpg（README 中 <img src="./assets/index.jpg">）
• 下载方式：curl -L -o 06_livetalking_webui.jpg "<上述 URL>"；2026-10-25 下载后 file 校验：JPEG image data, JFIF standard 1.01, 2642x1356, baseline，大小 279,848 字节（>20KB）。

备用官方架构图（已下载备查，本节未在正文引用）：数据流图 https://raw.githubusercontent.com/lipku/LiveTalking/main/assets/dataflow.png，本地保存为 https://zhouruolin.cn/upload/06_livetalking_dataflow.png，file 校验为 PNG image data, 2476 x 262，84,053 字节。

06.3 环境要求

下表"官方依据"列标注信息是否直接来自官方 README / 文档 / 源码；官方未给出的数值不做推算填充。

06.4 最详细部署步骤（WSL2 Ubuntu 24.04 / Windows 双视角）

视角 A：WSL2 内 Ubuntu 24.04（与官方测试环境 Ubuntu 22.04 同系，源码部署主路径）。视角 B：Windows 10/11 原生，优先使用官方整合包；源码级调试建议回到 WSL2。

06.4.1 安装基础依赖

视角 A：WSL2 Ubuntu 24.04（官方 README 命令）

# 0. 确认已安装 NVIDIA 驱动（Windows 侧）并在 WSL2 中可看到显卡
nvidia-smi

# 1. 安装 miniconda 后创建官方指定环境（README 原文命令）
conda create -n livetalking python=3.12
conda activate livetalking

# 2. 安装 PyTorch：README 测试组合 CUDA 12.8
#    若 nvidia-smi 显示的 CUDA 版本不同，请按 https://pytorch.org/get-started/previous-versions 选择对应 cu 版本
pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu128

# 3. 拉取源码（国内可改用 Gitee / GitCode 镜像，见 06.4.2"国内加速方案"）
git clone https://github.com/lipku/LiveTalking.git
cd LiveTalking

# 4. 安装 Python 依赖（README 原文命令）
pip install -r requirements.txt

# 5. ffmpeg（FAQ 官方方式：conda 安装；需保证编译选项含 libx264）
conda install -c conda-forge ffmpeg
ffmpeg -version    # 输出信息中应能看到 --enable-libx264 相关支持

视角 B：Windows 10/11 原生

• 官方 README 2.5 节提供 Windows 整合包：https://pan.quark.cn/s/a040bf5cb065（curl 200 核验，2026-10-25），按包内说明启动即可，无需手动装 PyTorch。
• 官方 README 2.3 节另提供 Windows 桌面客户端：https://pan.quark.cn/s/d7192d8ac19b（curl 200 核验）。
• README 未提供 Windows 原生逐条源码安装命令；若需源码部署，在 WSL2 Ubuntu 中执行视角 A 的步骤。

06.4.2 下载模型 / 权重

wav2lip 后端（README 2.1 节 + 官方文档 3.1.1 节，两个官方网盘二选一）

下载后按官方文档 3.1.1 节放置文件：

musetalk 后端（官方文档 3.1.2 节）

• 官方迅雷网盘地址：https://pan.xunlei.com/s/VOW3nYho64jeCxT2sxrjcE7fA1?pwd=evnw（curl 200，2026-10-25 核验；提取码 evnw 来自链接本身）
• 将压缩包内 models/ 下文件拷贝到项目 models/ 目录；解压 musetalk_avatar1.tar.gz 后将整个文件夹拷贝到 data/avatars/ 目录下。
• 官方文档 3.1.2 节注明：以下库只在生成 avatar 时需要，推理不需要：

conda install ffmpeg
sudo apt install build-essential cmake
pip install "setuptools<81"
pip install face_recognition

国内加速方案（README 原文给出）

• 源码国内镜像：Gitee https://gitee.com/lipku/LiveTalking、GitCode https://gitcode.com/lipku/LiveTalking（README 首页"国内镜像"章节；两站 curl 均 200）。
• 模型本身官方即托管于国内网盘（夸克 / 迅雷），无需 HF 镜像；Google Drive 为 README 备选下载渠道。

06.4.3 关键配置（命令行参数，来源：官方 config.py 源码 parse_args()）

环境变量（来源：官方 .env.example）：.env.example 提供 TENCENT_APPID / TENCENT_SECRET_KEY / TENCENT_SECRET_ID / DASHSCOPE_API_KEY / DOUBAO_API_KEY / AZURE_SPEECH_KEY / AZURE_TTS_ENDPOINT，按所选 TTS / LLM 服务填写；不使用对应服务可留空。

06.4.4 启动服务（官方 README 2.2 节命令）

conda activate livetalking
cd LiveTalking

# wav2lip 后端（默认）
python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1

# musetalk 后端示例（需先按 06.4.2 下载对应模型与 avatar）
python app.py --transport webrtc --model musetalk --avatar_id musetalk_avatar1

README 原文注意事项：服务端需开放端口 TCP:8010，UDP:1-65536（WebRTC 媒体通道）。本机 http://127.0.0.1:8010 无需额外放行；云服务器部署需在安全组放行。

06.5 使用方法

06.5.1 启动方式与入口页面（README 2.3 / 2.4 节 + docs/api.md）

06.5.2 WebUI 操作流程（README 2.3 节 + 官方文档 3.1 节）

1. 启动服务后浏览器访问 http://127.0.0.1:8010/index.html。
2. 点击"开始连接"建立 WebRTC 通道，页面出现数字人待机画面。
3. 在文本框输入要播报的文字，提交后由默认 TTS（edgetts）合成语音并驱动口型；切换到对话模式会先经 LLM 生成回复再播报。
4. 需要自定义形象时进入 /avatar.html 上传闭嘴不说话的视频生成 avatar（官方文档 3.1.1 / 3.1.2 节给出的命令行等价方式见 06.5.4）。
5. 录制：首页提供录制控制按钮；对应后端 API 为 /record 与 /record/{sessionid}。

06.5.3 HTTP API 参数说明（来源：官方 docs/api.md，web_fetch 全文核验）

06.5.4 常用命令行补充（官方文档 3.1 节）

# wav2lip 后端：用自己的视频生成 avatar（输入视频需闭嘴不说话；img_size 固定 256）
python -m avatars.wav2lip.genavatar --video_path xxx.mp4 --img_size 256 --avatar_id wav2lip256_avatar1
# 若一直卡住不动，可将 --face_det_batch_size 改小（文档 3.1.1 节备注）

# musetalk 后端：用视频或图片生成 avatar
python -m avatars.musetalk.genavatar --avatar_id musetalk_avatar1 --file ~/sun.mp4

# 多并发会话（文档 3.6 节）
python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1 --max_session 3

# 虚拟摄像头输出（文档 3.8 节：先安装 pyvirtualcam 驱动与 Python 包、pyaudio）
pip install pyvirtualcam
pip install pyaudio
python app.py --transport virtualcam --model wav2lip --avatar_id wav2lip256_avatar1
# 浏览器另开 http://<serverip>:8010/virtualcam.html；OBS 等直播软件选择虚拟摄像头即可

06.5.5 端到端示例（输入 → 命令 → 输出）

场景：本机 WSL2 内用默认 wav2lip 数字人播报一句开场词，并录制为 MP4。

1. 输入素材：无需额外图片/视频素材，使用官方示例 avatar wav2lip256_avatar1；播报文本：大家好，欢迎来到我的频道。
2. 启动服务：

conda activate livetalking
cd LiveTalking
python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1

3. 浏览器打开 http://127.0.0.1:8010/index.html → 点击"开始连接"；在文本框输入 大家好，欢迎来到我的频道。 提交（type=echo 复读模式，不依赖 LLM Key）。
4. 录制（docs/api.md）：先 POST /record，body {"sessionid": "<连接后获得的 sessionid>", "type": "start_record"}；播报结束后 type 改为 end_record；最后 GET http://127.0.0.1:8010/record/<sessionid>.mp4 下载成片。
5. 输出：浏览器端实时看到口型同步的数字人画面；服务端 data/record/<sessionid>.mp4 为录制视频。
6. 实时性自检（README"6. 性能指标"）：后端日志 inferfps = GPU 推理帧率，finalfps = 最终推流帧率，两者均需 ≥25 才算实时。

06.6 常见坑（现象 + 原因 + 解决，均来自官方 README / FAQ / 文档）

06.7 本节来源清单

07. MuseTalk —— 腾讯音乐 Lyra Lab 出品的实时高保真音频驱动视频口型同步模型

适用场景：给已有视频/照片中的人物换配音口型、配合 MuseV 生成的虚拟人视频完成口型对齐、离线批量配音成片；仓库同时提供普通推理、实时推理与 Gradio 网页 Demo 三套入口。本节命令与参数均以官方 README、官方仓库脚本（scripts/inference.py、scripts/realtime_inference.py、app.py、inference.sh、download_weights.sh、download_weights.bat、requirements.txt、configs/inference/*.yaml）为准。

07.1 项目定位与基本信息

07.2 官方图片

图 07-1 MuseTalk 模型结构（README "Model" 章节原图）

• 来源 URL：https://github.com/user-attachments/assets/02f4a214-1bdd-4326-983c-e70b478accba（README ![Model Structure](...) 原始链接，跟随 302 重定向下载）
• 下载方式：curl -L -o 07_musetalk_model_structure.png "<上述 URL>"；2026-10-25 下载后 file 校验：PNG image data, 1934 x 646, 8-bit/color RGBA，大小 410,486 字节（>20KB）。

图 07-2 Gradio Demo 参数面板（README "Gradio Demo" 章节引用图 assets/figs/gradio_2.png）

• 来源 URL：https://raw.githubusercontent.com/TMElyralab/MuseTalk/main/assets/figs/gradio_2.png
• 下载方式：curl -L -o 07_musetalk_gradio_params.png "<上述 URL>"；2026-10-25 下载后 file 校验：PNG image data, 1781 x 1066, 8-bit/color RGBA，大小 75,170 字节（>20KB）。

说明：仓库另一张 assets/figs/gradio.png（硬件耗时对比图）下载后仅 13,911 字节，未达到本节 ">20KB" 的交付要求，故未引用；本地亦未保留。

07.3 环境要求

07.4 最详细部署步骤（WSL2 Ubuntu 24.04 / Windows 10-11 双视角）

07.4.1 环境搭建（README Installation 原文命令）

视角 A：WSL2 Ubuntu 24.04 / Linux

# 1. 创建官方推荐环境
conda create -n MuseTalk python==3.10
conda activate MuseTalk

# 2. 安装 PyTorch 2.0.1（README Option 1：pip cu118 wheel）
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118
# README Option 2（conda 方式，二选一即可）：
# conda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.8 -c pytorch -c nvidia

# 3. 拉取源码
git clone https://github.com/TMElyralab/MuseTalk.git
cd MuseTalk

# 4. 安装其余 Python 依赖（README 原文命令）
pip install -r requirements.txt

# 5. 安装 MMLab 生态（README 原文命令）
pip install --no-cache-dir -U openmim
mim install mmengine
mim install "mmcv==2.0.1"
mim install "mmdet==3.1.0"
mim install "mmpose==1.1.0"

# 6. 安装 ffmpeg（README Quickstart Prerequisites：Linux 用系统包管理器）
sudo apt-get update && sudo apt-get install -y ffmpeg
ffmpeg -version    # 确认命令在 PATH 中

视角 B：Windows 10/11 原生

# 1. conda 环境（与 Linux 一致）
conda create -n MuseTalk python==3.10
conda activate MuseTalk

# 2. PyTorch（README 同一组 pip 命令，Windows 下直接可用）
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118

# 3. 源码与依赖
git clone https://github.com/TMElyralab/MuseTalk.git
cd MuseTalk
pip install -r requirements.txt
pip install --no-cache-dir -U openmim
mim install mmengine
mim install "mmcv==2.0.1"
mim install "mmdet==3.1.0"
mim install "mmpose==1.1.0"

ffmpeg 安装（README "Setup FFmpeg" 原文）：

1. 下载 ffmpeg-static 构建包：https://github.com/BtbN/FFmpeg-Builds/releases（curl 200 核验）。
2. Linux：解压后设置环境变量 export FFMPEG_PATH=/path/to/ffmpeg，README 示例 export FFMPEG_PATH=/musetalk/ffmpeg-4.4-amd64-static。
3. Windows：将 ffmpeg-xxx\bin 目录加入系统 PATH；命令行运行 ffmpeg -version 能输出版本信息即配置成功；也可以在推理命令中用 --ffmpeg_path 参数指定实际 bin 目录（README Windows 推理命令即采用该方式）。

07.4.2 下载权重（两种官方方式）

方式一：官方下载脚本（推荐，脚本内置国内 HF 镜像）

方式二：手动下载（README "Option 2: Manual Download" 原文清单）

1. MuseTalk 训练权重：https://huggingface.co/TMElyralab/MuseTalk/tree/main
2. 其他组件权重： - sd-vae-ft-mse：https://huggingface.co/stabilityai/sd-vae-ft-mse/tree/main（curl 200） - whisper-tiny：https://huggingface.co/openai/whisper-tiny/tree/main（curl 200） - dwpose：https://huggingface.co/yzd-v/DWPose/tree/main（curl 200） - syncnet：https://huggingface.co/ByteDance/LatentSync/tree/main（curl 200） - face-parse-bisent 79999_iter.pth：https://drive.google.com/file/d/154JgKpzCPW82qINcVieuPH3fZ2e0P812/view?pli=1 - resnet18：https://download.pytorch.org/models/resnet18-5c106cde.pth（curl 实测 46,827,520 字节）

权重目录结构（README 原文树形清单，必须按此组织到 models/ 下）：

./models/
├── musetalk
│   ├── musetalk.json
│   └── pytorch_model.bin
├── musetalkV15
│   ├── musetalk.json
│   └── unet.pth
├── syncnet
│   └── latentsync_syncnet.pt
├── dwpose
│   └── dw-ll_ucoco_384.pth
├── face-parse-bisent
│   ├── 79999_iter.pth
│   └── resnet18-5c106cde.pth
├── sd-vae
│   ├── config.json
│   └── diffusion_pytorch_model.bin
└── whisper
    ├── config.json
    ├── pytorch_model.bin
    └── preprocessor_config.json

07.4.3 权重文件清单与实测体积（2026-10-25 HTTP HEAD Content-Length 实测）

国内加速：download_weights.sh / download_weights.bat 已把 HF_ENDPOINT 指向 https://hf-mirror.com（curl 200 核验）；手动下载时也可在各 HF URL 前替换域名 huggingface.co → hf-mirror.com。

07.4.4 关键配置文件修改（以官方 YAML 原文为准，web_fetch 核验）

普通推理配置 configs/inference/test.yaml（当前 main 分支原文）：

task_0:
 video_path: "data/video/yongen.mp4"
 audio_path: "data/audio/yongen.wav"

task_1:
 video_path: "data/video/yongen.mp4"
 audio_path: "data/audio/eng.wav"
 bbox_shift: -7

实时推理配置 configs/inference/realtime.yaml（当前 main 分支原文）：

avator_1:
 preparation: True # your can set it to False if you want to use the existing avator, it will save time
 bbox_shift: 5
 video_path: "data/video/yongen.mp4"
 audio_clips:
     audio_0: "data/audio/yongen.wav"
     audio_1: "data/audio/eng.wav"

README 补充：为获得最佳效果，输入视频建议 25fps（与训练时一致）；帧率偏低的视频可先插帧，或用 ffmpeg 转成 25fps。

07.4.5 启动与推理命令

普通推理（Normal Inference，README Quickstart 原文）

Linux：

# MuseTalk 1.5（README 推荐）
sh inference.sh v1.5 normal
# MuseTalk 1.0
sh inference.sh v1.0 normal

Windows（README 原文命令，路径分隔符为反斜杠；--ffmpeg_path 指向实际 ffmpeg bin 目录）：

REM MuseTalk 1.5（推荐）
python -m scripts.inference --inference_config configs\inference\test.yaml --result_dir results\test --unet_model_path models\musetalkV15\unet.pth --unet_config models\musetalkV15\musetalk.json --version v15 --ffmpeg_path ffmpeg-master-latest-win64-gpl-shared\bin

REM MuseTalk 1.0：相应改为 models\musetalk、pytorch_model.bin、--version v1

实时推理（Real-time Inference，README Quickstart 原文）

Linux：

# MuseTalk 1.5（推荐）
sh inference.sh v1.5 realtime
# MuseTalk 1.0
sh inference.sh v1.0 realtime

Windows（README 原文命令）：

REM MuseTalk 1.5（推荐）
python -m scripts.realtime_inference --inference_config configs\inference\realtime.yaml --result_dir results\realtime --unet_model_path models\musetalkV15\unet.pth --unet_config models\musetalkV15\musetalk.json --version v15 --fps 25 --ffmpeg_path ffmpeg-master-latest-win64-gpl-shared\bin

REM MuseTalk 1.0：相应改为 models\musetalk、pytorch_model.bin、--version v1

inference.sh 脚本事实（web_fetch 核验）：normal → scripts.inference + configs/inference/test.yaml + results/test；realtime → scripts.realtime_inference + configs/inference/realtime.yaml + results/realtime，并附加 --fps 25；v1.0 对应 --version v1 与 models/musetalk/pytorch_model.bin，v1.5 对应 --version v15 与 models/musetalkV15/unet.pth。

Gradio 网页 Demo（README "Gradio Demo" 原文命令；Windows / Linux 通用）：

# 可去掉 --use_float16 换取更好画质，但会增加显存占用与推理时间（README 原文说明）
python app.py --use_float16 --ffmpeg_path ffmpeg-master-latest-win64-gpl-shared\bin

app.py 参数（源码 argparse 核验）：--ip 默认 127.0.0.1，--port 默认 7860，--share（创建公开链接），--use_float16，--ffmpeg_path 默认 Windows 路径 ffmpeg-master-latest-win64-gpl-shared\bin。启动后浏览器访问 http://127.0.0.1:7860。

07.5 使用方法

07.5.1 方式一：Gradio 网页 Demo（README "Gradio Demo" 章节 + app.py 界面定义）

1. 启动 python app.py --use_float16 --ffmpeg_path <ffmpeg bin 目录>。
2. 左侧面板：Drving Audio（app.py 源码原始标签，即 Driving Audio）上传驱动音频；Reference Video 上传参考视频（app.py 的 check_video 会自动把视频转成 25fps）。
3. 参数区： - BBox_shift value, px（bbox_shift，默认 0，仅 v1.0 可调；Demo 固定使用 v15） - Extra Margin（滑块 0–40，默认 10，决定下颌区域可动范围） - Parsing Mode（jaw / raw，默认 jaw） - Left Cheek Width / Right Cheek Width（滑块 20–160，默认 90；jaw 模式下决定左右脸颊编辑范围）
4. 先点 "1. Test Inpainting" 仅生成第一帧用于微调口型参数，减少成片面部瑕疵（README 建议：为节省推理时间，可先生成第一帧调试最佳参数）。
5. 参数满意后点 "2. Generate"，右侧输出口型同步视频。

07.5.2 方式二：命令行普通推理（离线批量配音）

1. 编辑 configs/inference/test.yaml，把 video_path / audio_path 换成自己的素材；可写多个 task_* 任务。
2. 执行 07.4.5 节普通推理命令。
3. 输出目录：results/test/v15/<视频名>_<音频名>.mp4（scripts/inference.py 命名规则：output_basename = f"{input_basename}_{audio_basename}"，先帧序列 + 临时视频，再用 ffmpeg 合并输入音频）。

07.5.3 方式三：命令行实时推理

1. 首次为新数字人准备素材：configs/inference/realtime.yaml 中 preparation: True，填写 video_path 与 audio_clips。
2. 执行 07.4.5 节实时推理命令；首次会做人脸检测、坐标提取、VAE latent 等准备工作并缓存：v15 为 results/v15/avatars/<avatar_id>/，v1 为 results/avatars/<avatar_id>/（scripts/realtime_inference.py 源码路径规则）。
3. 后续复用同一形象：将 preparation 改为 False，跳过准备阶段。
4. 可选跳过图片保存以测速：

python -m scripts.realtime_inference --inference_config configs/inference/realtime.yaml --skip_save_images

（README "For faster generation without saving images" 原文命令）

07.5.4 普通推理参数说明表（来源：scripts/inference.py 源码 argparse，逐项核验默认值）

07.5.5 实时推理参数补充（来源：scripts/realtime_inference.py 源码 argparse）

07.5.6 端到端示例（输入 → 命令 → 输出，使用仓库自带示例素材）

1. 输入素材（仓库内置，已核验可达）： - 视频：data/video/yongen.mp4（https://raw.githubusercontent.com/TMElyralab/MuseTalk/main/data/video/yongen.mp4，HTTP HEAD 实测 1,870,923 字节） - 音频：data/audio/yongen.wav（https://raw.githubusercontent.com/TMElyralab/MuseTalk/main/data/audio/yongen.wav，实测 1,536,078 字节）
2. 配置：保持 configs/inference/test.yaml 中 task_0 默认值不变（即上述两个文件）。
3. 命令（Linux / WSL2）：

conda activate MuseTalk
cd MuseTalk
sh inference.sh v1.5 normal

4. 处理过程：ffmpeg 抽帧 → Whisper 提取音频特征 → 人脸关键点与 bbox 检测（坐标缓存为 .pkl）→ VAE 编码 latent → UNet 逐 batch 推理 → 解码贴回原画面 → ffmpeg 合成 yongen_yongen.mp4 并合并音频。
5. 输出：results/test/v15/yongen_yongen.mp4（scripts/inference.py 输出命名规则）。
6. Windows 等价命令：

python -m scripts.inference --inference_config configs\inference\test.yaml --result_dir results\test --unet_model_path models\musetalkV15\unet.pth --unet_config models\musetalkV15\musetalk.json --version v15 --ffmpeg_path <实际 ffmpeg bin 目录>

07.6 常见坑（现象 + 原因 + 解决，依据官方 README 与源码）

07.7 本节来源清单

08. Hugging Face speech-to-speech —— 本地全链路实时语音对话（语音进、语音出）开源语音智能体

适用场景说明：面向博主个人电脑本地部署，基线环境 Windows 10/11 + WSL2（Ubuntu 24.04）、RTX 3070 8GB / RTX 4090 24GB，另含 Linux 云服务器视角。本节严格以官方仓库 README、docs/configuration.md、demo/README.md 与 src/speech_to_speech/ 下 STT / LLM / TTS 组件指南原文为事实来源；README 未提供的 Colab / T4 方案、官方未给出的显存数值均如实标注，不做推测补充。

08.1 项目定位与基本信息

08.2 官方图片

• 下图为官方 README 顶部 logo（README 第 3 行 <img src="https://raw.githubusercontent.com/huggingface/speech-to-speech/main/logo.png" width="600"/>）：

• 补充素材（非 PNG/JPEG，按本节图片规则不嵌入正文，仅登记来源）：README 「How it works」上方的端点切换演示动图 docs/assets/endpoint-swap-light.gif（暗色模式 endpoint-swap-dark.gif），来源 https://raw.githubusercontent.com/huggingface/speech-to-speech/main/docs/assets/endpoint-swap-light.gif ，curl 200 已验证可访问。

08.3 环境要求