DeepSeek-V4.1-Flash マルチモーダル視覚理解：画像入力から視覚 Agent まで — AI開発チュートリアル

2026年9月10日、DeepSeekは新アーキテクチャファミリーの中で最小サイズのメンバー——DeepSeek-V4.1-Flashをリリースしました。これは通常のバージョンアップではなく、アーキテクチャレベルの再設計です。552B総パラメータのMoE、まったく新しいCausal-Encoder-Decoder（CED）非対称アーキテクチャ、入力側ではわずか8Bのみを活性化し出力側では16Bを活性化、さらにネイティブなマルチモーダル視覚理解と1Mコンテキスト、384K最大出力を備え、「小サイズ」のメンバーをV4 Proを全面的に超えるフラッグシップ級の能力へと仕上げています。本記事はマルチモーダル視覚理解の実運用に焦点を当てます。1枚の画像がどのようにモデルへ送られるのか、長文書の複数画像プランニング、視覚Agentのマルチターン推論、さらには思考強度の段階とtoken予算制御までを扱います。すぐに実行できるコード、本番環境に投入できるパラメータ選定表、そして実際にハマってみて初めて分かるエンジニアリングの詳細をお届けします。本記事は2回に分けて公開され、これは第1/2回です。まずアーキテクチャ、KV Cache、コンテキスト、視覚入力チャネルを徹底的に解説し、最初の視覚理解リクエストを動かします。

CED非対称アーキテクチャの分解：552B MoEがなぜ入力側で8Bのみ、出力側で16Bを活性化するのか

V4.1-Flashの設計を理解するには、まずCausal-Encoder-Decoder（CED）という名前の背後にある分業の哲学を理解する必要があります。従来のTransformerは「統一アテンション」です。コンテキストを読み込む場合でも、次のtokenを生成する場合でも、同じパラメータセットと同じ因果マスクを使います。これに対しCEDは、「読む」ことと「書く」ことを性質がまったく異なる2つの事柄としてモデリングします。

エンコード側（Encoder、入力側）のタスクは入力の理解です。テキストtoken、画像patch、テキストと画像が交互に並ぶシーケンスを意味表現へエンコードします。理解は「並列・双方向・何度も見返せる」プロセスです——100番目のtokenを見たときに、3番目のtokenの理解を振り返って修正するのはごく自然なことです。したがってCEDのエンコード経路は非因果（双方向）アテンションを採用し、入力シーケンス内で情報が自由に流れることを許します。その代わり、この部分は自己回帰サンプリングを行う必要がないため、極めて低い活性化量で計算を完了できます。V4.1-Flashはここで8Bパラメータのみを活性化します。

デコード側（Decoder、出力側）のタスクは生成です。画像理解後の回答、Agentのツール呼び出しパラメータ、長文書要約の本文などです。生成は「直列・因果・段階的に累積する」プロセスであり、各ステップで全履歴に基づいて意思決定を行う必要があり、品質が最終出力を直接左右するため、より高いパラメータ容量とより強力な推論能力が求められます。V4.1-Flashは出力側で16Bパラメータを活性化し、ちょうど入力側の2倍になっています。

この1:2の非対称活性化は思いつきの数字ではなく、実際のワークロードに基づく計算です。マルチモーダルなシナリオでは、1024×1024の画像は視覚エンコード後に数千の視覚tokenを生成する可能性があり、1回のリクエストの入力token数は出力の数倍から数十倍になることがよくあります。入力側も16Bで活性化すると、計算の大部分が「すでに理解された内容」に浪費されてしまいます。入力側を8Bに圧縮し、容量を出力側へ傾けることは、「安価な読解」に大量のコンテキストを処理させ、「高価な執筆」に火力を集中させて高品質な結果を生成させることと等価です。

エンジニアリング実務への直接的な影響は3点あります。

視覚入力のコストが構造的に引き下げられる。複数画像の長文書のような入力主導型タスクでは、tokenあたりの限界計算コストが出力主導型タスクより大幅に低くなり、「PDF全体を画像に分割して放り込む」ことが初めて経済的に成立します。
出力側は依然として予算の大部分を占める。16Bの活性化は、長文テキストや長チェーンのAgent軌跡の生成が依然として高コストであることを意味するため、切り詰め戦略やmax_tokensの計画がこれまで以上に重要になります。
MoE総パラメータ552Bが知識容量を保証する。活性化量が小さいことは能力が弱いことを意味しません。スパース活性化により、モデルは推論時に現在のtokenに関連するエキスパートだけを動員します。これも、Flashの価格帯でPro級の能力を提供できる根本的な理由です。

強調しておきたいのは、552Bは総パラメータであり、8B/16Bは活性化パラメータであるということです。両者は「倉庫の大きさ」と「1回の取り出し量」の関係にあります。これが、公式がHugging Faceで重みを公開できる理由でもあります（deepseek-ai/DeepSeek-V4.1-Flash）——総パラメータ規模がVRAMのしきい値を決め、活性化規模が計算クラスタへの需要の形を決め、両者が相まってローカル展開に適しているかどうかを決めます。

V4 ProからV4.1-Flashへ：新しい事前学習手法＋より大規模なRL後学習がもたらす能力の飛躍

常識的に考えれば、ファミリー内の「小サイズのメンバー」は能力の下限であるはずです。しかしV4.1-Flashが示す公式ベンチマークは直感に反します。それは複数の次元で前世代のフラッグシップV4 Proを全面的に超えています。理由は2つの技術路線が同時に推進されたことです——新しい事前学習手法とより大規模なRL後学習です。

まずハードな指標を見てみましょう。公式に公表されたデータでは：

GPQA Diamond 90.9——博士レベルの科学Q&Aで、このベンチマークの飽和領域に近づいています。
Codeforcesレーティング3471——競技プログラミングで、トップ選手の領域に属します。
MathArena Apex 65.6——高難度の数学推論。
Terminal-Bench 2.1スコア90.6で、V4 Proは87.9です。
CyberGym 88.1で、V4 Proは83.3です。

