zt-closet-backend/.codebuddy/plans/models_auto_download_fallback_2b158447.md

name, overview, todos

name	overview	todos
models_auto_download_fallback	为分类服务（Fashion-CLIP）与抠图服务（BiRefNet）统一改造模型加载逻辑：启动时先尝试完全离线加载本地缓存，本地不存在则自动联网下载；同时统一两个服务的 HF 镜像配置。	id content status matting-two-level-loading 改造抠图服务 main.py（镜像、日志、绝对路径 cache_dir、两级加载）并同步 requirements.txt 注释 completed id content status classification-two-level-loading 改造分类服务 main.py（镜像统一 hf-mirror.com、模型与处理器两级加载） completed id content status dependencies syntax-verify 对两个 main.py 执行 py_compile 语法验证并清理 __pycache__ completed matting-two-level-loading classification-two-level-loading

产品概述

对两个纯 Python AI 服务（衣物分类服务 Fashion-CLIP、抠图服务 BiRefNet）的模型加载逻辑统一改造：启动时先检查本地缓存，本地已存在则完全离线加载（零网络请求）；本地不存在或不完整时自动联网下载模型到本地缓存，下载完成后后续启动均走离线分支。

核心功能

• 抠图服务改造：新增国内镜像与日志模块，模型缓存目录改为绝对路径（消除启动工作目录依赖），模型加载改为「本地存在则离线、不存在则自动下载」两级模式，并同步更新 requirements.txt 注释说明
• 分类服务改造：镜像地址统一为 hf-mirror.com（与代码注释保持一致），模型与处理器加载改为同一套「本地存在则离线、不存在则自动下载」两级模式
• 运行行为：首次启动无缓存时自动下载（走国内镜像加速），有缓存后完全离线；日志明确区分「命中本地缓存」与「自动下载」两种路径

技术栈

• Python 3 + HuggingFace Transformers（CLIPModel / CLIPProcessor / AutoModelForImageSegmentation）
• 国内镜像 hf-mirror.com（通过 HF_ENDPOINT 环境变量，在 import transformers 之前设置）
• 依赖与 FastAPI 服务结构不变，仅改模型加载段

实现方案

统一两级加载模式

利用 local_files_only=True 的行为特性：本地缓存缺失或不完整时 huggingface_hub 抛出 OSError（Python 3 中 LocalEntryNotFoundError 是 OSError 子类）或 ValueError，捕获后回退联网下载。两级使用同一个 cache_dir，HF 缓存结构固定（models--repo/snapshots/...），无需手动判断目录结构：

try:
    model = XXX.from_pretrained(REPO, ..., local_files_only=True, cache_dir=CACHE_DIR)
    logger.info("模型命中本地缓存，离线加载")
except (OSError, ValueError) as e:
    logger.info(f"本地未找到模型缓存，自动下载 ... ({e})")
    model = XXX.from_pretrained(REPO, ..., cache_dir=CACHE_DIR)

抠图服务 thirdparty/matting_server/main.py

1. 顶部（import transformers 之前）加镜像设置：if "HF_ENDPOINT" not in os.environ: os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"，并补 import os
2. 新增 logging.basicConfig(level=logging.INFO) + logger = logging.getLogger(__name__)
3. 模型缓存目录改为绝对路径：_model_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "model")，替换原相对路径 cache_dir="./model"
4. 模型加载改为两级加载（保持 trust_remote_code=True；model.eval()、device 判定、CUDA model.half() 逻辑保持不变）
5. 同目录 requirements.txt 注释同步：模型首次启动自动下载到本目录 ./model/ 缓存，无需手动放置

分类服务 thirdparty/classification_server/main.py

1. 第 21 行镜像从 https://hf-api.gitee.com 改为 https://hf-mirror.com（与第 12 行 docstring 一致）
2. 第 450-451 行 model 与 processor 放入同一 try 块两级加载：local_files_only=True 先试，任一失败则整体回退联网下载；model = model.to(device)、model.eval()、CUDA half() 保持原位置

性能与可靠性

• 有缓存时零网络请求，启动时间不受网络影响；无缓存时仅首次下载（约 400MB，走镜像）
• 缓存不完整（下载中断）时第一级失败自动触发补齐，天然容错
• 日志两条路径可观测，便于运维确认模型来源

目录结构

thirdparty/
├── classification_server/
│   ├── main.py            # [MODIFY] 镜像统一 hf-mirror.com；模型/处理器两级加载
│   └── requirements.txt   # 不变
└── matting_server/
    ├── main.py            # [MODIFY] 新增镜像/日志；cache_dir 绝对路径；模型两级加载
    └── requirements.txt   # [MODIFY] 注释更新为自动下载说明

验证方式

• 两个文件 python3 -m py_compile 语法验证，验证后清理 __pycache__
• 交付说明：首次启动自动下载（走 hf-mirror 镜像），有缓存后完全离线；日志区分「命中本地缓存」与「自动下载」