【2026 最新】Raon-1 mini 本機部署怎麼做？MLX 上手、GPU 路徑與繁中工具呼叫五步教學

你看到「mini」，以為筆電下載後就能用，結果安裝完成卻載不進模型；好不容易開始聊天，工具又只變成一段奇怪的文字。Raon-1 mini 本機部署最容易卡住的，正是容量、執行軟體與訊息格式這三道交接。

這篇專為第一次接觸本機模型的讀者寫：先選 Apple silicon 的 MLX 或 NVIDIA GPU 路徑，再學會把一個繁中查詢工具接成完整回合。程式範例會逐段解釋；你需要能開終端機、建立檔案，但不必先懂模型訓練。

以下依 2026 年 10 月 26 日查閱的官方文件與程式碼整理。本文沒有執行 Raon 模型推論；安裝步驟是文件核對，工具回合是供你驗收的範例，不把它寫成繁中能力或速度實測。

先說結論：先讓一個工具回合交件

• mini 描述模型定位，並非你的記憶體預算。完整權重、對話快取及執行時空間都要算。
• 先選一條 Runtime，再下載對應權重。Runtime 是實際替模型運算、提供服務的軟體；不同格式要配不同載入方式。
• 成功條件是「提出呼叫 → 程式執行 → 結果回填 → 繁中回答」。只看到工具名稱，還不算接通。

本機 Agent ＝ 模型權重 ＋ Runtime ＋ 受控工具回合。把它想成餐廳：權重是整份食譜，Runtime 是廚房，工具回合則是點單、備料與回單。會念菜名，和真的端出菜，是兩回事。模型之外由誰接單，可先搭配 Agent Harness 白話解析。

Raon-1 mini 本機部署，第一步先算「整份食譜」

Raon 是 KRAFTON AI 的文字語言模型。官方模型卡將這次版本標為 Preview，採 MoE（混合專家：每次運算選部分專家參與）架構。啟用參數量反映每個 token 動用多少計算，完整參數量則關係到需要儲存、載入哪些權重；兩者用途不同。

圖中是官方儲存庫的 .safetensors 檔案大小加總，尚未包含 tokenizer、設定檔、Runtime 工作區與作業系統。MLX 與 NVIDIA NVFP4 的下載檔案雖接近，也不能把兩種格式混用。用下載容量直接承諾某台機器一定跑得動，會少算好幾項。

KV cache 是模型保留對話計算結果的「工作筆記」。模型卡列出的 BF16 快取估算，乘上最大 Context，只得到這一項筆記的空間；線性注意力狀態、權重與其他緩衝區仍要另外預留。更長的對話、更多同時請求，都應重新量整體峰值。需要通用估算方法，可讀 本機 LLM 記憶體指南。

操作：Mac 先執行 sysctl -n hw.memsize 與 df -h .，分別確認實體記憶體與磁碟餘量。若總記憶體連完整權重檔案的量級都不到，先不要下載；這不是靠把輸出字數調短就能解決的容量差距。

第二步：MLX、MXFP8、NVFP4 該選哪條路？

① Apple silicon：以官方 MLX 權重起步

MLX 是 Apple silicon 上的機器學習框架。本篇主線採用 官方 MLX 儲存庫，以其專用權重與自訂模型程式搭配指定套件版本。你可以把量化理解成「用較精簡的數字存食譜」；它改變儲存方式，也要求廚房認得這種格式。

先確認 python3 --version 為 Python 3.11 或以上。以下在新資料夾建立虛擬環境，把套件限制在這個練習目錄；若系統尚無符合版本的 Python，先處理 Python 環境，再繼續。

mkdir raon-lab
cd raon-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "mlx==0.32.4" "mlx-lm==0.32.2" "transformers==5.20.1" huggingface_hub

先登入 Hugging Face，在模型頁完成存取申請，再執行 hf auth login。官方將模型儲存庫設為需申請存取；遇到 401／403，先檢查帳號、存取資格與登入狀態，別先改模型程式。Token 留在登入工具中，不要貼進範例檔。

hf download KRAFTON/Raon-1-mini-preview-mlx --revision 2474b55299c6446a51a342da332bd13cf869dfa1 --local-dir ./raon-mlx

這裡固定權重 revision，避免同一個名稱隔天指向不同內容。啟動前打開下載目錄的 raon_mlx_model.py、config.json 與 chat_template.jinja 檢查。--trust-remote-code 允許載入模型提供的 Python 程式，應把它當作執行外部程式碼的決定；本例只使用固定版本的官方檔案。

② NVIDIA GPU：按官方硬體設定選 NVFP4 或 MXFP8