この数値群でエンジニアが注目すべき点が2つあります。第一に、GPQA DiamondやCodeforcesといった「ハード推論」指標の上昇は、改善がデータの記憶の積み上げによるものではないことを示しています。それは推論能力そのものの進歩であり、こうした能力はマルチモーダル視覚推論タスク——たとえばグラフからの数値推測や図面の判読——に直接転移します。第二に、Agent／セキュリティ系ベンチマークであるTerminal-Bench 2.1とCyberGymがそれぞれ2.7ポイントと4.8ポイント向上しており、Agentの長チェーン実行能力が著しく強化されたことを示しています。これはまさに視覚Agentシナリオで最も必要とされる基礎的な素養です。

公式リリース投稿にはさらに4つのAgentベンチマークがあります：Terminal-Bench 3.0スコア30.0、DeepSWE v1.1スコア74.2、CyberGym 88.1、Automation-Bench 54.8。このうちTerminal-Bench 3.0とDeepSWEはいずれも強い手続き型タスクです——モデルは環境を連続して多段階で操作し、フィードバックに基づいて計画を修正しなければなりません。こうした能力を視覚入力と組み合わせると、「スクリーンショットを一目見る → 次の操作を決める → 実行する → 新しいスクリーンショットを見る」という閉ループになります。これこそ本記事の後半で構築する視覚Agentの形態です。

もう1つ見落とされがちな事実があります：北京時間2026-09-14 12:00以降、deepseek-v4-proへのリクエストはすべてV4.1-Flashへルーティングされ、Flashの価格で課金されます。これはV4.1-Proが登場するまで続きます。つまり、現在本番環境でV4 Proを動かしているなら、知らないうちにV4.1-Flashへアップグレードされており、しかも請求額は安くなっています。これは回帰テスト（regression test）の最良の機会です——実トラフィックを使って、「小サイズのメンバーが前世代のフラッグシップを全面的に超える」という主張が自分のビジネス分布で成り立つかを検証できます。

結論は明快です：もう「パラメータサイズ」でモデル能力を予測するのはやめましょう。V4.1-Flashは新しい事前学習手法と大規模RL後学習の産物であり、その能力の上限はデータと学習手法によって決まり、活性化パラメータ数によって決まるのではありません。

KV Cache圧縮の四重奏：890 bytes/token、HBMを1/4に、SSDを1/8に、どうやって実現したのか

長コンテキストとマルチモーダル推論に取り組む人にとって、「本番投入できるかどうか」を本当に決めるのはベンチマークスコアではなくKV Cacheです。V4.1-Flashのこの分野における公式データは非常に攻めています：

tokenあたりのKVサイズは約890 bytesで、V4 Flashは約3514 bytesです。
HBM需要は前世代の1/4に低減。
SSDストレージ需要は1/8に低減。
初代DeepSeekと比べて、KV Cacheは全体で約437分の1に縮小。

まずこの数字が何を意味するかを計算してみましょう。1Mコンテキストを例にとると、V4 Flashのtokenあたり3514 bytesは、単一シーケンスのKVが約3.5GBのオーダーであることを意味します。V4.1-Flashの890 bytesはそれを約0.89GBのオーダーまで圧縮します。同時接続2500のAPIサービスにとって、これは同じHBMでどれだけの長コンテキストセッションを収容できるかを直接左右します。

公式には HBM 需要が 1/4 に低減するとされており、890/3514 ≈ 0.253 という比率と高度に一致している——これはマーケティング上のレトリックではなく、同一の物理量を異なる次元で表現したものである。

『四重奏』は、四つの方向の圧縮が相乗的に働くことだと理解できる：

アーキテクチャ層の非対称設計。CED のエンコード側とデコード側は異なる役割を担い、KV の保存構造はパスごとに個別に最適化でき、単一の統一アテンションのために全量キャッシュのコストを払う必要はない。
アテンション構造のスパース化と低ランク化。長コンテキストの場面では、すべての履歴トークンを全精度で保持する必要はなく、低ランク射影と選択的保持によって、各層・各ヘッドの有効キャッシュ次元が下がる。
量子化と混合精度ストレージ。KV をより低いビット数で保存し、重要な層の精度保護を組み合わせることが、bytes/token を千の桁から百の桁へ下げる鍵となる。
階層キャッシュと SSD オフロード。HBM にホットデータを、SSD にコールドデータを置く。SSD 需要が 1/8 に下がったことは、単位トークンあたりのディスク書き込み量がさらに厳しく圧縮されたことを示しており、超長セッションの経済性にとって極めて重要である。

エンジニアリングの観点で最も重要な意味は、長コンテキストのコスト構造が書き換えられたことである。これまで 1M コンテキストの問題は「開けるが開けない（使えるが使えない）」ことだった——KV の VRAM が満杯になり、並列度が上がるとすぐに OOM になる。今や HBM 需要は 1/4、SSD は 1/8 であり、同じ並列度をより少ないマシンで回せるか、同じマシンでより長いセッションを回せることを意味する。価格設定においてキャッシュヒット入力はアイドル時わずか 0.02 元/百万 tokens（ピーク時 0.04 元）であることと組み合わせると、安定して変化しない長文ドキュメントをプレフィックスに置いてキャッシュヒットさせるのが、長文ドキュメントの視覚理解で最もコスト効率の良い方法である。

また、KV Cache の隠れたコストを覚えておく必要がある：それはセッション長に比例して線形に増加する。890 bytes/token がすでに非常に小さくても、10 時間続くマルチターンの視覚 Agent セッションでは、依然として相当なキャッシュが蓄積される。エンジニアリング上は、セッションを積極的に分割し、完了したサブタスクをアクティブなコンテキストから切り離し、要約だけを残すべきである。

