> ## 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.

# 安裝

> 安裝並執行 BRICKS Buttress 伺服器

Buttress 伺服器透過 npm 發行，並提供單一執行檔 `bricks-buttress`。可在 macOS、Linux 與 Windows 上執行；若要在 Linux 上使用 GPU 加速，請先安裝 CUDA 或 Vulkan 驅動程式。

## 硬體需求

| 資源  | 建議規格                                                 |
| --- | ---------------------------------------------------- |
| GPU | NVIDIA（CUDA）、AMD/Intel（Vulkan）或 Apple Silicon（Metal） |
| RAM | 至少為您預計載入最大模型大小的 2 倍                                  |
| 磁碟  | `cache_dir` 中需有足夠空間存放所有要下載的模型                        |
| 網路  | 有線區域網路 — UDP broadcast 必須能抵達 Foundation 裝置           |

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

## 從 npm 安裝

需要 **Node.js 22+**（或 **Bun**）。

```bash theme={null}
npm install -g @fugood/buttress-server
```

此指令會將 `bricks-buttress` 執行檔安裝至您的 `PATH`。

<Tip>
  在全新的 Apple Silicon Mac 上，使用 Bun（`bun add -g @fugood/buttress-server`）可獲得更快的冷啟動速度與更低的記憶體用量。
</Tip>

## 啟動伺服器

無設定檔時，伺服器會以合理的預設值在連接埠 `2080` 啟動：

```bash theme={null}
bricks-buttress
```

搭配 TOML 設定檔：

```bash theme={null}
bricks-buttress --config ./config.toml
```

或以同一旗標傳入內嵌的 TOML 字串：

```bash theme={null}
bricks-buttress --config '[server]
port = 3000

[[generators]]
type = "ggml-llm"
[generators.model]
repo_id = "ggml-org/gemma-3-270m-qat-GGUF"'
```

完整設定結構請參閱[設定參考](/zh-Hant/buttress/configuration)。

## CLI 旗標

| 旗標                          | 說明                    |
| --------------------------- | --------------------- |
| `-p, --port <port>`         | 監聽的連接埠（預設 `2080`）     |
| `-c, --config <path\|toml>` | TOML 檔案路徑或內嵌的 TOML 字串 |
| `-v, --version`             | 顯示伺服器版本               |
| `-h, --help`                | 顯示說明                  |

連接埠的優先順序為：`--port` 旗標 → TOML 中的 `[server] port` → 預設 `2080`。

## 環境變數

| 變數                                   | 效果                               |
| ------------------------------------ | -------------------------------- |
| `NODE_ENV`                           | 設為 `development` 以輸出詳細記錄         |
| `ENABLE_OPENAI_COMPAT_ENDPOINT`      | 設為 `1` 以啟用 OpenAI 相容端點           |
| `ENABLE_ANTHROPIC_MESSAGES_ENDPOINT` | 設為 `1` 以啟用 Anthropic messages 端點 |
| `HF_TOKEN`                           | 用於下載受限模型的 Hugging Face token     |

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

## macOS GPU 記憶體

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

```bash theme={null}
# 於 128 GB 主機允許 GPU 使用最多 128 GB
sudo sysctl iogpu.wired_limit_mb=137438

# 還原預設
sudo sysctl iogpu.wired_limit_mb=0
```

## 確認運作

伺服器啟動時會印出可從區域網路連線的網址，例如 `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 端點：

```bash theme={null}
# 伺服器識別、能力、generator 清單、認證狀態
curl http://localhost:2080/buttress/info

# 即時 generator／佇列／歷史快照（與儀表板相同資料）
curl http://localhost:2080/buttress/status
```

`/buttress/info` 是 Foundation 裝置在 HTTP 回退探索時讀取的內容 — 請參閱[區域網路自動探索](/zh-Hant/buttress/autodiscovery)。

## 下一步

<CardGroup cols={2}>
  <Card title="設定" icon="gear" href="/zh-Hant/buttress/configuration">
    設定 generator、快取與相容性端點。
  </Card>

  <Card title="工作區繫結" icon="key" href="/zh-Hant/buttress/workspace-binding">
    將伺服器與工作區配對並啟用 JWT 認證。
  </Card>
</CardGroup>