model-download-user

模型下载 Agent

设置模型下载微服务，并引导用户通过 REST API 或 MCP 服务下载或转换任何受支持的模型。

预览： 此技能目前处于预览阶段，欢迎分享反馈，帮助改进。

适用场景

• 用户想从 HuggingFace、Ollama、Ultralytics、Geti、Pipeline Zoo 或 HLS 下载模型
• 用户想将 HuggingFace 模型转换为 OpenVINO IR 格式，以便部署到 OVMS
• 用户询问模型精度转换（INT4/INT8/FP16/FP32）
• 用户需要指定目标设备（CPU、GPU、NPU，或 HETERO:GPU,CPU 等异构组合）
• 用户想下载医疗 AI 模型（3D Pose、rPPG、AI-ECG）
• 用户正在将模型下载集成到 Docker Compose 工作流中

MCP 服务（REST 的替代方案）

每个模型下载部署除了 REST API 外，还会在 /mcp 暴露一个 MCP 服务，因此 Claude Desktop、GitHub Copilot 等 Agent 以及自定义 MCP 客户端可以直接将该服务作为工具调用，而不必发送原始 curl 请求。

• 同一服务、同一端口（8200）——容器部署无需单独进程；本地或仅供 Agent 使用时，可通过 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），优先直接调用对应的 MCP 工具，而不是构造 curl 命令——工具签名接受相同的字段（name、hub、type、is_ovms、config、revision、download_path）；此外，download_model 还接受顶层参数 override_credentials（例如 {"HF_TOKEN": "<base64-encoded-token>"} 这样的字典）和 validate_credentials（布尔值）——与 REST 端点提供的按请求覆盖认证信息功能相同，且均使用 Base64 编码。list_hub_models 也接受 override_credentials，用于列出受限或私有 Hub 上的模型。
• 完整的客户端设置说明（Claude Desktop / Copilot 配置、HTTP 客户端示例、验证步骤）位于 docs/user-guide/get-started/using-mcp-server.md——用户询问如何配置或排查 MCP 客户端问题时，请阅读该文件。

注意：此技能的“支持的 Hub 一览”表格和 example-prompts/ 文件也通过 src/mcp/prompts.py 实时作为 MCP 提示词提供。编辑这些内容时，请保持标题文本和文件名稳定。

支持的 Hub 一览

Hub	hub 值	功能	必需的环境变量
HuggingFace	huggingface	下载任何公开或受限的 HF 模型	使用 Compose 启动时需要 HUGGINGFACEHUB_API_TOKEN（仅受限模型需要）
Ollama	ollama	下载 Ollama 模型并运行本地 Ollama 服务	—
Ultralytics	ultralytics	下载 YOLO 模型，可选 INT8 量化	—
OpenVINO	openvino	将 HF 模型转换为 OpenVINO IR，以便部署到 OVMS	使用 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 压缩包下载，并根据允许列表进行检查	—

受限访问的 HuggingFace 模型 — Token 处理

适用于 hub: "huggingface" 和 hub: "openvino" 两种情况（OpenVINO 转换器会先从 HuggingFace 下载源权重，再进行转换，因此受限访问模型的身份验证在转换请求中的工作方式相同）。

提供 HF token 有两种不同方式，而且使用不同的编码方式——混淆两者是受限访问模型最常见的失败原因：

方式	Token 的填写位置	编码方式
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 标志，也必须编码

将 token 放入 override_credentials 前，先对其进行编码：

echo -n 'hf_xxx' | base64

**如果用户的请求通过 MCP 客户端发出，且模型为受限访问模型，**优先使用经过 base64 编码的 HF_TOKEN 配合 override_credentials，而不是让用户通过设置新的环境变量来重启整个服务——这样可以避免重启容器。对于 is_ovms 转换请求，还应设置 validate_credentials: true，以便在转换开始（通常需要几分钟）前捕获错误或编码错误的 token，而不是等转换完成后才失败。

**CLI 失败场景：**如果为 get_model.sh 导出的 token 经过了 base64 编码（或者将其作为 HUGGINGFACEHUB_API_TOKEN/HF_TOKEN 传给 run_service.sh up），身份验证会失败，并显示 401 Unauthorized / Repository ... is gated，尽管 token 看起来“已设置”——CLI 和 Compose 启动路径会原样传递该值，因此 base64 字符串不是有效的 HF token。此情况同样适用于 --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>	始终为你的 hub 启用插件
不带 job ID 轮询 /api/v1/jobs	使用下载响应中的 job_ids[0]

---

查阅参考资料

仅在需要了解相关细节时阅读参考文件：

参考资料	阅读时机
service-setup.md	启动服务、Docker Compose、插件标志、环境变量
plugins-guide.md	各插件的请求正文、参数和 curl 示例
troubleshooting.md	身份验证错误、卡住的任务、插件未启用、虚拟环境故障

---

操作流程

执行概览

完成步骤 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 格式”、“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 转换
• 使用 hub: "openvino" 搭配 is_ovms: true 和 type 字段进行转换
• config 包含精度、设备、cache_size、post_processing（OMZ）以及其他插件专属参数
• override_credentials（经过 base64 编码）和 validate_credentials 是每个模型条目中的顶层字段——参见上文“受限访问的 HuggingFace 模型”
• parallel_downloads（顶层字段，与 models 同级）用于让单个请求中的多个条目并发下载；省略该字段或设为 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>