diff options
Diffstat (limited to 'doc/Specifications.md')
| -rw-r--r-- | doc/Specifications.md | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/doc/Specifications.md b/doc/Specifications.md new file mode 100644 index 0000000..3d2cd28 --- /dev/null +++ b/doc/Specifications.md @@ -0,0 +1,256 @@ +# Specifications.md + +## 1. 目的 + +本システムは、LLMがMCP経由でローカルGPU上のStable Diffusion 1.x互換モデルを利用して画像生成・画像誘導生成・インペイントを実行できるMCPサーバを提供する。 + +LLM側には生成意図に必要な最小限の入力のみを公開し、モデル構成・VAE・LoRA・ControlNet・生成パラメータなどの実行環境設定はMCPサーバ側で管理する。 + +--- + +## 2. スコープ + +| 区分 | 内容 | +|---|---| +| 対応モデル | Stable Diffusion 1.x互換モデル | +| モデル差し替え | 対応 | +| VAE差し替え | 対応 | +| LoRA | 複数指定・重み指定に対応 | +| ControlNet | ControlNet 1.1 Depth / Openpose / Inpaint | +| MCP経由のモデル変更 | 非対応 | +| モデル・生成設定 | TOML設定ファイルで管理 | +| CLI | `--config`, `--version` のみ | +| パッケージ管理 | uv | +| 実装言語 | Python 3.11 | +| GPU | NVIDIA CUDA GPUを主対象 | +| 主対象VRAM | 8GB級 | +| バッチ生成 | 1枚固定 | +| 同時生成 | 1ジョブのみ | +| 出力形式 | PNG | + +--- + +## 3. 機能要件 + +### 3.1 MCPツール + +| Tool | 用途 | 必須入力 | 任意入力 | +|---|---|---|---| +| `generate_image` | Text-to-Image | `positive_prompt` | `negative_prompt`, `size` | +| `generate_guided_image` | Depth / Openposeによる誘導生成 | `positive_prompt`, `control_mode`, `input_image` | `negative_prompt`, `size` | +| `inpaint_image` | 指定領域の再生成 | `positive_prompt`, `input_image`, `mask_image` | `negative_prompt`, `size` | + +### 3.2 `generate_image` + +| 項目 | 仕様 | +|---|---| +| positive_prompt | 必須文字列 | +| negative_prompt | 任意文字列。未指定時は空文字 | +| size | 許可済みサイズの列挙値 | +| 出力 | PNG画像1枚 | +| seed | 内部生成。結果メタデータへの記録は可 | + +### 3.3 `generate_guided_image` + +| 項目 | 仕様 | +|---|---| +| positive_prompt | 必須文字列 | +| negative_prompt | 任意文字列 | +| control_mode | `depth`, `openpose`, `openpose_full` | +| input_image | 必須 | +| size | 許可済みサイズの列挙値 | +| ControlNet同時利用 | 1種類のみ | + +### 3.4 `inpaint_image` + +| 項目 | 仕様 | +|---|---| +| positive_prompt | 必須文字列 | +| negative_prompt | 任意文字列 | +| input_image | 必須 | +| mask_image | 必須 | +| size | 許可済みサイズの列挙値 | +| 出力 | PNG画像1枚 | + +--- + +## 4. ControlNet要件 + +| モード | モデル | 入力 | 前処理 | +|---|---|---|---| +| Depth | ControlNet 1.1 Depth | 元画像 | Midas固定 | +| Openpose | ControlNet 1.1 Openpose | 元画像 | body | +| Openpose Full | ControlNet 1.1 Openpose | 元画像 | body + hand + face | +| Inpaint | ControlNet 1.1 Inpaint | 元画像 + mask | 専用Inpaint入力 | + +### 制約 + +| 項目 | 仕様 | +|---|---| +| Multi-ControlNet | 非対応 | +| Preprocessor選択 | MCPには公開しない | +| ControlNet strength | MCPには公開しない | +| ControlNetモデル切替 | 設定ファイルで管理 | +| GPU常駐 | 必要時ロード方式を許容 | + +--- + +## 5. 画像サイズ + +初期対応サイズはStable Diffusion 1.xの512px基準に限定する。 + +| ID | 解像度 | 用途 | +|---|---:|---| +| `square_512` | 512 x 512 | 標準 | +| `landscape_512` | 512 x 384 | 横長 | +| `portrait_512` | 384 x 512 | 縦長 | + +自由なwidth/height指定はMCPには公開しない。 + +--- + +## 6. モデル設定要件 + +### 6.1 設定方法 + +| 項目 | 仕様 | +|---|---| +| 設定形式 | TOML | +| 設定指定 | CLI `--config PATH` | +| デフォルト設定 | アプリケーション側で最小限保持可 | +| CLI上書き | 行わない | +| MCP経由変更 | 行わない | +| 起動時検証 | 必須 | + +### 6.2 モデル構成 + +| 項目 | 仕様 | +|---|---| +| Base checkpoint | 1ファイル | +| VAE | 0または1ファイル | +| LoRA | 0個以上 | +| LoRA weight | LoRAごとに指定 | +| ControlNet | Depth / Openpose / Inpaintを個別設定 | +| モデルルート | TOMLで1つのルートディレクトリを指定 | + +### 6.3 推奨ディレクトリ + +```text +models/ +├─ checkpoints/ +├─ vae/ +├─ lora/ +└─ controlnet/ +``` + +設定値には原則としてファイル名を記述し、内部で用途別ディレクトリへ解決する。 + +--- + +## 7. 設定ファイル仕様 + +例: + +```toml +[model] +root = "D:/AI/models" +checkpoint = "model.safetensors" +vae = "vae.safetensors" + +[[model.lora]] +file = "detail.safetensors" +weight = 0.8 + +[[model.lora]] +file = "style.safetensors" +weight = 0.5 + +[generation] +steps = 25 +cfg_scale = 7.0 +scheduler = "dpmpp_2m" +default_size = "square_512" + +[controlnet.depth] +enabled = true +model = "control_v11f1p_sd15_depth.safetensors" +preprocessor = "midas" + +[controlnet.openpose] +enabled = true +model = "control_v11p_sd15_openpose.safetensors" + +[controlnet.inpaint] +enabled = true +model = "control_v11p_sd15_inpaint.safetensors" + +[output] +directory = "./outputs" +``` + +--- + +## 8. CLI要件 + +| 引数 | 仕様 | +|---|---| +| `--config PATH` | 使用するTOML設定ファイルを指定 | +| `--version` | アプリケーションのバージョンを表示 | + +その他の実行設定はCLIでは提供しない。 + +--- + +## 9. 非機能要件 + +| 分類 | 要件 | +|---|---| +| VRAM | 8GB級GPUでの動作を主対象 | +| Precision | FP16を基本 | +| Batch | 1固定 | +| 同時実行 | 1生成のみ | +| キュー | 単一GPUキュー | +| ネットワーク | 推論時に外部通信を必須としない | +| モデルDL | 起動時の自動ダウンロードを前提としない | +| 異常系 | 設定不正・モデル不正は起動時エラー | +| ログ | 実行状態、モデル構成、エラーを記録 | +| 再現性 | seedを結果メタデータとして記録可能 | +| セキュリティ | 設定外パスへの任意アクセスを避ける | +| 保守性 | MCP層と画像生成層を分離 | + +--- + +## 10. 主要コンポーネント + +| コンポーネント | 役割 | +|---|---| +| Python 3.11 | 実装言語 | +| uv | Python・依存関係・仮想環境・lock管理 | +| MCP Python SDK | MCP server実装 | +| PyTorch | CUDA / Tensor実行 | +| Diffusers | SD1.x / VAE / LoRA / ControlNet統合 | +| Transformers | CLIP tokenizer / text encoder | +| PEFT | LoRA adapter管理 | +| Safetensors | モデルファイル読込 | +| Pillow | 画像入出力 | +| NumPy | 画像・前処理 | +| OpenCV | 必要な画像前処理 | +| tomllib | TOML設定読込 | +| pytest | テスト | +| Ruff | lint / format | +| Pyright | 静的型チェック | + +--- + +## 11. 完了条件 + +| ID | 完了条件 | +|---|---| +| G1 | TOMLからcheckpoint / VAE / 複数LoRAをロードできる | +| G2 | `generate_image`でPNG画像を1枚生成できる | +| G3 | Depth / Openpose / Openpose Full生成が動作する | +| G4 | Inpaintが元画像+maskから動作する | +| G5 | 3ツールすべてMCP経由で呼び出せる | +| G6 | 同時生成が1ジョブに制御される | +| G7 | 不正設定・不正モデル時に起動失敗する | +| G8 | GPU不要の設定・schemaテストが自動実行できる | |