1M コンテキスト + 384K 最大出力：長文ドキュメント視覚理解と長チェーン Agent のウィンドウ計画戦略

V4.1-Flash は1M tokens のコンテキストと384K tokens の最大出力を提供する。この二つの数字は必ずセットで理解する必要がある。なぜなら、それらはまったく異なる二種類のタスクに対応しているからである。

1M コンテキストが解決するのは「全体を見る」ことである。複数画像の長文ドキュメントの場面では、数百ページの技術マニュアル、図表付きの財務報告書、UI デザイン案一式を、事前分割せずにそのまま投入できる。これにより、これまで最もよくあった精度損失の原因——分割によってページをまたぐ・画像をまたぐ関連情報が失われること——が解消される。画像リンク、base64、Files API の三つのチャネルはいずれもこの 1M のウィンドウを使え、違いは伝送方式だけである。

384K 最大出力が解決するのは「書き切る」ことである。視覚 Agent のマルチターン計画は大量の中間テキストを生む：思考チェーン、ツール呼び出しパラメータ、観察結果の書き戻し、計画の修正。もし出力上限が 8K しかなければ、複雑なタスクは数ターンで打ち切られてしまう。384K があれば、単一の呼び出しで超長い Agent 軌跡を担えるか、あるいは一冊の本の構造化解析結果を一度に出力できる（たとえば 200 ページのスキャン資料を構造化 JSON に変換する）。

しかし「ウィンドウが大きい」ことは「好き勝手に使える」ことではない。実行可能なウィンドウ計画戦略を三つ挙げる：

プレフィックスの固定化。会話によって変化しない資料（長文ドキュメント、参考画像集、システムプロンプト）をメッセージ列の先頭に置き、プレフィックスを安定させ、キャッシュヒット率を最大化する。公式価格では、キャッシュミス入力はアイドル時 1 元/百万 tokens、ヒット時はわずか 0.02 元で、50 倍の差がある。プレフィックス設計がコストの桁を直接決める。
階層的トランケーション。文字数で乱暴に切り詰めるのではなく、意味単位で切り詰める：まずシステム指示とタスク定義を保持し（切り詰め不可）、次に直近 N ターンの完全な対話を保持し、中間の履歴は要約に圧縮し、最後にようやく古い画像の破棄を検討する。画像は一度破棄されるとコンテキストの関連を回復できないため、優先度は最も低い。
出力予算の明示的宣言。Agent の場面では、max_tokens をタスク種別ごとに段階分けする：単一ステップのツール呼び出しには小さな値（例：2K）、最終要約には大きな値（例：64K）、文書全体の構造化出力にのみ数十万の桁を与える。出力予算を宣言しないと、モデルは「よく考える」ために予想をはるかに超える思考テキストを書く可能性がある。

視覚 Agent では特に注意すべきである：各ターンのスクリーンショット入力は入力ウィンドウを占有し、マルチターンで蓄積すると入力側が極めて速く増大する。N ターンごとに履歴スクリーンショットをテキスト記述の要約に置き換え、ウィンドウを返却することを推奨する。これによりコストを制御できるだけでなく、モデルが過剰な視覚的詳細の中で本筋を見失うのを避けられる。

ネイティブ・マルチモーダル視覚理解の三チャネル：画像リンク、base64、Files API の選定とコスト

V4.1-Flash はネイティブにマルチモーダル視覚理解をサポートし、公式に三つの画像入力チャネルを提供する：画像リンク（URL）、base64 インライン、Files API。三者は能力としては等価だが、遅延、帯域、キャッシュ、再利用性において大きな差がある。以下の表はエンジニアリング選定の核心的な参考である：

チャネル	遅延特性	帯域/サイズ	キャッシュヒット	再利用性	典型的な場面
画像リンク URL	サーバー側での取得が必要で、オリジンサイトの影響を受け、初回パケット遅延は不確定	リクエストボディは極めて小さい	URL が安定し内容が不変なら、プレフィックスは安定してヒットする	高い。同じ URL をリクエストをまたいで再利用可能	画像がすでに CDN/オブジェクトストレージにあり、ゲートウェイでバッチ処理
base64 インライン	追加のネットワーク往復がなく、最速	リクエストボディが約 33% 膨張し、単一リクエストのサイズ上限に制約される	毎回内容が同一の場合のみヒットし、繰り返し呼び出しはコストが高い	低い。リクエストごとに再送が必要	単一画像の迅速な検証、小さい画像、一時的な画像
Files API	一度アップロードすれば、以降の参照はサーバー側を通り、安定して低遅延	アップロード帯域は一度だけ払う	ファイル ID が安定しており、プレフィックスキャッシュに有利	最も高い。一度アップロードして多数ターン・多数回参照	マルチターン視覚 Agent、繰り返し参照される長文ドキュメント画像集

選定の推奨は、そのまま三つのルールに落とし込める：

単発の一問一答、画像が非常に小さい（数十 KB）→ base64。ネットワーク往復を一回節約でき、コードも最も簡単。
画像がすでに公網からアクセス可能で、同じ画像が複数のリクエストから参照される → URL。リクエストボディが最小で、帯域コストが最も低い。
マルチターン視覚 Agent、同じ一群の画像を繰り返し参照する必要がある → Files API。これはマルチターン対話において画像を「安定したプレフィックス資産」として扱える唯一のチャネルであり、キャッシュヒット価格 0.02 元/百万 tokens と組み合わせれば、長セッションのコストを極めて低く抑えられる。

実際の落とし穴が二つある。第一に、base64 は小さい画像では便利に見えるが、マルチターンで繰り返し送信すると入力トークンが重複課金されるうえ、膨張したリクエストボディがゲートウェイのサイズ上限に触れ、画像が大きくなると 413 になる可能性がある。第二に、URL チャネルの安定性はオリジンサイトに依存する。画像が期限切れになる署名付き URL から来ている場合、キャッシュプレフィックスが壊れ、取得失敗によってリクエスト全体が失敗することさえある。本番環境では、長期間有効なオブジェクトストレージのアドレスを使うか、取得層でキャッシュプロキシを実装すべきである。さらに、どのチャネルを使うにせよ、画像解像度は視覚トークン数に直接影響し、ひいては入力コストとウィンドウ占有に影響する。高精度 OCR と全体シーン理解では解像度の要求が異なるため、タスクに応じてダウンサンプリングすべきである。

