教程2026年11月18日3,180 浏览约 7 分钟阅读

不用按Token付费!OpenCode+Ollama部署Qwen3-Coder

不想为AI编程助手持续支付API费用?教你用OpenCode、Ollama和Qwen3-Coder搭建本地编程环境,详解显卡要求、安装步骤、模型配置与常见故障排查。

不用按Token付费!OpenCode+Ollama部署Qwen3-Coder

一、这套组合为什么值得单独写一篇

本地部署 AI 编程助手,过去最大的阻力不是模型能力,而是工程链路太长。要自建推理服务、自己写 OpenAI 兼容层、自己维护客户端插件,任何一环版本不匹配就跑不起来。

OpenCode + Ollama + Qwen3-Coder 这套组合,把三段拼图各自补齐了:

  • OpenCode 是当前 GitHub 上 star 数达到 22.7 万的开源编程 Agent 项目,内置支持 200 多个模型提供商,模型切换只改一个配置字段。
  • Ollama 承担本地运行时,负责权重下载、显存调度与服务暴露,对外提供 OpenAI 兼容的 /v1 接口。累计下载量已超过 10 亿次。
  • Qwen3-Coder 是阿里千问团队面向代码场景训练的模型系列,在 Ollama 上的下载量已突破 1100 万次。30B 版本采用 MoE 架构,激活参数 3.3B,上下文窗口 256K。

三者拼在一起的意义在于:代码不出本机。除了 Ollama 拉取权重那一次外网请求,后续所有推理都发生在本地环路,不经过任何第三方 API。数据合规要求严格的团队、内网隔离环境、或者单纯不想为每次补全付 token 费的个人开发者,都能直接受益。

完整链路搭建时间大约 15 分钟,前提是硬件达标。

二、架构分层与数据流向

整条链路分三层,从上到下依次是客户端、运行时、模型。

层级组件职责关键参数
客户端OpenCode编程 Agent 界面、上下文收集、工具调用200+ 模型提供商内置
运行时Ollama权重管理、显存调度、OpenAI 兼容 API默认监听 127.0.0.1:11434
模型Qwen3-Coder 30B代码生成与补全推理256K 上下文、激活 3.3B、显存 19GB

数据流向清晰:OpenCode 读取项目文件、构造提示、通过 HTTP 调用本地 Ollama 的 /v1/chat/completions 接口,Ollama 加载模型完成推理并返回结果。中间没有任何外部网络跳出。

这也是这套方案与云端 API 的核心差异:延迟由本地显存带宽和 GPU 算力决定,不受公网链路影响;成本固定为电费和硬件折旧,不随调用量线性增长。

三、硬件门槛与模型选型

选型表先给出,再解释判断逻辑。

模型显存占用上下文激活参数适用场景
qwen3-coder:30b19GB256K3.3B(MoE)桌面级 GPU 日常开发
qwen3-coder:480b290GB256K—多卡服务器、NAS 集群
qwen2.5-coder:7b4.7GB32K—8GB 内存老机器
qwen2.5-coder:14b9.0GB32K—16GB 内存办公本

判断规则很简单:

  • 显存 24GB 及以上(例如 RTX 4090、RTX 3090),直接上 qwen3-coder:30b,这是本文主推配置。
  • 内存 20GB 左右的老机器,先用 qwen2.5-coder:7b,4.7GB 显存、32K 上下文足够覆盖单文件级别的补全和重构。qwen2.5-coder 系列在 Ollama 上的累计下载量已超过 2380 万次,社区排错资料最丰富。
  • 16GB 内存的办公本,用 qwen2.5-coder:14b,9.0GB 占用仍有余量。
  • 多卡服务器或 NAS 集群才考虑 480B,单机桌面场景不现实。

苹果平台另有一条路径。MLX 框架在 2026 年 11 月 9 日的版本中已对 Apple Silicon 做了推理优化,Qwen3-Coder 在 M 系列统一内存上的占用可压到约 27GB,相比通用路径有明显下降。这意味着 32GB 统一内存的 Mac 可以跑起 30B 版本,不必依赖 NVIDIA 显卡。

需要强调的是:显存占用和上下文长度是两个独立约束。30B 版本标称 256K 上下文,但实际能稳定用满多少,取决于推理框架的 KV Cache 实现、批处理策略和并发规模。选型时按显存先卡住,再实测长上下文表现,不要反过来用标称参数去推硬件。

四、五步落地流程

第一步:安装 Ollama

macOS 与 Linux 用官方脚本:

