> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Buttress 進行推論

> 將 LLM 與語音辨識 generator 卸載至區域網路上的 Buttress 伺服器

BRICKS Foundation 可將 LLM、MLX 與語音辨識推論卸載至同一區域網路上的 [BRICKS Buttress](/zh-Hant/buttress) 伺服器。Brick 的 generator API 維持不變；當在伺服器執行更快（或本機根本無法執行）時，裝置會透明地將工作委派出去。

## 需求

* BRICKS Foundation 2.25 或更新版本
* 區域網路上可達的 Buttress 伺服器 — 請參閱 [Buttress 安裝](/zh-Hant/buttress/installation)
* 伺服器與裝置繫結至同一工作區 — 請參閱[工作區繫結](/zh-Hant/buttress/workspace-binding)

## 運作方式

1. 當裝置所屬工作區至少有一台已繫結的 Buttress 伺服器時，launcher 會啟動探索管理員並取得工作區範圍的 JWT。
2. 管理員監聽連接埠 `8089` 的 UDP 通告，並收集所有 `serverId` 出現於工作區繫結清單的伺服器。
3. 各 LLM、MLX 或 STT brick 讀取其 **Buttress (Remote Inference)** 屬性群組，自動挑選伺服器或使用手動設定的 URL。
4. 能力比較會決定要在本機、遠端或任一側執行；您於 brick 上選擇的策略則決定如何解讀該建議。

如果 launcher 無法連到伺服器（無區域網路、伺服器離線、工作區不符），它會回退到本機執行 — 除非您明確關閉此行為。

## 在 brick 上設定卸載

於 **BRICKS Controller** > **Config Editor** 開啟任一 LLM 或 STT brick。**Buttress (Remote Inference)** 屬性群組會出現於 **Connection** 之下。

| 欄位                | 預設值               | 效果                                                                     |
| ----------------- | ----------------- | ---------------------------------------------------------------------- |
| **Enabled**       | `false`           | 為此 brick 啟用 Buttress                                                   |
| **Auto-discover** | `Auto`            | `Auto` 透過 UDP 找伺服器；`Manual` 使用 URL 欄位                                  |
| **URL**           | 空                 | Auto-discover 為 `Manual` 時的 WebSocket URL（例如 `ws://buttress.lan:2080`） |
| **Strategy**      | `prefer-buttress` | 裝置在本機與遠端之間如何取捨                                                         |
| **Fallback**      | `no-op`           | Buttress 已啟用但無法連線時的處理方式                                                |

### 策略

| 策略                | 行為                             |
| ----------------- | ------------------------------ |
| `prefer-buttress` | 只要有可用伺服器即送至 Buttress，不會偵測本機硬體。 |
| `prefer-local`    | 若裝置記憶體足夠則於本機執行，否則回退至 Buttress。 |
| `prefer-best`     | 比較評分後，於較快的一側執行。                |

預設值為 `prefer-buttress`，因為選擇使用 Buttress 的 Foundation 裝置通常本機硬體並非最佳選擇。

### 回退

| 回退設定        | Buttress 已啟用但無法連線時的行為           |
| ----------- | ------------------------------- |
| `no-op`（預設） | brick 不會於本機執行任何動作 — 不下載模型、不執行完成 |
| `use-local` | brick 完全回退至本機執行，等同於關閉 Buttress  |

若您希望 brick 在區域網路中斷時仍能運作，請選擇 `use-local`；若您寧可看到明確失敗，也不願讓裝置於無法處理的模型上消耗電力，則保持 `no-op`。

## 工作區變更時

若裝置所屬工作區改變 — 例如管理員從 BRICKS Controller 重新指派 — launcher 會：

1. 停止目前的 Buttress 管理員並關閉所有開啟的 WebSocket 連線。
2. 捨棄已快取的 access token。
3. 以新工作區的繫結伺服器清單與新核發的 token 啟動新的管理員。

針對舊工作區認證的進行中 generator 會以乾淨的方式報錯，而不會陷入無限重連迴圈。

## 音訊上傳（STT）

語音辨識需要將音訊檔放在伺服器上。Brick 透過 HTTPS 上傳至 `POST /buttress/upload`，伺服器將檔案儲存於 `[server] temp_file_dir` 設定的暫存目錄（預設為 `<os-tmpdir>/.buttress`）。轉錄完成後，該檔會與 session 中其他暫存檔一併自動清理。

## 疑難排解

| 症狀                                         | 可能原因                       | 解決方式                                  |
| ------------------------------------------ | -------------------------- | ------------------------------------- |
| Brick 記錄出現 `no LAN provider is registered` | 裝置未繫結至工作區，或該工作區沒有任何已繫結的伺服器 | 繫結裝置，或以 `bricks buttress bind` 配對伺服器  |
| Brick 記錄出現 `no '<type>' endpoint yet`      | UDP 探索 10 秒內未回傳伺服器         | 確認伺服器在同一子網路，且 `[autodiscover]` 區段未被停用 |
| WebSocket 以 close code `1008` 關閉           | 裝置 token 與伺服器繫結的工作區不符      | 確認雙方位於同一工作區；重新啟動 launcher             |
| 啟用 Buttress 後 brick 「沒反應」                  | 回退設為 `no-op` 且無可達伺服器       | 將回退切換為 `use-local`，或修復區域網路連線          |
| Unknown generator id 錯誤                    | 伺服器重啟或淘汰了已載入模型             | brick 會在下一次呼叫時自動重新初始化 generator       |

## 相關文件

<CardGroup cols={2}>
  <Card title="Buttress 概覽" icon="server" href="/zh-Hant/buttress">
    Buttress 是什麼、何時使用，以及整體系統如何串接。
  </Card>

  <Card title="工作區繫結" icon="key" href="/zh-Hant/buttress/workspace-binding">
    伺服器與裝置如何繫結至同一工作區。
  </Card>
</CardGroup>