思考モード三档 low/high/max：視覚タスクにおける思考強度とコスト・遅延のトレードオフ

V4.1-Flash は非思考モードと思考モードをサポートし、うち思考モードがデフォルトであり、low / high / max の三档の思考強度を提供する。これは視覚タスクで最も乱用されやすいスイッチである——多くの人がデフォルトで max 档にしておき、その結果コストと遅延が制御不能になる。

三档の違いの本質は、モデルが最終回答を出す前の内部推論の深さである。档が高いほど推論チェーンが長く、中間仮説の自己検証が多く、初稿を覆してやり直す可能性が高い；档が低いほど、直感的で素早い回答に傾く。視覚タスクでは、「視覚—言語—推論」の三層の難易度に応じて档を選べる：

low：OCR、画像記述、単純な分類。こうしたタスクの答えはほぼ完全に視覚入力で決まり、多段推論を必要としない。low 档を使えば、遅延とコストで最大の利益を得られ、品質もほとんど損なわれない。
high：図表の質疑応答、数値を読み取る必要のある模式図、画像とテキストの整合性検証。タスクは「まず図を読み、次に計算し、さらに照合する」ことを要し、中程度の推論深度に属する。high はこの档の最良のバランス点であり、マルチモーダル業務のデフォルト推奨値でもある。
max：複雑な視覚推論。たとえば複数画像のページをまたぐ比較、工程図面の多制約判断、視覚 Agent においてスクリーンショットと履歴動作を総合して次の一手を計画する場合、およびコード/数学的推論と結合する必要のある視覚タスク。max 档の思考テキストは出力が長くなるため、必ず出力予算とタイムアウト制御を組み合わせてください。

実用的なコツの一つは段階的なダウングレードです。Agent の通常ステップには high を使い、あるステップが繰り返し失敗したり、全体的な再計画が必要な場合にのみ max にエスカレートしてリトライします。これにより、難しいステップの成功率を保ちながら、すべてのステップで max のコストを払う必要がなくなります。また、公式が明示している制限を一つ覚えておいてください。FIM（Fill-in-the-Middle）は非思考モードでのみ利用可能です。業務でプレフィックス継続や FIM をコード補完に使っている場合は、非思考モード用に別の経路を用意する必要があります。

主要パラメータ早見表：API モデル名 deepseek-flash、並列数 2500、旧名互換ルーティング

着手前にまずパラメータを揃えましょう。そうしないと、最もつまずきやすいのがモデル名です。現在有効なパラメータは以下のとおりです。

API モデル名：deepseek-flash。これが唯一推奨される安定した識別子です。
並列制限：2500。かなり高い並列枠ですが、これは同時に行われるリクエスト数を制約するものであり、並列数が高くても長いセッションが安くなるわけではない点に注意してください。
旧名互換ルーティング：deepseek-v4-flash と deepseek-v4-flash-vision-exp は廃止済みですが、公式は一時的な互換ルートを維持しており、この二つの旧名を V4.1-Flash に振り向けています。これによりスムーズな移行のための猶予期間が得られますが、長期的な解決策として扱うべきではありません。できるだけ早く設定センターでモデル名を deepseek-flash に統一してください。
deepseek-v4-pro のトラフィックは 2026-09-14 12:00 以降、V4.1-Flash にルーティングされ、Flash の料金で課金されます。これは V4.1-Pro が登場するまで続きます。突合とキャパシティプランニングではこの変化を考慮に入れる必要があります。
対応インターフェース面：JSON Output、Tool Calls、Responses API、Anthropic API、会話プレフィックス継続、および非思考モードでのみ利用可能な FIM。

並列設計において、2500 の制限と 890 bytes/token の KV サイズを組み合わせると、単一ノードで安全に処理できる長いセッション数は前世代よりはるかに多くなります。ただしリクエスト側では依然としてキューイングと優先度付けを自分で行う必要があります。低価値のバッチ画像解析はアイドル時間帯（ピークは月曜から金曜の 9:00–12:00、14:00–18:00、アイドル料金はピークの半額）に回し、重要なインタラクションパスには高優先度の枠を確保します。料金面では、キャッシュヒット時のアイドル入力は 100 万 tokens あたりわずか 0.02 元、キャッシュミス時のアイドル入力は 1 元、アイドル出力は 4 元です。V4 Flash と比較すると、キャッシュヒットは 60% 安く、ミスは約 33.3% 安く、出力は約 11.1% 安くなります。再利用可能なコンテンツをプレフィックス化し、思考強度を必要に応じて段階化するというこの二つの手法が、ほとんどの業務の請求動向をほぼ決定づけます。

最小動作コード：Responses API で画像を deepseek-flash に送る

以下にすぐ実行できる三段のコードを示します。第一段は最小動作例です。base64 チャネルでローカル画像を deepseek-flash に送り、思考強度を指定します。

import base64
import json
from openai import OpenAI

client = OpenAI(
    api_key="your-deepseek-api-key",
    base_url="https://api.deepseek.com",
)

# 1) ローカル画像を読み込み、base64（data URL 形式）に変換する
def image_to_data_url(path: str) -> str:
    with open(path, "rb") as f:
        raw = f.read()
    b64 = base64.b64encode(raw).decode("utf-8")
    return f"data:image/png;base64,{b64}"

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "この画像の主な内容を説明し、その中の重要なテキストを列挙してください。"},
                {
                    "type": "image_url",
                    "image_url": {"url": image_to_data_url("demo.png")},
                },
            ],
        }
    ],
    # 思考モード（デフォルトで有効）と思考強度：low / high / max
    extra_body={
        "thinking": {"type": "enabled", "budget": "high"}
    },
    max_tokens=2048,
)

