1. 项目概述为什么一个本地大模型部署教程值得花三小时读完我最近把 Qwen3.5-9B 稳稳当当地跑在了自己那台双卡 4090 的工作站上不是为了发论文也不是为了搭 Demo 给老板看而是为了每天写代码时少点“CtrlC / CtrlV”、少点翻文档、少点对着报错信息发呆。你可能也试过用 Ollama 拉个 Qwen2结果一问复杂逻辑就卡死或者用 vLLM 启动发现上下文刚撑到 32K 就开始 OOM又或者好不容易跑起来了想塞进 VS Code 插件里却发现接口协议对不上——不是缺/v1/chat/completions就是tool_calls字段解析失败。这些坑我都踩过而且是连续踩了五次直到把日志翻烂、把 sglang 源码扒开看了三层、把 Claude Code 的启动流程反向追踪了两遍才真正理清楚本地部署不是“能跑就行”而是要“跑得稳、接得上、改得动、查得清”。这篇教程不讲虚的不堆参数不画架构图只说我在真实开发场景中验证过的每一步为什么--mem-fraction-static 0.85是 9B 模型在单卡 24G 显存如 4090上的黄金值为什么--reasoning-parser qwen3和--tool-call-parser qwen3_coder这两个参数必须同时出现缺一个 Claude Code 就会静默失败为什么ANTHROPIC_MODEL字段填qwen3.5-91b故意写错反而比填对更安全这些细节官方文档不会写GitHub Issues 里散落着几十条相互矛盾的回复而我要做的就是把它们全部串起来变成你打开终端就能复制粘贴、出错就能立刻定位的实操路径。它适合三类人正在为本地代码助手找稳定底座的开发者、需要复现 Qwen3.5 推理链路的技术负责人、以及刚买完显卡想亲手把大模型“焊”在自己机器上的硬核玩家。核心关键词只有一个claude-code——因为这不是一个通用大模型部署教程而是一份专为让 Claude Code 这个工具真正“认出”并“用好”Qwen3.5 而写的生存指南。2. 整体设计思路与方案选型深度拆解2.1 为什么放弃 vLLM坚定选择 sglang不只是“社区风向”的问题很多人看到“sglang 火了”就跟着切但实际落地时才发现vLLM 和 sglang 的底层哲学完全不同。vLLM 是一个极致优化的推理引擎Inference Engine它的强项是吞吐量和长文本生成速度比如批量跑评测、做离线摘要。而 sglang 是一个系统级编程框架System-level Programming Framework它把模型服务、函数调用、推理状态管理、甚至前端交互协议都打包成可编程的原语。这直接决定了它和 Claude Code 的适配性。Claude Code 的底层通信协议本质是 Anthropic 的messages格式 tool_use扩展。它发送的请求里tools是一个 JSON Schema 数组tool_choice是一个明确指定调用哪个 tool 的对象返回的content里必须包含tool_use类型的 message 块并且id字段要严格匹配。vLLM 默认只支持 OpenAI 风格的function_call即使你强行 patch 它的chat_template也无法处理tool_use的嵌套结构和状态流转。而 sglang 原生内置了reasoning-parser和tool-call-parser两大解析器插槽你可以把 Qwen3.5 的 tokenizer、output post-processing、tool call 提取逻辑全部注入进去。我实测过用 vLLM 加自定义 template 启动 Qwen3.5-9B向 Claude Code 发送一个带os.listdir工具的请求返回的永远是纯文本tool_use字段根本不会出现换成 sglang 启动加上--reasoning-parser qwen3 --tool-call-parser qwen3_coder同一请求返回的 content 中type: tool_use的 message 块完整、name和input字段精准Claude Code 拿到后能立刻执行工具整个链路丝滑得像开了挂。提示不要被“sglang 支持 vLLM backend”误导。那只是 sglang 可以调用 vLLM 做底层计算但 parser 层、state manager 层、API 协议层全都是 sglang 自己的。你真正依赖的是 sglang 的协议栈而不是它的计算内核。2.2 为什么必须引入 LiteLLM 做一层转发Claude Code 的“协议洁癖”Claude Code 是个“协议洁癖”。它只认 Anthropic 官方 SDK 定义的那套 URL 路径、Header 规则、JSON 字段名。它发请求时POST /v1/messages是铁律x-api-key必须存在anthropic-versionheader 必须是2023-06-01。而 sglang 的原生 API默认走的是/generate旧版或/v1/chat/completionsOpenAI 兼容模式压根没有/v1/messages这个 endpoint。你强行把ANTHROPIC_BASE_URL指向 sglang 的 8000 端口Claude Code 启动时就会报404 Not Found连握手都失败。LiteLLM 在这里扮演的是一个“协议翻译官”的角色。它不碰模型不碰 GPU只做一件事把 Claude Code 发来的 Anthropic 协议请求实时翻译成 sglang 能听懂的 OpenAI 协议请求再把 sglang 返回的 OpenAI 格式响应翻译回 Anthropic 格式原封不动塞给 Claude Code。这个过程是零延迟的因为 LiteLLM 本身是纯 Python 实现没有额外的模型加载或 tokenization 开销。我用time curl对比过直连 sglang需修改 Claude Code 源码耗时 127ms经 LiteLLM 转发耗时 132ms多出的 5ms 就是两次 JSON 序列化/反序列化的开销完全可以忽略。更重要的是LiteLLM 的配置极其灵活。你可以在lite_llm.yaml里定义model_name: claude-3-5-sonnet-20241022然后在 Claude Code 的 settings.json 里写ANTHROPIC_MODEL: claude-3-5-sonnet-202410241022它会自动映射到你后端真实的qwen3.5-9b模型。这意味着你完全可以用 Claude Code 的 UI享受 Qwen3.5 的能力而所有“欺骗”都在 LiteLLM 这一层完成干净、安全、可逆。2.3 Docker 镜像选型blackwell 不是“开箱即用”而是“开箱即调”看到lmsysorg/sglang:blackwell这个镜像名第一反应是“哇官方维护肯定最稳”。但实际拉下来一跑ImportError: cannot import name Qwen3ForCausalLM from transformers直接报错。原因很现实blackwell 镜像是为 LMSYS 的 Arena 平台定制的它冻结了transformers4.44.0而 Qwen3.5 的 Hugging Face 官方实现要求transformers4.46.0。这不是 bug是版本策略的必然冲突。所以Docker 方案的本质不是“拿来就用”而是“拿来就调”。blackwell镜像的价值在于它已经预装好了 CUDA 12.4、Triton 3.0.0、PyTorch 2.4.0 这些底层硬核依赖省去了你在裸机上编译 Triton 的数小时痛苦。你只需要在这个坚实的基础上做最小化的升级pip install --upgrade transformers --break-system-packages。注意--break-system-packages是必须加的因为镜像里用的是apt安装的python3-pip默认禁止覆盖系统包。不加这个 flag你会卡在权限错误上。我试过用--user安装结果 sglang 启动时找不到新版本的 transformers因为sys.path里系统路径在前。这个细节官方文档没写但它是 Docker 方案能否跑通的生死线。3. 核心细节解析与实操要点从命令行到生产环境的每一处关键3.1 sglang 启动命令的逐参数精解不是照抄而是理解每个数字背后的显存博弈下面这条命令是我经过 17 次不同参数组合测试后为单卡 RTX 409024G 显存 Qwen3.5-9B 找到的最优解.venv/bin/python -m sglang.launch_server \ --model-path Qwen/Qwen3.5-9B \ --served-model-name qwen3.5-9b \ --host 0.0.0.0 \ --port 8000 \ --tp-size 1 \ --mem-fraction-static 0.85 \ --context-length 131072 \ --reasoning-parser qwen3 \ --tool-call-parser qwen3_coder \ --attention-backend triton \ --chunked-prefill-size 1024 \ --triton-attention-num-kv-splits 8 \ --enable-tokenizer-batch-encode \ --enable-metrics \ --disable-flashinfer我们来逐个拆解重点说清“为什么是这个值”--mem-fraction-static 0.85这是最常被误用的参数。很多人以为这是“显存占用率”其实它是静态 KV Cache 分配比例。sglang 启动时会按这个比例预先为 KV Cache 分配显存。Qwen3.5-9B 的 full precisionbf16权重约 18GBKV Cache 的理论峰值128K context需要约 9GB。如果你设成0.95它会尝试分配 22.8GB 的 KV Cache但你的显存只有 24GB剩下的 1.2GB 不够放模型权重和中间激活值直接 OOM。0.85意味着预留 20.4GB 给 KV Cache实际使用中它会根据 batch size 和 sequence length 动态调整但上限被锁死避免突发 OOM。我实测0.85下单请求 128K context 稳定batch_size4 时 32K context 也无压力。--context-length 131072Qwen3.5 官方支持 128K但 sglang 的--context-length参数必须是 2 的幂次方且要大于等于模型 config 中的max_position_embeddings。Qwen3.5 的 config 是131072所以这里不能填128000或128K必须是131072。填错会导致启动时报ValueError: context_length must be max_position_embeddings。--reasoning-parser qwen3和--tool-call-parser qwen3_coder这是 Claude Code 能用起来的命门。qwen3parser 负责解析模型输出中的|reserved_special_token_1|即 reasoning start token和|eot_id|end of turn确保reasoning内容被正确截取。qwen3_coderparser 则专门识别tool_useblock它会扫描输出文本匹配正则r\|tool_code\|(.*?)\|eot_id\|并提取name和input字段。这两个 parser 必须同时启用否则 Claude Code 收到的 response 里content数组里全是texttype没有tool_use工具调用功能彻底失效。--triton-attention-num-kv-splits 8这是针对 Triton attention 的关键调优。RTX 4090 的 GPU 架构是 Ada Lovelace其 shared memory 大小为 164KB。num-kv-splits控制 KV Cache 分块计算的粒度。设为8意味着每次计算只加载 1/8 的 KV大幅降低 shared memory 压力。我对比过4、8、164时128K context 下显存占用飙升延迟增加 40%16时计算碎片化严重GPU 利用率掉到 60%8是吞吐和显存的完美平衡点。--disable-flashinfer必须加。FlashInfer 是一个高性能 attention 库但它和 Qwen3.5 的rope_theta参数有兼容性问题。不加这个 flag启动时会报RuntimeError: rope_theta mismatch因为 FlashInfer 会强制重写 RoPE 的 base frequency而 Qwen3.5 的 tokenizer 依赖原始值。Triton backend 更“老实”完全尊重模型 config所以这里主动禁用 FlashInfer拥抱 Triton。3.2 Claude Code 配置文件的致命陷阱ANTHROPIC_MODEL字段的“假名”哲学Claude Code 的~/.claude/settings.json文件表面看是个标准 JSON但它的字段校验逻辑非常特殊。最关键的陷阱在ANTHROPIC_MODEL{ env: { ANTHROPIC_BASE_URL: http://192.168.3.27:4000, ANTHROPIC_AUTH_TOKEN: sk-local, ANTHROPIC_MODEL: qwen3.5-91b, ANTHROPIC_DEFAULT_HAIKU_MODEL: qwen3.5-91b, ANTHROPIC_DEFAULT_OPUS_MODEL: qwen3.5-91b, ANTHROPIC_DEFAULT_SONNET_MODEL: qwen3.5-91b, ANTHROPIC_REASONING_MODEL: qwen3.5-91b } }注意qwen3.5-91b是个彻头彻尾的“假名”。它和你后端 sglang 的--served-model-name qwen3.5-9b完全不一致甚至91b这个型号根本不存在。为什么可以这样写因为 Claude Code 的源码里ANTHROPIC_MODEL字段只用于 UI 显示和日志记录不参与任何路由或协议协商。它真正的路由依据只有两个ANTHROPIC_BASE_URL决定发往哪个 IP:PORT和ANTHROPIC_AUTH_TOKEN决定用哪个 API key。只要 LiteLLM 的lite_llm.yaml里model_name: claude-3-5-sonnet-20241022这个名字和你在 settings.json 里写的ANTHROPIC_MODEL字符串完全一致LiteLLM 就能找到对应的后端配置。提示这就是为什么我建议你把ANTHROPIC_MODEL写成一个明显错误的名字如qwen3.5-91b。一旦你把它写成qwen3.5-9b而 LiteLLM 配置里写的是claude-3-5-sonnet-20241022两者不匹配LiteLLM 会 fallback 到默认模型导致请求失败而错误日志里只会显示Model not found根本看不出是名字没对上。用一个“假名”能让你一眼就意识到“哦这只是个占位符真正的绑定在 LiteLLM 那边”。3.3 LiteLLM 配置的隐藏规则drop_params: false是工具调用的生命线LiteLLM 的lite_llm.yaml配置看着简单但drop_params: false这个开关是决定工具调用能否成功的关键model_list: - model_name: claude-3-5-sonnet-20241022 litellm_params: model: openai/qwen3.5-9b api_base: http://127.0.0.1:8000/v1 api_key: sk-local litellm_settings: drop_params: falseClaude Code 发送的请求里tools和tool_choice是两个顶级字段。而标准的 OpenAI/v1/chat/completions接口根本不认识这两个字段。如果drop_params: true这是 LiteLLM 的默认值LiteLLM 会在转发前把所有它不认识的字段包括tools和tool_choice全部丢弃然后把一个“干净”的、只有messages和model的请求发给 sglang。sglang 收到后当然不会做工具调用因为它根本没看到tools。drop_params: false的作用就是告诉 LiteLLM“别管你认不认识把所有字段原封不动地透传过去”。这样tools和tool_choice就能完整抵达 sglangsglang 的qwen3_coderparser 才有机会工作。我曾经因为漏掉这一行调试了整整一个下午日志里看到 LiteLLM 收到了tools但 sglang 的 access log 里却只有messages百思不得其解最后翻 LiteLLM 源码才找到这个隐藏开关。4. 实操过程与核心环节实现手把手带你从零构建可工作的本地代码助手4.1 环境准备Python、CUDA、依赖包的精确版本锁定在开始任何部署前必须建立一个纯净、可复现的 Python 环境。我强烈建议放弃系统 Python全程使用pyenvvenv# 1. 安装 pyenvmacOS brew update brew install pyenv # 2. 安装 Python 3.12.7必须是 3.12.x3.13 的某些 C API 变更会导致 sglang 编译失败 pyenv install 3.12.7 pyenv global 3.12.7 # 3. 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # 4. 升级 pip确保能安装最新 wheel pip install --upgrade pip # 5. 安装 CUDA 12.4 ToolkitUbuntu 22.04 wget https://developer.download.nvidia.com/compute/cuda/12.4.1/local_installers/cuda_12.4.1_535.86.10_linux.run sudo sh cuda_12.4.1_535.86.10_linux.run --silent --override # 6. 验证 CUDA nvcc --version # 应输出 12.4.1 nvidia-smi # 应显示 GPU 状态依赖包的安装绝不能pip install sglang了事。sglang 的pyproject.toml里requires-python 3.10,3.13且dependencies列表明确指定了torch2.3.0,2.5.0和transformers4.46.0。我实测过用pip install sglang会拉取一个旧版 wheel里面绑定了transformers4.44.0直接导致 Qwen3.5 加载失败。正确做法是# 1. 克隆 sglang 官方仓库确保获取最新 master git clone https://github.com/sgl-project/sglang.git cd sglang # 2. 安装时指定 --no-deps先清空依赖 pip install --no-deps -e . # 3. 手动安装精确版本的依赖这才是关键 pip install torch2.4.0cu124 torchvision0.19.0cu124 --index-url https://download.pytorch.org/whl/cu124 pip install transformers4.46.3 pip install sentencepiece0.2.0 pip install tiktoken0.7.0注意torch2.4.0cu124这个版本字符串里的cu124是必须的它表示 CUDA 12.4 编译版。如果只写torch2.4.0pip 会安装 CPU 版后续 sglang 启动时会报CUDA not available。4.2 sglang 服务启动与健康检查如何确认服务真的“活”了启动命令执行后终端会输出大量日志。不要只盯着最后一行INFO: Uvicorn running on http://0.0.0.0:8000就认为成功了。你需要做三步健康检查第一步检查模型加载日志滚动日志找到类似这样的几行INFO:root:Loading model from Qwen/Qwen3.5-9B... INFO:root:Using Triton attention backend. INFO:root:Loaded model in 12.4s, using 18.2 GB VRAM. INFO:root:KV cache will use up to 20.4 GB VRAM (85% of total).如果看到Loaded model in X.Xs且VRAM数字合理18-20GB说明模型加载成功。如果卡在Loading model...超过 60 秒大概率是transformers版本不对或者model-path指向了一个损坏的模型目录。第二步用 curl 发送最简请求新开一个终端执行curl -X POST http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-local \ -d { model: qwen3.5-9b, messages: [{role: user, content: Hello}], max_tokens: 10 }预期返回是一个 JSONchoices[0].message.content字段里有Hello或类似回应。如果返回{error: {message: Not Found, ...}}说明你访问的是/v1/chat/completions但 sglang 默认没开这个 endpoint。此时你需要确认启动命令里是否加了--enable-openai-compatible新版 sglang 已默认开启老版本需手动加。第三步检查 metrics endpoint最可靠的指标sglang 的--enable-metrics会暴露一个 Prometheus metrics endpointcurl http://127.0.0.1:8000/metrics | grep sglang_request_success你应该能看到类似sglang_request_success_total{modelqwen3.5-9b,status200} 1.0的行。这个1.0表示已经有 1 个成功的请求被记录。这是服务真正“活”着的铁证比任何日志都可靠。4.3 LiteLLM 服务启动与协议桥接验证LiteLLM 的启动同样需要精确的配置和验证# 1. 安装 LiteLLM必须带 proxy否则没有 server 功能 pip install -U litellm[proxy] # 2. 创建 lite_llm.yaml注意缩进YAML 对空格极其敏感 cat lite_llm.yaml EOF model_list: - model_name: claude-3-5-sonnet-20241022 litellm_params: model: openai/qwen3.5-9b api_base: http://127.0.0.1:8000/v1 api_key: sk-local litellm_settings: drop_params: false EOF # 3. 启动 LiteLLM-d 参数开启 debug 日志排错必备 litellm --config lite_llm.yaml --port 4000 -d启动后LiteLLM 会输出INFO: Uvicorn running on http://127.0.0.1:4000。此时用 curl 模拟 Claude Code 的请求curl -X POST http://127.0.0.1:4000/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-local \ -H anthropic-version: 2023-06-01 \ -d { model: claude-3-5-sonnet-20241022, messages: [{role: user, content: Hello}], max_tokens: 10 }如果返回{error: {message: Model claude-3-5-sonnet-20241022 not found}}说明model_name在 yaml 里写错了或者curl里的model字段和 yaml 里的model_name不一致。如果返回一个正常的 JSON且content数组里有texttype 的 message说明桥接成功。此时你就可以放心去改~/.claude/settings.json了。4.4 Docker 部署全流程从拉取镜像到生成可复用的自定义镜像Docker 部署的目标是生成一个sglang-qwen35:latest镜像它可以直接docker run启动无需任何额外操作# 1. 拉取官方 blackwell 镜像 docker pull lmsysorg/sglang:blackwell # 2. 启动一个临时容器进行升级 docker run -it --rm --gpus all lmsysorg/sglang:blackwell /bin/bash # 3. 在容器内执行注意必须在 root 权限下 pip3 install --upgrade transformers4.46.3 --break-system-packages pip3 install --upgrade torch2.4.0cu124 torchvision0.19.0cu124 --index-url https://download.pytorch.org/whl/cu124 # 4. 退出容器exit然后查看容器 ID docker ps -a | head -2 # 5. 将修改后的容器保存为新镜像假设容器 ID 是 abc123 docker commit abc123 sglang-qwen35:latest # 6. 验证新镜像运行一个测试命令 docker run --rm --gpus all sglang-qwen35:latest python -c from transformers import AutoModel; print(OK)如果最后一步输出OK说明新镜像里的transformers和torch都已正确升级。接下来就可以用这个镜像启动 sglang 服务了# 创建一个启动脚本 start_sglang.sh cat start_sglang.sh EOF #!/bin/bash python -m sglang.launch_server \ --model-path /models/Qwen3.5-9B \ --served-model-name qwen3.5-9b \ --host 0.0.0.0 \ --port 8000 \ --tp-size 1 \ --mem-fraction-static 0.85 \ --context-length 131072 \ --reasoning-parser qwen3 \ --tool-call-parser qwen3_coder \ --attention-backend triton \ --chunked-prefill-size 1024 \ --triton-attention-num-kv-splits 8 \ --enable-tokenizer-batch-encode \ --enable-metrics \ --disable-flashinfer EOF # 构建最终的生产镜像Dockerfile cat Dockerfile EOF FROM sglang-qwen35:latest COPY start_sglang.sh /start_sglang.sh RUN chmod x /start_sglang.sh CMD [/start_sglang.sh] EOF # 构建 docker build -t sglang-qwen35-prod:latest . # 运行假设模型文件在 ./models/Qwen3.5-9B docker run -d --name qwen35-server --gpus all -p 8000:8000 -v $(pwd)/models:/models sglang-qwen35-prod:latest这个sglang-qwen35-prod:latest镜像就是你可以分享给同事、部署到服务器、甚至做成 CI/CD 流水线产物的终极形态。5. 常见问题与排查技巧实录那些让我凌晨三点还在看日志的坑5.1 问题速查表高频故障现象、原因与一键修复现象根本原因修复命令/步骤验证方式ImportError: cannot import name Qwen3ForCausalLMtransformers版本过低4.46.0pip install --upgrade transformers4.46.3python -c from transformers import Qwen3ForCausalLM; print(OK)sglang 启动后curl/v1/chat/completions返回404未启用 OpenAI 兼容模式在启动命令中添加--enable-openai-compatiblecurl http://127.0.0.1:8000/docs应打开 Swagger UIClaude Code 启动报Connection refusedANTHROPIC_BASE_URL的 IP 地址错误将192.168.3.27改为127.0.0.1本机或宿主机真实 IPping 127.0.0.1和telnet 127.0.0.1 4000LiteLLM 启动后curl/v1/messages返回Model not foundlite_llm.yaml中model_name与 curl 请求中的model字段不一致检查 yaml 缩进确保model_name: claude-3-5-sonnet-20241022顶格且 curl 中model值完全相同litellm --config lite_llm.yaml --print-config查看解析后的配置sglang 启动时卡在Loading model...超过 2 分钟模型文件损坏或model-path指向空目录ls -la Qwen/Qwen3.5-9B/确认存在config.json,pytorch_model.bin.index.json,tokenizer.model等文件huggingface-cli scan-cache检查缓存完整性5.2 “静默失败”类问题的独家排查法日志分层过滤术很多问题比如工具调用不触发、reasoning 内容被截断表现出来就是“没反应”没有任何报错。这时你需要一套分层的日志过滤法第一层Claude Code 的 debug 日志启动 Claude Code 时加上--log-level debugclaude-code --log-level debug然后在它的日志里搜索Sending request to和Received response from。如果只看到前者没看到后者说明请求根本没发出去问题在 network 或 DNS。第二层LiteLLM 的 debug 日志启动 LiteLLM 时加上-d参数然后在日志里搜索Proxy: Received request for model和Proxy: Forwarding request to。如果只看到前者说明 LiteLLM 收到了请求但没转发出去问题在api_base或api_key配置。第三层sglang 的 access logsglang 默认会打印每条请求的 access log格式为INFO: 127.0.0.1:XXXXX - POST /v1/chat/completions HTTP/1.1 200 OK。如果这里完全没日志说明 LiteLLM 的api_base指向了一个错误的地址比如http://localhost:8000而 sglang 绑定的是0.0.0.0。第四层sglang 的 model output log在 sglang 启动命令中加上--log-level DEBUG然后搜索Generated text:。如果这里输出的文本里|tool_code|和|eot_id|标签是完整的但 LiteLLM 的日志里却显示content: [{type: text, text: ...}]那问题一定出在--tool-call-parser qwen3_coder没生效或者 LiteLLM 的drop_params: false没配置。这套四层过滤法能帮你把一个模糊的“没反应”精准定位到是网络层、代理层、模型层还是 parser 层的问题效率提升十倍。