> ## 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 伺服器的 TOML 設定參考

Buttress 伺服器透過 `--config` 讀取單一 TOML 檔案。每個區段皆為選填，省略時會使用預設值。

## 最小範例

```toml theme={null}
[server]
port = 2080

[[generators]]
type = "ggml-llm"
[generators.model]
repo_id = "ggml-org/gpt-oss-20b-GGUF"
quantization = "mxfp4"
n_ctx = 12800
```

## 頂層區段

| 區段                        | 用途                                   |
| ------------------------- | ------------------------------------ |
| `[env]`                   | 環境變數，**僅在尚未設定時**寫入處理程序               |
| `[server]`                | HTTP/WebSocket 監聽器（連接埠、日誌等級、Body 上限） |
| `[runtime]`               | 所有 generator 共用的預設值                  |
| `[runtime.session_cache]` | `ggml-llm` 的 KV cache 重用儲存           |
| `[autodiscover]`          | 區域網路 UDP / HTTP 探索開關                 |
| `[openai_compat]`         | 啟用 OpenAI 相容 HTTP 路由                 |
| `[anthropic_messages]`    | 啟用 Anthropic 相容 HTTP 路由              |
| `[[generators]]`          | generator 實例陣列，每個項目對應一個載入的模型         |

## `[server]`

| 鍵                 | 型別              | 預設值                            | 說明                                    |
| ----------------- | --------------- | ------------------------------ | ------------------------------------- |
| `id`              | string          | `buttress-<machineId>`         | 用於繫結與探索的穩定伺服器 id                      |
| `name`            | string          | `Buttress Server (<short id>)` | 顯示於 BRICKS Controller 的友善名稱           |
| `port`            | number          | `2080`                         | HTTP/WebSocket 連接埠（會被 `--port` 覆寫）    |
| `log_level`       | string          | 未設定                            | `debug`、`info`、`warn` 或 `error`       |
| `max_body_size`   | number 或 string | `"50MB"`                       | 最大上傳大小；接受 `"100MB"`、`"1GB"` 或原始位元組數   |
| `session_timeout` | number 或 string | `60000`                        | WebSocket 閒置逾時（毫秒）；也接受 `"1m"`、`"30s"` |
| `temp_file_dir`   | string          | `$TMPDIR/.buttress`            | STT 音訊上傳與其他暫存檔案的目錄                    |

## `[runtime]`

所有 generator 共用的預設值。`[generators.model]` 下的逐項 generator 設定會優先生效，否則套用這裡的預設值。

```toml theme={null}
[runtime]
cache_dir = "~/.buttress/models"
huggingface_token = "hf_..."
n_gpu_layers = "auto"
```

| 鍵                             | 型別                | 說明                                                                                                      |
| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| `cache_dir`                   | string            | 模型與中繼資料快取根目錄（預設 `~/.buttress/models`）                                                                   |
| `huggingface_token`           | string            | Hugging Face 認證 token；若未設定會回退至 `$HUGGINGFACE_TOKEN`。**所有**後端都會套用，無關環境變數名稱                               |
| `http_headers`                | table             | 附加於 Hugging Face / HTTP 下載的額外標頭                                                                         |
| `context_release_delay_ms`    | number            | 卸載 context 前的閒置時間（預設 `10000`；`0` 代表立即卸載）                                                                |
| `prefer_variants`             | string\[]         | 覆寫後端 variant 探測順序（ggml 後端）                                                                              |
| `n_threads`                   | number            | CPU 執行緒數                                                                                                |
| `n_ctx`                       | number            | Context window（per-model 值優先；會自動限制在訓練 context 範圍內）                                                      |
| `n_gpu_layers`                | number 或 `"auto"` | 卸載到 GPU 的層數（預設 `"auto"`）                                                                                |
| `n_batch`                     | number            | Prompt batch 大小。**注意：** 模型層的 `n_batch` 預設值為 `512`，會遮蔽 runtime 值，除非在 `[generators.model]` 明確設定 `n_batch` |
| `n_ubatch`                    | number            | Prompt micro-batch 大小                                                                                   |
| `n_parallel`                  | number            | 平行序列數（預設 `4`）                                                                                           |
| `n_cpu_moe`                   | number            | 卸載到 CPU 的 MoE 專家層數                                                                                      |
| `flash_attn_type`             | string            | `"on"`、`"off"` 或 `"auto"`。預設值依 GPU 而定：選用 GPU 後端時為 `"auto"`，CPU 時為 `"off"`                               |
| `cache_type_k`、`cache_type_v` | string            | KV cache 資料型別（`f16`、`f32`、`q8_0`、`q4_0`…）                                                               |
| `kv_unified`                  | boolean           | 跨序列共用統一 KV cache                                                                                        |
| `swa_full`                    | boolean           | 即使是 sliding-window 層也展開完整 attention                                                                     |
| `ctx_shift`                   | boolean           | 允許 llama.cpp 的滾動 context shift                                                                          |
| `use_mmap`、`use_mlock`        | boolean           | 記憶體映射 / 鎖定                                                                                              |
| `no_extra_bufts`              | boolean           | 停用額外運算 buffer 型別                                                                                        |
| `cpu_mask`、`cpu_strict`       | string / boolean  | CPU 親和性（進階）                                                                                             |
| `devices`                     | string\[]         | 限制使用特定 GGML 裝置                                                                                          |
| Speculative 鍵                 | various           | `speculative`、`spec_type`、`spec_draft_n_max`、`spec_draft_n_min`、`spec_draft_p_min`、`spec_draft_p_split` |

