model-download-user

モデルダウンロードエージェント

Model Download マイクロサービスをセットアップし、REST API または MCP サーバーを使って、サポートされているモデルのダウンロードまたは変換をユーザーに案内します。

プレビュー： このスキルはプレビュー版です。改善のため、ぜひフィードバックをお寄せください。

使用する場面

• HuggingFace、Ollama、Ultralytics、Geti、Pipeline Zoo、または HLS からモデルをダウンロードしたい場合
• OVMS へのデプロイ用に、HuggingFace モデルを OpenVINO IR 形式に変換したい場合
• モデルの精度変換（INT4／INT8／FP16／FP32）について質問された場合
• 特定のデバイス（CPU、GPU、NPU、または HETERO:GPU,CPU のような HETERO の組み合わせ）を対象にする必要がある場合
• 医療 AI モデル（3D Pose、rPPG、AI-ECG）をダウンロードしたい場合
• Docker Compose ワークフローにモデルのダウンロードを組み込みたい場合

MCP サーバー（REST の代替）

Model Download の各デプロイでは、REST API とともに /mcp で MCP サーバーも公開されるため、Claude Desktop、GitHub Copilot、カスタム MCP クライアントなどのエージェントは、生の curl リクエストを発行する代わりに、ツールとしてサービスを直接呼び出せます。

• 同じサービス、同じポート（8200）を使用します。コンテナデプロイでは別プロセスは不要です。ローカルでエージェント専用に使用する場合は、uv run python -m src.mcp でスタンドアロン（stdio）として起動できます。
• ツールは REST API の機能に対応しています：health_check、download_model、get_job_status、list_jobs、cancel_job、get_model_jobs、get_model_results、list_plugins、list_hub_models。
• リソース：models://jobs、models://jobs/{job_id}、models://results、models://plugins。
• ユーザーのリクエストが MCP クライアント（Claude Desktop、model-download MCP サーバーに接続された Copilot など）経由の場合は、curl コマンドを組み立てるのではなく、対応する MCP ツールを直接呼び出してください。 ツールのシグネチャは同じフィールド（name、hub、type、is_ovms、config、revision、download_path）を受け付けます。また、download_model はトップレベルの override_credentials（{"HF_TOKEN": "<base64-encoded-token>"} のような辞書）と validate_credentials（bool）も受け付けます。これらは REST エンドポイントで使用できる、リクエストごとの Base64 エンコード認証情報の上書きと同じものです。list_hub_models も、ゲート付きまたはプライベートなハブのモデル一覧取得に override_credentials を受け付けます。
• クライアントのセットアップ方法（Claude Desktop／Copilot の設定、HTTP クライアントの例、確認手順）は docs/user-guide/get-started/using-mcp-server.md に記載されています。ユーザーから MCP クライアントの設定またはトラブルシューティングを求められた場合は、このファイルを参照してください。

注：このスキルの「サポート対象ハブ一覧」テーブルと example-prompts/ ファイルは、src/mcp/prompts.py によって MCP プロンプトとしてもライブ配信されます。編集時は、見出しのテキストとファイル名を変更しないでください。

サポート対象ハブ一覧

ハブ	hub の値	機能	必須の環境変数
HuggingFace	huggingface	公開またはゲート付きの任意の HF モデルをダウンロードします	Compose ベースの起動では HUGGINGFACEHUB_API_TOKEN（ゲート付きモデルのみ）
Ollama	ollama	Ollama モデルをダウンロードし、ローカルの Ollama サーバーを実行します	—
Ultralytics	ultralytics	YOLO モデルをダウンロードします。INT8 量子化はオプションです	—
OpenVINO	openvino	HF モデルを OVMS 用の OpenVINO IR に変換します	Compose ベースの起動では HUGGINGFACEHUB_API_TOKEN（通常必要）
Geti	geti	Intel Geti プラットフォームからトレーニング済みモデルをダウンロードします	GETI_HOST、GETI_TOKEN、GETI_WORKSPACE_ID
Pipeline Zoo	pipeline-zoo-models	DL Streamer pipeline-zoo モデルをダウンロードします	—
HLS	hls	医療 AI モデル（3d-pose、rppg、ai-ecg）をダウンロードします	—
Open Model Zoo	omz	omz_downloader／omz_converter を使って OMZ モデルをダウンロードし、変換します	—
リモート URL	remote-url	config.url の tarball アーカイブをダウンロードします。許可リストとの照合が行われます	—