GPU 路徑請從 官方 Quickstart挑與自己硬體相符的設定。模型卡提供 RTX 5090 的 NVFP4 範例，並要求 CUDA Toolkit 13 與可在 PATH 找到的 nvcc；它與 B300 的 MXFP8 範例不是可以互換的容量保證。

vLLM 範例使用 KRAFTON 的 raon-1-mini-preview 分支。先記錄分支所指的 commit，再依該版文件安裝；不要把 Hugging Face 頁面自動產生的通用 pip install vllm 小卡，當成已驗證的 Raon 專用設定。工具呼叫需要核對 --enable-auto-tool-choice --tool-call-parser raon_1，推理分離則核對 --reasoning-parser raon_1。

官方 GPU 範例另包含 DFlash2 草稿模型。它是讓較小模型先擬稿、主模型再驗收的加速設計；下載、權重、快取與相容性也都多一份。第一次照做時保留完整的硬體對應設定，先確認服務健康與普通對話，再調整效能。本文不把其他硬體的加速數字換算成你的預期速度。

第三步：Raon-1 mini 本機部署先驗收普通對話

回到 MLX 主線，在已啟用的虛擬環境執行下列命令。模型來自固定的本機目錄；服務只綁定 127.0.0.1，讓測試用戶端在同一台電腦連線。輸出上限沿用官方範例，實際請求另給較小預算。

python -m mlx_lm server --model ./raon-mlx --trust-remote-code --host 127.0.0.1 --port 8000 --max-tokens 32768 --chat-template-args '{"enable_thinking":true,"truncate_history_thinking":false}' --decode-concurrency 1 --prompt-concurrency 1

另開終端機，執行 curl -f http://127.0.0.1:8000/v1/models。取得正常回應後，再測一次聊天：

curl -sS http://127.0.0.1:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"default_model","messages":[{"role":"user","content":"請用繁體中文介紹你自己，限兩句。"}],"max_tokens":4096,"temperature":1.0,"top_p":0.95,"top_k":20}'

本例的 default_model 來自 MLX-LM 0.32.2 server 程式：它會對應啟動時指定的模型。若改走 vLLM，請求名稱要跟 --served-model-name 一致；不要把名稱相似誤認為所有伺服器共用同一個別名。

核對回應的 choices[0].finish_reason 與 message.content。若因長度上限結束、只看到推理而答案為空，這輪尚未完成；保留 JSON，調整輸出預算後再試。能回 HTTP 200，只能證明請求被處理，還要看它交出了什麼。

第四步：接一個繁中工具回合，逐欄核對

工具呼叫不是模型自己執行函式。依 官方工具文件的流程，你先提供函式說明；模型提出呼叫，你的程式驗證、執行，再把結果回填。託管 API 文件另談伺服器代跑的網頁搜尋，那是另一種服務能力，本機這裡只接自己的固定筆記。

先看最容易混淆的欄位：content 是回答，tool_calls 是待辦的函式呼叫。此版本 MLX-LM 與官方 vLLM 範例用 reasoning 輸出推理；llama.cpp 範例則列 reasoning_content。更細的交接差異是：本文固定的 MLX 聊天範本會讀取歷史訊息的 reasoning_content。因此範例保留原回應，同時補上範本需要的名稱，避免回填時丟掉這份歷史。

把以下程式存成 tool_round.py。它只允許查詢一筆固定筆記，沒有 shell、任意網址或檔案路徑參數；最多做兩次模型請求。這是刻意縮小的驗收器：碰到超時、格式錯誤、第二輪仍想叫工具，會直接報錯，留待你檢查，沒有自動重試或完整 Agent 排程。

import json, os
from urllib.request import Request, urlopen

model = os.environ.get("RAON_MODEL", "default_model")
tools = [{"type": "function", "function": {
    "name": "lookup_note",
    "description": "讀取本機教學筆記，唯一 slug 是 setup",
    "parameters": {"type": "object", "properties": {
        "slug": {"type": "string", "enum": ["setup"]}},
        "required": ["slug"], "additionalProperties": False}}}]
messages = [{"role": "user", "content":
    "請先呼叫 lookup_note，查詢 slug=setup，再用繁體中文轉述筆記。"}]

def ask():
    payload = {"model": model, "messages": messages, "tools": tools,
        "max_tokens": 8192, "temperature": 1.0, "top_p": 0.95,
        "top_k": 20, "presence_penalty": 1.5,
        "chat_template_kwargs": {"enable_thinking": True,
                                  "truncate_history_thinking": False}}
    req = Request("http://127.0.0.1:8000/v1/chat/completions",
        data=json.dumps(payload).encode(),
        headers={"Content-Type": "application/json"})
    with urlopen(req, timeout=300) as response:
        result = json.load(response)
    print(json.dumps(result, ensure_ascii=False))
    choice = result["choices"][0]
    if choice["finish_reason"] == "length":
        raise RuntimeError("輸出用盡，這輪未通過")
    return choice["message"]

