> ## 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` で渡された 1 つの 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 リスナー（ポート、ログレベル、ボディ上限） |
| `[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 単位の値が優先され、それ以外はここで定義した値が適用されます。

```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 認証トークン。未設定なら `$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 処理をスキップできます。

```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` は `{cache_dir}/mlx-session-cache/` に別の session cache を持ち、generator ごとに個別設定されます。

## `[[generators]]`

各 `[[generators]]` ブロックは、サーバーがホストする 1 つのモデルを宣言します。複数モデルを提供する場合はブロックを繰り返します。各ブロックには `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 リポジトリ（`org/repo`）  |
| `revision`    | string  | デフォルト `"main"`                  |
| `download`    | boolean | サーバー起動時に事前ダウンロード（デフォルト `false`） |

**ggml-llm** と **ggml-stt** のみで尊重されます（mlx-llm は量子化をリポジトリ自体から取得するため、以下のキーは無視されます）：

| キー                        | 型         | 説明                                                                          |
| ------------------------- | --------- | --------------------------------------------------------------------------- |
| `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）

```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）** — 同じリポジトリから対応する `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 decoding**

| キー                   | 型      | 説明                    |
| -------------------- | ------ | --------------------- |
| `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）

```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` に設定すると、GPU が利用可能でも CPU を強制                                                       |
| `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 アダプタディレクトリ                               |
| `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 デバイスから検出可能にします。自動検出はデフォルトで有効です。

```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` に設定すると検出が完全に無効になります。プロトコルの詳細は[自動検出リファレンス](/ja/buttress/autodiscovery)を参照してください。

## `[env]`

起動時に適用する環境変数。ただしシステム環境にまだ設定されていない場合のみ反映されます。システム変数とコマンドラインの export が優先されます。

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

ggml バックエンドが読むのは `HUGGINGFACE_TOKEN` です（`HF_TOKEN` ではありません）。変数名に依存せず単一の token をすべてのバックエンドに適用したい場合は、代わりに `[runtime] huggingface_token` を設定してください。

## 互換エンドポイント

<Info>
  これらのエンドポイントは実験的機能です。スキーマ、エラー形式、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="/ja/buttress/workspace-binding">
    サーバーを BRICKS ワークスペースとペアリングして認証を有効化します。
  </Card>

  <Card title="LAN 自動検出" icon="broadcast-tower" href="/ja/buttress/autodiscovery">
    Foundation デバイスが LAN 上でサーバーを見つける仕組み。
  </Card>
</CardGroup>