print(resp.choices[0].message.content)

第二段は Responses API で画像リンクチャネルを使うもので、画像がすでにオブジェクトストレージや CDN 上にあるシナリオに適しています。リクエストボディが最小で、プレフィックスが最も安定してキャッシュにヒットしやすくなります。

import json
from openai import OpenAI

client = OpenAI(
    api_key="your-deepseek-api-key",
    base_url="https://api.deepseek.com",
)

resp = client.responses.create(
    model="deepseek-flash",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "このグラフはどのような傾向を示していますか？数値を読み取り、前年比変化を計算してください。"},
                {
                    "type": "input_image",
                    "image_url": "https://cdn.example.com/report/q3-revenue.png",
                },
            ],
        }
    ],
    # 思考強度：グラフの読み取り＋計算は中程度の推論なので high を選ぶ
    extra_body={"thinking": {"type": "enabled", "budget": "high"}},
    max_output_tokens=8192,
)

print(resp.output_text)

第三段はマルチターンの視覚 Agent の骨組みを示します。Files API で画像を一度アップロードし、ファイル ID を取得した後、複数ターンで繰り返し参照することで、画像を安定したキャッシュプレフィックス資産に変えます。同時に、低難度のステップは low にダウングレードし、難しいステップは max にアップグレードします。

import json from openai import OpenAI client = OpenAI( api_key="your-deepseek-api-key", base_url="https://api.deepseek.com", ) # 1) 画像をアップロードし、繰り返し参照できるファイル ID を取得する with open("screenshot.png", "rb") as f: upload = client.files.create(file=f, purpose="vision") file_id = upload.id print("file_id =", file_id) # 2) マルチターン視覚 Agent：同じ画像＋履歴アクションの要約 messages = [ {"role": "system", "content": "あなたは視覚 Agent であり、スクリーンショットに基づいて次の操作を計画します。"}, { "role": "user", "content": [ {"type": "text", "text": "これは現在のインターフェースのスクリーンショットです。次の操作を提示してください。"}, {"type": "image", "file_id": file_id}, ], }, ] for step in range(3): budget = "low" if step < 2 else "max" # 通常ステップは low、難しい再計画は max に上げる resp = client.chat.compl etions.create( model="deepseek-flash", messages=messages, extra_body={"thinking": {"type": "enabled", "budget": budget}}, tools=[{"type": "function", "function": {"name": "click", "parameters": {"type": "object", "properties": {"x": {"type": "integer"}, "y": {"type": "integer"}}}}], max_tokens=4096, ) msg = resp.choices[0].message messages.append(msg) # ここでツール呼び出しを実行し、observation を書き戻す必要がありますが、サンプルでは省略しています print(step, budget, msg.content or msg.tool_calls) # 3) セッション終了後にファイルを削除し、長期的な占有を避ける client.files.delete(upload.id)

re>

この3つのコードを実行し終えた時点で、あなたはすでに視覚入力の3つのチャネルと思考強度の基本的な制御をカバーしています。次のセクションでは、視覚Agentの完全なループを深掘りします。複数ラウンドのスクリーンショットとツール呼び出しをどのように編成するか、長文書で複数画像をどのように予算計画するか、キャッシュヒットがプレフィックス設計によってどのように50倍のコスト差を生むか、そして2500同時実行下でのレート制限と縮退の実践です。

前のセクションでは、画像入力の3つのチャネル（リンク、base64、Files API）をすでに開通させ、CED非対称アーキテクチャと1M tokensコンテキストの背後にあるエンジニアリングロジックを分析しました。このセクションではカメラを引きます。単なる「画像を見て質問に答える」から、「画像を下流で消費可能な構造に変え、視覚能力をAgentツールチェーンに組み込み、コストを制御可能な範囲に抑える」へとアップグレードし、最終的に実運用可能なプロダクションレベルのソリューションを形成します。

構造化視覚抽出：画像情報抽出におけるJSON OutputとTool Callsの組み合わせ用法

マルチモーダル実装の最初のハードルは「理解できるかどうか」ではなく、「理解した後、プログラムによって安定的に消費できるかどうか」です。視覚情報は本質的に非構造化であり、下流の業務が必要とするのはフィールド、列挙、金額、日付です。DeepSeek-V4.1-FlashはJSON OutputとTool Callsをネイティブにサポートしており、この2つを組み合わせることが視覚抽出の正しいやり方です。JSON Outputは出力形態を制約し、モデルがschemaの境界内でフィールドごとに生成できるようにします。Tool Callsは外部能力をつなぎ、正確に読み取れないフィールド（為替換算、商品データベース照合、請求書検証）を外部に委ねます。

エンジニアリング上は「2段階」の編成を推奨します。第1段階ではJSON Outputを使って画像に対して純粋な視覚フィールド抽出を行い、外部依存を一切導入せず、再現性を確保します。第2段階では第1段階の結果をツール呼び出しパラメータとして、検証と補完をトリガーします。こうすれば、外部ツールがタイムアウトしても、手元には完全な生の抽出結果が残り、リトライと監査が容易になります。以下のコードは、請求書画像を厳格なschema構造に変換し、フィールド信頼度が不足している場合にツール検証をトリガーする方法を示しています。

from openai import OpenAI
import json

client = OpenAI(
    api_key="your-deepseek-api-key",
    base_url="https://api.deepseek.com"
)

EXTRACT_SCHEMA = {
    "type": "object",
    "properties": {
        "invoice_no": {"type": "string"},
        "date": {"type": "string"},
        "total_amount": {"type": "number"},
        "currency": {"type": "string"},
        "line_items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "qty": {"type": "number"},
                    "price": {"type": "number"}
                },
                "required": ["name", "qty", "price"]
            }
        }
    },
    "required": ["invoice_no", "date", "total_amount", "currency"]
}

