--config 讀取單一 TOML 檔案。每個區段皆為選填，省略時會使用預設值。
最小範例
頂層區段
[server]
[runtime]
所有 generator 共用的預設值。[generators.model] 下的逐項 generator 設定會優先生效，否則套用這裡的預設值。
[runtime.session_cache]
針對 ggml-llm generator，伺服器可在請求之間保留 KV cache 狀態，讓共用相同 prompt 前綴的後續完成可省略 prompt 處理。
快取檔案存放於
{cache_dir}/.session-state-cache/。
mlx-llm 使用獨立的 session cache，位於 {cache_dir}/mlx-session-cache/，每個 generator 個別設定。
[[generators]]
每個 [[generators]] 區段宣告一組伺服器要提供的模型。可重複多次以提供多個模型。每個區段都包含 type、可選的 [generators.backend] 表，以及 [generators.model] 表。type 為 ggml-llm、ggml-stt、ggml-tts、ggml-decision、mlx-llm、onnx-stt 或 onnx-tts 其中之一。
共用 [generators.model] 鍵
所有 generator 類型（ggml-llm、ggml-stt、ggml-tts、ggml-decision、mlx-llm、onnx-stt、onnx-tts）都適用：
僅 ggml-llm、ggml-stt、ggml-tts 與 ggml-decision 適用。
mlx-llm 的量化由 repo 本身決定，而 ONNX 後端（onnx-stt、onnx-tts）改以 dtype 選擇權重，因此三者皆會忽略以下鍵：
ggml-llm（llama.cpp / GGUF）
[generators.backend] 僅控制後端選擇與資源規劃。Runtime 覆寫（n_ctx、n_gpu_layers、flash_attn_type 等）請放在 [generators.model] 下。
[generators.backend]
[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。
嵌入模型
專用的嵌入模型需要
embedding = true。本地函式中的 context.buttress.embedding 會拒絕未設定此鍵的 generator，因此請為嵌入模型建立獨立的 [[generators]] 區塊，不要沿用 chat 模型的設定。嵌入 context 只會執行單一原生序列，因此平行解碼 slot 對它不適用。僅載入詞彙表的 context 完全沒有運算後端，只能服務 tokenizer 呼叫。
同一個 repo 可以用不同模式載入多次 — chat、嵌入、僅詞彙表。每種模式在 generator 登錄表中都是獨立項目，因此某個使用者的 context 不會繼承另一個的設定。Vector Store brick 會從遠端驅動這兩個鍵，而不需要在這個檔案中出現。
多模態（mtmd） — 從同一 repo 自動下載對應的 mmproj-*.gguf：
Speculative decoding
ggml-stt（whisper.cpp）
[generators.backend]
snapdragon 變體會在 Hexagon NPU 上執行 Whisper。它適用於具備可運作 Qualcomm HTP/FastRPC 執行環境的 Linux arm64 主機，且不包含 OpenCL — 請以 --ggml-variant=snapdragon 安裝，預設的 CPU 組建會一併保留，供回退使用。此變體會隨附自己的 HTP 函式庫，載入器會將 ADSP_LIBRARY_PATH 指向該處，並將 GGML_HEXAGON_NDEV 設為 16，除非你自行設定這兩個變數。即使 use_flash_attn 為 "off"，Hexagon 仍一律啟用 flash attention。
語音轉文字的 Hexagon 加速為實驗性功能。
[generators.model] — 除了上述共用 ggml 鍵外：
Runtime 額外設定 — 僅
ggml-stt 適用，放在 [runtime] 下：
ggml-tts（llama.cpp + codec.cpp）
此後端未接上 phonemizer，因此 NeuTTS 收到的是原始文字而非音素 — 這與裝置端 generator 的限制相同。
[generators.backend]
[generators.model] — 除了上述共用 ggml 鍵外：
同時包含主幹模型與 codec 的 repo 會依檔名（
codec、vocoder、wavtokenizer、dac、mimi）區分。若某個 repo 存放多種不相關的 codec，僅靠量化偏好無法判斷，請明確設定 vocoder_filename。
Runtime 額外設定 — ggml-tts 放在 [generators.runtime] 下：
輸出快取 — 合成的 WAV 會快取於磁碟的
{cache_dir}/.tts-cache/，以文字 + 模型 + 選項為鍵，因此重複的語句可立即回傳。於 [generators.runtime.output_cache] 設定：
ggml-decision（llama.cpp 型別化決策）
choice、score 與 noul（是／否）問題。每個答案只需一次前向傳遞，不會產生任何 token。裝置透過 Typed Decision (GGML) Generator 使用它，本機函式則透過 context.buttress.decide 使用。
模型會在 context 載入時接受檢查。一般的 chat 模型，或決策類型不受此版本支援的決策模型，都會載入失敗並附上原因。同一個 generator 上的請求會逐一執行。
[generators.backend] — 與 ggml-tts 相同的鍵：variant、variant_preference、gpu_memory_fraction、cpu_memory_fraction。
[generators.model] — 除了上述共用 ggml 鍵外：
設定任一
mmproj_* 鍵就會載入投影器，之後請求即可以檔案路徑或 data URL 傳入圖片。若模型的提示詞沒有放置圖片的位置，伺服器會忽略投影器並記錄警告。
Runtime 額外設定 — ggml-decision 放在 [generators.runtime] 下：
mlx-llm（Apple Silicon）
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 之外：
quantization、filename 與 preferred_quantizations 不會使用，量化由 MLX repo 本身決定。
Runtime 額外設定 — mlx-llm 適用，放在 [runtime] 下：
onnx-stt（ONNX Runtime / Whisper）
onnx/ 子資料夾下載至 {cache_dir}/{owner}/{repo}/，後端會在回傳最終文字前串流部分轉錄結果。
[generators.backend]
若所有已設定的 provider 都無法初始化，generator 便無法啟動。
[generators.model]
Runtime 額外設定 — 放在
[generators.runtime] 下：
全域
[runtime] 鍵 cache_dir、huggingface_token 與 http_headers 亦適用。
onnx-tts（ONNX Runtime / Kokoro、VITS、SpeechT5）
onnx/ 子資料夾下載至 {cache_dir}/{owner}/{repo}/。
[generators.backend] — 與上方 onnx-stt 相同的鍵：provider、provider_preference、gpu_memory_fraction、cpu_memory_fraction。
[generators.model]
輸出快取 — 合成的音訊會快取於磁碟的
{cache_dir}/.tts-cache/，以文字 + 模型 + 選項為鍵，因此重複的語句可立即回傳。於 [generators.runtime.output_cache] 設定：
[generators.runtime] 的 prefer_providers 鍵，以及全域 [runtime] 鍵（cache_dir、huggingface_token、http_headers）的適用方式與 onnx-stt 相同。
[autodiscover]
伺服器會於 UDP 8089 廣播自己，以便相同區域網路上的 Foundation 裝置能找到。預設啟用自動探索。
autodiscover = false 可完全停用自動探索。協定細節請參閱自動探索參考。
[env]
啟動時套用的環境變數，但僅在系統環境中尚未設定時生效。系統變數與命令列匯出值的優先順序更高。
HUGGINGFACE_TOKEN（並非 HF_TOKEN）。若希望單一 token 套用至所有後端而與變數名稱無關，請改設 [runtime] huggingface_token。
相容性端點
以下端點為實驗性功能，schema、錯誤格式與 CORS 預設值未來可能變動。
每項端點亦可透過環境變數啟用：
ENABLE_OPENAI_COMPAT_ENDPOINT=1 或 ENABLE_ANTHROPIC_MESSAGES_ENDPOINT=1。
[functions]
本地函式屬於實驗性功能。端點、函式檔案契約與這些設定鍵都可能在版本之間變動。
.ts / .js 檔案公開為 MCP 工具與 HTTP 端點。預設關閉。
對應的環境變數：
ENABLE_FUNCTIONS_ENDPOINT=1、BUTTRESS_FUNCTIONS_DIR=<dir>、BUTTRESS_FUNCTIONS_HOT_RELOAD=1 與 BUTTRESS_FUNCTIONS_ALLOW_UNAUTHENTICATED=1。
檔案契約、注入的 context、端點與安全模型請參見本地函式。
[[agents]]
Agents 屬於實驗性功能。這些設定鍵、
/agents 端點以及 context.agents API 都可能在版本之間變動。[[agents]] 區段之前，此功能為關閉狀態。
未被辨識的鍵會直接傳遞給生成，因此
temperature 與 top_p 可照寫。
agent 定義會在啟動時驗證 — 錯誤的模型參照、工具名稱或提示檔案都會讓伺服器停止。
模型、工具、session、端點、CLI 與安全性模型請參閱 Agents。
下一步
工作區繫結
將伺服器與 BRICKS 工作區配對並啟用認證。
區域網路自動探索
Foundation 裝置如何於區域網路上找到您的伺服器。