Gemma 4 12B 本地部署

把 Gemma 4 12B 的 GGUF 版本部署成本机模型服务。默认使用 llama.cpp / llama-server、Apple Metal、Q4_K_M 和 tmux，只监听 loopback；用户明确要求 QAT、256K、对比演示或 Ollama 时才切换路线。

Operating Contract

• Direct actions: 读取本机硬件、磁盘、端口、进程和模型缓存；在用户已要求本地部署时，安装或升级明确的软件包、下载选定模型、创建专用模型目录和 tmux 会话，并只绑定 127.0.0.1。
• Escalate before: 停止不属于本 Skill 的现有进程、覆盖已有模型或配置、删除用户数据、监听公网地址、改变防火墙，或下载用户未选择的大型模型变体。
• Evidence-backed pushback: 如果用户指定的模型标签、上下文、内存预算或本机能力与当前可验证状态冲突，先展示命令输出并提出可运行的 profile，不伪造支持状态。
• Feedback loop: 现状检查 → 选择并复述 profile → 执行一条部署路线 → 当前会话完成健康、模型和聊天验证 → 报告端点、资源与限制。

默认选择

• 默认模型仓库：ggml-org/gemma-4-12B-it-GGUF
• 默认量化：Q4_K_M
• 默认模型名：gemma-4-12b-it
• 默认端点：http://127.0.0.1:8080
• 默认上下文：32768
• 12B 长上下文：用户明确要求时选择 65536 或 131072
• QAT 仓库：google/gemma-4-12B-it-qat-q4_0-gguf
• QAT profile：Q4_0、262144 上下文
• 默认后台会话：gemma4-12b
• 默认关闭 thinking：--reasoning off，避免 OpenAI API 的 message.content 为空
• Ollama：只在用户明确要求 Ollama 或需要 Ollama 生态时使用

QAT 是训练时模拟量化，不等于无损。关键任务仍要用当前会话的真实响应验证。用户明确要更高质量时，优先建议 Q6_K 或 Q8_0；除非用户接受更高内存和更慢加载，不默认使用 bf16。

Profile 选择

Profile	适用场景	Model / quant	Context	Port / alias
daily-q4km-32k	默认日常聊天、编码、低风险本地 API	ggml-org/...:Q4_K_M	32768	8080 / gemma-4-12b-it
long-q4km-128k	明确需要更长上下文，但保留默认 GGUF 路线	ggml-org/...:Q4_K_M	65536 或 131072	8080 / gemma-4-12b-it
qat-q4_0-256k	明确要求 QAT、Q4_0、256K 或低内存长上下文	google/...qat-q4_0-gguf:Q4_0	262144	8080 / gemma-4-12b-it-qat-q4_0
compare-32k-vs-256k	录屏、演示或 A/B 比较资源与速度	左 Q4_K_M，右 QAT Q4_0	32768 + 262144	8080 + 8081

最终回复必须说明选定 profile、端口、上下文和选择依据。不要把 256K 当作日常默认值。

执行流程

1. 搜索并确认现状

先检查已有安装、进程、端口、缓存、硬件和磁盘，避免重复部署：

command -v llama-server || true
llama-server --version || true
tmux has-session -t gemma4-12b 2>/dev/null && tmux display-message -p -t gemma4-12b '#S #{pane_pid}' || true
lsof -nP -iTCP:8080 -sTCP:LISTEN || true
ls -lh "$HOME/Library/Caches/llama.cpp/"*gemma-4-12B-it*Q4_K_M*.gguf 2>/dev/null || true
find "$HOME/Library/Caches/llama.cpp" "$HOME/Models" \( -name '*gemma-4-12b-it-qat-q4_0*.gguf' -o -name '*gemma-4-12B-it-qat-q4_0*.gguf' \) 2>/dev/null || true
system_profiler SPHardwareDataType | sed -n '1,30p'
df -h "$HOME"

这些 || true 只用于允许“尚未安装/尚未运行”这一预期发现结果；必须展示实际输出，不能把查询失败描述成部署成功。

2. 执行一条部署路线

• daily-q4km-32k、long-q4km-128k、qat-q4_0-256k 或 compare-32k-vs-256k：先读并执行 llama.cpp 部署路线。
• 用户明确要求 Ollama：先读并执行 Ollama 部署路线。
• 不要同时混用两条路线，也不要在没有端口检查的情况下启动第二个服务。

3. 验证并报告

部署后必须读取并执行 验证、资源与排障。成功至少需要当前会话证明：

• /health 返回健康状态
• /v1/models 或 Ollama 模型列表包含选定模型
• 用户要求长上下文时，运行时报告实际 n_ctx
• 一次聊天响应的正文非空
• 端点仍只监听预期的本机地址和端口

Final response shape

默认用中文回答，并包含：

• 实际 endpoint URL 和 model id
• 选定 profile、量化与上下文
• tmux/session 管理命令
• 当前会话的验证结果
• 实际资源摘要、失败项和限制

没有验证数据时写“未验证”，不能用计划值代替运行值。

Cross-check

部署计划涉及超出默认 profile 的模型、上下文或资源判断时，使用 agents/openai.yaml 做独立复核；复核不能替代当前会话的本机验证。