message = ask()
calls = message.get("tool_calls") or []
if len(calls) != 1:
    raise RuntimeError("預期恰好一個工具呼叫")
call = calls[0]
args = json.loads(call["function"]["arguments"])
if call["function"]["name"] != "lookup_note" or args != {"slug": "setup"}:
    raise RuntimeError("拒絕工具名稱或參數")
if not isinstance(call.get("id"), str) or not call["id"]:
    raise RuntimeError("缺少 tool_call_id")
if not message.get("reasoning_content") and message.get("reasoning"):
    message["reasoning_content"] = message["reasoning"]
messages.append(message)
messages.append({"role": "tool", "tool_call_id": call["id"],
    "content": json.dumps({"slug": "setup", "text":
        "先確認權重容量，再啟動本機服務，最後驗收工具回合。"}, ensure_ascii=False)})
answer = ask()
if answer.get("tool_calls") or not (answer.get("content") or "").strip():
    raise RuntimeError("尚未取得最終文字回答")
print(answer["content"])

執行 python3 tool_round.py > trace.log；若使用 vLLM 且其服務別名是 Raon-1-mini-preview，先設定 export RAON_MODEL=Raon-1-mini-preview。終端機報錯時，先讀錯誤，再檢查已保存的回應。這份練習只送示範筆記，Trace 不需要放真實工作資料。

讀 Trace 的順序是：第一個回應有沒有正確函式與參數；回填的 tool_call_id 是否等於模型給的 ID；第二個回應是否確實轉述筆記、保持繁中、沒有捏造筆記外的結果。程式檢查結構，你再檢查語意。這四項都成立，才算你的環境跑通這一題。

第五步：用同一個小任務決定要不要換模型

別急著把它接進重要專案。先拿一個你有權使用、可丟棄的小型 Repo，例如修正「空清單輸入應回傳零」的函式錯誤；預先寫好測試與允許修改的檔案。將相同起點、問題描述、工具權限、輸出上限與時間上限，交給 Raon 和既有模型。

每輪保留模型 revision、量化格式、Runtime commit／套件清單、提示、完整工具 Trace、修改差異、測試結果、耗時及峰值記憶體。python -m pip freeze > requirements.lock.txt 能保存套件版本；記憶體用所選 Runtime／作業系統的量測方式，並寫清楚是在量程序、GPU 還是整機。

把「完成」定義成測試通過且修改符合範圍；超時、工具格式錯誤與改壞其他測試要分開記。若有多個任務，就按通過題數除以總題數計算完成率，再一起看每題時間。這是你接下來可做的評估方法，本文沒有填入尚未取得的成績。想延伸到修 Repo，可接著讀 本機 coding Agent 修補驗收。

常見問題：先把八個誤會拆開

名字有 mini，16 GB 筆電就能直接跑嗎？

不一定。先比完整權重與實體記憶體，再加系統與執行餘量；啟用參數量不是下載大小。這篇列出的 MLX 權重檔本身，就已超過 16 GiB。

MLX 和 NVIDIA 的 NVFP4 可以拿同一份權重互換嗎？

應使用各自對應的官方儲存庫。本篇 MLX 命令載入 MLX 版本；GPU 命令則按官方 GPU 配置選模型，別因為量化名稱相近就換檔。

看到模型寫出工具名稱，就代表成功了嗎？

還沒。要收到可解析的呼叫，通過名稱與參數檢查，執行本機函式、回填結果，再取得最終回答。

reasoning_content 和 content 是同一個東西嗎？

不是。前者用於分離推理，後者是回答；某些 Runtime 將推理輸出命名為 reasoning。請按版本對照輸出欄位與歷史範本。

模型會自己上網查資料嗎？

本篇範例只提供固定筆記工具，不提供網路查詢。官方託管服務的 web search，與你本機註冊的函式要分開設定與驗收。

可以一開始就把 Context 開到最大嗎？

先從短輸入與單請求起步。容量上限是模型規格的一部分，實際部署仍受權重、快取、排程與硬體共同約束。

官方跑分能代表我的繁中任務嗎？

不能直接代替你的驗收。官方面板使用特定測試與配置；本篇要求你另外檢查繁中用字、工具參數與最終任務結果。

本機執行就能接真實工作檔案嗎？

先限縮到可丟棄資料與明確允許的工具。本機描述的是運算位置，工具的讀寫、網路與憑證權限仍由你的程式配置。

給新手的三個重點

• 先算完整權重，再選 Runtime；容量不合就先停在選型。
• 先跑普通對話，再接固定工具；每一階段都留下可檢查的 JSON。
• 先用自己的小任務驗收，再擴大權限；把模型、執行軟體與工具分別排錯。