为什么要在本地跑 Qwen3-Coder
代码上云训练 / 上传 API 是国内企业团队的硬合规红线。本教程用 Ollama + Qwen3-Coder-30B-A3B + Continue 三个组件，30 分钟内搭一个”代码不出本机”的 AI 编程助手。Qwen3-Coder 30B 是阿里发布的 MoE 编码模型（30B 总参 / ~3B 激活），在 RTX 5090 / M3 Max 这类消费级硬件上即可流畅运行。
硬件要求
| 配置 | 可用度 | 说明 |
|---|---|---|
| ≥ 32GB 内存（统一内存） | ✅ 推荐 | M2/M3/M4 Max / 32GB+ 独显台式 |
| 24GB 独显 + 16GB 内存 | ⚠️ 可用 | 需降低 num_ctx，可能慢 |
| 16GB 内存 | ❌ 不推荐 | 改用 14B 或 7B 量化版 |
5 步落地
第 1 步：装 Ollama
macOS：
brew install ollama
Linux：
curl -fsSL https://ollama.com/install.sh | sh
验证：
ollama --version
第 2 步：拉模型
Qwen3-Coder 30B 官方 GGUF 约 19GB：
ollama pull qwen3-coder:30b
如果想要更高质量，可以拉 Unsloth 的动态量化版：
ollama run hf.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:UD-Q4_K_XL
验证：
ollama list
第 3 步：关键调整上下文窗口
坑点警告：Ollama 默认 num_ctx 是 2048，对 Agent 来说基本等于”瞎”。必须改大：
cat > ~/Modelfile.qwen3coder <<EOF
FROM qwen3-coder:30b
PARAMETER num_ctx 64000
PARAMETER num_gpu 99
EOF
ollama create qwen3coder-30b-long -f ~/Modelfile.qwen3coder
把 num_ctx 拉到 32768–64000 是最低要求，否则 Agent 读几个文件就触发上下文截断。
第 4 步：本地 API 起服
Ollama 默认监听 http://localhost:11434，并暴露 OpenAI 兼容端点 /v1。手动启动：
OLLAMA_CONTEXT_LENGTH=64000 ollama serve
验证 API：
curl http://localhost:11434/v1/models
第 5 步：接入 Continue / Cline
Continue（开源）为例，在 VS Code 安装 Continue 扩展后，编辑 ~/.continue/config.json：
{
"models": [
{
"title": "Qwen3-Coder 30B (Local)",
"provider": "ollama",
"model": "qwen3coder-30b-long",
"apiBase": "http://localhost:11434"
}
],
"tabAutocompleteModel": {
"title": "Qwen3-Coder 30B",
"provider": "ollama",
"model": "qwen3coder-30b-long"
}
}
重启 VS Code，打开 Continue 面板，选中代码段按 Cmd+L 即可让本地模型改写 / 解释。Agent 模式同样支持跨文件编辑。
常见坑
- 上下文截断：必须显式设置
num_ctx，默认 2048 基本不可用。 - 工具调用失败：用
llama.cpp时一定要加--jinja，否则 Agent 工具调用静默失败。 - 内存不足：将
num_gpu改为 0 可强制纯 CPU，速度会慢 5–10 倍但保证能跑。 - 速度慢：检查是否启用了 Metal / CUDA；macOS 上 Ollama 自动用 Metal，不需要额外配置。
FAQ
Q：完全断网能用吗？
可以。Ollama 一旦下载完模型权重就完全离线运行，不需要任何外网请求。
Q：30B 跑不过 Claude Sonnet 怎么办？
在简单补全上 Qwen3-Coder 30B 已经接近 Sonnet 4 水平，但长链推理 / 复杂架构设计仍弱于 Sonnet。生产场景建议”本地跑 80% 任务 + 云端兜底 20%”。
Q：Qwen3-Coder 有中文代码注释能力吗？
有，但生成的代码注释仍是英文为主。中文场景建议在系统 prompt 里明确指定”用中文写注释”。
行动建议
- 先小后大：第一次跑先用 7B / 14B 验证流水线，再切 30B 避免一开始就死磕硬件。
- 量化优先 Q5_K_M：32GB 显存下 Q5_K_M 是质量/体积甜点；Q4 体积小但质量掉 1–2%。
- 别忘了 num_ctx：90% 的”模型变笨”问题来自上下文窗口没拉满，不是模型本身的问题。
