Qwen3 系列（官方 GGUF 量化版）：阿里开源大模型本地一键部署｜部署与使用全指南

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。

项目定位与基本信息

官方图片

下图为 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）。

环境要求

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

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

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

依赖安装

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

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

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

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

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

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

RTX 4090 24GB 选型建议：

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

官方推荐采样参数（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 节）。

启动

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）。

使用方法

启动方式

命令行操作步骤（以 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                            # 退出会话

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

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

场景：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 文档）。

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

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+。

本节来源清单

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