tools = [{
    "type": "function",
    "function": {
        "name": "verify_invoice",
        "description": "請求書検証プラットフォームを呼び出して請求書の真偽と金額を検証する",
        "parameters": {
            "type": "object",
            "properties": {
                "invoice_no": {"type": "string"},
                "total_amount": {"type": "number"}
            },
            "required": ["invoice_no", "total_amount"]
        }
    }
}]

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url",
             "image_url": {"url": "https://example.com/invoice.png"}},
            {"type": "text",
             "text": "schemaに厳密に従って請求書フィールドを抽出してください。重要フィールドを確認できない場合は、verify_invoiceツールを呼び出して検証してください。"}
        ]
    }],
    response_format={"type": "json_object"},
    tools=tools,
    tool_choice="auto"
)
print(resp.choices[0].message)

実践で強調すべきいくつかの細部があります。第一に、schemaは狭いほど安定するため、オープンなobjectを避け、できるだけenumとrequiredで絞り込むこと。第二に、金額や日付などの重要フィールドでは、モデルに同時にconfidenceフィールドを出力させ、閾値を下回ったら盲信せずツールに再検証を委ねることを推奨します。第三に、思考モードではモデルがまず推論してから出力するため、思考連鎖が本文に混入しやすくなります。抽出を行う際は非思考モードに切り替えて、よりクリーンな構造化結果を得ることを推奨します。フィールドが多く画像が雑多な場合は、大きなschemaを複数回の小さな抽出に分割してから統合する方が、一度に大きな抽出を行うよりも安定することが多いです。

FIMと会話プレフィックス継続：非思考モードにおける視覚補完と制御可能な生成境界

視覚シーンには2種類の「制御された生成」の要求があります。一つは補完——画像と途中までのテキストが与えられ、モデルに続きを書かせる。もう一つはフォーマット制約——モデルに既定のプレフィックスから出力を開始させ、逸脱を防ぐ。V4.1-Flashは2つの手段を提供します。会話プレフィックス継続とFIM（Fill-In-the-Middle）です。ここで必ず覚えておくべき制限があります。FIMは非思考モードのみをサポートします。これは、思考モードがまず推論軌跡を生成してから答えを出すのに対し、FIMはモデルが中間のギャップから厳密に続きを書くことを要求するため、両者は生成セマンティクス上で互いに排他的だからです。

会話プレフィックス継続は本質的にassistantロールに冒頭を事前設定し、モデルは後ろにしか書けません。視覚シーンでは、これはフォーマット制御に非常に適しています。たとえば、モデルにMarkdownテーブルを出力させたい場合、ヘッダーを事前設定すればモデルが自動的に行を埋めます。たとえば、固定JSONを出力させたい場合、{"result": "を事前設定すればモデルが引用符内から続きを書きます。一方、FIMはコードと文書の補完により適しています。スクリーンショットにテーブル構造図があり、注釈やCREATE TABLE文を補完したい場合、before/afterの両端をモデルに与えれば中間を埋めます。両者の境界は明確です——プレフィックス継続が制約するのは「起点」であり、FIMが制約するのは「ギャップ」です。エンジニアリングでは、タスクが画像を含み厳格なフォーマットを必要とする場合は、プレフィックス継続＋非思考モードを優先し、コード補完を含み明確なコンテキストギャップがある場合はFIMを使い、思考モードをオンにしたらFIMを諦める必要があります。

Anthropic API互換アクセス：既存の視覚AgentをV4.1-Flashへ移行するための改造チェックリスト

多くのチームの視覚AgentはAnthropicスタイルのインターフェースを中心に構築されており、V4.1-FlashはAnthropic API互換を提供するため、移行コストは大幅に下がります。しかし互換はゼロ変更を意味しません。以下の表は必須変更項目と推奨項目を列挙しています。

改造項目	Anthropicスタイルの書き方	V4.1-Flashへの移行時の書き方/説明
モデル名	claude-*シリーズ	一律でdeepseek-flashに変更。旧名のdeepseek-v4-flash / deepseek-v4-flash-vision-expはすでに提供終了しており、一時的な互換ルートのみが残されているため、できるだけ早く切り替えること
画像入力	source .type=base64 / url	画像リンク、base64、Files API の3つのチャネルに対応。長い会話では、再利用のために画像を Files API 経由で送ることを推奨
思考モード	thinking budget	思考強度 low/high/max の3段階にマッピング；デフォルトで思考オン、抽出系タスクは非思考に切り替え可能
ツール呼び出し	tool_use / tool_result	Tool Calls にマッピング；同時実行上限 2500 に注意、高並行シナリオではキューイングが必要
コンテキスト	200K 級	V4.1-Flash のコンテキストは 1M tokens、最大出力は 384K tokens で、図鑑一冊や長いスクリーンショットストリームを扱える
価格の見込み	Anthropic に基づく課金	Flash 価格で課金され、さらに 2026-09-14 12:00 から deepseek-v4-pro のリクエストはすべて V4.1-Flash にルーティングされ、Flash 価格で課金される。V4.1-Pro が登場するまで

移行時に最もハマりやすい落とし穴は画像フォーマットとサイズの想定です。Anthropic は画像に対して一辺ごとの解像度と容量の制限を設けているため、移行後は V4.1-Flash の入力方式に従って再検証する必要があります。同時に、思考モードがデフォルトで有効になることで、もともと「直接回答」していた prompt が冗長になります。system で思考するかどうかを明示的に宣言し、ツール編成について一度回帰テストを行うことをおすすめします。全体として、インターフェース層の互換性により、まずリクエストを通し、その後で項目ごとにセマンティクスを合わせられるため、移行ウィンドウは数日に短縮できます。

ビジュアル Agent 実践：Terminal-Bench 3.0 30.0、DeepSWE v1.1 74.2、Automation-Bench 54.8 から設計トレードオフを逆算する

公式リリース投稿では4つの Agent ベンチマークが示されています：Terminal-Bench 3.0 スコア 30.0、DeepSWE v1.1 スコア 74.2、CyberGym 88.1、Automation-Bench 54.8。この数値群はビジュアル Agent の設計にとって極めて参考になります。Terminal-Bench 3.0 がわずか 30.0 であることは、長距離のターミナル操作チェーンが依然として弱点であり、Agent は数十ステップの操作の後で目標から逸脱しやすいことを示しています。DeepSWE v1.1 が 74.2 に達していることは、コードレベルのタスクが比較的成熟していることを示しています。Automation-Bench 54.8 は中位にあり、日常的な自動化にはまだ大きな改善余地があることを意味します。CyberGym 88.1 はセキュリティ系タスクで際立った性能を示しています。

これに基づいて設計トレードオフを逆算すると、ターミナル系ビジュアル Agent では「一発完了」を追求せず、タスクを短いチェーン + 高頻度の検証に分割し、各ステップでモデルが最新のスクリーンショットに基づいて再判断し、履歴アクションへの長期的な依存を避けるべきです。スクリーンショットの返送には差分圧縮を行い、変化した領域だけを送り、1M コンテキストは本当に全量情報が必要なシナリオに残すべきです。失敗時のリトライは「リトライ可能」（タイムアウト、ツールエラー）と「リトライ不可」（権限拒否、対象が存在しない）を区別し、前者には指数バックオフを使い、後者は直接人にエスカレーションします。コード系タスクではより積極的に、Agent に長めのツールチェーンを自律的に完了させられます。長いターミナルタスクでは外部状態機械をフォールバックとして導入し、モデルは重要なノードでの視覚判断のみを担当すべきです。以下は、スクリーンショット返送とリトライを備えた Agent ループの骨格です。

import time, base64
from openai import OpenAI

client = OpenAI(api_key="your-deepseek-api-key",
                base_url="https://api.deepseek.com")

def call_model(history, image_b64, thinking="low"):
    return client.chat.completions.create(
        model="deepseek-flash",
        messages=history + [{
            "role": "user",
            "content": [
                {"type": "image_url",
                 "image_url": {"url": f"data:image/png;base64,{image_b64}"}},
                {"type": "text", "text": "現在のスクリーンショットに基づいて次の操作を決定し、JSON アクションを出力してください。"}
            ]
        }],
        response_format={"type": "json_object"},
        extra_body={"thinking": {"effort": thinking}}
    )

def run_visual_agent(env, max_steps=15):
    history = []
    for step in range(max_steps):
        shot = env.screenshot()
        b64 = base64.b64encode(shot).decode()
        for attempt in range(3):
            try:
                resp = call_model(history, b64)
                action = resp.choices[0].message.content
                break
            except Exception as e:
                if attempt == 2:
                    raise
                time.sleep(2 ** attempt)  # 指数バックオフ
        history.append({"role": "assistant", "content": action})
        if env.done(action):
            break
    return history

ここでは thinking effort low を使っている点に注意してください。ビジュアル Agent は各ステップで素早く判断する必要があり、high/max はループを著しく遅くします。曖昧なフレームに遭遇したときだけ一時的に段階を上げます。スクリーンショットの base64 はコンテキストを急速に消費します。1M は大きいものの、直近の数フレーム + 圧縮サマリー1份だけを保持することをおすすめします。

評価対照：Terminal-Bench 2.1 90.6 と CyberGym 88.1 の V4 Pro に対する差の解釈

公式ベンチマークでは、V4.1-Flash は Terminal-Bench 2.1 で 90.6、CyberGym で 88.1 を記録し、V4 Pro はそれぞれ Terminal-Bench 2.1 で 87.9、CyberGym で 83.3 です。これは、このファミリーの中で最小サイズのメンバーが、2つの厳しい指標でそれぞれ 2.7 点と 4.8 点リードしていることを意味します。バージョン差に注意：Agent 投稿の Terminal-Bench 3.0 はより難しい新バージョンで、スコアは 30.0 であり、2.1 の 90.6 と直接比較はできません。「30点」を見ても能力が後退したと誤解しないでください。これはタスク難度の上昇によるものです。

ベンチマークを再現する際の3つの要点：第一にバージョンの整合で、2.1 を走らせているのか 3.0 を走らせているのかを必ず確認してください。バージョンを間違えると結論が完全に逆転します。第二にサンプリングとリトライ戦略で、公式スコアには通常固定のリトライ回数があり、自測でリトライ回数が異なると変動が 3 点を超える可能性があります。第三にランダム性で、思考強度、温度、思考を有効にするかどうかが結果に影響するため、パラメータを固定して複数回実行し平均を取ることをおすすめします。より大きな視点で見ると、V4.1-Flash は新しい事前学習手法 + より大規模な RL 後学習を採用しており、公式にはベンチマークで V4 Pro を全面的に上回るとされています。この Terminal-Bench 2.1 と CyberGym の対照はまさにその裏付けです。エンジニアリングチームにとっての結論は、「最小サイズ」だからといって期待を下げてはいけないということです。多くの厳しいベンチマークでは、むしろ現在のファミリーで最強の選択肢です。

エンジニアリングの落とし穴と解決策：画像容量、キャッシュヒット、ピーク価格下でのコスト管理

ビジュアルアプリの請求の大部分は、しばしば出力ではなく、入力画像のトークン化とピーク時間帯の割増です。まず価格を明確にします（100万 tokens あたり、北京時間 2026-09-10 12:00 発効；ピークは月曜から金曜の 9:00-12:00、14:00-18:00、アイドルはピークの半分）：

課金項目	アイドル料金（元/百万トークン）	ピーク料金（元/百万トークン）
キャッシュヒット入力	0.02	0.04
キャッシュミス入力	1	2
出力	4	8

V4 Flash と比較して、キャッシュヒットは60%値下げ、ミスは約33.3%値下げ、出力は約11.1%値下げとなりました。ただし、価格が低いからといって請求額が低いわけではなく、鍵となるのはヒット率です。キャッシュヒットとミスの入力価格差は最大50倍（アイドル時 0.02 対 1 元）に達するため、安定したシステムプロンプト、ツール定義、画像の再利用プレフィックスをキャッシュの前段に置くことがコスト削減の最優先事項です。画像については、長いセッションでは Files API を使って同じ画像を参照し、毎回 base64 を再送信するのを避けるべきです。同じ画像が繰り返しミス入力として計上されると、コストは急速に積み上がります。

KV Cache に関連するもう一組の事実も注目に値します。V4.1-Flash のトークンあたりの KV Cache サイズは約 890 bytes、V4 Flash は約 3514 bytes です。HBM 需要は前世代の 1/4 に、SSD ストレージは 1/8 に低下し、初代 DeepSeek と比べて約 437 倍小さくなっています。これは、自社構築のデプロイ時に VRAM とストレージの負荷が大幅に緩和され、長いコンテキストの限界コストが著しく下がることを意味します。実践的な提案：バッチ処理タスクはアイドル時間帯に実行して直接半減させる。出力は必要な長さに制限し、できるだけ JSON を使って無効なトークンを減らす。高頻度で繰り返される抽出タスクでは、まず画像を重複排除してからモデルに入れる。キャッシュヒット率を監視し、想定より低い場合はプレフィックスが動的コンテンツによって分断されていないか確認する。

デプロイとエコシステムの実装：Hugging Face の重み、超算インターネットのワンクリック API、WorkBuddy と OpenCode の接続

V4.1-Flash は 2026-09-10 にリリースされオープンソース化されました。重みは Hugging Face で公開され、リポジトリは deepseek-ai/DeepSeek-V4.1-Flash で、技術レポートも添付されており、直接ダウンロードして二次開発やローカルデプロイが可能です。GPU クラスタを持たないチームにとっては、国家超算インターネットが 2026-09-11 に DeepSeek V4.1 Flash モデル API サービスと重みファイルを公開しました。開発者はワンクリックで API を呼び出すことも、重みをダウンロードしてローカルデプロイすることもでき、これは「ゼロインフラ」で始めるための経路です。

エコシステム側では、公式パートナーである WorkBuddy（CodeBuddy を含む）と OpenCode が全面的に接続済みで、これらのツール内で V4.1-Flash を直接選択できます。公式は、オープンソースコミュニティと密接に協力して V4.1-Flash の推論サポートを推進し、さらなるデプロイオプションを模索すると述べています。2000 GPU + ストレージクラスタを対象とした大規模デプロイについては、公式と相談して協業できます。注意が必要なのは、旧モデル名 deepseek-v4-flash と deepseek-v4-flash-vision-exp はサービス終了となり、V4.1-Flash を指す一時的な互換ルートのみが残されていることです。長期的に使用する場合は deepseek-flash に統一してください。C 向け製品でも、従来の「高速応答／専門相談／画像認識」という3つの対話入口が単一のインタラクティブ画面に統合されており、マルチモーダルがもはや独立した入口ではなく、デフォルトの機能であることを示しています。

まとめとベストプラクティス

全文を実行可能なチェックリストに圧縮します：

モデルの統一：一律で deepseek-flash を使用し、base_url は https://api.deepseek.com。deepseek-v4-flash と deepseek-v4-flash-vision-exp は直ちに停止する。
抽出系タスク：JSON Output で schema を制約し、フィールドは狭いほど安定する。重要フィールドには confidence を付け、閾値未満なら Tool Calls で再検証する。
制御された生成：フォーマット制御が必要なら対話プレフィックス継続を使用。コード／テキスト補完なら FIM を使用し、FIM は非思考モードに限定。
モード選択：デフォルトは思考、強度は low/high/max を必要に応じて。抽出と高頻度 Agent ループには low または非思考を使い、複雑な推論で格上げする。
コンテキスト管理：1M コンテキスト、384K 最大出力は上限であり目標ではない。スクリーンショットは差分圧縮し、長いセッションの画像は Files API で再利用する。
Agent 設計：Terminal-Bench 3.0 30.0、DeepSWE v1.1 74.2、Automation-Bench 54.8 を参考にし、長いターミナルタスクでは短いチェーン + 高頻度検証 + 外部ステートマシンによるフォールバックを行う。
評価の対照：Terminal-Bench 2.1 90.6、CyberGym 88.1 と V4 Pro の 87.9 および 83.3 を比較し、バージョン差とリトライ戦略に注意し、固定パラメータで複数回の平均を取る。
コスト管理：キャッシュヒット入力はアイドル 0.02 元／ピーク 0.04 元、ミスは 1／2 元、出力は 4／8 元。安定したプレフィックスを前に置いてヒット率を上げ、バッチ処理はアイドル時間帯に配置し、出力は JSON で長さを制御する。
デプロイ経路：自社構築なら deepseek-ai/DeepSeek-V4.1-Flash の重みをダウンロード。ゼロインフラなら国家超算インターネット（2026-09-11 公開）のワンクリック API。ツール側は WorkBuddy / OpenCode を使用。大規模クラスタ（2000 GPU + ストレージ）は公式に相談する。
並行性と移行：並行上限は 2500 で、キューイングが必要。Anthropic スタイルのインターフェースは互換移行でき、主な変更点はモデル名、画像入力パラメータ、思考モードのマッピング。

これで、画像入力からビジュアル Agent までの完全なループを詳しく説明しました。V4.1-Flash は最小サイズで、ファミリー内でも非常に競争力のあるハードベンチマークと極めて低い推論コストを実現しています。あとは、上記のチェックリストを一つずつ本番システムに落とし込むだけです。