download_model warning

快速结论：这个 download_model warning 通常出现在 Faster Whisper v1.1.0 调用 faster_whisper.utils.download_model 下载模型时，huggingface_hub 提示 local_dir_use_symlinks 已废弃；第二次下载同一模型时还可能因缓存目录权限触发 PermissionError。优先排查 huggingface_hub 版本与目标目录的写入权限。

适用环境：Issue 中确认的环境为 Faster Whisper v1.1.0、Python 3.11、huggingface_hub（未给出具体版本，触发废弃警告）、运行在 Docker 容器内并挂载 Docker volume；其余 CUDA、显卡、操作系统版本未在 Issue 中说明。

最快修复方案：Issue 评论中给出的处理方式是降级 huggingface-hub：pip install huggingface-hub==0.19.4。

注意事项：降级 huggingface-hub 只是 Issue 评论中的建议，Issue 正文未说明该操作是否已由原发帖人验证解决；降级可能影响其他依赖较新 huggingface_hub 的包。此外，PermissionError 指向 /tiny/.cache/huggingface/download/config.json.lock，如果目标目录权限或 Docker volume 挂载权限本身有问题，仅降级版本不一定能完全解决。

问题场景

用户在 Faster Whisper v1.1.0 中使用 faster_whisper.utils.download_model 加载模型，调用方式如下：

from faster_whisper.utils import download_model
download_model('tiny','/tiny')

首次调用时出现 huggingface_hub 的废弃警告；第二次用相同参数调用时出现 PermissionError。用户将模型下载到 Docker volume，并怀疑这与权限问题有关。用户还提出疑问：download_model 是否应该检测到本地缓存已存在模型，从而不再重复下载。

报错原文

/usr/local/lib/python3.11/dist-packages/huggingface_hub/file_download.py:834: UserWarning: `local_dir_use_symlinks` parameter is deprecated and will be ignored. The process to download files to a local folder has been updated and do not rely on symlinks anymore. You only need to pass a destination folder as`local_dir`.
For more details, check out https://huggingface.co/docs/huggingface_hub/main/en/guides/download#download-files-to-local-folder.

PermissionError: [Errno 13] Permission denied: '/tiny/.cache/huggingface/download/config.json.lock'
make: *** [Makefile:165: transcript] Error 1

原因分析

最直接的原因是 Faster Whisper v1.1.0 依赖的 huggingface_hub 在下载文件时仍传入 local_dir_use_symlinks 参数，而新版 huggingface_hub 已将该参数标记为废弃并忽略，因此抛出 UserWarning。

第二次运行出现 PermissionError 的可能原因是：模型缓存或下载锁文件目录 /tiny/.cache/huggingface/download/ 在当前用户或 Docker 容器用户下不可写，导致创建 config.json.lock 失败。由于用户将模型下载到 Docker volume，权限映射问题也可能参与其中。Issue 中没有明确确认 download_model 为什么不跳过已存在的本地缓存，因此“未检测本地缓存导致重复下载”只能作为可能原因，不能作为确定结论。

环境排查

确认 Faster Whisper 版本：Issue 中为 v1.1.0。
确认 Python 版本：Issue 中为 Python 3.11。
确认 huggingface_hub 版本：Issue 未给出具体版本，但该版本会触发 local_dir_use_symlinks 废弃警告。
确认运行环境：Issue 中为 Docker 容器，模型目标目录为 /tiny，并挂载 Docker volume。
确认目标目录权限：检查 /tiny 及 /tiny/.cache/huggingface/download/ 是否对当前运行用户可写。
确认是否有其他依赖要求较新版本的 huggingface_hub。
CUDA、显卡、PyTorch、faster-whisper 之外的依赖版本在 Issue 中未说明，无需补充推断。

解决步骤

先尝试按 Issue 评论中的建议降级 huggingface-hub：
```
pip install huggingface-hub==0.19.4
```
该做法可优先尝试，目的是避开触发 local_dir_use_symlinks 废弃警告的 huggingface_hub 版本。
如果降级后仍然出现 PermissionError，检查并修复目标目录权限，尤其是 /tiny/.cache/huggingface/download/ 目录是否允许当前用户写入。
如果使用 Docker volume，确认容器内运行用户与 volume 挂载目录的 UID/GID 权限匹配，避免锁文件无法创建。
不要直接假设 download_model 一定会跳过本地缓存；在 Issue 中该行为没有得到明确确认。

验证方法

重新运行 download_model('tiny','/tiny')，观察是否还出现 local_dir_use_symlinks 废弃警告；再次以相同参数运行，确认是否还弹出 PermissionError: [Errno 13] Permission denied: '/tiny/.cache/huggingface/download/config.json.lock'。如果警告和权限错误都消失，说明处理生效。