multimodal-embedding-serving-user

マルチモーダル埋め込みサービング — ユーザー

埋め込みサービスを実行して呼び出します。コマンドは自分で実行し、出力を伝えてください。REST ベース URL：http://localhost:9777（ホストポートは setup.sh でハードコードされています。コンテナーは 8000）。

使用する場面

• 埋め込みサービスをデプロイ（Docker Compose またはスタンドアロン）して、正常性を確認する
• ポート 9777 の REST 経由でテキスト、画像、動画を埋め込む
• CLIP/SigLIP/MobileCLIP/CN-CLIP/Blip2/QwenText モデルを選択または切り替える
• Python SDK wheel を使って、プロセス内で埋め込みを統合する
• 400/422 エラーやモデルの機能不一致を診断する

プロンプトの例

このスキルでエンドツーエンドに対応する、問題解決シナリオの例：

例	解決する問題
image-similarity-finder.md	ローカルフォルダー内で視覚的・意味的に類似した画像を見つける
text-to-image-search.md	自然言語のクエリで画像フォルダーを検索する（ローカルメディア向けの「Google Lens」）
image-duplicate-detector.md	整理、QC、データセットの重複排除のために、フォルダー内の重複画像や類似画像を検出する

ドキュメントとデプロイファイル — クローンの有無を問いません

以下のすべてのパスは、edge-ai-libraries リポジトリ内の microservices/multimodal-embedding-serving/ を基準としています。クローンしていない場合は？ GitHub raw から取得してください：

https://raw.githubusercontent.com/open-edge-platform/edge-ai-libraries/main/microservices/multimodal-embedding-serving/<path>

必要に応じて、以下の既存ドキュメントを読み込んでください：

リソース	読み込む場面
docs/user-guide/api-reference.md + docs/user-guide/api-docs/openapi.yaml	テキスト以外のペイロード（画像／動画、base64、segment_config）を作成する場合、またはレスポンス／エラーを解析する場合
docs/user-guide/supported-models.md	モデルを選択または切り替える場合（次元数、モダリティ、言語、サイズ）
docs/user-guide/sdk-usage.md + docs/user-guide/wheel-installation.md	Python SDK wheel を使って、プロセス内で統合する場合
docs/user-guide/get-started.md	curl の追加例や環境変数の表が必要な場合
setup.sh、docker/compose.yaml	以下で使用するデプロイ成果物

1. コンテキストの振り分け — リポジトリをクローンするかスタンドアロンか？REST か SDK か？

• プロセス内の Python 統合を希望する場合（別個のサーバーは不要）：このサービスは SDK としても機能します — poetry build で wheel をビルドし（リポジトリが必要）、get_model_handler(...) + EmbeddingModel を使用してください。docs/user-guide/sdk-usage.md を参照してください。目安：まず REST を選び、Python プロセスで大量の埋め込みを行い、各項目の HTTP 通信が支配的なオーバーヘッドになる場合は SDK を選んでください。注：MobileCLIP/Blip2 の追加機能は Docker イメージにのみ含まれ、wheel は PyPI にありません。
• それ以外の場合は、クローンの有無を確認します：

  [ -f setup.sh ] && grep -q 'name = "multimodal-embedding-serving"' pyproject.toml 2>/dev/null \
    && echo REPO || echo STANDALONE
  

  REPO → マイクロサービスのルートからステップ 2 に進みます。STANDALONE → 2 つのデプロイファイルを取得してから、同じステップ 2 に進みます：

  RAW=https://raw.githubusercontent.com/open-edge-platform/edge-ai-libraries/main/microservices/multimodal-embedding-serving
  mkdir -p embedding-serving/docker && cd embedding-serving
  curl -fsSL $RAW/setup.sh -o setup.sh
  curl -fsSL $RAW/docker/compose.yaml -o docker/compose.yaml
  

  すでに実行中の場合（curl -sf localhost:9777/health）→ ステップ 3 に進みます。

2. 起動（どちらのコンテキストでも同じ）

1. モデルを選択します — デフォルトは CLIP/clip-vit-b-32（512 次元、テキスト＋画像＋動画）です。 トレードオフについては docs/user-guide/supported-models.md を参照してください。
2. setup.sh は必ず source で読み込む必要があり、EMBEDDING_MODEL_NAME が設定されていない場合は即座に失敗します。REGISTRY_URL=intel を指定するとビルド済みイメージが選択され、--no-build を指定するとソースからのビルドが無効になります。バックグラウンドで実行してください — 初回起動時にモデルがダウンロードされます：

   bash -c 'export EMBEDDING_MODEL_NAME="CLIP/clip-vit-b-32" REGISTRY_URL=intel TAG=latest \
     && source setup.sh && docker compose -f docker/compose.yaml up -d --no-build'
   

   Intel GPU の場合は、export EMBEDDING_DEVICE=GPU も実行してください（その後 setup.sh が OpenVINO + THROUGHPUT モードを自動的に有効にします）。
3. 準備完了になるまで待ちます：

   until curl -sf http://localhost:9777/health; do sleep 5; done
   

3. 機能の確認（テキスト以外の入力の前に必須）

curl -s http://localhost:9777/model/capabilities

QwenText モデルはテキスト専用です — 画像／動画のリクエストは 400 を返します。GET /model/current は、リクエストで使用する正確な読み込み済みモデル ID を表示します。

4. 埋め込み

テキスト（単一の文字列または文字列のリスト）：

curl -s http://localhost:9777/embeddings -H 'Content-Type: application/json' -d '{
  "model": "CLIP/clip-vit-b-32",
  "input": {"type": "text", "text": "a red truck at a loading dock"},
  "encoding_format": "float"
}'

応答：{"embedding": [...]} — テキスト／画像ではフラットなベクトル、動画入力ではフレームごとのベクトルのリストです。

• model は読み込まれたモデルと一致している必要があります（一致しない場合は 400）。
• 画像：{"type":"image_url","image_url":"https://…"}（ネストされたオブジェクトではなく、通常の文字列）または image_base64。動画：segment_config（デフォルトの num_frames は 64、extraction_fps、frame_indexes）とともに video_url／video_base64／video_frames を使用します。形式と例については、docs/user-guide/api-reference.md を参照してください。

5. 停止／クリーンアップ

• docker compose -f docker/compose.yaml down
• ボリューム ov-models（モデルキャッシュ）と data-prep は保持されます。削除すると再ダウンロードが必要になります。必ず先にユーザーに確認してください。

トラブルシューティング

症状	考えられる原因 → 対処方法
source setup.sh が ERROR を出力して停止する	EMBEDDING_MODEL_NAME がエクスポートされていません → 先にエクスポートしてください
9777 で応答がない	起動中またはダウンロード中です → docker logs -f multimodal-embedding-serving
400「model mismatch」	リクエストの model ≠ 読み込まれたモデル → GET /model/current
画像／動画で 400 unsupported modality	テキスト専用モデル（QwenText）です → モデルを切り替えるか、テキストを送信してください
テキスト以外の最初のリクエストが遅い	OpenVINO の遅延変換／コンパイルです → 初回のみの想定動作です
/embeddings で 422	input のユニオン形式が不正です → docs/user-guide/api-reference.md で形式を確認してください
ポート 9777 が使用中	競合するサービスを停止してください（EMBEDDING_SERVER_PORT は setup.sh でハードコードされています）