---
slug: frognano-4b-small-coding-agent
title: "FrogNano 4B：微軟把小模型訓練成修程式碼的代理"
status: published
excerpt: "FrogNano 以 Qwen3.5-4B 為底座，透過合成任務與強化學習訓練專案級程式碼修補。從 Leaf 五個工具、官方評測到本機下載，理解小模型如何接下有限範圍的開發工作。"
category: Local AI
tags: [FrogNano, Qwen, coding-agent]
source_checked: "2026-10-06"
author: Seer
author_role: Author
read_time: 8 min
cover: "/static/frognano-4b-small-coding-agent-cover.png"
closing_note: ""
published_at: "2026-10-06T15:21:53Z"
updated_at: "2026-10-06T15:21:53Z"
---
[FrogNano-4B-2609](https://huggingface.co/microsoft/FrogNano-4B-2609) 是微軟以 **Qwen3.5-4B** 為底座、專門針對程式開發流程訓練的代理模型。它的工作情境很具體：給定既有專案與問題描述，模型要在程式庫中找出相關程式碼、修改檔案、跑測試驗證，並根據測試回饋反覆調整補丁。[1]

想把可重現且附帶測試的修復工作交給本機小模型，FrogNano 的修補流程是個不錯的觀察切入點。這篇整理它的訓練方法、Leaf 五個工具、官方評分與下載入口；目前適用的主力情境，仍建議先鎖定在英文問題描述與 Python 專案。

我的選型判斷是：**先把它當成範圍明確、有人審查的程式碼修補助手。** 建議由具備重現測試的 Python 專案著手；若要擴展到其他語言、框架或複雜度更高的流程，則必須依賴專案自身的測試來逐一驗收，這也符合官方目前的適用邊界。[1]

## 從問題描述到候選補丁

軟體開發代理在工作推進時，要處理的上下文資訊會一路累積。找到目標檔案後往往需要追查呼叫鏈；修好某個函式後，跑測試又可能引發其他錯誤。FrogNano 的後訓練正是針對這種多輪互動、跨檔案編輯的工程流程而設計。[1]

評估此模型時，可參考以下幾類場景。表格中的搭配方式屬於導入建議，最終成果仍應由專案既有的測試套件與人工審查確認。

| 使用場景 | 模型與工具層負責什麼 | 後續還需要什麼 |
| --- | --- | --- |
| 有測試的錯誤修復 | 查相關檔案、修改程式碼、利用測試回饋修正 | 確認根因、補回歸測試、審查 diff |
| 範圍明確的小功能 | 根據需求修改局部流程，必要時跨檔案編輯 | 驗收條件、相容性與邊界案例測試 |
| 測試失敗的維護任務 | 讀取失敗輸出，提出與驗證修補 | 確認修改保留原本行為 |
| 小模型代理研究 | 觀察模型如何選工具、處理錯誤與結束工作 | 固定模型、工具、任務與資源預算做比較 |

若任務描述只有「幫忙改善這個專案」這類寬泛語句，模型往往難以收斂。實務上較理想的做法，是提供確切的失敗案例、預期行為、限制修改的目錄範圍，以及可執行的驗收指令。

例如挑選一個能穩定重現的 Python 錯誤，要求它定位原因、補上回歸測試並產出最小修改。第一輪觀察重點在於：模型是否找對檔案、有沒有確實執行測試，以及修補範圍是否超出需求之外。

## 五個工具，讓小模型專心處理專案

微軟隨模型一併釋出了 [FrogNano／Leaf 官方程式庫](https://github.com/microsoft/FrogNano)。Leaf 扮演模型與專案環境之間的執行橋樑，僅提供五個核心工具：[2][3]

- **Read：** 讀取文字檔案或指定行數。
- **Write：** 寫入完整檔案。
- **Edit：** 透過精確文字比對來替換內容。
- **Glob：** 依檔名樣式搜尋檔案路徑。
- **Bash：** 在專案工作目錄下執行各類指令與測試。

整體運作由模型輸出工具名稱與參數，Leaf 執行後將結果回傳給模型。論文設計的互動邏輯相當簡潔：只要模型回覆包含工具呼叫就繼續推進；一旦不再呼叫工具，就結束這次互動，再評估產出的修改。[7]

這個簡化介面的影響很顯著。論文記錄了一組底座 Qwen3.5-4B 的對照組：在其他執行環境維持相同的情況下，僅將介面由 R2E-Gym 改為 Leaf，SWE-bench Verified 的解題率便從 **8.3% 大幅提升至 37.2%**。研究指出，小模型在過於繁複的介面下容易迷失、無法正確結束任務；工具設計與結束機制本身，已成為影響代理表現的關鍵環節。[7]

若更換不同的代理客戶端，提示詞、工具格式、對話狀態管理與結束條件都會連帶改變。整合至自有的開發工具鏈時，必須重新驗證整個互動流程，而不能單純只測試模型的文字問答能力。

## 約 1,500 個任務，訓練的是解題流程

FrogNano 採用 Qwen3.5-4B 為底座，額外的代理後訓練全數採用強化學習。官方將這輪流程界定為 **distillation-free**，學習依據是模型自身的解題軌跡與測試回饋。[1][7]

微軟利用 TaskPilot 自動生成、驗證並篩選了約 **1,500 個合成軟體工程任務**，引導模型從實際執行結果中摸索解題策略。[1][7]

TaskPilot 會自真實專案快照中擷取環境，生成問題、參考補丁與隱藏測試。每個候選任務都經過嚴格校驗：原始專案必須在新增測試上失敗、套用參考補丁後必須通過，且既有測試不能出現退化。接著讓當前小模型進行試解，並依其成功與失敗的回饋動態調節任務難度。[7]

任務難度會隨模型能力的提升動態演進。太簡單的題目提供的學習訊號會減少，始終無法攻克的問題也難以帶來有效回饋。TaskPilot 的作用是將訓練集中在模型尚有進步空間的有效區間內。[7]

此處需特別區分外部大模型的參與角色：生成模型參與的是題目設計、參考補丁與測試案例的建構；FrogNano 在這輪後訓練中，依靠的是自身產生的探索軌跡，並未拿更高階模型的推理過程、操作步驟或最終補丁作為模仿目標。這個 distillation-free 說法限定 FrogNano 追加的代理後訓練；上游底座的訓練配方需另查。參考補丁僅用於自動驗證題目，對解題模型全程保持隱藏。[1][7]

論文在描述出題模型時僅使用 task-generation model 或 stronger task-generation model 等通用詞彙，並未註明確切型號。出題模型、底座模型與蒸餾教師屬於不同環節，目前可確認的事實是 Qwen3.5-4B 的底座身分，以及 FrogNano 本身採用的強化學習流程。[7]

因此，約 1,500 個任務指的是這輪後訓練所建立的環境總數；模型既有的自然語言與程式碼理解基礎，依然來自上游預訓練的 Qwen3.5-4B。

## 官方成績，看的是一整套代理配置

官方模型卡與技術報告揭露了基準評測數據。評測統一使用 Leaf 框架，每道任務上限為 **150 個互動步驟**、約 **131K token 上下文**，採樣溫度設為 **0.6**，最終分數取自三個隨機種子的平均值。[1][7]

| 評測 | 平均單次成功率 Avg@3 | 三次至少成功一次 Pass@3 | 評估的工作 |
| --- | --- | --- | --- |
| SWE-bench Verified | 61.5% | 71.0% | 真實 Python 專案問題修復 |
| SWE-bench Pro | 37.6% | 47.6% | 較長流程、跨多種語言的專案任務 |
| Terminal-Bench 2.0 | 31.1% | — | 終端機中的軟體與系統任務 |
| PatchEval-Verified | 47.3% | — | 真實漏洞案例的修補 |

表格中的破折號表示這裡只列官方主評分，沒有補入 Pass@3 數值。**Avg@3** 的計算方式是將每個任務跑三次後的單次解題成功率取平均；**Pass@3** 則是看三次嘗試中是否至少成功一次，SWE-bench Verified 的 Pass@3 為 **71.0%**。兩者對應不同的使用策略：前者代表一次性產出修補的可靠度，後者則適用於多次採樣後再挑選候選方案的情境。[1]

資料集定位也值得關注：SWE-bench Verified 在該研究中被作為觀察訓練進展的驗證集，其餘三組是保留測試集。評估其跨專案遷移能力時，應將保留測試集與自有專案的驗收結果一併參照。[7]

模型卡與論文正文對底座起步分數的紀錄存在些微出入，此處採用雙方記錄一致的最終成績。前文提及的工具介面對照則屬於獨立實驗，閱讀時應與訓練歷程分開解讀。[1][7]

部署評測環境需要對應的基礎設施。官方開源的評測流程要求 **Python 3.12 以上、Kubernetes 叢集、專屬任務映像檔，以及設定好推理與工具解析器的 OpenAI 相容端點**。以 SGLang 提供推論服務時，README 指定需帶入 `--reasoning-parser qwen3` 與 `--tool-call-parser qwen3_coder` 參數。[2]

官方預設評測會啟動完整基準，使用 150 個共享工作執行器。初次驗證環境時，建議依文件指引限縮為單一任務、單一種子與一個工作執行器，確認流程與資源調度無誤後再行擴展。[2]

## 小模型的好處，是有較輕的本機下載入口

原生 BF16 權重檔案約為 **9.3 GB**，實際運算時還需額外保留模型狀態、KV 快取與工作區記憶體。約 131K token 為實驗中的最大互動長度，展開長上下文會顯著推高記憶體開銷。在本機端運行的生成速度與佔用空間，取決於採用的量化格式、推論引擎與具體提示詞長度。[1]

若想先在本機驗證文字與程式碼邏輯，可從社群提供的 GGUF 量化版本著手。以下將官方原生權重與社群版本分列，具體檔名可參考下載連結：[1][4]

| 版本 | 起手用途 | 權重／檔案大小 | 下載入口 |
| --- | --- | --- | --- |
| 官方原生版 | 原生模型整合、GPU 推論與研究評測 | BF16 權重約 9.3 GB | [微軟官方模型](https://huggingface.co/microsoft/FrogNano-4B-2609) |
| 社群 GGUF 起手版 | 本機文字與程式碼試用 | 約 2.80 GB | [模型檔](https://huggingface.co/bartowski/FrogNano-4B-2609-GGUF/blob/dfbb801e04ddf045ffd245b9f1a546ed0c7d960f/FrogNano-4B-2609-Q4_K_M.gguf) |
| 社群 GGUF 較高精度版 | 容量允許時比較輸出差異 | 約 3.36 GB | [模型檔](https://huggingface.co/bartowski/FrogNano-4B-2609-GGUF/blob/dfbb801e04ddf045ffd245b9f1a546ed0c7d960f/FrogNano-4B-2609-Q5_K_M.gguf) |

表格中的 GGUF 數值僅代表模型靜態檔案大小，推論執行時的總記憶體消耗仍需計入上下文快取與引擎開銷。官方已特別註明，尚未針對一般桌機、純 CPU 與各類量化格式進行專屬驗證；採用社群量化版時，應透過自訂測試來確認能力保留的狀況。[1][4]

### 先用 llama.cpp 接出文字服務

macOS 使用者可透過 Homebrew 安裝 llama.cpp；其他作業系統可參考 [Hugging Face 的安裝指南](https://huggingface.co/docs/hub/gguf-llamacpp)。依據社群模型卡建議，可使用下列指令啟動本機伺服器（初次執行會自動下載權重）：[4][5]

```bash
brew install llama.cpp

llama-server \
  -hf bartowski/FrogNano-4B-2609-GGUF:Q4_K_M
```

社群模型卡標註該檔案由 llama.cpp **b11279** 版本轉換而成；若本地 runtime 尚未支援該架構，需升級至對應或更新的版本。服務預設啟動於 `http://localhost:8080`。[4]

可發送一則純文字請求確認服務運作正常：[5]

```bash
curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Explain an empty-input test."
      }
    ],
    "temperature": 0.6,
    "max_tokens": 2048
  }'
```

這一步只驗證文字生成。若要進一步支援專案檢索、檔案編輯與執行測試等完整功能，還需搭配支援工具呼叫的代理客戶端，或接入官方 Leaf 執行環境。[1][2]

### 要重現官方代理流程，再準備 Leaf

官方程式庫的安裝指令如下；模型端點、Kubernetes 叢集與評測參數需另行設定：[2]

```bash
git clone https://github.com/microsoft/FrogNano.git
cd FrogNano

uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .
```

此套件核心在於提供基準評測與代理執行框架。若計畫整合至現有的開發工具，建議先理清工具 Schema 定義、思考歷程（Reasoning）解析、任務終止條件與指令執行權限，再從小型任務展開實測。

## 能操作專案，就要把執行權限管好

FrogNano 的官方定位屬於研究與受監督的輔助開發。由於 Leaf 具備寫檔與 Bash 執行權限，導入時應配置專案副本或隔離沙盒，嚴格限制檔案存取與網路權限，避免注入生產環境憑證；產出的 diff 必須經過人工審查，並執行獨立的回歸與安全性測試。[1]

在實際生成中，模型仍可能調錯 API、提供不完整的修補，甚至寫出恰好通過現有測試卻引發隱性問題的程式碼。工具輸出與測試回饋僅供輔助查驗，最終品質與驗收責任仍在開發者自身。[1]

評估採用時，還有兩項前提條件需要留意：

- **視覺能力：** 權重雖繼承上游基礎模型的視覺元件，但微軟對 FrogNano 的後訓練與效能評估僅限純文字，明確將圖像與影片標記為不支援。社群釋出的視覺量化檔並不等同於官方驗證過的支援範疇。[1][4]
- **授權條款：** 官方程式庫採用 MIT 授權；模型卡在授權標籤上則存在衝突，頁首 metadata 標示為 MIT，正文內欄位則寫為 Apache-2.0。程式庫與模型權重應分開看待，商業應用前宜先向上游釐清權重條款。[1][6]

## 先交一個小任務，再決定是否擴大使用

FrogNano 展示了一條清晰的方向：在參數量受限的小模型上，藉由將訓練任務、工具介面與可執行的測試流程整合在一起，依然能引導模型逐步完成專案級的修補工作。

初步驗收時，不妨挑選幾組範圍明確的真實 Issue，記錄修復成功率、修改檔案數、測試覆蓋度、人工修正成本以及整體耗時。摸清它擅長的工作類型後，再評估是否擴大導入至更長鏈條或多任務並行的工作流中。

對開發者而言，最具實務價值的切入點，是讓它在受控、可驗證的邊界內，穩定分擔那一小段範圍明確的修補工作。

## 參考來源

- [1：官方模型卡](https://huggingface.co/microsoft/FrogNano-4B-2609/blob/b90468c11a913c1916b4542b4b7a530ec42024a4/README.md)
- [2：官方 Leaf 與評測流程](https://github.com/microsoft/FrogNano/blob/7077a19d93f38fa0a7afd58b90a0774b25f6b629/README.md)
- [3：Leaf 五個工具](https://github.com/microsoft/FrogNano/blob/7077a19d93f38fa0a7afd58b90a0774b25f6b629/frognano/harness/leaf/tools.py)
- [4：社群 GGUF 版本](https://huggingface.co/bartowski/FrogNano-4B-2609-GGUF/blob/dfbb801e04ddf045ffd245b9f1a546ed0c7d960f/README.md)
- [5：Hugging Face llama.cpp 安裝與服務指南](https://huggingface.co/docs/hub/gguf-llamacpp)
- [6：官方程式碼授權](https://github.com/microsoft/FrogNano/blob/7077a19d93f38fa0a7afd58b90a0774b25f6b629/LICENSE)
- [7：FrogNano 技術報告 v4](https://arxiv.org/html/2609.07925v4)
