設定 - BRICKS

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

最小範例

[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 設定會優先生效，否則套用這裡的預設值。

[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 處理。

[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] 表。

[[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）

[[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）

[[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）

[[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 裝置能找到。預設啟用自動探索。

[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 可完全停用自動探索。協定細節請參閱自動探索參考。

`[env]`

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

[env]
HUGGINGFACE_TOKEN = "hf_..."
CUDA_VISIBLE_DEVICES = "0"

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

相容性端點

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

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

[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。

設定

最小範例

頂層區段

`[server]`

`[runtime]`

`[runtime.session_cache]`

`[[generators]]`

共用 `[generators.model]` 鍵

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

`ggml-stt`（whisper.cpp）

`mlx-llm`（Apple Silicon）

`[autodiscover]`

`[env]`

相容性端點

下一步

工作區繫結

區域網路自動探索

​最小範例

​頂層區段

​[server]

​[runtime]

​[runtime.session_cache]

​[[generators]]

​共用 [generators.model] 鍵

​ggml-llm（llama.cpp / GGUF）

​ggml-stt（whisper.cpp）

​mlx-llm（Apple Silicon）

​[autodiscover]

​[env]

​相容性端點

​下一步

工作區繫結

區域網路自動探索

最小範例

頂層區段

`[server]`

`[runtime]`

`[runtime.session_cache]`

`[[generators]]`

共用 `[generators.model]` 鍵

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

`ggml-stt`（whisper.cpp）

`mlx-llm`（Apple Silicon）

`[autodiscover]`

`[env]`

相容性端點

下一步