linkfox-multimodal-product-similarity

マルチモーダルな商品画像の類似性分析

このスキルでは、商品のメイン画像の視覚的な類似性に基づいて、商品を分析およびグループ化する方法を説明します。Amazonの出品者が同じスタイルの商品を特定し、競合商品の類似品を検出し、商品リストを視覚的にまとまりのあるクラスターに整理するのに役立ちます。

基本概念

商品画像の類似性分析では、マルチモーダル AI を使用して商品のメイン画像を比較し、外観、色、構図、素材などの視覚的特徴に基づいて自動的にグループ化します。これは後処理ツールです。前のステップ（商品検索や商品レコメンデーションなど）ですでに取得された商品データを対象に動作します。

類似性しきい値：similarityThreshold パラメーターは、2つの商品が同じグループに分類されるために、どの程度視覚的に似ている必要があるかを制御します。0から100までの整数で、パーセンテージを表します。値が高いほど照合条件が厳しくなり、ほぼ同一の画像のみが同じグループに分類されます。値が低いほど照合条件が緩やかになり、より幅広い視覚的クラスターが作成されます。デフォルト値は 60 です。

単一ブランドのグループのフィルタリング：includeSingleBrandGroups フラグ（デフォルトは true）は、1つのブランドの商品のみを含むグループを結果に含めるかどうかを制御します。false に設定すると、単一ブランドのグループが除外されます。競合商品の類似品分析など、ブランドをまたいだ視覚的な重複に注目したい場合に便利です。

入力データ要件

このツールには、前のステップから渡される products リストが必要です。単独で商品データを取得することはできません。一般的なワークフローは次のとおりです。

1. 商品検索ツールまたはレコメンデーションツールを実行して、商品リストを取得します。
2. 視覚的な類似性に基づいてグループ化するため、refResultData を介してその商品リストをこのツールに渡します。

入力データは、products 配列を含む JSON オブジェクトである必要があります。

パラメーター

パラメーター	型	必須	説明
similarityThreshold	integer	いいえ	類似性のしきい値（0～100）。デフォルトは 60 です。値が高いほど照合条件が厳しくなります。
includeSingleBrandGroups	boolean	いいえ	1つのブランドのみを含むグループを含めるかどうか。デフォルトは true です。ブランドをまたいだ類似性に注目するには、false に設定します。
refResultData	string	いいえ	商品リストを含む、前のツールの結果データを表す JSON 文字列です。
userInput	string	いいえ	元のユーザーのクエリまたは指示のテキストです。

レスポンスフィールド

フィールド	型	説明
groups	array	類似グループのリストです。各グループには、groupNumber、reason、brandCount、商品詳細の配列 asins が含まれます。
analysisInfo	object	概要：totalProductsAnalyzed、totalGroupsFound、similarityThreshold、analysisTimestamp。
tables	array	表形式の結果データです。各要素には data、columns、name が含まれます。
total	integer	結果項目の合計数です。
title	string	結果のタイトルです。
type	string	レンダリングスタイルのヒントです。
costToken	integer	消費された LLM トークンの合計数（入力＋出力）です。

グループ項目（asins 配列の要素）

フィールド	型	説明
asin	string	商品の ASIN
productId	string	商品 ID
brand	string	ブランド名
price	number	価格
rating	number	評価スコア
ratings	integer	評価数
monthlySalesUnits	integer	月間販売数
monthlySalesRevenue	number	月間売上高
monthlySalesUnitsGrowthRate	number	月間販売数の成長率
imageUrl	string	メイン画像の URL
productImageUrls	array	すべての商品画像の URL
imagePrompt	string	AI が生成した画像の説明
asinUrl	string	商品詳細ページの URL
availableDate	string	出品日
color	string	色
material	string	素材

呼び出し方法

• API エンドポイント：POST /multimodal/analyzeProductSimilarity（完全なパラメーター／レスポンス／エラーコードは references/api.md を参照）
• Python スクリプト：python scripts/multimodal_analyze_product_similarity.py '<JSON 参数>' [--inline]
• コストの制約：このツールは計算リソースを消費します。同一セッション内で同じパラメーターの組み合わせを使用する呼び出しは、デフォルトで 1 回のみです。スクリプトには 24h のローカルキャッシュがあります。失敗または空の結果が返された場合、キーワードの変更、ページ送り、郵便番号の変更を自動で繰り返して試してはいけません。検索を続ける必要がある場合は、追加のコストが発生することを事前にユーザーに説明してください。

出力方針（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-multimodal-product-similarity-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリに該当します。<session> は環境変数 SESSION_ID から取得し、ユーザーのタスクに応じて自動的に集約されます。**/tmp への書き込みは禁止です。**現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルに書き込んだ後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに書き込んだ後、stdout には要約（トップレベルのフィールド、total／costToken などの一般的なカウント、最大のリストフィールドの長さと先頭 3 件のサンプル）のみを出力します
• --inline を追加すると、stdout への全量出力を強制します（同様にファイルにも書き込みます）

データの読み取りに関する提案：まず要約を確認し、十分かどうかを判断してください。具体的なフィールドが必要な場合は、保存された json ファイルから jq または ConvertFrom-Json を使って必要なデータだけを抽出し、JSON 全体をコンテキストに含めないようにしてください。

