1. 为什么要在本地跑 Qwen3-Coder vLLM Qwen Code如果你和我一样日常写代码离不开终端里的 AI 助手但又不想把公司内部代码片段发到公网模型上那这套组合值得认真搭一次Qwen3-Coder-30B-A3B-Instruct负责代码理解与生成vLLM把它变成标准 OpenAI 兼容接口Qwen Code作为终端里的编码 Agent 直接调用这个接口。整条链路跑通之后你的补全、重构、写测试、生成小页面这些动作全部走本地推理数据不出内网。Qwen Code 是通义千问团队推出的命令行编程助手交互形态和 Claude Code 类似支持/auth切换认证方式、支持 OpenAI 兼容协议所以它天然能对接 vLLM 暴露的/v1接口。Qwen3-Coder-30B-A3B-Instruct 是 MoE 架构总参数 30B、激活约 3B单机双卡就能跑起来推理速度对交互式编码来说够用。不过实际落地时有个绕不开的问题本地 vLLM 服务只在你那台机器上一旦你想在笔记本、公司另一台开发机、或者临时开的云主机上复用同一个模型通道就得自己处理 Key 分发、地址切换、多模型路由。我的做法是本地 vLLM 负责主力推理同时用TaoToken做统一 Key 与 API 通道管理把本地模型和云端模型收敛到一套配置里Qwen Code 只认一个OPENAI_BASE_URL换环境不用改代码。这篇就按「本地部署 → vLLM 起服务 → Qwen Code 接入 → TaoToken 统一 Key → 验证补全 → 排错」的顺序走一遍命令和配置都能直接复制。2. 环境准备与 TaoToken 统一 Key 前置先把依赖版本对齐版本错位是后面报错的主要来源。我实测下来这套组合比较稳组件版本说明Python3.10 / 3.113.12 部分 wheel 还没跟上torch2.6.0与 vLLM 0.8.4 匹配transformers4.51.3Qwen3-Coder 需要较新版本modelscope1.23.1下载模型用vllm0.8.4提供 OpenAI 兼容服务Node.js≥ 18Qwen Code 是 npm 包装依赖建议单独建虚拟环境避免和系统里的 torch 打架conda create -n qwen-coder python3.11 -y conda activate qwen-coder pip install torch2.6.0 transformers4.51.3 modelscope1.23.1 vllm0.8.4Node 侧只装一个全局包npm install -g qwen-code/qwen-codelatest接下来是 TaoToken 的部分。它的定位是统一 Key 与 API 通道你可以在控制台创建一把 Key用它访问模型对话、Coding Plan 等能力也可以把本地 vLLM 的地址登记进去做统一入口。对 Qwen Code 来说最终只需要一个 base URL 和一把 Key。先去控制台拿 Key入口在这里TaoToken 控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建 API Key 的页面API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到形如sk-xxxx的 Key 之后先存到环境变量里别硬编码进配置文件export TAOTOKEN_API_KEYsk-你的Key如果你只想先验证模型通道是否通可以直接用模型对话页面发一条消息模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite接入文档在接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite这一步做完你手里应该有两样东西本地 vLLM 即将暴露的http://127.0.0.1:8060/v1以及 TaoToken 的统一 Key。后面 Qwen Code 的配置就是把这两者串起来。3. 用 vLLM 部署 Qwen3-Coder-30B-A3B-Instruct3.1 下载模型权重用 modelscope 拉模型国内下载速度比直接从 HuggingFace 拉稳modelscope download \ --modelQwen/Qwen3-Coder-30B-A3B-Instruct \ --local_dir ./Qwen3-Coder-30B-A3B-Instruct下载完检查目录里有没有config.json、tokenizer.json和一堆.safetensors分片。如果只有配置文件没有权重多半是网络中断重跑一次即可。3.2 启动 vLLM 服务假设你有两张卡指定 0、1 号 GPUtensor parallel 设为 2export CUDA_VISIBLE_DEVICES0,1 vllm serve ./Qwen3-Coder-30B-A3B-Instruct \ --host 0.0.0.0 \ --port 8060 \ --dtype bfloat16 \ --tensor-parallel-size 2 \ --cpu-offload-gb 0 \ --gpu-memory-utilization 0.8 \ --max-model-len 65536 \ --api-key token-abc123 \ --enable-prefix-caching \ --enable-auto-tool-choice \ --tool-call-parser hermes \ --trust-remote-code关键参数逐个说清楚方便你按自己显存调--dtype bfloat16用 16 位浮点A100、A800、H800 这类卡原生支持精度和显存都合适老卡如果只支持 fp16改成float16。--tensor-parallel-size 2表示张量并行切 2 份建议和实际使用的 GPU 数量一致。单卡跑 30B MoE 显存会紧张双卡是常见起点。--cpu-offload-gb 0是往 CPU 内存卸载权重的开关单位 GB。显存不够时可以设成 8 或 16 救急但推理速度会明显下降交互式编码体验会变差能不加就不加。--gpu-memory-utilization 0.8限制 vLLM 最多用 80% 显存留一点给系统和其他进程。显存吃紧就往下调到 0.7。--max-model-len 65536是最大上下文长度越大占显存越多。Qwen3-Coder 支持长上下文但如果你只是做代码补全32768 也够能省不少显存。--enable-prefix-caching开启前缀缓存多轮对话里重复的系统提示词不用重算交互场景收益明显。--enable-auto-tool-choice配合--tool-call-parser hermes打开 function call 解析Qwen Code 的 Agent 能力依赖这个不开启的话工具调用会失败。启动过程会打印加载进度第一次加载权重比较慢耐心等到出现Uvicorn running on http://0.0.0.0:8060就说明服务起来了。3.3 显存不够时的调整顺序如果启动直接 OOM按这个顺序调先把--max-model-len从 65536 降到 32768还不行把--gpu-memory-utilization降到 0.7再不行才考虑--cpu-offload-gb 8。前两个对速度影响小最后一个影响大。4. Qwen Code 的 config.toml 与统一 Key 配置4.1 安装与首次进入前面已经全局装了 Qwen Code直接在项目目录下敲qwen第一次进入会提示你选择认证方式。按i进入插入模式输入/auth在列表里选 OpenAI 兼容方式然后填入 base URL 和 API Key。4.2 用 .env 管理本地模型在项目根目录建一个.env把本地 vLLM 的地址和 Key 写进去OPENAI_BASE_URLhttp://127.0.0.1:8060/v1 OPENAI_API_KEYtoken-abc123 OPENAI_MODELQwen3-Coder-30B-A3B-Instruct这里的token-abc123就是启动 vLLM 时--api-key指定的值两边必须一致。OPENAI_MODEL要和/v1/models返回的模型名完全对上差一个字符都会 404。4.3 config.toml 骨架Qwen Code 支持用config.toml做更细的控制放在~/.qwen/config.toml或项目级目录。一个可用的骨架长这样[model] name Qwen3-Coder-30B-A3B-Instruct provider openai [provider.openai] base_url http://127.0.0.1:8060/v1 api_key_env OPENAI_API_KEY model Qwen3-Coder-30B-A3B-Instruct timeout 120 [agent] auto_approve false max_turns 20api_key_env指向环境变量名这样 Key 不落盘。timeout给到 120 秒本地推理首 token 可能慢一些设太短会误判超时。auto_approve建议先保持 false每次文件修改都让你确认跑顺了再考虑放开。4.4 接入 TaoToken 统一通道如果你希望 Qwen Code 既能用本地模型又能在离开内网时切到 TaoToken 的统一通道可以把 base URL 换成 TaoToken 的 API 地址Key 换成控制台创建的那把[provider.openai] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model Qwen3-Coder-30B-A3B-Instruct timeout 120这样切换环境只需要改base_url一行或者用两个 profile 分别指向本地和 TaoToken。长期做编码和 Agent 任务的话Coding Plan 会更划算入口Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite如果你用的是 Claude Code 那套 Anthropic 协议TaoToken 也有对应通道ClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeanthropicutm_campaignrewrite5. 验证请求从 /v1/models 到一次代码补全5.1 确认服务活着先看模型列表curl http://127.0.0.1:8060/v1/models \ -H Authorization: Bearer token-abc123返回里应该能看到Qwen3-Coder-30B-A3B-Instruct。如果返回 401说明 Key 不对返回连接拒绝说明 vLLM 没起来或端口被占。5.2 发一条 chat 请求curl http://127.0.0.1:8060/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer token-abc123 \ -d { model: Qwen3-Coder-30B-A3B-Instruct, messages: [ {role: system, content: You are a helpful coding assistant.}, {role: user, content: 用 Python 写一个快速排序带注释} ], temperature: 0.2 }能拿到正常回复就说明推理链路通了。temperature设 0.2 是因为代码任务要稳定别让它自由发挥。5.3 在 Qwen Code 里做一次真实补全回到项目目录启动qwen输入一条具体指令比如在当前目录创建一个 utils/retry.py实现一个带指数退避的 retry 装饰器支持最大重试次数和异常类型参数Qwen Code 会先给出文件修改方案你确认后它写入文件。接着让它补测试为 utils/retry.py 写 pytest 测试覆盖成功、重试后成功、超过最大次数三种情况跑一下pytest如果测试通过说明从 vLLM 推理到 Qwen Code 工具调用整条链路都正常。这一步是判断环境是否真正可用的关键光看 curl 返回不够Agent 的工具调用才是完整验证。6. 本篇常见错排查启动 vLLM 报 CUDA out of memory。先降--max-model-len再降--gpu-memory-utilization最后才用--cpu-offload-gb。另外确认CUDA_VISIBLE_DEVICES指定的卡没有被其他进程占着nvidia-smi看一眼。/v1/models 返回 404。多半是 base URL 少了/v1或者模型名和启动时不一致。vLLM 的模型名默认取权重目录名用--served-model-name可以显式指定建议指定成和配置文件里一致的名字。Qwen Code 报 401 Unauthorized。检查.env里的OPENAI_API_KEY和 vLLM 的--api-key是否一致如果走 TaoToken检查TAOTOKEN_API_KEY是否导出到了当前 shellecho $TAOTOKEN_API_KEY确认一下。工具调用不生效Agent 只会聊天不改文件。确认启动参数带了--enable-auto-tool-choice和--tool-call-parser hermes这两个缺一不可。另外 Qwen Code 的auto_approve如果是 false每次修改都要你手动确认别以为是没反应。首 token 特别慢。检查是不是开了--cpu-offload-gb卸载到 CPU 的权重每次前向都要搬回 GPU延迟会成倍增加。另外--max-model-len设太大也会拖慢按实际需要调小。Qwen Code 连不上本地服务。如果 Qwen Code 跑在容器里127.0.0.1指向的是容器自身要换成宿主机的可达地址。vLLM 启动时--host 0.0.0.0已经允许外部访问问题通常出在地址写错。切换 TaoToken 后模型名对不上。TaoToken 通道下的模型名以接入文档为准别直接沿用本地权重目录名。文档地址在上面第 2 节给过配置前先对一遍。排障时如果怀疑是 Key 或通道问题最快的办法是去 API Keys 页面重新生成一把替换后重启 Qwen Code。接入细节以文档为准别凭记忆改参数。