> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ビジョンと画像理解

> Agent に画像を送れます — メインモデルがビジョンに対応していなくても動作します。

# ビジョンと画像理解

Myrm は WebUI のチャット、IM チャネル、デスクトップで画像の送信に対応しています。**メインモデルがビジョンに対応していない**場合でも、\*\*Vision Fallback（ビジョン代替モデル）\*\*が自動的に画像をテキスト説明へ変換し、メインモデルがそのまま会話を続けます — 手動でモデルを切り替える必要はありません。

## 仕組み

1. WebUI で任意のファイル（画像・PDF・文書・動画・音声・コードなど）を貼り付け・ドラッグ・アップロードするか、対応チャネルでファイルを送信します。
2. Myrm は現在のメインモデルがビジョンに対応しているか判定します（`supports_vision`）。
3. **対応あり** — 画像はネイティブのマルチモーダル内容として直接メインモデルへ送られます
4. **対応なし** — 画面に **「画像を解析しています…」** が出て、設定した **Vision Fallback** モデルが説明文を生成し、画像ブロックを差し替えてメインモデルが回答を続けます

**動画**も同じ経路を通ります。ネイティブ動画に対応したモデルはそのまま渡し、対応しない場合はフレーム抽出 + ビジョン解析でテキスト説明へ降格します。

## 設定手順

1. **設定 → モデル** を開きます。
2. **メインモデル** を選びます（どのプロバイダーでも構いません）。
3. **Vision Fallback** にビジョン対応モデルを設定します（GPT-4o、Gemini Flash、Qwen-VL など）。
4. **ビジョン経路をテスト** をクリックし、順序付きの完全な降格経路を検証します（失敗時は `resolved_model` と API エンドポイントが表示されます）。
5. メインモデルがテキスト専用で代替が未設定の場合は、**「このモデルを使う」** ワンクリック推奨カードが出ることがあります — 有効化済み Provider から最初の `supports_vision` を選びます。
6. 任意: モデルセレクターで能力アイコンを確認できます。目がアイコンのモデルはネイティブにビジョンに対応しています。

Myrm は LiteLLM と models.dev を通じてモデル能力を自動検知します。モデルカードで手動上書きすることもできます。

## ビジョン未設定の場合

画像や動画をアップロードしたものの、メインモデルも Vision Fallback も解析できない場合、Myrm は **警告トースト** を表示し、**設定へ移動** ボタンを提供します（**設定 → モデル → 既定モデル** タブへの直リンク）。アップロードはブロックしません（Web 検索の config gap と同じ方針）— ファイルは送れますが、解析には先に設定が必要です。

## 典型シーン

* **超長スクリーンショットと WeChat の長いチャット画像の劣化なし解析** — 極端に高いピクセル数や極端な縦長比（複数画面をまたがるチャット記録、長い承認書、データレポート）をアップロードすると、系統はメモリ内だけの幾何スライス経路を自動起動し、空白行で分割しつつチャンク間に安全マージンを残し、並行で文字起こしして文脈をシームレスに再構成します。従来の圧縮による文字モザイクやぼやけを根絶します
* **スクリーンショットの質問** — スクリーンショットを貼り付けて質問や次の操作を尋ねる
* **6 ツールの画像アノテーター** — 組み込みエディターでペン・矩形・楕円・矢印・テキスト・ぼかしの 6 ツールでスクリーンショットや画像に注釈を付け、注釈後は自動で添付として送信され、Agent は注釈内容をマルチモーダルで理解します
* **指差し照準の Element Picker** — HTML アーティファクトのプレビューで picker モードに切り替え、任意の UI 要素をクリックします。系統が CSS セレクタ・DOM パス・outerHTML を自動取得し、「◯◯をこう直して」と一言伝えるだけで Agent が正確に該当コードを特定して修正します
* **選択即操作ツールバー** — コードエディターでコードを選択（修正・説明・最適化・コメント）または文書プレビューでテキストを選択（修正・説明・書き直し）すると、選択範囲の文脈に artifact ID と行番号範囲が含まれ、自動で Agent へ送信されます
* **VisualApproval の操作承認の可視化** — Agent がブラウザやデスクトップの操作権限を求める際、スクリーンショットの座標ハイライトで対象位置を表示し、デスクトップでは OS ネイティブのオーバーレイにも対応。承認判断がひと目で分かります
* **テキスト系メインモデル + ビジョン代替** — メインモデルを低コストなテキストモデルにし、画像は Vision Fallback が処理

## 状態とキャッシュ

Vision Fallback の実行中、チャット領域には **画像を解析しています**（または **動画を解析しています**）の表示が出て、完了後に自動的に消えます。

**同じ会話内で内容が同じ画像**はハッシュでキャッシュされ、繰り返し送信してもビジョン API を重複呼び出ししません。

## 非同期画像生成

エージェントが **画像生成** ツールを有効にしている、かつ認証情報が有効な場合、「バナーを描いて」のような頼みごとでも会話が 30〜120 秒空回りすることはありません。

1. Agent はタスクをキューへ入れ、すぐに `task_id` を返します
2. メッセージ領域に **ImageTaskCard** が出現し、SSE でリアルタイムに進捗を表示します（ポーリングによるフォールバックあり）
3. 生成中もチャットを続けたり、prompt を変えたり、新しいタスクを開始したりできます
4. 完了後、カードに生成画像が表示され、メディアライブラリへ入れられます

**セキュリティ（クラウドホストとデスクトップ共通）**: API Key と Gateway Token はローカルの `tasks.db` へ書き込む**前に** AES-GCM で暗号化されます — バックアップやサンドボックスボリューム内に平文の鍵は残りません。

**設定 → モデル**（またはエージェントのツールパネル）で画像モデルを有効にしてプロバイダーを選びます（LiteLLM 経由の 20+ モデル、failover 自動対応）。

## 使い方のヒント

* **端末側での秒級圧縮と大画像の准入**: 数十 MB の超高解像度原画像をドラッグ・貼り付けすると、端末側で `OffscreenCanvas` により送信瞬間に等比の軽量圧縮が完了します（1 枚あたり約 98% 減して \~400KB まで縮小）— 待たずに送信でき、ゲートウェイの `HTTP 413` 遮断を根絶します
* **複数ターンの Prompt Cache の完全ロック**: 多数のスクリーンショットを含む長程会話では、系統が 2MB の量子化バッファ段差で履歴画像の Base64 ペイロードを追い出し、寸法とサンドボックスパスを含む構造化プレースホルダを自動注入します。これはモデルの視覚記憶の喪失を防ぐだけでなく、Prompt Cache のヒット率を 90% 以上に保ち、長程の視覚 Token 支出を 80% まで下げます
* 通常のコードスクリーンショットを頻繁に送する場合は、**応答が速く単価も安い**モデルを Vision Fallback に設定できます（Gemini 2.5 Flash や GPT-4o-mini など）
* 解析に失敗した場合は明確なエラーが出て、メッセージの残りの部分は通常どおり処理されます

## 関連ドキュメント

* [モデル設定（英語）](/guides/model-configuration) — スロット、ルーティング、API Key
* [音声対話（英語）](/guides/voice-interaction) — 音声・動画メッセージの文字起こし
* [ブラウザ自動化（英語）](/guides/browser-automation) — ビジョン支援によるページ検証


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.