![]()
![]()
![]()
2026年11月20日,modelscope 发布 v1.40.3 版本。本次更新围绕一个非常核心的主题展开:让模型与数据集的本地缓存管理更安全、更清晰,让离线下载真正摆脱网络与凭证依赖,同时继续保障旧接口、旧缓存路径和 Hugging Face 生态调用方式的兼容性。
从更新内容来看,v1.40.3 并不是简单的依赖升级,而是一次针对缓存体系、离线场景、命令行清理、文件下载逻辑、异常兼容和本地模型更新行为的集中修复。对于依赖 ModelScope 下载模型、在受限网络环境中部署推理服务、维护大量本地缓存,或者通过 Hugging Face 风格接口接入模型资源的开发者而言,这个版本具有很强的实际价值。
本版本要求使用modelscope-hub>=0.7.0。同时,ModelScope 进一步明确了传统 SDK 缓存目录和 modelscope-hub 实际快照缓存目录之间的边界,新增了面向当前缓存体系的查询入口,并对历史接口补充了更准确的文档说明。
一、版本核心变化:缓存管理能力进入更严格、更安全的新阶段
在此前的使用方式中,开发者可能会通过一些传统缓存路径辅助函数,直接拼接模型或数据集的本地目录。例如,先获取缓存根目录,再将模型标识追加到路径中。这种方式在历史缓存布局下可以工作,但随着 modelscope-hub 的快照缓存机制持续演进,传统目录结构已经不再等同于实际的快照目录。
v1.40.3 对这一问题进行了明确处理。
新版本增加了:
•
modelscope.utils.file_utils.get_hub_cache_root()•
modelscope.hub.cache_manager.get_cache_root•
modelscope.hub.cache_manager.resolve_cached_snapshot
其中,get_hub_cache_root()用于获取当前实际生效的 modelscope-hub 缓存根目录,且不会为了获取路径而创建额外目录。
resolve_cached_snapshot()则用于定位一个仓库及其指定版本对应的实际缓存快照。对于需要准确找到模型快照目录的场景,应该使用snapshot_download()返回的目录,或者使用resolve_cached_snapshot()进行查询,而不是再依赖传统缓存根目录加模型标识的拼接方法。
这一调整的意义非常明确:旧路径辅助函数继续保留,以维持旧代码的调用兼容;但新的缓存体系应该通过新的 API 查询实际快照位置,从而避免因为缓存布局变化导致路径判断错误、读取失败或误操作缓存目录。
二、离线下载修复:local_files_only=True不再请求默认版本
本次更新中最重要的一项修复,来自model_file_download()的离线下载行为。
此前,当调用model_file_download()且未明确提供revision参数时,代码会尝试通过 API 解析默认版本。即使调用方已经设置了local_files_only=True,也可能仍然触发网络访问。
这会导致一个明显的问题:开发者明明希望只从本地缓存读取文件,却仍可能因为网络不可用、无法访问服务端或缺少认证凭证而失败。对于离线部署、内网环境、隔离网络环境、容器镜像预热后的运行场景而言,这种行为尤其不理想。
v1.40.3 对逻辑进行了调整:
if revision is None and not local_files_only:
...也就是说,只有当没有指定版本,并且并非本地文件模式时,才会调用 API 去解析默认版本。
当用户设置:
local_files_only=True并且模型文件已经位于本地缓存中时,下载流程不会再为了查询默认版本而访问网络。这样一来,真正的离线缓存下载可以在没有网络、没有服务端访问能力、没有有效凭证的条件下完成。
这一改动直接提升了离线使用的可靠性,也使local_files_only=True的语义更加符合开发者直觉:只使用本地已有缓存,不触发远程请求。
三、缓存清理命令升级:先展示目标,再执行安全删除
缓存清理是本次更新的另一大重点。ms clear-cache命令的行为得到了明显强化。
旧的清理方式通常是根据模型或数据集标识,直接构造目录路径后进行删除。新版本改为委托 modelscope-hub 的作用域缓存清理 API,先解析出实际需要删除的目标,再展示给用户确认。
执行清理时,新逻辑会首先计算缓存根目录和待删除目标列表:
root, targets = _cache_clear_targets(self.cache_dir, repo_type, repo_id)随后在终端输出缓存根目录以及每一个已解析的删除目标。若不存在任何目标,则会明确提示:
Cache not found. Nothing to do.只有在确实存在待删除目标的情况下,命令才会等待用户输入确认。用户输入Y后,才会调用统一的缓存清理能力:
clear_cache(cache_dir=root, repo_type=repo_type, repo_id=repo_id)这带来了几个直接收益。
• 清理前可以看到将被删除的实际路径。
• 模型和数据集可通过对应的仓库类型进行作用域清理。
• 不再依赖旧逻辑手工拼接路径后删除。
• 缓存删除流程统一交由 modelscope-hub 的缓存管理机制处理。
• 当目标不存在时,不会误报成功,也不会进行无意义删除。
对于全量缓存清理、单模型清理、单数据集清理等场景,新行为都更透明、更可控。
四、删除安全增强:拒绝空标识、路径穿越、越界目录和符号链接风险
缓存清理不仅要方便,更必须安全。
v1.40.3 对FileSystemCache的删除流程进行了加固,使其通过同一套经过验证的删除逻辑执行缓存移除操作。此次安全约束包括:
• 拒绝空的仓库标识。
• 拒绝路径穿越行为。
• 拒绝删除缓存根目录之外的目标。
• 拒绝跟随符号链接删除路径。
• 删除操作必须在经过验证的缓存作用域内进行。
在缓存工具实现中,原先直接使用递归删除目录的方式被替换为更严格的安全删除方式。现在清理会使用_safe_rmtree(),并传入需要删除的目录以及已解析的缓存根目录:
_safe_rmtree(
Path(path),
Path(self.cache_dir).expanduser().resolve())这意味着,即使路径表面上看起来位于缓存目录中,系统仍会进行作用域与路径解析验证,避免符号链接将删除操作引导到缓存目录外部。
对于模型缓存对象,在初始化阶段也增加了缓存作用域验证:
_validate_cache_scope('model', f'{owner}/{name}')这一变化尤其适合自动化环境、共享机器、容器环境和长期运行的服务环境。缓存清理命令通常具有较高风险,一旦路径处理存在漏洞,可能误删用户文件、工作目录或其他业务资源。新版本通过统一验证和安全删除,显著降低了这类风险。
五、MS_CACHE_HOME桥接时统一转换为绝对路径
本次更新还处理了旧环境变量与新 hub 配置之间的路径一致性问题。
当使用MS_CACHE_HOME并将其桥接到 hub 配置时,新版本会将路径执行展开和解析,转换为绝对路径:
_Path(legacy_cache).expanduser().resolve()这意味着:
•
~会被展开为真实的用户目录。• 相对路径会被转换为绝对路径。
• 缓存根目录在配置层面更稳定。
• 同一缓存位置不会因为相对路径、绝对路径或用户目录写法不同而出现不一致判断。
这一调整看似细微,但对缓存路径比较、目录边界校验、跨模块读取缓存和安全删除都非常重要。特别是在命令行运行目录变化、服务启动位置变化、容器工作目录不同的情况下,使用统一的绝对路径可以减少意外行为。
六、传统缓存路径函数保留,但文档明确其仅描述旧布局
为了兼容已有项目,以下传统辅助函数仍然保留:
•
get_default_modelscope_cache_dir()•
get_modelscope_cache_dir()•
get_model_cache_root()•
get_dataset_cache_root()•
get_dataset_cache_dir()•
get_model_cache_dir()•
get_cache_dir()
不过,v1.40.3 对这些函数的文档字符串进行了重要更新,明确说明它们描述的是传统 SDK 缓存布局,而不是 modelscope-hub 当前快照目录的真实位置。
例如,get_modelscope_cache_dir()现在明确说明,它返回的是传统 SDK 缓存根目录;如果需要获取当前 modelscope-hub 的实际缓存根目录,应使用:
get_hub_cache_root()如果需要找到具体模型或数据集的实际快照目录,应使用:
snapshot_download()或:
resolve_cached_snapshot()对于get_model_cache_root(),文档也强调,不应再通过向根目录追加模型标识的方式定位实际快照。snapshot_download()会返回真实可用的快照路径;为了兼容旧调用方式,旧目录下的模型标识路径仍可能与返回目录建立链接,但这仅服务于历史调用方。
这一变更没有移除旧接口,而是通过文档让开发者清楚区分“旧布局路径”和“真实快照路径”。这是一种兼顾稳定性与演进方向的处理方式。
七、本地模型更新优化:缓存中的模型不再被重复复制
在音频工具相关的本地模型更新逻辑中,v1.40.3 修复了一个可能造成冗余复制的问题。
update_local_model()会检查传入的模型路径。如果模型已经位于以下任意位置,就不再重复复制:
• 传统模型缓存根目录。
• modelscope-hub 缓存根目录下的
models目录。
新逻辑会将模型路径以及两个缓存根目录转换为解析后的路径,并判断模型路径是否等于缓存根目录,或者是否位于其子目录中。
逻辑可以概括为:
location = Path(model_path).resolve()
cache_roots = (
Path(dst_dir_root).resolve(),
(Path(get_hub_cache_root()) / 'models').resolve()
)if any(root == location or root in location.parents for root in cache_roots):
return
这项改动避免了模型已经处于缓存管理目录时,又被复制到传统缓存位置的情况。
其直接效果包括:
• 减少重复磁盘占用。
• 避免无意义的文件复制。
• 降低本地模型准备时间。
• 避免同一个模型在不同缓存布局中出现重复副本。
• 更好地适配 modelscope-hub 的实际缓存目录。
对于大型模型而言,重复复制会占用大量磁盘空间,也会增加启动或更新时的等待时间。因此,该修复具有实际的资源节约意义。
八、Hugging Face 兼容补强:异常类型更加符合调用方预期
v1.40.3 对 Hugging Face 风格下载接口的异常行为进行了修复。
在通过补丁机制调用文件下载时,可能出现两类典型问题:
• 请求的远程文件不存在。
• 本地缓存中不存在需要的文件,且调用方要求只使用本地文件。
不同生态中的调用方往往会根据特定异常类型处理这两种情况。例如,调用方可能通过捕获“条目不存在”异常判断某个可选文件是否存在,或者通过捕获“本地条目不存在”异常判断是否需要联网下载。
新版本中,文件下载逻辑增加了异常转换。
当底层 HTTP 错误的原因是远程对象不存在时,会转换为:
EntryNotFoundError当本地缓存未命中时,会转换为:
LocalEntryNotFoundError对应逻辑为:
except HTTPError as e:
if isinstance(e.__cause__, NotExistError):
raise EntryNotFoundError(str(e)) from e
raise
except CacheNotFound as e:
raise LocalEntryNotFoundError(str(e)) from e这意味着,依赖 Hugging Face 异常类型进行逻辑分支的调用方,在接入 ModelScope 的兼容层时,能够继续按照原有预期工作。
例如,某些应用会探测一个模型目录中是否存在可选配置文件、额外权重文件或辅助资源。对于这种“文件不存在但不是致命错误”的场景,调用方通常只需要捕获EntryNotFoundError并继续执行。现在,这种异常语义得到了更好的保持。
同样,在本地离线缓存模式下,缓存未命中将抛出LocalEntryNotFoundError,使调用方可以明确区分“远程文件不存在”和“本地没有缓存”两种不同问题。
九、恢复InvalidParameter导出,保持快照下载模块的异常契约
modelscope.hub.snapshot_download在本次版本中重新导出了InvalidParameter。
对应的导出列表调整为:
__all__ = [
'snapshot_download',
'dataset_snapshot_download',
'InvalidParameter'
]这一变化的重点在于保持兼容层模块的异常契约。
有些既有代码可能会从modelscope.hub.snapshot_download直接导入InvalidParameter。如果该符号不再导出,虽然底层功能本身可能仍然可用,但调用方的导入逻辑会被破坏。
重新导出这一异常类型后,旧代码可以继续保持原有的导入路径和异常处理方式,避免升级版本后出现不必要的兼容问题。
十、依赖要求更新:需要modelscope-hub>=0.7.0
v1.40.3 将 hub 依赖版本从较低版本提升为:
modelscope-hub>=0.7.0这一依赖升级与本次新增的缓存能力直接相关。新的安全缓存清理、缓存目标解析、实际缓存根目录查询、快照定位能力,都依赖于新版 modelscope-hub 提供的支持。
因此,升级 modelscope v1.40.3 时,需要确保运行环境中的modelscope-hub版本满足要求。否则,新的缓存管理能力、作用域验证和相关接口无法得到完整支持。
十一、测试覆盖:重点验证离线、缓存路径和安全清理行为
本次更新新增了针对缓存热修复的测试内容,覆盖多个关键场景。
测试会设置临时缓存目录和认证目录,并创建模拟的本地快照结构,例如:
models
└── org--model
└── snapshots
└── master
└── config.json测试重点验证以下行为:
•
get_modelscope_cache_dir()仍返回传统 SDK 缓存根目录。•
get_model_cache_root()仍返回传统模型缓存根目录。•
get_hub_cache_root()返回实际 hub 缓存根目录。•
get_cache_root()返回实际缓存根目录对象。•
resolve_cached_snapshot('org/model')可以正确解析本地快照路径。• 在
local_files_only=True场景中,snapshot_download()可以从本地缓存返回结果。• 本地缓存下载不会触发网络请求。
• 传统缓存辅助函数的文档中包含“legacy SDK”和
resolve_cached_snapshot等说明。• 清理缓存命令在测试环境中能够使用新的配置和缓存根目录逻辑。
其中一个关键验证是:通过模拟网络请求失败,确保离线快照下载不会访问网络。这正对应了本次model_file_download()在本地模式下不再解析默认版本的修复目标。
此外,清理缓存命令的测试还特别处理了 hub 默认配置可能在进程范围内被缓存的问题。在测试中会重置默认配置,使环境变量修改可以正确生效,从而保证缓存清理行为基于当前测试环境的目录配置执行。
十二、版本总结:从“能缓存”走向“可离线、可验证、可安全清理”
代码地址:github.com/modelscope/modelscope
modelscope v1.40.3 的更新重点非常集中,核心可以概括为四个方向。
第一,离线能力更可靠。
设置local_files_only=True后,不再为了获取默认版本而访问网络。已经存在于本地缓存中的模型文件可以在无网络、无凭证环境下完成读取。
第二,缓存定位更清晰。
传统 SDK 缓存路径函数继续保留,但文档明确其只是旧布局的描述。开发者应使用get_hub_cache_root()获取当前 hub 缓存根目录,使用snapshot_download()或resolve_cached_snapshot()获取真实快照目录。
第三,缓存清理更安全。
ms clear-cache会在删除前列出所有已解析目标;实际删除委托给 modelscope-hub 的作用域缓存 API;删除逻辑拒绝空标识、路径穿越、缓存根目录外路径和符号链接风险。
第四,生态兼容更稳定。
Hugging Face 风格下载接口会把缺失文件和本地缓存未命中转换为对应的异常类型;快照下载模块重新导出InvalidParameter;本地模型更新避免对已存在于缓存目录中的模型进行重复复制。
对于依赖本地缓存进行模型管理的开发者来说,v1.40.3 提升的并不是某一个单独功能,而是一整套使用体验:离线时更稳定,清理时更安全,查找时更准确,兼容旧代码时更平滑。
如果业务环境包含离线部署、缓存预热、受限网络、私有环境运行、大模型本地存储,或者依赖 Hugging Face 风格调用接口,那么 modelscope v1.40.3 的这些修复具有直接价值。
芯谷ai:xinguhub.com/sign-up?aff=txk5
我们相信人工智能为普通人提供了一种“增强工具”,并致力于分享全方位的AI知识。在这里,您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”,发消息可获得面试资料,让AI助力您的未来发展。
特别声明:以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布,本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.