majiayu000/spellbook / skills/gemma4-local-deploy
gemma4-local-deploy
Verified在本机 Mac 或 Apple Silicon 上部署 Gemma 4 12B。本地安装/升级 llama.cpp,下载 GGUF 量化模型,用 llama-server 暴露 OpenAI-compatible API,或用 Ollama 暴露本地模型服务;按用户需求在默认 Q4_K_M、64K/128K 长上下文、QAT Q4_0 @ 256K、左右对比演示之间选择,配置 tmux 后台运行,验证健康检查、问答接口、资源占用和常见故障。当用户说部署 Gemma 4、Gemma 4 12B、本地大模型、长上下文、QAT、量化、llama-server、Ollama、GGUF、Mac 本地模型服务时使用。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| agents/openai.yaml | config | 370 B |
| references/llama-cpp.md | markdown | 4.6 KB |
| references/ollama.md | markdown | 2.1 KB |
| references/verification.md | markdown | 2.5 KB |
references/verification.md
View on GitHub# 验证、资源与排障
部署完成后必须在当前会话运行本文件中的适用检查。没有真实输出时不能宣称成功。
## llama.cpp 验证
```bash
curl -fsS http://127.0.0.1:8080/health
curl -fsS http://127.0.0.1:8080/v1/models
curl -fsS http://127.0.0.1:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"gemma-4-12b-it","messages":[{"role":"user","content":"用一句中文回答:现在可以问你问题吗?"}],"max_tokens":80,"temperature":0.2}'
```
成功需要:
- `/health` 返回 `{"status":"ok"}`
- `/v1/models` 包含选定 alias
- 长上下文请求的实际 `n_ctx` 与选择一致
- `choices[0].message.content` 非空
- `lsof -nP -iTCP:8080 -sTCP:LISTEN` 显示预期监听状态
QAT alias 不同时要同步修改聊天请求的 `model`,不要用错误 model id 制造假失败。
## Ollama 验证
```bash
curl -fsS http://127.0.0.1:11434/api/version
ollama list
```
再对实际安装的 model id 运行一次 `ollama run`,正文必须非空。
## 资源使用
llama.cpp 路线使用实际 PID:
```bash
pid=$(pgrep -f 'llama-server .*gemma-4-12B-it' | head -1)
ps -p "$pid" -o pid,stat,%cpu,%mem,rss,vsz,etime,command
footprint -p "$pid" -summary 2>/dev/null | sed -n '1,80p'
memory_pressure | sed -n '1,20p'
```
解释时区分:
- GGUF 文件大小、进程 RSS 和 `footprint` 物理压力不是同一指标。
- Apple Silicon 使用统一内存,不会出现独立 NVIDIA 风格 VRAM 数字。
- 更大的 `--ctx-size` 会增加 KV/cache 内存,并可能降低短提示速度。
- 只报告本次命令的数字,不复用旧机器上的近似值。
## Troubleshooting
| Symptom | Fix |
|---|---|
| `unknown model architecture: 'gemma4'` | 升级 `llama.cpp` 后重试。 |
| 端口 8080 忙 | 用 `lsof` 展示监听者;由用户决定停止它还是换端口。 |
| Chat `content` 为空、只有 reasoning | 用 `--reasoning off` 重启并复验。 |
| 首次 `-hf` 卡在 metadata resolution | 查找已缓存 GGUF,改用 `-m` 本地路径。 |
| `ollama pull gemma4:12b` 返回 manifest 不存在 | 当前官方 tag 不可用;按 Ollama 参考文档手工导入 GGUF。 |
| Ollama 报 `llama-server` / `llama-quantize` 不存在 | 只在确认错误后使用 `llama.cpp` sidecar 链接 workaround。 |
| 用户需要图片/多模态 | 只有完成 `mmproj` 兼容验证后才移除 `--no-mmproj`。 |
| 内存过高 | 降低 context、使用 `Q4_K_M`、保持 `--parallel 1`,然后重新测量。 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |