| name | claudecode-cli-vision |
| description | claudecode.wl の Claude Code CLI 経路 (provider == "claudecode") で multimodal /
vision API (Image・PDF page 画像 OCR 等) を使うときの設計と動作パターン。
Phase 35 で `iClaudeQueryBgAPIMultimodal` に CLI リダイレクトが追加され、
$ClaudeModel = {"claudecode", "..."} のまま画像 OCR が無課金で動くようになった
仕組み。SourceVault.wl Stage 4C OCR (ClaudeVision backend) で実証済み。
|
claudecode CLI 経由の Vision / Multimodal
背景
claudecode.wl は次の 4 つの provider を $ClaudeModel = {provider, model} で区別する:
| provider | 経路 | 課金 |
|---|
claudecode | Claude Code CLI (Pro/Max サブスクリプション内) | なし |
anthropic | Anthropic API 直叩き | あり |
openai | OpenAI API | あり |
lmstudio | ローカル LLM | なし |
Phase 28 (2026-05-12) で provider tuple 化されたが、vision/multimodal は anthropic API
経路のみ実装されていた。Phase 35 (2026-05-18) で claudecode CLI 経路にも vision
が回るようになった。
Phase 35 修正の構造
iClaudeQueryBgAPIMultimodal[items_List, modelSpec_, timeoutSpec_] の provider 判定直後に
1 行追加するだけ:
provider = Which[
ListQ[modelSpec] && Length[modelSpec] >= 2 && StringQ[modelSpec[[1]]], modelSpec[[1]],
ListQ[$ClaudeModel] && Length[$ClaudeModel] >= 2 && StringQ[$ClaudeModel[[1]]], $ClaudeModel[[1]],
True, "anthropic"
];
providerLower = ToLowerCase[provider];
(* Phase 35 fix (2026-05-18): provider == "claudecode" は CLI 経路へリダイレクト *)
If[providerLower === "claudecode",
Return[iClaudeQueryRawNonBlocking[items, timeoutSpec]]];
(* multimodal は現時点 Anthropic のみ対応 (claudecode は上で処理済み) *)
If[providerLower =!= "anthropic",
Return["Error: multimodal API は現在 Anthropic または Claude Code CLI (provider 'claudecode') のみ対応..."]];
なぜこれで動くのか — iNormalizePrompt の既存実装
claudecode.wl の iNormalizePrompt[items_List] には 元々画像対応の実装が入っていた:
Image[...] オブジェクトを tmp dir に PNG として書き出しmediaFiles リスト構築- prompt text に「添付ファイル: 」として埋め込む
imageDirs を iMakeBat 経由で --add-dir <path> として Claude CLI に渡す- Claude Code CLI は prompt 内の画像ファイル参照を自動認識して vision 処理
つまりインフラは完成していたが、iClaudeQueryBgAPIMultimodal が claudecode を弾いていただけ。1 行のリダイレクトで実装が活きた。
呼出側のコード例 (PDFIndex / SourceVault 流)
呼出側 (SourceVault Stage 4C iOCRViaClaudeVision) は何も変更不要:
result = Quiet[
Block[{ClaudeCode`$iMediaMaxImageSize = 1568},
ClaudeCode`ClaudeQueryBg[
{prompt, img},
NonBlocking -> True,
Timeout -> 180]]];
Block[{$iMediaMaxImageSize = 1568}]: API 制限 (Anthropic 1568px) と同じ値で CLI 経路も
リサイズ。CLI 自身に上限はないが、無駄に大きな PNG を CLI に渡しても遅くなるだけNonBlocking -> True: フロントエンドをブロックしない経路 (ScheduledTask 不要、CLI に直接 invoke)- 戻り値は String (OCR 結果テキスト) または
"Error: ..." 文字列
性能特性
実測 (SourceVault.wl, Stage 4C ClaudeVision backend, page 1 of arXiv 1992-WOOC):
- PyMuPDF rasterization (page → PNG 300 DPI): ~0.7 秒
- 上半分 OCR: ~15 秒
- 下半分 OCR (30px overlap): ~19 秒
- 合計 35 秒/page
Anthropic API 直叩きより遅いが、無課金で動く実用範囲。複数 page を OCR する場合は
SourceVault の Phase 4B cache でその後の操作は瞬時。
エラーパターン
Pre-Phase 35: claudecode で multimodal を呼ぶと即エラー
Error: multimodal API は現在 Anthropic のみ対応しています。
詳細: provider 'claudecode' の multimodal API 形式 (例: OpenAI は image_url 方式) は
iClaudeQueryBgAPIMultimodal ではサポートされていません。
Phase 35 以降このエラーは出ない (Return[iClaudeQueryRawNonBlocking[items, timeoutSpec]] で先取り)。
Post-Phase 35: 起こりうるエラー
CLI 経路は次のように失敗しうる:
- Timeout: 大きな画像 + 長い prompt で 180 秒超過 (
"Error: タイムアウト (180秒)")
- CLI 自体の問題:
claude コマンドが PATH にない、サブスクリプション切れ
- 画像 PNG エクスポート失敗:
iResizeImageObj で Quiet[Export[..., "PNG"]] が失敗
呼出側 (SourceVault) は iOCRViaClaudeVision 内で StringStartsQ[result, "Error:"] で
判定し、OCRFailReason フィールドに記録する。
制約
- stream-json モードでは vision 未検証 (Phase 30.1 で導入された CLI モード)
- Anthropic API キーが必要なケースは依然存在:
$ClaudeModel = {"anthropic", ...} で
指定すれば直接 API、CLI を経由しない (より高速、ただし課金)
- モデル切替:
claudecode での model 指定 (e.g. {"claudecode", "claude-opus-4-7"}) は
CLI の --model フラグに反映される
検証手順 (リグレッション防止)
ClaudeCode`$ClaudeModel = {"claudecode", "claude-sonnet-4-6"};
(* 画像 1 枚を vision に流す *)
img = Rasterize[Plot[Sin[x], {x, 0, 2 Pi}], ImageResolution -> 100];
result = ClaudeCode`ClaudeQueryBg[
{"What does this image show? Reply in one sentence.", img},
NonBlocking -> True, Timeout -> 60];
StringQ[result] && StringLength[result] > 10 && !StringStartsQ[result, "Error:"]
(* True なら Phase 35 が正しく機能している *)
関連
- skill
ocr-backend-design: SourceVault Stage 4C の 3 backend 設計、ClaudeVision はこの skill の hook
- rules/97-pdfindex.md: PDFIndex の
cli-vision task category、ScheduledTask 経由の OCR 呼出
- claudecode.wl Phase 35 ChangeLog (header 53-62 行)
