--- license: apache-2.0 base_model: google/gemma-4-12B-it base_model_relation: quantized tags: - gguf - llama.cpp - lm-studio - ollama - coding - agentic - long-context - 1M-context - function-calling - xcloudinfo language: - en - zh pipeline_tag: text-generation library_name: gguf ---

xGemable-12B-coder

# xGemable-12B-coder-v1.5 — GGUF 云碩科技（xCloudinfo）**代理式編程模型**——這是一顆為「寫程式」而生的模型，不是通用聊天模型。 ## 這顆模型的程式邏輯從哪裡來 模型的程式邏輯能力以 **Anthropic Claude（前沿級編程模型）為教師蒸餾**而來，方法是云碩的**執行驗證蒸餾（Execution-Verified Distillation）**： 1. 由 Claude 在真實工程任務上實際解題——分析需求、推理邊界條件、寫出完整程式。 2. 每一條教師軌跡都先丟進**真實編譯器與測試執行**（pytest / dotnet / javac / go / rustc），**測試全過才收錄**，跑不過的一律丟棄。 3. 通過驗證的解題軌跡再蒸餾進 `google/gemma-4-12B-it` 底座。 所以它學到的不是「聊程式的口吻」，而是 Claude 面對工程問題時的**推理路徑、邊界條件判斷、與可執行的正確實作**。訓練資料裡沒有一行未經執行驗證的程式碼。 ## 工程師可以拿它做什麼 - **函式/模組實作**：給簽名或 docstring，產出可編譯、可通過測試的完整實作 - **多語言**：Python 為主力，C# / Java / Go / JavaScript / Rust 皆可 - **代理式工作流**：原生 function calling / tool use，能讀錯誤訊息、迭代修復（agentic coding，非單發問答） - **長上下文程式理解**：256K 原生 / 1M（YaRN）——整個中型 repo 塞進 context 做跨檔案推理 - **地端私有部署**：GGUF 量化，單機 16GB RAM 起跑，資料不出內網 底座 `google/gemma-4-12B-it`。 ## 為什麼寫程式選這顆，而不是更大的 gemma-4-26B / 31B 參數量大，不等於會寫程式。gemma-4-26B / 31B 是**通用指令模型**——訓練目標是知識問答、對話、摘要等泛用任務，程式碼只是其訓練分佈的一小部分，也沒有針對「可執行的正確性」做過任何驗證式訓練。拿它們寫程式，常見的就是：看起來很像對、實際編譯不過或測試不過的程式碼。 xGemable-12B-coder 相反：**整個微調預算全部押在編程一件事上**，且每條訓練資料都經過真實編譯器與測試把關（上節所述）。結果是： | | xGemable-12B-coder | gemma-4-26B / 31B（通用版） | |---|---|---| | 定位 | 編程專用（agentic coding） | 通用對話 / 知識問答 | | 程式訓練資料 | 100% 執行驗證通過 | 無執行驗證 | | HumanEval pass@1 | **87.8%**（自測，方法公開於下） | 未針對編程最佳化 | | function calling / 工具迭代修復 | 原生，蒸餾自 Claude 代理軌跡 | 基本支援 | | 部署門檻 | Q4 約 7.4GB，16GB RAM 即跑 | 26B Q4 約 16GB 起，一般開發機吃緊 | | 產速（同硬體） | 12B，快 | 26B/31B 慢約一倍以上 | 一句話：**要聊天查知識，用大顆通用版；要寫會過測試的程式，用這顆。** 更小、更快、在編程這件事上更準。 ## 量化版本 | 檔案 | 位元 | 大小 | 建議 | |---|---|---|---| | `xGemable-12B-coder-v1.5-Q4_K_M.gguf` | 4-bit | ~7.4 GB | **一般使用**，16GB RAM 可跑 | | `xGemable-12B-coder-v1.5-Q5_K_M.gguf` | 5-bit | ~8.5 GB | 品質與體積之平衡 | | `xGemable-12B-coder-v1.5-Q6_K.gguf` | 6-bit | ~9.8 GB | 高品質 | | `xGemable-12B-coder-v1.5-Q8_0.gguf` | 8-bit | ~12.7 GB | 接近無損 | > 註：本模型底座為 gemma-4，無 MTP（Multi-Token Prediction）變體——MTP 為部分他家架構之特性，本底座不具備。 ## 能力 | 項目 | 分數 | |---|---| | HumanEval pass@1 | **87.8%**（乾淨取樣解碼，全量 164 題實際執行判分） | 約當 GPT-4-turbo（2024）水準，居 12B 開源編程模型第一梯隊。 本模型之數字均為云碩自測、可重現（評測方式與解碼參數如下所述），非引用之宣稱。 ## 上下文長度：1M tokens，開箱即用 - **1,048,576（1M）tokens，預設啟用**——YaRN rope-scaling 已直接寫入 GGUF metadata（`rope.scaling.type=yarn, factor=4`），llama.cpp / Ollama / LM Studio 載入即生效，**不需要任何額外參數**。 - 底子是 **256K 原生視窗**（`gemma4.rope.scaling.original_context_length = 262144`，已驗證未截斷）——1M 只是 4 倍溫和外推。同級距多數模型的 1M 是從遠小的原生視窗高倍外推而來，長文品質衰減遠大於 4 倍外推。**原生視窗大小，才是長上下文品質的硬實力。** - 整個中型 repo、數十篇文件一次塞進 context 做跨檔案推理都放得下。 - 注意：實際可用長度受你的 RAM 限制（KV cache 隨長度線性成長）；一般 16GB 機器建議 num_ctx 32K 以內，1M 需要大記憶體機器。 ## 解碼參數（務必遵守） gemma-4 對解碼參數極度敏感，設定錯誤會使表現大幅劣化。 - **溫度**：編程 `0.2`、代理／工具呼叫 `0.7` - **搭配**：`top_p 0.95`、`top_k 64` - **禁止**：貪婪解碼、`repetition_penalty`、`no_repeat_ngram` （這些會使模型無法重現題目給定的函式簽名與工具語法） ## 重要：務必使用附帶的解碼參數與模板（否則分數會腰斬） gemma-4 這顆底座是「帶思考通道的對話模型」，部署工具鏈若不知道它的回合/通道標記，會出現三類劣化——**這不是模型變笨，是部署設定不對**。本 repo 的 GGUF 與附帶檔案已經全部修好，逐一說明： | 根因 | 沒修的症狀 | 本 repo 的修法 | |---|---|---| | 推理端自動開啟思考模式（偵測到模板支援 thinking 就啟用） | 寫完程式又「Wait, let me re-check…」二次推敲、內部標記洩漏到回覆 | Ollama：附帶 `template`（預填空思考通道）；llama.cpp：加 `--chat-template-kwargs '{"enable_thinking":false}'` | | 舊版 GGUF 缺回合結束標記（eot_token_id） | 回合結束不停、越界生成出殘缺程式碼 | 已烙入 `eot_token_id=106`（``），載入即生效 | | Q4 量化損傷特殊 token 判斷 | Q4 版在短補全中隨機吐出模板標記、截斷程式碼 | Q4 已重新量化（embedding/output 層保 q8 精度），實測回到全精度行為 | | Ollama 預設 `repeat_penalty 1.1` / `num_predict 128` | 不准照抄函式簽名 → 亂改；函式寫不完就截斷 | 附帶 `params`：`repeat_penalty 1.0`、`num_predict 1024` | **實測對照（同一組 C# 編譯測試，各跑 3 輪）**：修復後 Q4/Q5/Q6/Q8 全部 3/3（= bf16 本尊水準）；修復前 Q4 僅 1/3。HumanEval 同樣由 62~77%（Ollama 預設）回到 ~90%。 ## 使用方式 ### 方式一：Ollama 一行安裝（建議）— 全自動，零設定 本 repo 附有 `params` 檔（repo 層級，**一個檔對所有量化版生效**）。Ollama 從 hf.co 拉取時會自動套用上表全部修正——不用下載 Modelfile、不用改名、不用手動設任何參數。依你的硬體選一行執行即可： ```bash # Q4_K_M — 一般使用，約 7.4GB，16GB RAM 可跑（不加 tag 也是預設這個） ollama run hf.co/xCloudinfo/xGemable-12B-coder-v1.5-GGUF:Q4_K_M # Q5_K_M — 品質再高一階，約 8.5GB ollama run hf.co/xCloudinfo/xGemable-12B-coder-v1.5-GGUF:Q5_K_M # Q6_K — 接近無損，約 9.8GB ollama run hf.co/xCloudinfo/xGemable-12B-coder-v1.5-GGUF:Q6_K # Q8_0 — 最高品質，約 12.7GB，24GB RAM 建議 ollama run hf.co/xCloudinfo/xGemable-12B-coder-v1.5-GGUF:Q8_0 ``` 安裝後可用 `ollama show <模型名>` 確認參數已自動帶入（temperature 0.2、repeat_penalty 1.0、stop 序列等）。 > 若你先前已用舊方式 `ollama create` 建過模型，那顆**不會**自動更新——請刪掉重拉，或照方式二用 Modelfile 重建。 ### 方式二：Ollama 離線安裝（無網路內網 / 政府機關 / 校園環境） 離線環境連不到 `hf.co`，改用附帶的 Modelfile（每個量化版各附一個：`Modelfile.Q4_K_M`、`Modelfile.Q5_K_M`、`Modelfile.Q6_K`、`Modelfile.Q8_0`，內容 = 方式一會自動套用的同一組參數）。 步驟：在有網路的機器下載「GGUF + 對應 Modelfile」兩個檔 → 帶進內網 → create： ```bash # 步驟 1（有網路的機器）：下載兩個檔。請打確切檔名，不要用 *.gguf 萬用字元 hf download xCloudinfo/xGemable-12B-coder-v1.5-GGUF \ Modelfile.Q4_K_M xGemable-12B-coder-v1.5-Q4_K_M.gguf --local-dir . # 步驟 2（目標機器，兩檔放同一資料夾）：直接 -f 指定，不必改名 ollama create xgemable-coder -f Modelfile.Q4_K_M ollama run xgemable-coder ``` 其他量化版把上面兩處 `Q4_K_M` 換成 `Q5_K_M` / `Q6_K` / `Q8_0` 即可。 ### LM Studio 載入 `.gguf` 後，於推論參數手動設定（LM Studio 無法讀 Modelfile）： Temperature `0.2`、Top P `0.95`、Top K `64`、**Repeat Penalty `1.0`（關閉）**、 Max Tokens `1024`，並在 Stop Strings 加入 ``、`<|turn>`、`<|channel>`。 ### llama.cpp ```bash ./llama-server -m xGemable-12B-coder-v1.5-Q4_K_M.gguf -c 8192 --jinja \ --chat-template-kwargs '{"enable_thinking":false}' \ --temp 0.2 --top-p 0.95 --top-k 64 ``` `--chat-template-kwargs '{"enable_thinking":false}'` 必加——llama.cpp 偵測到模板支援思考會自動開啟，導致回覆夾雜推敲過程。1M 上下文已是預設（YaRN 烙入 metadata），把 `-c` 調大即可，無須額外 rope 參數。 ## 能力範圍 - **擅長**：函式與演算法實作、單元測試、程式碼解釋與審查、多輪工具使用探索。 - **限制**：完整倉庫級自動除錯（在整個專案中定位並修復真實 bug）尚未達實用門檻，此為當前 12B 級模型之共通限制。 ## 訓練 以 LoRA 監督式微調，採「保存底座編程能力、疊加代理行為」之最少擾動策略； 訓練軌跡均經 pytest 執行驗證（通過測試方才收錄）。 ## 授權 Apache-2.0（底座 gemma-4-12B-it 之授權）。訓練所用之蒸餾軌跡為一次性輸入，不改變產出權重之授權狀態。 --- 云碩科技股份有限公司　xCloudinfo Corp. Limited 台北・台中・新竹　│　自主 AI・地端部署・資料不離企業內網