在 WSL2 Ubuntu 中部署 Gemma-4-E4B 视觉模型全记录（含 Claude Code 接入）
Google发布了最新的gemma4开源模型系列，号称开源“最强”。
本地跑一个能看图、读文档的多模态模型，选了一圈最终锁定了 Google 的 Gemma-4-E4B —— 40 亿参数，视觉能力不错，关键是在消费级显卡上也能流畅运行。
但我的主力机是 Windows 11，权衡之后决定走 WSL2 + Ubuntu 22.04 的方案。
下面就记录一下完整过程，方便以后复现，也给同样折腾的朋友一个参考。
为什么是 WSL2 而不是直接在 Windows 上跑？
先说结论：不推荐在 Windows 原生环境部署 llama.cpp。虽然现在 Windows 下也能编译 CUDA 版本，但折腾依赖、路径、权限问题耗时又费力，最终推理速度还远不如 WSL2 里的原生 Linux 环境。WSL2 现在对 GPU 直通支持非常成熟，配合 Mirrored 网络模式，体验几乎和裸机 Linux 无异。
第一步：WSL2 环境准备
1. 安装 WSL2 与 Ubuntu 22.04
如果系统还没装 WSL，用管理员权限打开 PowerShell，一条命令搞定：
wsl --update
wsl --install -d Ubuntu-22.04安装完成后重启，进入 Ubuntu 设置用户名密码。
2. 配置 .wslconfig（关键一步）
在 Windows 用户目录下（C:\Users\<你的用户名>\）创建或编辑 .wslconfig 文件，内容如下：
[wsl2]memory=12GBprocessors=4networkingMode=mirroredmemory=12GB：给 WSL 分配 12G 内存，因为接入claude 或者 openclaw都是需要并行，上下文会存储在内存上。processors=4：根据你的 CPU 核心数调整，我分配了 4 核。networkingMode=mirrored：这个非常重要！启用后 WSL 的网络和 Windows 共享同一个 IP，你从 Windows 访问 WSL 服务直接用127.0.0.1即可，代理设置也会自动继承，省去一堆端口转发烦恼。
配置完记得重启 WSL 生效：
wsl --shutdown
#重新进入Ubuntuwsl -d Ubuntu-22.04第二步：CUDA 环境与显卡检测
安装 CUDA Toolkit
进入 WSL Ubuntu，依次执行：
#没有代理可以使用国内apt镜像sudo apt updatesudo apt install nvidia-cuda-toolkit -y安装完成后用 nvidia-smi 验证显卡是否被 WSL 识别。
第三步：编译 llama.cpp（CUDA 加速版）
llama.cpp 官方仓库更新频繁，直接拉取最新代码编译即可。
git clone https://github.com/ggerganov/llama.cppcd llama.cpprm -rf buildmkdir build && cd buildcmake .. -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="89" -DGGML_CUBLAS=ON -DLLAMA_CURL=ONcmake --build . --config Release -j $(nproc)参数说明：
-DGGML_CUDA=ON：启用 CUDA 加速。-DCMAKE_CUDA_ARCHITECTURES="89"：我的显卡是 RTX 40 系列（Ada Lovelace），架构代号89。如果你用 30 系列填80或86，20 系列填75，不确定的话可以去 NVIDIA 官网 查询。-DGGML_CUBLAS=ON：启用 cuBLAS 矩阵运算加速。-DLLAMA_CURL=ON：支持从 URL 直接拉取模型（可选）。
第四步：下载模型与多模态投影文件
Gemma-4-E4B 需要两个文件：
- 主模型文件（.gguf）：用于文本生成。
- mmproj 投影文件（.gguf）：用于图像、视频、音频等多模态输入理解。
我使用的是社区 Uncensored 版本，直接从 Hugging Face 拉取：
# 创建模型存放目录mkdir -p ~/models/gemma-4-E4B-it
# 下载主模型（约 4.7GB，Q4_K_M 量化版本）wget -c -P ~/models/gemma-4-E4B-it https://huggingface.co/HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive/resolve/main/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive-Q4_K_P.gguf
# 下载配套 mmproj 文件wget -c -P ~/models/gemma-4-E4B-it https://huggingface.co/HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive/resolve/main/mmproj-Gemma-4-E4B-Uncensored-HauhauCS-Aggressive-f16.gguf第五步：启动 llama-server 服务
llama.cpp 自带一个 HTTP 服务端，支持 OpenAI 兼容 API，非常方便后续集成。
llama-server \ -m ~/models/gemma-4-E4B-it/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive-Q4_K_P.gguf \ --mmproj ~/models/gemma-4-E4B-it/mmproj-Gemma-4-E4B-Uncensored-HauhauCS-Aggressive-f16.gguf \ --host 0.0.0.0 --port 8080 \ -ngl 99 -fa on -ub 1024 -t 16 -b 8192 -n 4096 \ --jinja关键参数解释：
-ngl 99：把 99 层模型全部加载到 GPU，显存占用约 6~7GB。-fa on：启用 Flash Attention，降低显存开销并加速推理。-ub 1024：批处理上限，平衡吞吐与延迟。-t 16：使用 16 个线程处理 CPU 任务。-b 8192 -n 4096：上下文大小与最大生成长度。--jinja：启用 Jinja 模板，提升对话格式兼容性。
启动后，因为前面配置了 Mirrored 网络模式，直接在 Windows 浏览器打开 http://127.0.0.1:8080 就能看到 llama.cpp 自带的 Web UI。
我开的东西太多了，正常下是54token/s，整体效果还不错 也可以使用27B-A4B，输出慢点，但是智商比E4B强
第六步：接入 Claude Code（通过 LiteLLM 做 API 转换）
我想在 Claude Code 里用这个本地模型，但 Claude Code 只认 Anthropic 官方 API 格式。LiteLLM 就是为此而生的——它能将各种模型接口统一成 OpenAI 格式，并支持自定义模型名映射。
1. 安装 LiteLLM
pip install 'litellm[proxy]'2. 配置 config.yaml
我在 ~/claude-proxy/config.yaml 中写入了以下内容：
model_list: - model_name: gemma-4-e4b litellm_params: model: openai/llama api_base: http://127.0.0.1:8080/v1 api_key: dummy stream: true max_tokens: 4096 - model_name: claude-haiku-4-5-20251001 litellm_params: model: openai/llama api_base: http://127.0.0.1:8080/v1 api_key: dummy stream: true max_tokens: 4096这里解释一下：
- 本地 llama-server 的 API 地址是
http://127.0.0.1:8080/v1，格式兼容 OpenAI。 - 我将本地模型映射了两个名字：
gemma-4-e4b（自己用）和claude-haiku-4-5-20251001（欺骗 Claude Code）。 api_key: dummy是因为 llama-server 默认无需鉴权，随便填一个即可。
3. 启动 LiteLLM 代理
litellm --config ~/claude-proxy/config.yaml --port 4000 --host 127.0.0.1启动后 LiteLLM 会监听在 http://127.0.0.1:4000。
4. 在 Claude Code 中配置自定义端点
打开 Claude Code 设置，将 API Base URL 修改为 http://127.0.0.1:4000，然后在模型选择列表里就会出现我们伪造的 claude-haiku-4-5-20251001，选中它即可使用本地 Gemma 模型。
推理速度相当可观，稳定在 50 tokens/秒左右，配合图片理解能力，日常 Coding 助手体验完全不输云端小模型。
总结
整个流程走下来，最顺畅的体验来自于两点：
- WSL2 的 Mirrored 网络模式 —— 彻底告别
localhost:8080连不上的困惑。 - LiteLLM 的模型名称映射 —— 让任何支持自定义端点的客户端都能无缝接入本地模型。
- 其实还可以llamacpp更优化，让速度达到60-70，这里我就没尝试了
如果你也有一块 8G 以上显存的 N 卡，强烈建议试试这套方案，本地多模态模型跑起来的感觉真的很棒。
如果这篇文章对你有帮助，欢迎分享给更多人！