1. 项目概述:本地部署Qwen3.5-9B的核心价值
最近在折腾大模型本地部署时,发现Sglang这个新晋推理框架确实给力。相比传统的vLLM方案,它在处理超长上下文(128K)和工具调用场景下表现更稳定。这次要分享的是用Sglang部署Qwen3.5-9B模型,并接入Claude Code开发环境的完整流程。
这个方案特别适合两类开发者:
- 需要离线运行代码辅助工具的安全敏感场景
- 希望深度定制模型推理参数的技术团队
实测在RTX 5090(32G显存)上,9B模型推理速度能达到28 token/s,显存占用稳定在28GB左右。下面我会从环境准备到问题排查,把整个部署过程拆解成可复现的步骤。
2. 环境准备与硬件选型
2.1 硬件配置要求
最低配置:
- GPU:NVIDIA RTX 4090(24G显存)
- 内存:64GB DDR5
- 存储:至少50GB可用空间(建议NVMe SSD)
推荐配置:
- GPU:RTX 5090(32G显存)
- 内存:128GB DDR5
- 存储:1TB NVMe SSD
重要提示:实测9B模型在24G显存卡上会出现OOM,建议预留至少10%显存余量
2.2 软件依赖清单
必须组件:
- Python 3.12+(建议用conda管理)
- CUDA 12.8
- cuDNN 8.9+
- Sglang 0.3.0+
验证环境是否就绪:
bash复制nvidia-smi # 确认驱动版本≥535
python -c "import torch; print(torch.cuda.is_available())" # 应输出True
3. Sglang服务部署详解
3.1 模型下载与准备
推荐使用modelscope加速下载:
bash复制pip install modelscope
python -c "from modelscope import snapshot_download; snapshot_download('qwen/Qwen3.5-9B')"
模型会下载到~/.cache/modelscope/qwen/Qwen3.5-9B
3.2 启动参数深度解析
这是经过调优的启动命令:
bash复制export SGLANG_DISABLE_CUDNN_CHECK=1
python -m sglang.launch_server \
--model-path ~/.cache/modelscope/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 \
--kv-cache-dtype bf16 \
--context-length 131072 \
--reasoning-parser qwen3 \
--tool-call-parser qwen3_coder \
--attention-backend triton \
--chunked-prefill-size 65535 \
--triton-attention-num-kv-splits 4 \
--max-running-requests 4
关键参数说明:
| 参数 | 推荐值 | 作用 |
|---|---|---|
| --mem-fraction-static | 0.85 | 显存占用上限 |
| --context-length | 131072 | 支持128K上下文 |
| --chunked-prefill-size | 65535 | 预填充分块大小 |
| --triton-attention-num-kv-splits | 4 | Triton注意力头分割数 |
3.3 常见启动问题排查
问题1:CUDA版本不兼容
code复制RuntimeError: Detected CUDA version 12.8, but need >= 12.9
解决方案:修改环境变量绕过检查
bash复制export SGLANG_DISABLE_CUDNN_CHECK=1
问题2:Transformers版本冲突
code复制AttributeError: 'Qwen2Config' has no attribute 'sliding_window'
解决方案:升级transformers
bash复制pip install transformers>=4.40.0
4. Claude Code集成方案
4.1 本地服务配置
修改~/.claude/settings.json:
json复制{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:8000",
"ANTHROPIC_AUTH_TOKEN": "sk-local",
"ANTHROPIC_MODEL": "qwen3.5-9b"
},
"syntaxHighlightingDisabled": false
}
4.2 LiteLLM转接方案
对于需要OpenAI兼容接口的场景:
- 安装LiteLLM:
bash复制pip install 'litellm[proxy]'
- 创建配置文件
lite_llm.yaml:
yaml复制model_list:
- model_name: claude-3-5-sonnet
litellm_params:
model: openai/qwen3.5-9b
api_base: http://127.0.0.1:8000/v1
api_key: sk-local
- 启动代理服务:
bash复制litellm --config lite_llm.yaml --port 4000
5. Docker化部署实践
5.1 定制化镜像构建
基于官方blackwell镜像的Dockerfile:
dockerfile复制FROM lmsysorg/sglang:blackwell
RUN pip3 install --upgrade transformers \
&& pip3 install modelscope
ENV SGLANG_DISABLE_CUDNN_CHECK=1
构建命令:
bash复制docker build -t sglang-qwen .
5.2 容器启动命令
bash复制docker run -it --rm --gpus all \
-p 8000:8000 \
-v ~/.cache/modelscope:/root/.cache/modelscope \
sglang-qwen \
python -m sglang.launch_server \
--model-path /root/.cache/modelscope/qwen/Qwen3.5-9B \
--served-model-name qwen3.5-9b \
--port 8000
6. 性能调优与监控
6.1 关键指标监控
启用Prometheus监控:
bash复制--enable-metrics \
--metrics-port 9090
重要监控指标:
sglang_request_duration_seconds:请求延迟sglang_gpu_memory_usage:显存占用sglang_running_requests:并发请求数
6.2 推理参数调优
对于代码补全场景,建议调整:
bash复制--max-new-tokens 512 \
--temperature 0.2 \
--top-p 0.95
7. 踩坑实录与解决方案
坑1:35B-A3B-GPTQ版本部署失败
根本原因:MoE架构与当前Sglang版本不兼容
解决方案:暂时使用9B基础版
坑2:长上下文推理速度下降
优化方案:
bash复制--chunked-prefill-size 32768 \
--triton-attention-num-kv-splits 8
坑3:Claude Code连接超时
检查点:
- 确认防火墙放行8000端口
- 测试curl访问:
bash复制curl http://localhost:8000/v1/health
8. 扩展应用场景
8.1 作为VS Code插件后端
配置settings.json:
json复制{
"claude.serverUrl": "http://localhost:4000",
"claude.model": "claude-3-5-sonnet"
}
8.2 集成到CI/CD流程
示例GitLab CI配置:
yaml复制test:
image: sglang-qwen
script:
- python -m sglang.launch_server &
- pytest tests/
经过两周的实测,这套方案在代码生成任务上响应速度比API调用快3-5倍,而且完全避开了网络延迟问题。对于需要频繁调用模型的开发场景,本地部署带来的体验提升非常明显。