curl -fsSL [https://ollama.com/install.sh](https://ollama.com/install.sh) | sh

macOS 也可以用 Homebrew:

brew install ollama

安装完成后启动服务:

ollama serve

验证服务是否正常:

curl [http://127.0.0.1:11434/api/tags](http://127.0.0.1:11434/api/tags)

返回 JSON 列表即表示运行时已就绪。如果这一步失败,后面所有环节都不必继续,先解决端口监听问题。

第二步:拉取模型

# 主力模型,30B,显存 19GB
ollama pull qwen3-coder:30b

# 老机器备选 7B
ollama pull qwen2.5-coder:7b

# 办公本备选 14B
ollama pull qwen2.5-coder:14b

拉取完成后做一次冒烟测试:

ollama run qwen3-coder:30b "用 Python 写一个每秒打印一次 Hello World 的脚本"

能正常返回代码,说明模型加载、显存分配、推理链路三项全部通过。这一步比在 OpenCode 里试要快得多,出错时定位也更直接。

第三步:安装 OpenCode

三种安装方式按平台选择:

# 通用脚本
curl -fsSL [https://opencode.ai/install](https://opencode.ai/install) | bash

# npm
npm i -g opencode-ai@latest

# Homebrew
brew install sst/tap/opencodeß

验证:

opencode --version

第四步:配置本地模型

OpenCode 会自动发现本地运行的 Ollama 实例,但项目级配置需要显式声明模型标识。在项目根目录创建 opencode.jsonc:

{
  "$schema": "[https://opencode.ai/config.json](https://opencode.ai/config.json)",
  "model": "ollama/qwen3-coder:30b"
}

模型 ID 的格式规则是 ollama/<模型名>:<标签>。几个常见写法:

// 7B 版本
"model": "ollama/qwen2.5-coder:7b"

// 14B 版本
"model": "ollama/qwen2.5-coder:14b"

如果 Ollama 不在默认地址,或者跑在远程机器上,需要补充 provider 配置:

{
  "$schema": "[https://opencode.ai/config.json](https://opencode.ai/config.json)",
  "model": "ollama/qwen3-coder:30b",
  "provider": {
    "ollama": {
      "options": {
        "baseURL": "[http://192.168.1.100:11434/v1](http://192.168.1.100:11434/v1)"
      }
    }
  }
}

本机默认监听地址不需要写 apiKey,Ollama 侧不做鉴权。

第五步:在项目里跑起来

进入项目目录直接启动:

cd /your-project
opencode

OpenCode 会读取当前目录的 opencode.jsonc,把请求路由到本地 Ollama。

如果只想跑一次性的代码任务,不改配置文件:

opencode run --model ollama/qwen3-coder:30b --agent build "帮我写一个分页查询工具函数 paginate_users"

这条命令适合验证链路是否打通,也适合集成到 CI 里做离线代码生成。

五、几个容易踩的细节

OpenCode 显示无法连接模型,但 `ollama serve` 明明在跑。 先确认端口:curl [http://127.0.0.1:11434/api/tags](http://127.0.0.1:11434/api/tags)。返回空白或报错,说明服务实际没有监听。macOS 上如果任务栏里有 Ollama 应用图标,它可能已经在后台接管了服务生命周期,手动再起一个 ollama serve 反而会冲突。

`qwen3-coder:30b` 下载很慢。 Ollama 的权重缓存目录在 ~/.ollama/models(Linux 下为 /root/.ollama/models),权限受限时可改 OLLAMA_MODELS 环境变量指向其他路径。下载支持断点续传,中断后重新执行 ollama pull 会从断点继续,不会重头开始。国内网络环境下,如果长时间停滞,先确认 Hugging Face 侧镜像是否可达,再考虑配置代理。

30B 跑起来了,但上下文一长就卡。 这是显存被 KV Cache 吃满的典型表现。降低并发数、缩短单次输入、或者改用更激进的量化版本都能缓解。不要指望标称的 256K 在 24GB 卡上全量可用。

六、本地与云端的成本边界

这套方案的经济性有明确适用范围,越过边界后反而不划算。

本地模型够用的任务: 单文件函数补全、单元测试改写、命名与格式规范化、小范围 bugfix、文档注释生成。30B 版本在这些任务上与云端旗舰模型的差距不明显,而边际成本为零。

建议切换云端的任务: 跨仓库的多步重构、需要长链条推理的复杂缺陷定位、依赖大规模检索的任务拆解、以及输出质量直接关联商业结果的高价值代码。这类任务上模型能力差距会明显拉开,本地模型额外消耗的时间和返工次数,比 token 费用更贵。

一条实用的判断规则:如果本地模型已经稳定承接了约 80% 的日常任务,剩下的 20% 就应该接云端 API,而不是继续加硬件。此时工程上的重点是让本地与云端共用一套调用抽象,避免切换时改动业务代码。koalaapi 作为 API 网关,可以统一管理多家模型的接入与路由,让本地 Ollama 与云端模型在同一条调用链上共存,按任务类型分流而不必重写客户端。

七、结语

这套组合的核心价值不在"免费",而在"可控"。硬件是可预期的固定投入,模型是可替换的模块,数据不出本机。三件事叠在一起,才让本地部署从实验性方案变成可长期运行的工程选择。

选型上按显存卡第一道门槛:24GB 以上直接上 qwen3-coder:30b,20GB 以下从 qwen2.5-coder:7b 起步。配置上守住一个原则:模型标识集中在 opencode.jsonc 里维护,不要散落在命令行和历史脚本中。这样换模型时只改一行,验证链路时也只改一行。

对多数个人开发者和小团队,这套本地栈足以覆盖日常编程任务的绝大部分。真正需要云端算力的场景,用网关做按需分流,比一次性堆满本地硬件更务实。

标签OpenCodeOllamaQwen3-CoderQwen2.5-Coder本地大模型本地AIAI编程助手AI编程Agent私有化部署
Koala API · 一站式大模型 API 中转

把博客读到的,落地到你的下一个项目

国内直连 · 兼容 OpenAI SDK · GPT / Claude / Gemini 等主流模型聚合

延伸阅读

免费注册