MLX-VLM 本地 Hugging Face 缓存模型清单hf-cache-models 技能与--model-discovery hf-cache实战指南【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm本指南围绕 mlx-vlm 仓库中skills/skills/hf-cache-models/SKILL.md定义的工作流系统讲解如何列出、筛选并上报本地 Hugging Face 缓存中可以被 MLX-VLM 服务器暴露的模型候选。你将掌握配套脚本list_supported_hf_cache_models.py的全部参数用法、服务器端--model-discovery hf-cache的底层过滤逻辑mlx_vlm/server/app.py以及如何通过curl /v1/models交叉验证结果并产出可用于 issue 报告的模型清单。技能定位什么时候使用 hf-cache-modelsMLX-VLM 服务器默认只通过/v1/models暴露由当前进程显式加载served的模型。但如果你希望把共享 Hugging Face 缓存目录中看起来可以被 MLX-VLM 加载的模型也一并纳入发现列表就需要显式开启服务器的hf-cache发现模式。hf-cache-models技能就是为这一场景设计的当用户需要列出、检查或上报本地 Hugging Face 缓存中的 MLX-VLM 模型候选包括服务器的 opt-in hf-cache 发现模式、cache-dir 覆盖、JSON 输出或生成可直接用于 issue 的缓存模型清单时使用该技能对应技能元数据description字段。需要强调的是这个工作流是纯缓存/文件存在性检查它不加载模型、不证明生成能力正常、也不影响默认的served列表。它镜像的是服务器端 opt-in 的hf-cache发现模式实现在mlx_vlm/server/app.py。支持的模型判定规则无论使用脚本还是服务器端发现模式判定一个缓存仓库是否为受支持的模型候选都遵循同一套五条规则仓库类型repo_type为model缓存中存在main修订版本mainrevision存在config.json存在tokenizer_config.json存在model.safetensors.index.json或至少存在一个*.safetensors权重文件。这五条规则在脚本中对应is_supported_model()skills/skills/hf-cache-models/scripts/list_supported_hf_cache_models.py#L25-L29在服务器端对应models_endpoint()内部的probably_mlx_lm()过滤函数mlx_vlm/server/app.py#L1012-L1019两者逻辑完全一致。# 脚本中的核心判定逻辑 REQUIRED_FILES {config.json, tokenizer_config.json} def is_supported_model(files: dict[str, Path]) - bool: has_weights model.safetensors.index.json in files or any( name.endswith(.safetensors) for name in files ) return REQUIRED_FILES.issubset(files) and has_weights注意满足以上规则只代表文件齐全像是一个可加载的模型即cache candidate。若想进一步缩小为probably loadable很可能可加载需要配合--check-arch做架构校验见下文。使用配套脚本四种常用调用方式SKILL.md 明确要求使用仓库自带的脚本而非重写缓存扫描逻辑原因在于脚本与服务器端共享同一套过滤语义且不会引入重复代码。1. 基础列出uv run python skills/skills/hf-cache-models/scripts/list_supported_hf_cache_models.py输出为每行一个模型 ID末尾打印统计行Qwen/Qwen2.5-VL-7B-Instruct 1 supported model(s)2. JSON 输出uv run python skills/skills/hf-cache-models/scripts/list_supported_hf_cache_models.py --json每个模型条目包含四个字段对应脚本supported_models()中构造的字典scripts/list_supported_hf_cache_models.py#L77-L82[ { id: Qwen/Qwen2.5-VL-7B-Instruct, repo_type: model, last_modified: 1733908800, cache_dir: /home/user/.cache/huggingface/hub } ]idHugging Face 仓库 ID如org/model-namerepo_type当前恒为model已按规则过滤last_modified缓存修订的最近修改时间戳Unix 秒cache_dir实际使用的缓存目录便于排查非默认目录场景。3. 架构校验从文件齐全到很可能可加载uv run python skills/skills/hf-cache-models/scripts/list_supported_hf_cache_models.py --check-arch--check-arch会额外要求从缓存仓库的config.json中读取model_type若缺失则回退到speculators_model_type见_config_model_type()并要求该model_type能在mlx_vlm/models/下找到同名目录。实现上脚本通过importlib.util.find_spec(mlx_vlm)定位包路径并枚举models子目录_mlx_vlm_model_types()刻意不导入 mlx_vlm从而避免引入 mlx 等重依赖保持脚本轻量快速。开启--check-arch后列表被收窄为既文件齐全、又有对应架构目录的模型统计标签从supported变为loadableJSON 输出会额外增加model_type字段。重要限制SKILL.md 明确提醒该检查是文件夹名匹配并不解析MODEL_REMAPPING别名映射定义于mlx_vlm/utils.py#L37。因此命中 强提示表示很可能可加载未命中 可能不可加载而非绝对结论判定结果只能作为强提示strong hint不能当作证明proof。4. 指定自定义缓存目录uv run python skills/skills/hf-cache-models/scripts/list_supported_hf_cache_models.py \ --cache-dir /path/to/huggingface/cache默认使用huggingface_hub的HF_HUB_CACHE常量即标准缓存位置~/.cache/huggingface/hub脚本内部通过Path(cache_dir or HF_HUB_CACHE).expanduser()解析scripts/list_supported_hf_cache_models.py#L64。当缓存目录不存在CacheNotFound时脚本返回空列表而非报错。三个参数可自由组合例如同时使用 JSON 输出、架构校验与自定义缓存目录uv run python skills/skills/hf-cache-models/scripts/list_supported_hf_cache_models.py \ --json --check-arch --cache-dir /data/models/hf_cache服务器端原理--model-discovery hf-cache与/v1/models脚本的判定逻辑镜像自服务器端实现理解服务端行为有助于解释脚本与服务器结果为何应一致。模式定义与参数入口发现模式通过环境变量MLX_VLM_MODEL_DISCOVERY控制合法值为served与hf-cache两种mlx_vlm/server/runtime.py#L6-L7MODEL_DISCOVERY_ENV MLX_VLM_MODEL_DISCOVERY MODEL_DISCOVERY_MODES (served, hf-cache)CLI 侧通过--model-discovery参数映射到该环境变量mlx_vlm/server/cli.py#L84-L93、#L312-L313即python -m mlx_vlm.server --model-discovery hf-cache等价于MLX_VLM_MODEL_DISCOVERYhf-cache python -m mlx_vlm.server默认值为served/v1/models只列出当前进程显式加载的模型。若传入非法的模式值_model_discovery_mode()会记录警告并安全回退到servedmlx_vlm/server/app.py#L108-L117。/v1/models端点如何合并缓存模型models_endpoint()mlx_vlm/server/app.py#L994-L1035同时注册在/models与/v1/models两个路径下其执行流程为先构造served模型字典_served_model_entries()若发现模式为hf-cache则调用scan_cache_dir()扫描缓存对每个仓库执行probably_mlx_lm()判定即上文五条规则通过判定的仓库若其repo_id尚未出现在served列表中则以repo_id为id、last_modified为created合并进结果最终按模型 ID 小写排序返回响应结构为 OpenAI 风格的{object: list, data: [...]}。因此若某个模型同时被服务器加载且存在于缓存中只会出现一次不会重复。交叉验证与结果上报用服务器验证 hf-cache 发现SKILL.md 给出的验证路径是以hf-cache模式启动服务器再与脚本输出对比# 终端 1启动服务器启用 hf-cache 发现 python -m mlx_vlm.server --model-discovery hf-cache # 终端 2对比脚本输出 uv run python skills/skills/hf-cache-models/scripts/list_supported_hf_cache_models.py # 终端 3查询服务器暴露的模型 curl http://127.0.0.1:8080/v1/models注意默认端口为 8080以实际启动日志为准两个来源的差异通常来自--cache-dir覆盖或served与缓存模型去重等场景是排查发现模式是否生效的常用手段。上报时应包含的要素根据 SKILL.md 的 Reporting 要求汇报结果时必须包含使用的缓存目录若非默认目录必须显式说明受支持模型的数量确切的模型 ID 列表数据来源是来自脚本list_supported_hf_cache_models.py还是来自curl http://127.0.0.1:8080/v1/models。与 bug 报告流程的衔接SKILL.md 明确建议如果该检查成为 bug 报告的一部分应切换到Skill(mlx-vlm-skills:reproducible-github-issues)技能以确保报告具备可复现性对应仓库中的skills/skills/reproducible-github-issues/。这说明 hf-cache-models 的定位是前置排查与事实收集而正式的 issue 提交流程由专门的技能接管。常见误用与边界提醒不要把候选当结论脚本与服务器都只做文件存在性检查不保证模型能成功加载或生成正常。需要真正验证可加载性时应加载模型实际推理或借助--check-arch作为强提示。--check-arch不解析别名MODEL_REMAPPINGmlx_vlm/utils.py中记录的模型类型别名不会被脚本解析判定结果需谨慎解读。环境变量优先级--model-discovery会覆盖MLX_VLM_MODEL_DISCOVERY环境变量CLI 赋值发生在解析参数之后mlx_vlm/server/cli.py#L312-L313非法值会被安全回退到served。默认只列 served未开启hf-cache时缓存模型不会出现在/v1/models这是预期行为而非故障。小结hf-cache-models技能为 MLX-VLM 提供了一个轻量、与服务器语义一致的本机缓存模型盘点方案脚本list_supported_hf_cache_models.py负责离线列出候选并支持 JSON、架构校验与自定义缓存目录服务器端--model-discovery hf-cache在/v1/models中按同一规则做在线暴露两者配合curl交叉验证即可得到可信的模型清单。其核心价值在于在不加载任何模型的前提下快速回答本机缓存里有哪些模型可被 MLX-VLM 服务器暴露并为后续加载、验证或 issue 上报提供事实依据。【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考