Skip to main content
Buttress 伺服器以獨立執行檔 bricks-buttress 的形式發行，支援 macOS、Linux 與 Windows，不需要 Node.js 執行階段。您也可以改用 npm 或 Bun 安裝。若要在 Linux 上使用 GPU 加速，請在執行安裝指令碼前先安裝 CUDA 或 Vulkan 驅動程式 — 指令碼會依偵測結果挑選對應的組建。

​
硬體需求

伺服器在無 GPU 環境下仍可執行，但吞吐量會大幅下降，能力評分也會將該主機標示為較不偏好的後端。

​
安裝

指令碼會偵測您的架構（Apple Silicon 或 Intel），並將 bricks-buttress 安裝至 ~/.bricks-cli/bin。Metal 加速已包含在預設組建中，不需另行選擇。若 ~/.bricks-cli/bin 不在您的 PATH 內，指令碼會將其附加至您的 shell 設定檔（~/.zshrc、~/.bash_profile 或 ~/.config/fish/config.fish），並提示您重新啟動 shell。
獨立執行檔的安裝指令碼會與 BRICKS CLI 共用安裝目錄，因此單一 PATH 設定即可涵蓋兩項工具。 確認安裝結果：

​
原生模組

獨立執行檔無法內嵌 GGML、ONNX Runtime、sharp 與 oxc-transform 等原生附加元件。安裝指令碼會從 npm registry 下載這些模組至執行檔旁的 node_modules 目錄，版本則固定為建置該執行檔時所使用的版本。指令碼同時會將狀態儀表板（public/status.html）放在該處，在 macOS 上還會放入 MLX bridge 指令碼。 每次安裝都會重新建立該目錄，因此升級後不會殘留舊版原生模組。若要從其他 npm registry（而非 https://registry.npmjs.org）下載原生套件，請設定 BUTTRESS_NPM_REGISTRY。

​
GPU 加速變體

GGML 後端會針對每種加速器提供不同組建。安裝指令碼會探測主機、挑選支援度最高的一種，並僅下載該變體與預設的 CPU 組建。 當偵測結果不符預期時可自行覆寫 — 例如驅動程式是事後才安裝的機器：
可接受的值為 auto（預設）、default、cuda、vulkan、snapdragon（僅限 Linux）與 all。使用 all 會下載所有變體 — 體積較大，但若您要製作安裝目錄的映像檔以套用到多台主機，會更具可攜性。
在 Windows 上以 MSYS 或 Git Bash 執行 install.sh 時會略過 GPU 探測，因為該環境的探測結果並不可靠。請明確傳入 --ggml-variant，或改用 PowerShell 安裝指令碼。

​
安裝指令碼選項

​
啟動伺服器

無設定檔時，伺服器會以合理的預設值在連接埠 2080 啟動：
搭配 TOML 設定檔：
或以同一旗標傳入內嵌的 TOML 字串：
完整設定結構請參閱設定參考。

​
CLI 旗標

連接埠的優先順序為：--port 旗標 → TOML 中的 [server] port → 預設 2080。 bricks-buttress 另提供一個子指令 update — 請參閱下方的更新。

​
環境變數

系統環境變數會覆寫 TOML 設定檔中 [env] 區段的值。

​
macOS GPU 記憶體

Apple Silicon Mac 預設僅允許 GPU 使用約 70% 的系統記憶體。在載入大型模型前，可先放寬上限：

​
確認運作

伺服器啟動時會印出可從區域網路連線的網址，例如 Visit http://<ip>:2080/status to see status via LAN.。開啟該網址（或在本機開啟 http://localhost:2080/status）即可載入狀態儀表板。 儀表板針對每個後端（GGML-LLM、GGML-STT、MLX-LLM）顯示：
  • 已載入的 generator 清單，以及目前持有 active 模型 context 的項目
  • STT 的平行 slot 使用率與排隊請求
  • 最近的模型載入記錄、completion / 轉錄記錄（可折疊）
頁面上的 Refresh 按鈕可隨時重新拉取資料。/status 沒有認證 — 僅於受信任的區域網路上提供伺服器。 如需機器可讀格式，請直接查詢 JSON 端點：
/buttress/info 是 Foundation 裝置在 HTTP 回退探索時讀取的內容 — 請參閱區域網路自動探索。

​
Beta 通道

兩個通道的執行檔皆命名為 bricks-buttress，因此安裝 beta 版會取代既有的穩定版。兩者無法共存於同一個目錄 — 若兩者都需要，請傳入 --dir / -InstallDir。

​
更新

執行 bricks-buttress update 可就地更新既有安裝。它會偵測伺服器的安裝方式 — 獨立執行檔、npm 全域或 Bun 全域 — 並執行對應的更新流程：
  • 獨立執行檔 — 重新執行 CDN 安裝指令碼，取代執行檔並重建原生模組目錄，一併套用新版中原生套件的版本異動。既有的安裝目錄會沿用，因此先前以 --dir 指定的位置會保留。
  • npm / Bun — 重新安裝全域的 @fugood/buttress-server 套件。
發行通道會依目前版本的 pre-release 字尾推斷。版本資訊的來源：npm 與 Bun 安裝取自 npm dist-tag，獨立執行檔安裝則取自 CDN 的發行中繼資料。當有新版可用時，執行中的伺服器也會印出含此指令的升級提示。 若偵測到的方式失敗，指令會改以獨立執行檔安裝指令碼作為備援。當原生模組遺失或損毀時同樣可走這條路徑 — update 會在伺服器後端載入前先執行，因此損壞的安裝可以自行修復。在 Windows 上，安裝指令碼會將被鎖定的原生模組目錄移至一旁而非直接失敗，讓伺服器可在執行中自我更新。

​
解除安裝

解除安裝指令碼只會移除屬於 Buttress 的檔案 — 執行檔、原生模組目錄、狀態頁面與 MLX bridge 指令碼。由於該目錄與 BRICKS CLI 共用，目錄本身永遠不會被刪除。若您安裝在其他位置，請傳入 --dir / -InstallDir。

​
下一步

設定

設定 generator、快取與相容性端點。

工作區繫結

將伺服器與工作區配對並啟用 JWT 認證。