Gated HuggingFace モデル — トークンの取り扱い

hub: "huggingface" と hub: "openvino" の両方に適用されます（OpenVINO コンバーターは変換前に HuggingFace からソースウェイトをダウンロードするため、ゲート付きモデルの認証は変換リクエストでも同じように機能します）。

HF トークンを指定する方法は2 通りあり、それぞれ異なるエンコーディングを使用します。これを取り違えることが、ゲート付きモデルで最もよくある失敗の原因です。

経路	トークンを指定する場所	エンコーディング
Compose／サービスの起動（run_service.sh up）または get_model.sh CLI	ホスト上の HUGGINGFACEHUB_API_TOKEN／HF_TOKEN 環境変数	プレーンテキスト（hf_...）。base64 は使用しません
REST／MCP の download_model 呼び出しによるリクエスト単位の上書き	モデルエントリーのトップレベルの override_credentials.HF_TOKEN フィールド — name／hub／config の兄弟フィールドであり、config の中にはネストしません	常にBase64 エンコードします — sensitive フラグもサポートするフィールドですが、エンコードは必須です

override_credentials に設定する前にトークンをエンコードします。

echo -n 'hf_xxx' | base64

MCP クライアント経由でユーザーのリクエストが届き、モデルがゲート付きの場合、サービス全体を新しい環境変数で再起動するよう求めるのではなく、Base64 エンコードした HF_TOKEN を含む override_credentials を優先してください。コンテナーの再起動を避けられます。is_ovms 変換リクエストでは、validate_credentials: true も設定してください。これにより、（多くの場合、数分かかる）変換の実行後に初めて失敗するのではなく、不正なトークンやエンコードが誤ったトークンを変換前に検出できます。

CLI での失敗シナリオ： Base64 エンコードしたトークンを get_model.sh 用にエクスポートした場合（または run_service.sh up に HUGGINGFACEHUB_API_TOKEN／HF_TOKEN として渡した場合）、トークンが「設定済み」に見えても、認証は 401 Unauthorized／Repository ... is gated で失敗します。CLI と Compose の起動経路では値がそのまま送信されるため、Base64 文字列は有効な HF トークンではありません。これは --hub huggingface と --hub openvino の CLI 呼び出しのどちらにも当てはまります。修正方法については、troubleshooting.md を参照してください。

Ollama クイックリファレンス

Ollama リクエストでは、必ず次の正確なフィールド名を使用してください — API は一般的なモデルダウンロードのドキュメントから想定されるものとは異なります。

{
  "models": [
    {
      "hub": "ollama",
      "name": "<model-family>",
      "revision": "<tag>"
    }
  ]
}

• hub は "ollama" でなければなりません（model_hub や type ではありません）
• name はベースモデルファミリーです："llama3.2"、"mistral"、"gemma2"（タグのサフィックスは付けません）
• revision はタグです："3b"、"7b"、"latest"（model_name ではなく、独立したフィールドです）
• ポートは常に 8200 です（8080 や 8000 ではありません）
• プラグインフラグ：source scripts/run_service.sh up --plugins ollama

例 — llama3.2:3b をダウンロードする場合：

curl -s -X POST "http://localhost:8200/api/v1/models/download?download_path=ollama-models" \
  -H "Content-Type: application/json" \
  -d '{"models": [{"hub": "ollama", "name": "llama3.2", "revision": "3b"}]}'

避けるべきよくある間違い