認証と計算リソースの問題を解決する

以下の異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください。

異常な状況

• API Key が設定されていない：環境変数 LINKFOX_AGENT_API_KEY および LINKFOXAGENT_API_KEY のどちらも設定されていません。
• レスポンスのステータスコードが 401 または 402
• レスポンスに計算リソースまたは残高不足の表示がある：メッセージに「計算リソース残高不足／課金不足／残高不足／quota exceeded／insufficient balance／プランの有効期限切れ／チャージが必要／チャージしてください」または同様の意味の内容が含まれている場合。

使用例

1. 視覚的な類似性で検索結果をグループ化する（デフォルトのしきい値） 検索ツールで商品リストを取得した後、その結果をこのツールに渡して、見た目が似ている商品をクラスタリングします：

User: "Group these products by how similar they look."
Action: Call the API with refResultData set to the preceding product list JSON, using the default similarityThreshold of 60.

2. ほぼ同一の商品を見つける（厳密なマッチング）

User: "Which of these products have almost the same main image?"
Action: Call the API with similarityThreshold set to 85 or higher for strict visual matching.

3. ブランドをまたいだ競合商品の類似品を検出する

User: "Show me groups where different brands have similar-looking products."
Action: Call the API with includeSingleBrandGroups set to false to filter out single-brand clusters.

4. 幅広い視覚的クラスタリング（緩いしきい値）

User: "Roughly categorize these products by appearance."
Action: Call the API with similarityThreshold set to 40 for broad grouping.

5. 組み合わせ：ブランドをまたいだ厳密な類似性

User: "Find products from different brands that look nearly identical."
Action: Call the API with similarityThreshold set to 80 and includeSingleBrandGroups set to false.

表示ルール

1. グループ化結果を明確に提示する：各類似グループについて、グループ番号、グループ化の理由、ブランド数、およびグループ内の商品一覧表を表示します。
2. 可能な場合は商品画像を表示する：画像 URL がある場合は、ユーザーがグループ化を視覚的に確認できるよう、画像を含めます。
3. ブランドをまたぐグループを強調する：ユーザーが競合分析を重視している場合、複数のブランドを含むグループを強調します。
4. 分析の要約：分析した商品の合計数、見つかったグループの合計数、使用した類似度のしきい値、タイムスタンプを必ず提示します。
5. 主観的な助言はしない：グループ化データを客観的に提示します。ユーザーから求められない限り、ビジネス上の推奨を加えないでください。
6. 結果が大量にある場合：グループが多数ある場合は、最も重要なグループ（例：商品数またはブランド数が最も多いグループ）を先に表示し、残りのグループがあることをユーザーに伝えます。
7. エラー処理：リクエストが失敗した場合は、レスポンスメッセージに基づいて理由を説明し、調整方法（例：入力された商品データが有効か確認する、しきい値を調整する）を提案します。

重要な制限事項

• 後処理専用：このツールは商品データを独自に取得できません。前のステップから商品データを受け取る必要があります。
• データベースへの保存なし：結果はデータベースに保存されません。出力に対する二次分析にデータベースクエリツールを使用しないでください。
• 入力形式：入力は products 配列を含む JSON オブジェクトである必要があります。
• 直接要約に渡す：このツールの処理完了後、結果を要約のステージに直接渡してください。追加の中間データ計算を行わないでください。

ユーザーの表現とシナリオのクイックリファレンス

該当する場合 — 商品リストの視覚的な類似性分析：

ユーザーの発言	シナリオ
「見た目でグループ分けして」	ビジュアルクラスタリング
「見た目が似ている商品を探して」「類似商品を探して」	類似性の検出
「見た目が同じ商品はどれ？」	画像の重複排除
「競合他社の模倣商品を見せて」	ブランド横断の類似商品分析
「外観／色／スタイルで分類して」	ビジュアル分類
「このリストに重複商品はある？」	画像ベースの重複排除
「異なるブランドの同じスタイルの商品」	ブランド横断の類似性

該当しない場合 — 画像の類似性以外が必要な場合：

• テキストベースの商品比較（タイトル、説明、キーワード）
• 視覚的な要素を含まない、価格や売上に基づくグループ分け
• 商品検索や商品発見（このツールは既存のリストを後処理するだけです）
• レビュー分析、出品情報の最適化、広告戦略

計算リソースの消費ルール

動的なルールに基づいて課金されます：計算リソースの消費量 = 商品ごとのメイン画像のプロンプト生成呼び出しにおける（入力で消費した計算リソース + 出力結果で消費した計算リソース）の合計。

重要：本スキルのサービスは倍率に応じて動的に計算され、一度に大量の計算リソースを消費する可能性があります。必ずユーザーに警告し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

次のいずれかに該当する場合は、Feedback API を通じてフィードバックを自動検出し、報告してください。

1. このスキルで説明されている機能や目的が実際の動作と一致しない
2. スキルの結果がユーザーの意図と一致しない
3. ユーザーがこのスキルに対する不満や称賛を表明した
4. 改善できると思われることがある

references/api.md に記載された方法で Feedback API を呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境ECスキルをさらに利用するには、LinkFox Skills を設定してください。