Buttress サーバーは --config で渡された 1 つの 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 リスナー（ポート、ログレベル、ボディ上限） |
[runtime] | すべての generator が共有するデフォルト値 |
[runtime.session_cache] | ggml-llm 用の KV cache 再利用ストア |
[autodiscover] | LAN UDP / HTTP の検出スイッチ |
[openai_compat] | OpenAI 互換 HTTP ルートを有効化 |
[anthropic_messages] | Anthropic 互換 HTTP ルートを有効化 |
[[generators]] | generator インスタンスの配列。1 エントリ＝1 モデル |
[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 認証トークン。未設定なら $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 | コンテキストウィンドウ（per-model 値が優先、訓練時のコンテキストで自動的に上限が掛かります） |
n_gpu_layers | number または "auto" | GPU にオフロードするレイヤー数（デフォルト "auto"） |
n_batch | number | Prompt バッチサイズ。注意: モデル層の n_batch デフォルトは 512 で、[generators.model] で明示的に n_batch を設定しない限り runtime 値を覆い隠します |
n_ubatch | number | Prompt マイクロバッチサイズ |
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 の dtype（f16、f32、q8_0、q4_0 など） |
kv_unified | boolean | 複数シーケンスで KV cache を統一 |
swa_full | boolean | sliding-window レイヤーでもフルアテンションを展開 |
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 接頭辞を持つ後続の completion で 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 は {cache_dir}/mlx-session-cache/ に別の session cache を持ち、generator ごとに個別設定されます。
[[generators]]
各 [[generators]] ブロックは、サーバーがホストする 1 つのモデルを宣言します。複数モデルを提供する場合はブロックを繰り返します。各ブロックには 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 リポジトリ（org/repo） |
revision | string | デフォルト "main" |
download | boolean | サーバー起動時に事前ダウンロード（デフォルト false） |
| キー | 型 | 説明 |
|---|
filename | string | リポジトリ内の特定ファイルを指定 |
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 | ローカルファイルをロードパスとして使用。リポジトリのメタデータは引き続き 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） — 同じリポジトリから対応する 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 | 視覚トークン最小値（動的解像度モデル、-1 は未設定） |
mmproj_image_max_tokens | number | 視覚トークン最大値（-1 は未設定） |
| キー | 型 | 説明 |
|---|
speculative | string | Draft モデル識別子 |
spec_type | string | 戦略（バックエンド定義） |
spec_draft_n_max | int | 1 ステップあたりの最大ドラフトトークン数 |
spec_draft_n_min | int | 最小ドラフトトークン数 |
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 に設定すると、GPU が利用可能でも CPU を強制 |
use_flash_attn | string または boolean | "auto" | "on"、"off"、"auto"。true / false も省略形として受け付け。"auto" は GPU 使用時に flash-attn を有効化 |
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 アダプタディレクトリ |
vlm | "auto" または boolean | "auto" | VLM（true）かテキスト専用（false）を強制。"auto" はリポジトリから推測 |
tokenizer_config | table | — | mlx_lm.load(..., tokenizer_config=...) に転送 |
model_config | table | — | mlx_lm.load(..., model_config=...) に転送 |
quantization、filename、preferred_quantizations は使われません。量子化は MLX リポジトリ自体が決定します。
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 で自身を通知し、同じ LAN の 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]
起動時に適用する環境変数。ただしシステム環境にまだ設定されていない場合のみ反映されます。システム変数とコマンドラインの export が優先されます。
[env]
HUGGINGFACE_TOKEN = "hf_..."
CUDA_VISIBLE_DEVICES = "0"
HUGGINGFACE_TOKEN です（HF_TOKEN ではありません）。変数名に依存せず単一の token をすべてのバックエンドに適用したい場合は、代わりに [runtime] huggingface_token を設定してください。
互換エンドポイント
これらのエンドポイントは実験的機能です。スキーマ、エラー形式、CORS デフォルトは変更される可能性があります。
[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。
次のステップ
ワークスペースバインディング
サーバーを BRICKS ワークスペースとペアリングして認証を有効化します。
LAN 自動検出
Foundation デバイスが LAN 上でサーバーを見つける仕組み。