## `[runtime.session_cache]`

針對 `ggml-llm` generator，伺服器可在請求之間保留 KV cache 狀態，讓共用相同 prompt 前綴的後續完成可省略 prompt 處理。

```toml theme={null}
[runtime.session_cache]
enabled = true
max_size_bytes = "10GB"
max_entries = 1000
```

| 鍵                | 預設值      | 說明                              |
| ---------------- | -------- | ------------------------------- |
| `enabled`        | `true`   | 啟用持久化的 KV cache                 |
| `max_size_bytes` | `"10GB"` | 磁碟總預算；接受 `"500MB"`、`"50GB"` 或數值 |
| `max_entries`    | `1000`   | 最大快取項目數（採 LRU 淘汰）               |

快取檔案存放於 `{cache_dir}/.session-state-cache/`。

`mlx-llm` 使用獨立的 session cache，位於 `{cache_dir}/mlx-session-cache/`，每個 generator 個別設定。

## `[[generators]]`

每個 `[[generators]]` 區段宣告一組伺服器要提供的模型。可重複多次以提供多個模型。每個區段都包含 `type`、可選的 `[generators.backend]` 表，以及 `[generators.model]` 表。

```toml theme={null}
[[generators]]
type = "ggml-llm"

[generators.backend]
# 後端選擇與資源規劃

[generators.model]
repo_id = "..."
# 模型識別與 runtime 覆寫
```

### 共用 `[generators.model]` 鍵

**所有** generator 類型（`ggml-llm`、`ggml-stt`、`mlx-llm`）都適用：

| 鍵             | 型別      | 說明                            |
| ------------- | ------- | ----------------------------- |
| `repo_id`（必填） | string  | Hugging Face repo（`org/repo`） |
| `revision`    | string  | 預設 `"main"`                   |
| `download`    | boolean | 啟動時預先下載（預設 `false`）           |

僅 **ggml-llm** 與 **ggml-stt** 適用（mlx-llm 的量化由 repo 本身決定，會忽略以下鍵）：

| 鍵                         | 型別        | 說明                                                         |
| ------------------------- | --------- | ---------------------------------------------------------- |
| `filename`                | string    | 指定 repo 內的特定檔案                                             |
| `url`                     | string    | 直接下載 URL（略過 manifest 查詢）                                   |
| `quantization`            | string    | 偏好的量化標籤，例如 `q4_0`、`q8_0`、`mxfp4`                           |
| `preferred_quantizations` | string\[] | 當 `quantization` 不符時的有序回退清單（別名：`quantizations`）            |
| `allow_local_file`        | boolean   | 使用 `local_path` 或 `mmproj_local_path` 時必須啟用                |
| `local_path`              | string    | 將本機檔案作為載入路徑。Repo 中繼資料仍會從 Hugging Face 解析，因此 `repo_id` 仍為必填 |
| `api_base`、`base_url`     | string    | 覆寫 Hugging Face API / blob 主機（鏡像或代理）                       |

### `ggml-llm`（llama.cpp / GGUF）

```toml theme={null}
[[generators]]
type = "ggml-llm"

[generators.backend]
variant_preference = ["cuda", "vulkan", "default"]
gpu_memory_fraction = 0.95

[generators.model]
repo_id = "ggml-org/gpt-oss-20b-GGUF"
quantization = "mxfp4"
n_ctx = 12800
download = true
```

`[generators.backend]` 僅控制後端選擇與資源規劃。Runtime 覆寫（`n_ctx`、`n_gpu_layers`、`flash_attn_type` 等）請放在 `[generators.model]` 下。

**`[generators.backend]`**