間違い	正しい方法
ポート 8080 または 8000	ポートは常に 8200
"model_hub": "ollama"	"hub": "ollama"
"model_name": "llama3.2:3b"	"name": "llama3.2", "revision": "3b"
docker compose up -d	source scripts/run_service.sh up --plugins <list>
--plugins <hub> を指定せずに起動する	使用するハブのプラグインを必ず有効にする
ジョブ ID なしで /api/v1/jobs をポーリングする	ダウンロードレスポンスの job_ids[0] を使用する

---

リファレンスの参照

参照ファイルは、記載されている詳細が必要なときだけ読んでください。

リファレンス	参照するタイミング
service-setup.md	サービスの起動、Docker Compose、プラグインフラグ、環境変数
plugins-guide.md	プラグインごとのリクエスト本文、パラメーター、curl の例
troubleshooting.md	認証エラー、停止したジョブ、プラグインが有効化されない問題、venv の失敗

---

手順

実行の概要

ステップ 0（要件の収集）の後、API 呼び出しの作成と並行してサービスのセットアップを開始します。

Step 0 (gather requirements — interactive)
  │
  ├──► Step 1 (service setup — may require user action)
  └──► Step 2 (compose API call body — reasoning)
         │
         ├──► Step 3 (submit job + poll status)
         └──► Step 4 (verify result + next steps)

---

ステップ 0 — 要件の収集

ユーザーのプロンプトから以下の内容を抽出します。不足している情報があれば、先に確認してください。

必須項目	確認する内容	指定がない場合の既定値
モデル名	正確なモデル識別子（例：meta-llama/Llama-3.2-1B）	必ず確認する
Hub	次のいずれか：huggingface、openvino、ollama、ultralytics、geti、pipeline-zoo-models、hls、omz、remote-url	必ず確認する
変換が必要か	ユーザーが「OVMS」、「OpenVINO format」、「convert」、「is_ovms」と指定しているか	false
デバイス	CPU / GPU / NPU / HETERO:<dev>[,<dev>...]（例：HETERO:GPU,CPU）	CPU
精度	int4 / int8 / fp16 / fp32	LLM は int8、それ以外は fp16
モデルタイプ	llm / vlm / embeddings / rerank / text2speech / speech2text / image_generation / vision / 3d-pose / rppg / ai-ecg	コンテキストから推測する

OpenVINO 固有のルール（ユーザーが OVMS / OpenVINO 変換を希望している場合のみ確認します）：

• NPU の場合は、他の設定にかかわらず int4 を使用します（対象はデバイスが厳密に NPU の場合のみです。HETERO:NPU,CPU のような HETERO の組み合わせには適用されません）
• HETERO デバイスは、出力パスでファイルシステムに安全なスラッグとして表記します：HETERO:GPU,CPU → openvino_models/hetero_gpu_cpu/
• LLM/VLM の変換では cache_size（GB 単位の KV キャッシュ）を指定できます。ユーザーがメモリの制約に言及している場合は確認してください
• Embeddings と reranker の変換では、内部的に text_generation/embeddings_ov/rerank_ov のエクスポートタイプを使用します。これらは type から自動的に決定されます

---

ユーザーのプロンプトにモデル名と Hub の両方が明記されている場合は、ステップ 1 に進みます。それ以外の場合は確認してください。

---

ステップ 1 — サービスのセットアップ

詳しくは service-setup.md を参照してください。

ユーザーのリクエストに必要なプラグインだけを使用して、サービスの起動コマンドを提示します：

# Clone (if not already done)
git clone https://github.com/open-edge-platform/edge-ai-libraries.git -b main
cd edge-ai-libraries/microservices/model-download

# Set env vars
export HUGGINGFACEHUB_API_TOKEN=<your-hf-token>   # mapped into the container as HF_TOKEN
export REGISTRY="intel/"
export TAG=latest

# Start service (adjust --plugins to match what you need)
source scripts/run_service.sh up --plugins <comma-separated-list> --model-path $PWD/models

プラグインリストの推奨事項：

• HuggingFace のみ → --plugins huggingface
• HuggingFace + OpenVINO 変換 → --plugins huggingface,openvino
• Ollama → --plugins ollama
• Ultralytics → --plugins ultralytics
• すべて → --plugins all

