google-image-search

Google Image Search Skill

Google Custom Search API を使用して、インテリジェントなスコアリングと LLM ベースの選択により画像を検索します。

使用する場面

• 技術記事や研究を説明する画像を探す
• プレゼンテーションに画像を追加する
• 関連画像を追加して Obsidian のノートを充実させる
• 複数のトピックを対象に画像を一括検索する
• プレーンテキストのリストから画像検索の設定を生成する

要件

• Google Custom Search API キーと Search Engine ID
• OpenRouter API キー（LLM による選択用）
• /opt/homebrew/bin/llm にインストールされた llm CLI

認証情報を .env に保存します。

Google-Custom-Search-JSON-API-KEY=your_key
Google-Custom-Search-CX=your_cx
OPENROUTER-API-KEY=your_openrouter_key

（OPENROUTER_API_KEY=... という形式も使用できます。以下のプラグインに関する注意事項をご覧ください。）

OpenRouter / llm-openrouter に関する注意事項

llm-openrouter プラグインは、OPENROUTER_KEY という名前のキー（環境変数、または llm keys set openrouter）を読み込める場合にのみ、モデルを登録します。OPENROUTER_API_KEY のみを設定すると、llm models list に OpenRouter のモデルが一つも表示されず、openrouter/... という名前はすべて Unknown model エラーになります。その場合、スクリプトは警告なくキーワードスコアリングにフォールバックします。llm_select.py はサブプロセス用に両方の名前を設定するため、この問題は処理されています。選択機能が再び動作しなくなった場合は、まず OPENROUTER_KEY を確認してください。

llm models list | grep -c openrouter   # 458+ means the plugin registered its models

動作モード

1. シンプルなクエリ

単一の語句を検索します。

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --query "neural interface wearable device" \
  --output-dir ./images \
  --num-results 5

2. 一括処理

JSON 設定から複数のクエリを処理します。

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --config image_queries.json \
  --output-dir ./images \
  --llm-select

3. 語句から設定を生成

LLM を使って、語句のリストから JSON 設定を作成します。

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --generate-config \
  --terms "AlterEgo wearable" "sEMG electrodes" "BCI headset" \
  --output my_queries.json

4. Obsidian のノートを充実させる

ノートから画像向きの語句を抽出し、画像を探して、見出しの下に挿入します。

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --enrich-note ~/Brains/brain/Research/neural-interfaces.md

このモードでは、次の処理を行います。

1. Obsidian の保管庫と添付ファイルフォルダーを検出します
2. LLM を使って、ノートから視覚的に適した語句を抽出します
3. 各語句に対応する画像を検索します
4. 最適な画像を添付ファイルフォルダーにダウンロードします
5. 関連する見出しの下に画像の埋め込みを挿入します
6. ノートを変更する前にバックアップを作成します

主なオプション

オプション	説明
--query TEXT	単一のクエリを検索します
--config FILE	一括処理用の JSON 設定
--generate-config	--terms から設定を生成します
--enrich-note FILE	Obsidian のノートを充実させます
--output-dir DIR	画像の保存先
--urls-only	ダウンロードせず、URL のみを返します
--llm-select	LLM を使って最適な画像を選択します（デフォルト：オン）
--no-llm-select	LLM による選択を無効にします
--num-results N	クエリごとの検索結果数（デフォルト：5）
--dry-run	実行される処理を表示します

JSON 設定の形式

各エントリで次の項目を指定できます。

{
  "id": "unique-id",
  "heading": "Display Heading",
  "description": "Context for what image to find",
  "query": "Google search query",
  "numResults": 5,
  "selectionCriteria": "What makes a good image",
  "requiredTerms": ["must", "have"],
  "optionalTerms": ["bonus", "terms"],
  "excludeTerms": ["stock", "clipart"],
  "preferredHosts": ["official-site.com"],
  "selectionCount": 2
}

詳しい説明は references/api_config_reference.md をご覧ください。

スコアリングシステム

画像は次の基準に基づいてスコアリングされます。

• 必須語句：含まれていない場合は -80、すべて含まれている場合は +30
• 任意の語句：一致する語句ごとに +5
• 除外語句：一致する語句ごとに -50
• 優先ホスト：信頼できる場合は +25、不明な場合は -5
• MIME タイプ：PNG／JPEG は +5、GIF は -10
• 解像度：高解像度は +10、低解像度は -10
• ファイルサイズ：非常に小さい場合は -5

LLM による選択

スコアリング後、LLM は次の情報に基づいて上位候補から最適な画像を選びます。

• タイトルと URL のメタデータ
• スコアリングの理由
• 選択基準

LLM は技術分野の読者にとっての信頼性、明瞭さ、関連性を評価します。

Obsidian との連携

Obsidian の保管庫内では、次の処理を行います。

• .obsidian フォルダーを使って保管庫のルートを自動検出します
• 設定済みの添付ファイルフォルダーを使用します（デフォルト：Attachments）
• Obsidian 形式の埋め込みを生成します：![[image.png|alt text]]
• ノートを変更する前にバックアップを作成します

スクリプトファイル

ファイル	役割
google_image_search.py	メインのエントリーポイント
api.py	Google Custom Search API
config.py	認証情報と設定の処理
download.py	マジックバイトを使った画像のダウンロード
evaluate.py	キーワードベースのスコアリング
llm_select.py	LLM による選択と語句の抽出
obsidian.py	保管庫の検出と内容の充実
output.py	Markdown 出力の生成