| 鍵                     | 型別        | 預設值                                           | 說明                                          |
| --------------------- | --------- | --------------------------------------------- | ------------------------------------------- |
| `variant`             | string    | auto                                          | 強制 `cuda`、`vulkan`、`snapdragon` 或 `default` |
| `variant_preference`  | string\[] | `["cuda", "vulkan", "snapdragon", "default"]` | 未設定 `variant` 時的探測順序                        |
| `gpu_memory_fraction` | number    | `0.85`                                        | 硬體 guardrails 可規劃的最大 GPU 比例                 |
| `cpu_memory_fraction` | number    | `0.5`                                         | CPU 端 buffer 可用的最大 RAM 比例                   |

**`[generators.model]`** — 除了上述共用 ggml 鍵外，每個 `[runtime]` 鍵都可在 generator 層覆寫：`n_ctx`、`n_gpu_layers`、`n_batch`、`n_ubatch`、`n_threads`、`n_parallel`、`n_cpu_moe`、`flash_attn_type`、`cache_type_k`、`cache_type_v`、`kv_unified`、`swa_full`、`ctx_shift`、`use_mmap`、`use_mlock`、`no_extra_bufts`、`cpu_mask`、`cpu_strict`、`devices`。

**多模態（mtmd）** — 從同一 repo 自動下載對應的 `mmproj-*.gguf`：

| 鍵                         | 型別      | 說明                                             |
| ------------------------- | ------- | ---------------------------------------------- |
| `enable_mtmd`             | boolean | 預設 `false`                                     |
| `mmproj_filename`         | string  | 指定特定的 projector 檔案                             |
| `mmproj_url`              | string  | 直接覆寫 URL                                       |
| `mmproj_local_path`       | string  | 本機 projector 檔案（需設定 `allow_local_file = true`） |
| `mmproj_use_gpu`          | boolean | 未設定 = 自動（`n_gpu_layers > 0` 時為 true）           |
| `mmproj_image_min_tokens` | number  | 視覺 token 下限（動態解析度模型；`-1` 代表未設定）                |
| `mmproj_image_max_tokens` | number  | 視覺 token 上限（`-1` 代表未設定）                        |

**Speculative decoding**

| 鍵                    | 型別     | 說明             |
| -------------------- | ------ | -------------- |
| `speculative`        | string | Draft 模型識別碼    |
| `spec_type`          | string | 策略（後端定義）       |
| `spec_draft_n_max`   | int    | 每步最大草稿 token 數 |
| `spec_draft_n_min`   | int    | 最小草稿 token 數   |
| `spec_draft_p_min`   | number | 最低接受機率         |
| `spec_draft_p_split` | number | 分割門檻           |

### `ggml-stt`（whisper.cpp）

```toml theme={null}
[[generators]]
type = "ggml-stt"

[generators.backend]
variant_preference = ["cuda", "vulkan", "default"]

[generators.model]
repo_id = "BricksDisplay/whisper-ggml"
filename = "ggml-large-v3-turbo-q8_0.bin"
use_gpu = true
use_flash_attn = "on"
download = true
```

**`[generators.backend]`**

| 鍵                     | 型別        | 預設值                             | 說明                             |
| --------------------- | --------- | ------------------------------- | ------------------------------ |
| `variant`             | string    | auto                            | 強制 `cuda`、`vulkan` 或 `default` |
| `variant_preference`  | string\[] | `["cuda", "vulkan", "default"]` | 探測順序                           |
| `gpu_memory_fraction` | number    | `0.85`                          |                                |
| `cpu_memory_fraction` | number    | `0.5`                           |                                |

**`[generators.model]`** — 除了上述共用 ggml 鍵外：

| 鍵                         | 型別               | 預設值                            | 說明                                                                                  |
| ------------------------- | ---------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| `repo_id`                 | string           | `"BricksDisplay/whisper-ggml"` | 已設定預設值（與 `ggml-llm` 不同）                                                             |
| `preferred_quantizations` | string\[]        | `["q8_0", <no-quant>, "q5_1"]` | 預設回退鏈                                                                               |
| `use_gpu`                 | boolean          | `true`                         | 設為 `false` 可強制使用 CPU，即使有可用 GPU                                                      |
| `use_flash_attn`          | string 或 boolean | `"auto"`                       | `"on"`、`"off"` 或 `"auto"`。也接受 `true` / `false` 作為簡寫。`"auto"` 在使用 GPU 時啟用 flash-attn |

**Runtime 額外設定** — 僅 `ggml-stt` 適用，放在 `[runtime]` 下：

| 鍵             | 型別     | 說明                    |
| ------------- | ------ | --------------------- |
| `max_threads` | number | 限制 whisper.cpp 的執行緒上限 |

### `mlx-llm`（Apple Silicon）