続行する前に、サービスが正常に稼働していることを確認します：

curl http://localhost:8200/api/v1/health
# Expected: {"status": "ok"}

---

ユーザーへの最終回答には、正しい --plugins リストを含む正確な起動コマンドとポート 8200 の両方を必ず再掲してください。リクエストペイロードだけでは不十分です。ユーザーは回答の一部だけをコピーして使用することがあるため、起動コマンドやポートを含まないペイロードは誤用につながりやすくなります。

ステップ 2 — API リクエストの作成

各プラグインの正確なリクエスト本文については、plugins-guide.md を参照してください。

POST /api/v1/models/download?download_path=<subdir> の一般的なリクエスト形式は次のとおりです：

{
  "models": [
    {
      "name": "<model-identifier>",
      "hub": "<hub-value>",
      "type": "<model-type-or-omit>",
      "is_ovms": false,
      "config": {},
      "override_credentials": {},
      "validate_credentials": false
    }
  ],
  "parallel_downloads": false
}

主なルール：

• is_ovms: true を指定すると OpenVINO 変換が実行されます
• 変換する場合は、is_ovms: true と type フィールドを指定して hub: "openvino" を使用します
• config には、精度、デバイス、cache_size、post_processing（OMZ）、その他のプラグイン固有のパラメーターを指定します
• override_credentials（base64 エンコード）と validate_credentials は、各モデルエントリーの最上位フィールドです。上記の「アクセス制限付き HuggingFace モデル」を参照してください
• parallel_downloads（models と同じ階層にある最上位フィールド）を指定すると、1 つのリクエスト内の複数エントリーが並行ダウンロードされます。省略するか false を指定すると順次処理されます（Ollama は常に順次処理されます）
• download_path クエリパラメーターは、モデルストア内のサブディレクトリを指定します。最終的な出力パスは <model-path>/<download_path>/<hub-specific-subpath> です

---

ステップ 3 — ジョブの送信とステータスの確認

# 1. Submit download job
JOB_RESPONSE=$(curl -s -X POST \
  "http://localhost:8200/api/v1/models/download?download_path=my-models" \
  -H "Content-Type: application/json" \
  -d '<your-request-body>')

echo "$JOB_RESPONSE"
# Response: {"message": "Started processing 1 model(s)", "job_ids": ["<uuid>"], "status": "processing"}

# 2. Extract job ID
JOB_ID=$(echo "$JOB_RESPONSE" | jq -r '.job_ids[0]')

# 3. Poll until completed or failed
watch -n 5 "curl -s http://localhost:8200/api/v1/jobs/$JOB_ID | jq ."

ジョブのステータス値：queued → downloading / converting → completed / failed

ステータスが failed の場合は、error フィールドを読み取り、troubleshooting.md を確認してください。

---

ステップ 4 — 確認と次の手順

# List all completed downloads
curl -s http://localhost:8200/api/v1/models/results | jq .

# Check a specific model's jobs
curl -s "http://localhost:8200/api/v1/models/jobs?model_name=<model-name>" | jq .

成功を確認したら、ユーザーに次の内容を伝えてください。

• モデルが保存されたホスト側のパス（ジョブ結果の download_path に表示されます）
• OVMS への変換の場合：モデルディレクトリを OVMS にマウントする方法と、使用するモデル名。結果には conversion_path が使われます
• Ollama の場合：モデルはコンテナのモデルストアボリューム内に保存されます

OpenVINO への変換に関する重要な注意点： モデルの変換には、hub: "openvino" と is_ovms: true を使用してください。

手早い代替方法： CI/CD やスクリプト化されたワークフローで、コンテナを一度だけ一時的に使用する場合は、get_model.sh のワンライナーを使用してください。

curl -sSLO https://raw.githubusercontent.com/open-edge-platform/edge-ai-libraries/main/microservices/model-download/scripts/get_model.sh
source ./get_model.sh --model-name <model> --hub <hub> --plugins <plugins>