Files

211 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# H3 Continuum 一時ストレージ設定 — 実装仕様 v1
作成日:2026-10-13
基準:V3.9.2 / `e9b1294ccd08dfce972cd8e5a11703b3f616ee54`
状態:V3.9.3の実装仕様。検証結果とプラットフォーム範囲は`../PACKAGE_VALIDATION.txt`を参照。
## 1. 目的と対象
Photoshopの仮想記憶ディスクに相当する、一時データの保存先指定を追加する。独自の仮想ディスクを作らず、ComfyUIサーバーに接続された別ストレージ上のフォルダーを利用する。
対象は次の二つ。
- FinalizeのDisk-backed IMAGEバッファ。
- Decode Cache Helperのディスクキャッシュ。
Run Storage、採用済みchunk、Take、State/Session、完成動画・音声、他の拡張機能の一時ファイルは対象外。保存先変更で生成条件、解像度、dtype、Sampling/Reference/Reviewの契約を変更しない。
一時データの移動は書き込み先の変更であり、総書き込み量を減らす機能ではない。物理ストレージが1台しかない場合、別フォルダーや別パーティションへ移しても、その機器への書き込みを逃がせない。ただし十分なRAMがある場合のRAM利用や、任意のDecode Cache無効化は別の対策として利用できる。
## 2. 設定画面
ComfyUIの設定に「H3Continuum → Storage → 一時ストレージを管理」を追加する。専用ノードやワークフロー内のパスwidgetは追加しない。
| 項目 | 確定した動作 |
| --- | --- |
| 保存先フォルダー | サーバー側の絶対パスを入力。空欄で既存の保存先を継承 |
| ストレージ候補 | サーバーで認識できるローカルボリューム/マウント先と空き容量を提示。選択すると保存先入力を補助 |
| 検証・保存 | サーバー上でパス、書き込み、mmap、容量取得を検証してから保存 |
| 保存先と使用量 | Finalize、Decode Cacheごとに実際のパスと管理対象ファイル量を表示 |
| 空き容量 | 各保存先のボリュームの現在の空き容量を表示 |
| 使用中/削除可能/判定不能 | 一時ファイルの状態を分けて表示。判定不能なファイルは保護 |
| 旧保存先 | この設定で登録した旧保存先に残る管理対象ファイル量も表示 |
| 更新 | 手動更新。設定画面を開いた時と保存・削除完了時にも更新 |
| 未使用の一時ファイルを削除 | 実行中は無効。サーバー側でも再検査して、安全と確認できた対象だけ削除 |
ブラウザー/モバイル端末のディスクではなく、ComfyUIが実行されているPC・サーバーのストレージを選ぶ。候補一覧が取得できないOSでも絶対パス入力で利用できる。SSD/HDDの種別を推測してラベル付けしない。異なるボリューム表示が異なる物理ディスクを意味するとは限らない。
表示するファイル量は論理ファイルサイズの合計。物理占有量、SSDの累計書き込み量、寿命指標ではないことを明記する。保存先の空き容量はファイルシステムから別途取得する。同じボリュームを使う二つの保存先の空き容量を加算しない。
描画callbackや常時タイマーでディスクを走査しない。画面表示・操作時に管理対象の範囲だけ確認し、ブラウザー側にイベントの重複登録を作らない。
API応答が404・空・不正な形式の場合は、その結果と再取得方法を表示する。候補欄は取得前から説明付きの幅を確保し、状態取得に成功するまで保存・削除を無効にする。更新で復帰でき、保存・削除リクエストを自動再送しない。起動ログにポート使用中エラーがある場合、旧プロセスが残って新しいPython側機能を起動できていない可能性を案内する。
## 3. 保存先の決定と既存動作
### 空欄
完全に既存の保存先を継承する。
- Finalize:ComfyUIのtemp配下の既存専用フォルダー。
- Decode Cache:既存の`H3_DECODE_CACHE_TEMP_DIR`指定があれば継承し、なければOSのtemp。
空欄のまま、二つの保存先を勝手に統一しない。ComfyUI全体のtemp設定やOSの環境変数を書き換えない。
### 指定あり
指定フォルダーの下に専用領域を作る。
```text
指定フォルダー/
h3-continuum-scratch/
finalize/ … 既存の.binと所有者情報を使用
decode/ … helperごとの私有ディレクトリと.npy
```
新しい設定がDecode Cacheの旧環境変数より優先する。内部テスト等が明示的に渡す`backing_root`や`temp_parent`の依存注入は維持する。
v1の対応先はサーバー上のローカルファイルシステム。ネットワーク共有・UNC・リモートマウントは正式対応外とし、明確に識別できる対象は保存時に拒否する。同期ツールや特殊なファイルシステムの適合性は、書き込み・mmapテストだけでは保証しない。RAMディスクは通常のローカル保存先として扱えるが、専用の作成・管理機能は追加しない。
保存時に正規化したパス、ボリューム識別情報、専用領域の識別情報を記録する。各ファイル作成前にも確認し、マウント解除により元のパスが別ボリュームへ変わった場合は利用しない。
## 4. 設定の保存と切替
- サーバー共通の設定としてComfyUIのsystem user領域に保存する。ブラウザーのローカル保存だけでバックエンドを制御しない。
- 設定本体と管理した保存先一覧は私有のJSONとし、atomic writeで更新する。インストール先、ワークフロー、公開READMEには利用者の実パスを保存しない。
- パス変更と保存はQueueが実行中・待機中でない場合に限る。検証と保存を分け、検証だけで有効設定を変えない。
- Finalize/Decodeの処理開始と設定切替・削除を共通の調停機構で制御する。各処理が取得した設定はその処理の終了まで保持する。
- 保存完了後の新規ファイルから新しい保存先を使う。ComfyUI再起動を必須にしない。
- 既存の一時ファイルは移動しない。旧出力のstorage/aliasやcache entryは、元の保存先と寿命管理を保持する。
- Decode Cacheは保存先の切替後、新規entryを新保存先へ作る。切替時に既存の参照中entryを削除しない。旧entryの安全な再利用・退役を維持する。
- 同じ設定ファイルを複数プロセスが変更する場合は、ファイルロックと設定revision照合で上書き競合を検出する。
- v1ではマルチユーザー運用時のUIからの共有保存先変更・削除を無効にする。共有サーバーの保存先は管理者がサーバー設定として管理する。既存のユーザープロファイルを管理者認証とみなさない。
指定先が使えない場合、元のSSD・OS tempへ黙って戻さない。Finalizeでディスクが必要なら明確なエラーにする。Decode Cacheだけが利用できない場合は、既存の方針に合わせてキャッシュをバイパスしてnative Decodeを続け、元の保存先へキャッシュを書かない。中断・native Decodeの例外はバイパスで隠さない。
## 5. RAM/Diskの選択と事前確認
新しい設定画面に別のRAM/Diskモードを作らず、既存ノードの選択を維持する。
| 対象とモード | 確定した動作 |
| --- | --- |
| Finalize / Auto | 既存の4 GiB境界とRAM安全余裕を維持。ディスクを選んだ場合に新保存先を使用 |
| Finalize / RAM | RAMを使用。確保前に安全余裕を検査し、不足・取得不能なら明確なエラー。ディスクへ自動変更しない |
| Finalize / Disk-backed | 指定先を使用。確保前に空き容量を検査し、不足ならエラー。RAMへ自動変更しない |
| Decode Cache / Auto | 既存のディスクキャッシュ方針とquotaを維持し、ファイルの保存先だけ変更 |
| Decode Cache / RAM | 既存のRAM予算・headroom判定を維持。保持できないentryはキャッシュしない。ディスクへ逃がさない |
| Decode Cache / Off | キャッシュ書き込みを行わない。Finalizeの保存方式は独立 |
Finalizeの必要バイト数`M`は、実際の出力shapeの要素数×実際のdtypeのバイト数で算出する。解像度と秒数だけの固定概算で判定しない。
RAM確保直前の判定は、既存のAutoと同じ余裕を基準にする。
```text
R = max(4 GiB, 物理RAM総量の10%)
利用可能RAM >= M + R
```
手動RAMにはAutoの4 GiB上限を適用しない。十分なRAMが確認できれば大きい出力も選択できる。Autoの4 GiB上限を引き上げる機能はv1に含めない。
Disk-backedの確保直前には、既存Autoと同じ`空き容量 >= M + 2 GiB`を確認する。設定保存時の小さなmmapテストは、将来の大容量確保が成功する保証として扱わない。
空き容量の検査は領域の予約ではない。検査後に別プロセスが容量を使う場合や、利用中のドライブが故障・切断する場合のI/O失敗を完全には防げない。メモリマップされた領域のI/O障害はOSによってプロセス終了につながる場合もある。v1で「誤設定やドライブ障害でもクラッシュしない」と保証しない。全領域を先にゼロ書き込みして二重の大量書き込みを発生させる対策は追加しない。
コンテナーのメモリ制限がある場合、ホストの空きRAMだけを根拠にしない。取得できる場合はプロセスに適用される制限と使用量も考慮し、より厳しい利用可能量を採用する。Autoの4 GiB/reserve方針自体は変えず、実効容量の取り方を検証する。
これはFinalizeの追加バッファを確保する前の確認であり、プロセス全体のOOM回避保証ではない。native VAE Decode、Sampling、下流ノードのコピー、並行処理、OSのページファイル利用まで制御しない。VRAMを一時ストレージにする機能は追加せず、GPUメモリ管理も変更しない。
RAM容量が取得不能な場合、Autoは既存どおりDisk-backedへ進む。手動RAMは安全確認不能として停止する。どちらの場合も選択理由と必要量を表示する。
## 6. 未使用ファイルの削除
「未使用」は生成が終わったことではなく、返したTensor/storage/aliasやcache mappingから参照されていないことを意味する。
- ブラウザーから削除パスを受け取らない。サーバーが登録・確認した保存先と、Continuum所有と確認できるファイルだけを対象にする。
- 使用中のFinalize buffer、未公開の作成中buffer、参照中cache、別の生存プロセスのファイルを保護する。
- Finalizeは既存のstorage寿命追跡、root lock、owner PID+process creation timeを再利用する。UI削除では、owner/sidecarが欠損・不正・判定不能なファイルを削除しない。
- Decode Cacheはstore lockの下で未参照のディスクentryを管理表から退役させて削除する。単に.npyをunlinkして管理表を残さない。RAMキャッシュはこのボタンの対象外。
- 参照中entryと削除保留entryはleaseが切れるまで残す。削除のために出力キャッシュを強制解放したり、gcを強制実行したりしない。
- 新しいDecode Cache私有ディレクトリに所有者情報と排他制御を追加する。前回異常終了のファイルは、所有者が終了したと確認できた範囲だけ削除する。
- 所有者情報がない既存のDecode Cacheディレクトリは、現在のstoreで管理しているファイル以外は自動削除しない。ファイル名のprefixだけを根拠にしない。
- シンボリックリンク/junctionによる管理対象外への遷移をたどらない。設定先の解決結果を記録し、削除時に専用領域の同一性を確認する。
- root・store lockと共通調停で作成/読み込み/削除の競合を防ぐ。他プロセスが現在書いている中間ファイルを削除しない。
- 結果は削除数、削除した論理バイト数、使用中・判定不能・削除失敗の残数を報告する。失敗は保留し、使用中ファイルの強制削除へ切り替えない。
管理対象外のファイル、Run/Take、保存動画、他のComfyUI一時データは削除しない。一時領域全体の再帰削除を実装しない。キャッシュを削除すると次の利用時に再デコード・再書き込みが必要になり得ることも説明する。
## 7. 実装するファイルと責務
| ファイル | 具体的な変更 |
| --- | --- |
| `storage_settings.py` | サーバー共通設定、保存先の検証・解決、管理領域の識別、保存先一覧、調停、容量probeを実装。Tensorの強参照を持たない |
| `storage_api.py` | 設定表示・検証・保存・使用量・削除を提供。登録済み管理対象以外を削除しない |
| `web/storage_settings.js` | ComfyUI設定に操作画面を登録。保存先と実際の使用状態、エラー、削除結果を表示 |
| `storage_fs.py` / `storage_memory.py` | privateファイル・所有者・atomic write・プロセス間lock・cgroupを考慮したRAM取得を担当 |
| `__init__.py` | ComfyUI実ランタイム時だけAPIを一度登録。standalone/offline importを壊さない |
| `v3/file_backed_buffer.py` | 保存先resolverを共通設定へ接続。既存の明示`backing_root`、Auto方針と寿命管理を維持。手動RAM/Diskのpreflightを追加 |
| `v3/assembly_v35.py` | 新規出力確保前に保存先・メモリ・ディスクpreflightを呼ぶ。フレームコピー/Seam/音声の計算は変更しない |
| `tools/p20_file_backed_tensor_poc.py` | 読み取り専用の管理状況取得と、UI向け保守的削除経路を追加。alias寿命追跡と既存sidecarの互換性を維持 |
| `decode_cache/store.py` | 保存先切替、所有者記録、weakなstore登録、状態取得と未参照entry削除を実装。既存key・digest・dtype・quotaは維持 |
| `decode_cache/nodes.py` | helper実行開始時に有効な保存先設定を取得し、storeへ適用。入力widget・既定値・登録IDは変更しない |
| `README.md` / `README_JA.md` | 設定手順、1台構成の限界、HDDの速度、RAM・ページファイル、削除の意味を説明 |
| tests / manifest類 | 新しい安全性・互換性の試験を追加。実装時に既存配布manifestを更新・検証 |
APIは`/h3-continuum/storage/`配下とし、`GET status`、`POST validate`、`POST settings`、`POST cleanup`で役割を分ける。UIは設定revisionを指定して保存し、古いrevisionや実行中の保存/削除は競合として拒否する。読み取りのstatusから削除やcache clearを起こさない。
既存のSampling・Run Storage・State/Session・Referenceの処理は変更しない。公式ワークフローJSON/ZIP、ノードID、socket/widget順序、既存のDecode Cache identityは維持する。Experimental 3、Review From Chunkの仕様は本件に含めない。
## 8. READMEへ必ず記載する内容
1. 別の物理ストレージへの移動は書き込み先を変える機能であり、総書き込み量を減らさない。
2. 物理ストレージが1台の場合、保存先変更で別機器へ書き込みを移すことはできない。同じSSDの別パーティションも同様。
3. HDDは使用できるが、Decode・結合・保存の速度が低下する場合がある。
4. RAMは十分な余裕がある場合に限って利用する。事前確認があってもOOMやページファイルへの書き込みを完全には防げない。
5. 一時保存先はComfyUIサーバー側。保存先を変えても旧ファイルは移動しない。
6. 削除は容量の解放であり、既に発生したSSD書き込みを取り消すものではない。キャッシュ削除は次回の再書き込みを増やす場合がある。
7. FinalizeとDecode Cacheは独立したモード。CacheをOffにするだけではFinalizeのDisk-backedを無効にしない。
8. RAMディスクのデータは再起動で失われる。Run/Takeや完成動画を一時領域と混同しない。
9. 現在の設定・直近の実行で選ばれたbackend・管理対象ファイル量を区別する。Autoを常にSSD使用と説明しない。
10. RAM/ディスクの事前検査は安全性を高めるものであり、実行中のメモリ変動、ディスク容量変動・切断による失敗を完全には防がない。
実装前にスクリーンショットを作成しない。実装後、ユーザー提供の実画面をREADMEへ掲載する。
## 9. 検証と完了条件
### CPU/ファイルシステム
- 空欄時のFinalize/Decode Cacheのパスと環境変数優先順位が従来と一致。
- 指定時は両者の新規ファイルが専用領域に入り、旧保存先へ新規書き込みしない。
- 日本語・空白を含むパス、Windowsドライブ、Linuxローカルマウントで動作。
- 書き込み不可、mmap失敗、容量不足、指定ディスク切断、マウント先入れ替わりで明確な結果を返す。
- 切替前の出力、Tensor view/alias、COW cache mappingが切替・削除後も読める。
- 未参照ファイルだけを削除し、Run/Takeと対象外ファイルを保持。
- owner不明、不正sidecar、symlink/junction、PID再利用、別の生存プロセスを保護。
- Queue/Decode/Finalizeの開始と設定変更・削除の競合を実行順を制御して検証。
- 異常終了後の新形式cacheの残骸は安全に回収でき、旧形式の未管理cacheは保護。
- RAM不足・取得不能・コンテナー制限を小型Tensorとprobe差し替えで検証。実機OOMを起こして試験しない。
- Autoの4 GiB境界とreserve、手動RAMの4 GiB超許可、手動Diskの容量検査を検証。
- キャッシュ障害時のnative Decode継続と、Decode例外/中断の伝播を維持。
- 小型入力で、保存先やbuffer backendを変えてもフレーム・音声・dtypeが一致。
### ブラウザーと互換性
- ComfyUI設定で保存・検証・更新・削除ができ、再接続/再読込後も保存先が一致。
- 実行中・Queue待機中の保存と削除はUIだけでなくサーバーでも拒否。
- 設定画面を繰り返し開閉してもlistenerやDOM、描画処理が増殖しない。
- モバイルではサーバー側パスを扱うことが明確。
- マルチユーザーでは設定・削除の変更操作を拒否。
- 既存V3.8X2/V3.9ワークフローを変更せず保存・再読込できる。
- 既存Review/Take/Reference、file-backed、Decode Cacheの回帰試験と標準validationが通過。
- 公式ワークフローのbyte同一性、配布manifestの整合を確認。
CPU・ブラウザー検証で一時保存先機能の受け入れを判断する。実H3の長尺生成速度、映像・音声品質、実SSD書き込み量は別の実機評価であり、GPU未検証を隠して全体保証としない。
## 10. 初回実装へ含めないもの
データの圧縮/半精度化、VRAMを一時ストレージとして使う機能、独自RAMディスク、複数ディスクへの自動分散・自動フォールバック、Auto RAM上限の変更、全フレームを持たないstreaming出力、ネットワーク共有の正式対応、実SSDの寿命推定は初回に含めない。
確定した初回実装は、保存先指定・状態表示・安全な未使用削除と、そのための容量/所有権/手動RAMの事前確認である。パッケージ番号は3.9.3。GitHub Release/tag・Registry公開はソース更新とは別の作業。