```toml theme={null}
[[generators]]
type = "mlx-llm"

[generators.model]
repo_id = "mlx-community/Qwen2.5-VL-3B-Instruct-4bit"
vlm = true
download = true
```

`mlx-llm` 不使用 `[generators.backend]` 區段。

首次使用時，後端會在 `{cache_dir}/mlx-env` 建立 Python virtualenv，並安裝 `mlx_lm_package`、`mlx_vlm_package`，以及部分 VLM 處理器所需的 `torch` 與 `torchvision`。若既有 venv 已可匯入 `mlx_vlm` 與 `torch`，安裝步驟會跳過。

**`[generators.model]`** — 共用的 `repo_id` / `revision` / `download` 之外：

| 鍵                  | 型別                 | 預設值      | 說明                                              |
| ------------------ | ------------------ | -------- | ----------------------------------------------- |
| `adapter_path`     | string             | —        | 本機 LoRA adapter 目錄                              |
| `vlm`              | `"auto"` 或 boolean | `"auto"` | 強制 VLM（`true`）或純文字（`false`）；`"auto"` 會依 repo 推斷 |
| `tokenizer_config` | table              | —        | 轉發給 `mlx_lm.load(..., tokenizer_config=...)`    |
| `model_config`     | table              | —        | 轉發給 `mlx_lm.load(..., model_config=...)`        |

`quantization`、`filename` 與 `preferred_quantizations` **不會**使用，量化由 MLX repo 本身決定。

**Runtime 額外設定** — `mlx-llm` 適用，放在 `[runtime]` 下：

| 鍵                 | 型別     | 預設值                   | 說明                   |
| ----------------- | ------ | --------------------- | -------------------- |
| `mlx_env_dir`     | string | `{cache_dir}/mlx-env` | 自動管理的 Python venv 位置 |
| `mlx_lm_package`  | string | `"mlx-lm==0.31.1"`    | 配置 venv 時使用的 pip 規格  |
| `mlx_vlm_package` | string | `"mlx-vlm==0.4.0"`    | 配置 venv 時使用的 pip 規格  |

## `[autodiscover]`

伺服器會於 UDP `8089` 廣播自己，以便相同區域網路上的 Foundation 裝置能找到。預設啟用自動探索。

```toml theme={null}
[autodiscover]
[autodiscover.udp]
port = 8089

[autodiscover.udp.announcements]
enabled = true
interval = 5000

[autodiscover.udp.requests]
enabled = true
responseDelay = 100

[autodiscover.http]
enabled = true
path = "/buttress/info"
cors = true
```

設為 `autodiscover = false` 可完全停用自動探索。協定細節請參閱[自動探索參考](/zh-Hant/buttress/autodiscovery)。

## `[env]`

啟動時套用的環境變數，但僅在系統環境中尚未設定時生效。系統變數與命令列匯出值的優先順序更高。

```toml theme={null}
[env]
HUGGINGFACE_TOKEN = "hf_..."
CUDA_VISIBLE_DEVICES = "0"
```

ggml 後端讀取的是 `HUGGINGFACE_TOKEN`（並非 `HF_TOKEN`）。若希望單一 token 套用至所有後端而與變數名稱無關，請改設 `[runtime] huggingface_token`。

## 相容性端點

<Info>
  以下端點為實驗性功能，schema、錯誤格式與 CORS 預設值未來可能變動。
</Info>

伺服器除原生 WebSocket RPC 外，可額外開放 OpenAI 與 Anthropic 相容的 HTTP 路由。每項皆需明確啟用。

```toml theme={null}
[openai_compat]
enabled = true
# cors_allowed_origins = "*"

[anthropic_messages]
enabled = true
# cors_allowed_origins = ["http://localhost:3000"]
```

| 端點                                                  | 設定旗標                                  |
| --------------------------------------------------- | ------------------------------------- |
| `POST /oai-compat/v1/chat/completions`              | `[openai_compat] enabled = true`      |
| `GET /oai-compat/v1/models`                         | `[openai_compat] enabled = true`      |
| `POST /anthropic-messages/v1/messages`              | `[anthropic_messages] enabled = true` |
| `POST /anthropic-messages/v1/messages/count_tokens` | `[anthropic_messages] enabled = true` |

每項端點亦可透過環境變數啟用：`ENABLE_OPENAI_COMPAT_ENDPOINT=1` 或 `ENABLE_ANTHROPIC_MESSAGES_ENDPOINT=1`。

## 下一步

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

  <Card title="區域網路自動探索" icon="broadcast-tower" href="/zh-Hant/buttress/autodiscovery">
    Foundation 裝置如何於區域網路上找到您的伺服器。
  </Card>
</CardGroup>