開発 #25
完了yfoxaiの作成
説明
- yfoxai — ローカルLLM(VLM)画像処理ライブラリ 新規作成計画
- Context(背景・目的)
yfoxlib はマシンビジョン向けの MFC C++ DLL 群。既存 `yfoximg` は古典的画像処理(2値化・ラベリング・マッチング・輪郭追跡)を提供するが、
「ローカルで動く VLMに画像を問い合わせ、良否判定・OCR・物体検出などを行う」 AI レイヤーは持たない。
本計画は、LM Studio / llama.cpp(`llama-server`)で動くローカル VLM を利用する新規 MFC 拡張 DLL `yfoxai` を、
既存 yfoxlib の規約(MFC 拡張 DLL / `_AFXEXT` エクスポート / `clog` ロギング / UTF-8 BOM+CRLF / 5.1.0.0)に沿って追加する。
成立性: LM Studio も llama.cpp も OpenAI 互換 REST(`POST /v1/chat/completions`、画像は `image_url` の base64 data URI)を出すため、
1つの HTTP クライアントで両対応可能。画像は yfoximg の `CDiBitmap`/`CImageEx`(GDI+)で JPEG/PNG に IStream エンコード→base64 できる。
→ 実現可能。新規実装が必要なのは ① HTTP 層、② JSON、③ base64、④ バックエンド抽象、⑤ VQA API 設計 のみ。
- 確定仕様(ユーザー回答)
- 提供機能(v1): 良否判定/分類・OCR/文字読取・物体検出(bbox)。入力画像は `CDiBitmap`。
- 通信: WinHTTP / 自前TCP / llama.cpp(in-process) を実行時に切替可能**にする。
- **依存/受け渡し: `CDiBitmap` を直接受け取る MFC 拡張 DLL。
- アーキテクチャ(層構成)
```
アプリ(ImgChkSystem 等, MFC)
└─ yfoxai.dll (MFC拡張DLL)
├─ CAiPipeline / IAiStage … 前処理→ROI→判定 を段連結。バッチ/並列で throughput
├─ CAiVision … 公開API。CDiBitmap* を受けVQAタスクを実行
├─ 画像→data URI 変換 … CDiBitmap → BGR→RGB / pitch補正 → JPEG/PNG → base64
├─ IChatBackend(抽象) … 「messages(text+image) を投げ応答テキストを得る」1関数
│ ├─ CWinHttpBackend (winhttp.lib, TLS/chunked/SSE をOS任せ) ★既定
│ ├─ CRawTcpBackend (yfoxnet CSocketComm/CClient 上に自前HTTP/1.1)
│ └─ CLlamaCppBackend (libllama C API を直接リンク; #ifdef で任意ビルド)
├─ nlohmann/json … リクエスト生成 / 応答(choices0.message.content)解析
└─ clog ロギング … SetAiLogSink / SetAiLogSeverity
依存: yfoximg.lib(CDiBitmap/画像エンコード) + yfoxbase.lib, 任意で yfoxnet.lib(自前TCP時)
```
設計の要: バックエンドを `IChatBackend` 1インターフェースに集約し、`CAiVision::SetBackend(BackendKind)` で切替。
上位の VQA ロジック(プロンプト・JSON スキーマ・応答パース)はバックエンド非依存にする。
- 1. プロジェクト雛形(yfoximg をベースに複製)
`yfoximg` を雛形に `yfoxai\` を新設(yfoximg は既に yfoxbase.lib リンク設定済みのため yfoxnet より手本に向く)。
複製・リネームする骨格ファイル(いずれも yfoxai へ改名):
- `yfoxai.vcxproj` / `.vcxproj.filters`(ProjectGuid を新規採番、`RootNamespace=yfoxai`、`yfoximg`→`yfoxai` 全置換)
- `stdafx.h` / `stdafx.cpp`(MFC + `#ifndef PLOG_INSTALL … #include "clog/Log.h"`。winsock は自前TCP採用時のみ `afxsock.h`)
- `dllmain.cpp`(`AFX_EXTENSION_MODULE yfoxaiDLL` + `SetAiLogSink`/`SetAiLogSeverity` の `__declspec(dllexport)` 実装)
- `yfoxai.h`(集約公開ヘッダ)/ `yfoxai.cpp`(空実装)/ `yfoxai.def`(空)
- `targetver.h` / `resource.h` / `yfoxai.rc`(バージョン 5,1,0,0 / 名称を yfoxai に)/ `res\yfoxai.rc2`
- `include\clog\Log.h`(root `C:\debug\yfoxlib\include\clog\Log.h` からコピー、4ファイル一致を維持)
.vcxproj 主要設定(4構成 Debug/Release × Win32/x64 に整理、yfoximg の `Release_debug*` は作らない):
- `PlatformToolset=v143` / `WindowsTargetPlatformVersion=10.0` / `CharacterSet=Unicode` / `UseOfMfc=Dynamic` / `ConfigurationType=DynamicLibrary`
- Preprocessor に `_AFXEXT` 必須、x64 は `stdcpp17`
- 依存(4構成すべてに設定 ← yfoximg の Release_debug* 未設定バグを踏襲しない):
- `AdditionalIncludeDirectories`: `$(SolutionDir)include;$(ProjectDir)..\yfoxbase;$(ProjectDir)..\yfoximg;%(...)`
- `AdditionalDependencies`: `$(ProjectDir)..\yfoxbase\$(Platform)\$(Configuration)\yfoxbase.lib;$(ProjectDir)..\yfoximg\$(Platform)\$(Configuration)\yfoximg.lib;%(...)`
- WinHTTP: `winhttp.lib` を追加(既定)。自前TCP採用時は `yfoxnet.lib` を追加。
- ソースは UTF-8 BOM+CRLF(`.rc` は UTF-16LE)。
- 2. 画像 → data URI 変換(新規ヘルパ)
`yfoximg` の GDI+ 経路を使う(参照: `yfoximg\atlimage0.h:353` `CImageEx::Save(IStream*, REFGUID)`, `yfoximg\DiBitmap.h`)。
新規 `AiImageCodec.h/.cpp`:
1. `CDiBitmap*` から画像を取得。**色順 BGR→RGB 入替**、**`m_nPitch<0`(ボトムアップ)補正**を行い正立 RGB に整える
(参照: `DiBitmap.h:17` `enum RGB_DATA{B,G,R}`、`DiBitmap.cpp:218` の reverse 処理)。
2. `CreateStreamOnHGlobal` で `IStream` を作り `CImageEx::Save(pStream, ImageFormatJPEG or PNG)` でメモリ上に符号化(ディスク不経由)。
- 既定 JPEG。OCR/微細判定は PNGを選べるオプション。
3. `IStream` のバイト列を base64 化(新規 `Base64Encode()`。`CryptBinaryToStringA(CRYPT_STRING_BASE64|NOCRLF)` で実装可)。
4. `data:image/jpeg;base64,<...>` の data URI 文字列を返す。
- 3. 通信バックエンド `IChatBackend`(切替可能)
```cpp
struct ChatRequest { CStringA model; CStringA systemPrompt; CStringA userPrompt;
CStringA imageDataUri; CStringA jsonSchema; int maxTokens; float temperature; };
struct ChatResult { bool ok; CStringA contentUtf8; CStringA rawJson; CStringA error; };
struct AFX_EXT_CLASS IChatBackend { virtual ChatResult Chat(const ChatRequest&) = 0; virtual ~IChatBackend(){} };
```
- CWinHttpBackend(既定): `WinHttpOpen/Connect/OpenRequest/SendRequest/ReceiveResponse`。
ヘッダ解析・chunked・タイムアウトを OS 任せ。LLM は応答が長いため 受信タイムアウトを分単位**に設定。TLS も透過対応。
- *CRawTcpBackend: `yfoxnet` の `CSocketComm::ConnectTo/WriteComm/ReadComm`(参照 `yfoxnet\SocketComm.h:141,152,153`)上に
`POST /v1/chat/completions HTTP/1.1` を手組み。`m_bNotYFMode=true` 相当の生バイト送信。`Content-Length`/chunked を自前解析。
接続は `CLogClient::ConnectTcpFast`(参照 `yfoxnet\LogClient.cpp:107`)のノンブロッキング connect 作法を流用しサーバ未起動時のフリーズを防ぐ。
- CLlamaCppBackend(任意, `#ifdef YFOXAI_WITH_LLAMACPP`): libllama の C API を静的リンクし in-process 推論。
外部 SDKは repo 規約どおり `$(SolutionDir)include\` / `$(SolutionDir)lib\$(Platform)\` に各自配置。
LM Studio/HTTP 非経由。*外部 SDK 依存が重いため v1 ではビルドスイッチで無効を既定**とし、HTTP 2 バックエンドを先に完成させる。
JSON: `yfoxai\include\nlohmann\json.hpp`(single-header)を同梱(既存 `include\clog\` と同じ自作/同梱方針)。
OpenAI 互換 body(`messages` に `{type:text}`+`{type:image_url}`、`response_format` に `json_schema`)を生成し、
応答 `choices0.message.content` を抽出。UTF-8(`CStringA`)前提で扱う。
- 4. 公開API `CAiVision`(AFX_EXT_CLASS)
```cpp
class AFX_EXT_CLASS CAiVision {
public:
enum BackendKind { BK_WinHttp, BK_RawTcp, BK_LlamaCpp };
void SetBackend(BackendKind); // 実行時切替
void SetEndpoint(LPCTSTR host, int port); // 既定 127.0.0.1:1234(LM Studio) / 8080(llama-server)
void SetModel(LPCTSTR modelName); // 空なら現在ロード中モデル
// --- v1 タスク(いずれも CDiBitmap* 入力・構造化 JSON 出力) ---
bool Classify(CDiBitmap* pSrc, const CStringArray& labels, /*out*/ CString& label, /*out*/ double& conf, /*out*/ CString& reason);
bool JudgeOkNg(CDiBitmap* pSrc, LPCTSTR criteria, /*out*/ bool& ng, /*out*/ double& conf, /*out*/ CString& reason);
int Ocr(CDiBitmap* pSrc, /*out*/ CString& text); // 文字列抽出
int Detect(CDiBitmap* pSrc, LPCTSTR targetDesc, /*out*/ CArray<AiDetection>& dets); // bbox(x,y,w,h)+label+score
bool Ask(CDiBitmap* pSrc, LPCTSTR prompt, /*out*/ CString& answer); // 汎用VQA(全機能の基礎)
CString LastError() const;
};
```
- 各タスクは `Ask`(汎用VQA)を土台**に、専用プロンプト+`json_schema`(`response_format`)で構造化応答を強制し、`json.hpp` でパースする実装。
- *物体検出の注意: VLM の bbox 精度は限定的。座標は画像サイズで正規化(0..1)して返し、必要ならアプリ側で yfoximg のマッチング/ラベリングと併用する旨をドキュメント化。
- エクスポートは既存同様 `AFX_EXT_CLASS`(`.def` 空)。*クライアントは MFC 前提**(CDiBitmap 直接受け渡しの帰結)。
- 5. 処理パイプライン `CAiPipeline`(段=ステージの連結)
古典画像処理(yfoximg)と VLM 推論(yfoxai)を ステージの連結**として構成し、
「前処理 → ROI 切出 → data URI 化 → VLM タスク → 後処理/集約」を宣言的に組めるようにする。
複数 ROI / 複数画像を **バッチ・非同期(スレッドプール) で流せる throughput 指向の設計。
ステージ抽象(共通コンテキストを受けて更新):
```cpp
struct AiPipeContext { // ステージ間で受け渡す作業データ
CDiBitmap* pImage; // 現在の対象画像(ROI切出で差し替わる)
CRect roi; // 関心領域
CStringA imageDataUri; // エンコード済み(EncodeStage が設定)
nlohmann::json results; // 各ステージの出力を蓄積(キー付き)
CString error;
};
struct AFX_EXT_CLASS IAiStage { // 1ステージ = 1責務
virtual bool Run(AiPipeContext& ctx) = 0; // false で以降を中断
virtual ~IAiStage() {}
};
class AFX_EXT_CLASS CAiPipeline {
public:
CAiPipeline& Add(IAiStage* pStage); // 段を追加(所有権を取る)
bool Run(CDiBitmap* pSrc, /*out*/ nlohmann::json& out); // 単一画像を通す
int RunBatch(const CArray<CDiBitmap*>& imgs, /*out*/ CArray<nlohmann::json>& outs); // バッチ
void SetParallelism(int nThreads); // バッチ/複数ROIの並列度(既定=論理コア-2)
CString LastError() const;
};
```
標準ステージ(すべて `IAiStage` 実装。yfoximg の `CImgProcessing`/`CDiBitmap` を内部利用):
- `CRoiStage` … `CRect` で ROI 切出(複数 ROI をファンアウトし各々を後段へ)。
- `CPreprocStage` … グレースケール化・2値化(`CImgProcessing::Threshold*`)・コントラスト/ガンマ等の前処理。
- `CEncodeStage` … §2 の `AiImageCodec` で `imageDataUri` を生成(JPEG/PNG 選択)。
- `CVqaStage` … `CAiVision::Ask/Judge/Classify/Ocr/Detect` のいずれかを実行し `results[key]` へ格納(バックエンドは共有)。
- `CGateStage` … 条件分岐(前段結果が閾値未満なら以降スキップ等)。**「まず古典手法で候補を絞り、絞った ROI だけ VLM に問う」** といった段構成でコスト削減。
- `CAggregateStage` … 複数 ROI/タスク結果を 1 つの JSON へ集約。
並列/非同期の要:
- バッチと複数 ROI は `SetParallelism` のスレッドプールで並列化するが、**VLM への同時リクエスト数は上限を設ける**
(ローカル LLM は基本 1〜数並列。過剰投入は逆に遅くなる)。既定は控えめ(例 2)にし調整可能とする。
- 各 `IChatBackend` 実装は スレッドセーフ(バックエンドはステートレスに近い設計、接続はリクエスト毎 or プール)にする。
- 進捗は clog ロギング(§5.5)へ。長時間タスクのため段ごとの所要時間を出す。
利用イメージ:
```cpp
CAiPipeline pipe;
pipe.SetBackend(BK_WinHttp);
pipe.Add(new CPreprocStage(GRAY))
.Add(new CRoiStage(rois)) // N個のROIへファンアウト
.Add(new CGateStage(/*古典スコアで足切り*/))
.Add(new CEncodeStage(JPEG))
.Add(new CVqaStage(TASK_JUDGE, _T("はんだ不良の有無"), "judge"))
.Add(new CAggregateStage());
nlohmann::json out; pipe.Run(pSrc, out);
```
- 6. ロギング(既存 clog パターン踏襲)
`yfoxai.h` に `_AFXEXT` 対称で宣言、`dllmain.cpp` に実装(参照: `yfoxnet\dllmain.cpp:66`)。
```cpp
#ifndef _AFXEXT
__declspec(dllimport) void SetAiLogSink(yclog::IYLogSink* pSink);
__declspec(dllimport) void SetAiLogSeverity(yclog::Severity severity);
#else
__declspec(dllexport) void SetAiLogSink(yclog::IYLogSink* pSink);
__declspec(dllexport) void SetAiLogSeverity(yclog::Severity severity);
#endif
```
実装は `yclog::SetSink<PLOG_DEFAULT_INSTANCE_ID>(pSink)` / `SetMaxSeverity`。アプリは既存 `CLogClientSink`(yfoxnet)をそのまま注入可能。
- 変更/新規ファイル一覧(要点)
新規ディレクトリ `C:\debug\yfoxlib\yfoxai\`:
- 骨格: `yfoxai.vcxproj(.filters)`, `stdafx.h/.cpp`, `dllmain.cpp`, `yfoxai.h/.cpp`, `yfoxai.def`, `targetver.h`, `resource.h`, `yfoxai.rc`, `res\yfoxai.rc2`
- 機能: `AiVision.h/.cpp`(公開API), `ChatBackend.h`(抽象), `WinHttpBackend.h/.cpp`, `RawTcpBackend.h/.cpp`, `LlamaCppBackend.h/.cpp`(#ifdef), `AiImageCodec.h/.cpp`(画像→data URI), `Base64.h/.cpp`
- パイプライン: `AiPipeline.h/.cpp`(`CAiPipeline`/`IAiStage`), `AiStages.h/.cpp`(`CRoi/CPreproc/CEncode/CVqa/CGate/CAggregate` 各ステージ)
- 同梱: `include\clog\Log.h`, `include\nlohmann\json.hpp`
- ドキュメント: `CLAUDE.md` の表へ `yfoxai` 行を追記、UML/docs は既存規約(全面書換禁止・実証済み構文で小さく追加)に従い後追い。
- ビルド手順
- 前提: yfoxbase, yfoximg を先にビルド
msbuild yfoxbase\yfoxbase.vcxproj /p:Configuration=Release /p:Platform=x64
msbuild yfoximg\yfoximg.vcxproj /p:Configuration=Release /p:Platform=x64 - 自前TCP バックエンドを使うなら yfoxnet も
msbuild yfoxnet\yfoxnet.vcxproj /p:Configuration=Release /p:Platform=x64 - 本体
msbuild yfoxai\yfoxai.vcxproj /p:Configuration=Release /p:Platform=x64
```
統合 `.sln` は使わず `.vcxproj` を直接 MSBuild(既存規約どおり)。
- 検証(end-to-end)
テストプロジェクトは無いため、小さな確認用ハーネスで実挙動を確認する:
1. 前提環境: LM Studio(既定 `127.0.0.1:1234`)または `llama-server`(`:8080`)を起動し、**VLMをロード**。
2. 疎通(バックエンド非依存の一次確認): PowerShell の `Invoke-RestMethod` で `/v1/models` と、テスト画像 base64 を含む `/v1/chat/completions` を叩き、期待どおり応答が返るか確認(WinHTTP/自前TCP が組む body の正解を先に固める)。
3. DLL 検証ハーネス(scratchpad に最小 MFC コンソール/ダイアログ):
- `CDiBitmap::Load` でサンプル画像読込 → `CAiVision::Ask/Ocr/JudgeOkNg/Classify/Detect` を呼び出し、結果を標準出力/ログへ。
- `SetBackend(BK_WinHttp)` と `SetBackend(BK_RawTcp)` の両方で同一画像・同一プロンプトの応答が一致することを確認(切替の等価性)。
- `SetAiLogSink` に簡易シンクを登録し、送信 body・受信サイズ・所要時間がログに出ることを確認。
4. 画像コーデック単体: 既知の小画像を data URI 化 → デコードして往復一致(BGR/pitch 補正の正しさ)を確認。
5. パイプライン: `CPreproc→CRoi(複数)→CGate→CEncode→CVqa→CAggregate` を組み、(a)集約 JSON が全 ROI 分揃う、(b)`CGate` で足切りされた ROI は VLM を呼ばない、(c)`SetParallelism` を上げても結果が同一(順序非依存)で所要時間が短縮、を確認。
6. `LlamaCppBackend` は SDK 配置後に別途(v2)。
- 段階実装(推奨順)
1. 雛形(ビルドが通る空DLL+`SetAiLogSink`)を確立。
2. `AiImageCodec`(画像→data URI)+ `Base64` + `json.hpp` 同梱、検証4を通す。
3. `CWinHttpBackend` + `CAiVision::Ask`(汎用VQA)で最短 end-to-end(検証3)を通す。
4. `JudgeOkNg`/`Classify`/`Ocr`/`Detect` を `json_schema` 構造化応答で追加。
5. *`CAiPipeline`/`IAiStage` と標準ステージ*を追加(単一→バッチ→並列の順)。まず逐次で正しさを固め、`SetParallelism` で throughput を上げる(検証5)。
6. `CRawTcpBackend`(自前HTTP/1.1 on CSocketComm)を追加し切替等価性を確認。
7. `CLlamaCppBackend`(任意, `#ifdef`)は SDK 配置後に v2。
8. `CLAUDE.md`/docs へ追記。
- 未決/リスク
- 物体検出(bbox)精度: VLM 依存で不安定。正規化座標+yfoximg 併用を前提とする。
- 自前HTTP の SSE/chunked: `stream:true` を使うなら逐次パースが必要。v1 は非ストリーミング(`stream:false`)で単純化し、必要時に拡張。
- エンドポイント差: LM Studio 既定 `:1234`、llama-server 既定 `:8080`。`SetEndpoint` で吸収。
- `response_format`/`json_schema` 対応: 新しめの LM Studio / llama.cpp は対応。非対応時はプロンプトで JSON 強制+寛容パースにフォールバック。
- パイプライン並列度: ローカル LLM は同時リクエストに弱い(1〜数並列で頭打ち/悪化)。VLM 段の同時数上限を既定控えめにし、`CGate` で古典手法の足切りを併用して VLM 呼び出し回数自体を削る方針。