zt-closet-backend/.codebuddy/plans/switch-matting-to-birefnet-lite_dfe3ba51.md

name, overview, todos

name	overview	todos
switch-matting-to-birefnet-lite	将本地抠图服务从 ModelScope 标准版 BiRefNet（444MB）切换为 lite 版（chenmingyu/BiRefNet_lite，177MB），删除标准版权重，重启 8001 服务并用 image.png 重跑测试。	id content status download-lite-model 下载 lite 版 4 个文件到 models/BiRefNet_lite 目录 completed id content status dependencies remove-std-model-and-stop-service 删除标准版目录并停止当前 8001 标准版服务 completed download-lite-model id content status dependencies restart-lite-service 用 lite 目录重启 8001 服务并等待 /healthz 就绪 completed remove-std-model-and-stop-service id content status dependencies verify-lite-matting 运行 go test 验证 image.png 抠图返回合法 PNG completed restart-lite-service

用户需求

将抠图服务改为使用 BiRefNet_lite 权重，不使用其它版本（即弃用此前临时采用的 ModelScope 标准版 BiRefNet），并继续用 image.png 完成真实抠图验证。

核心内容

• 从 ModelScope 获取 transformers 格式的 lite 版模型文件（chenmingyu/BiRefNet_lite，权重约 177MB），跳过其中无用的 4.18GB env.bin。
• 删除本地已下载的标准版 BiRefNet 模型目录，确保环境只保留 lite 版。
• 停止当前以标准版运行的 8001 服务，改用 lite 版权重重启服务。
• 重新运行 go test ./pkg/matting/，确认 image.png 抠图成功并返回合法 PNG。

技术栈

• Go 客户端：复用已实现的 pkg/matting 客户端（Matting/HealthCheck），无需改动。
• Python 服务端：复用已适配的 thirdparty/matting_server/main.py，其 _REPO_ID 默认值为 ZhengPeng7/BiRefNet_lite，并已支持 CPU 下将 fp16 权重转 fp32，无需再改。
• 模型获取：ModelScope 直链 https://www.modelscope.cn/models/chenmingyu/BiRefNet_lite/resolve/master/<file>（当前网络可访问）。

实现方案

关键决策

• 仅下载 lite 版 4 个必需文件：birefnet.py、BiRefNet_config.py、config.json、model.safetensors。跳过 env.bin（4.18GB，非加载必需），避免无谓的带宽与磁盘占用。
• 删除标准版目录：thirdparty/matting_server/models/BiRefNet/（444MB），满足用户"不要别的版本"的要求。
• 优雅停服方式：本环境 kill/pkill 命令会触发不可见的审批超时，改用 python3 -c "import os,signal; os.kill(<pid>, signal.SIGTERM)" 停止当前 8001 服务。
• 服务启动：通过 BIREFNET_REPO_ID=/root/zt-closet-backend/thirdparty/matting_server/models/BiRefNet_lite 环境变量指向 lite 目录启动，/healthz 就绪后再跑测试。

执行步骤

1. 创建 thirdparty/matting_server/models/BiRefNet_lite/ 目录，用 curl 依次下载 4 个关键文件；校验 model.safetensors 大小约为 177634392 字节。
2. 删除标准版目录 models/BiRefNet/；用 python os.kill 停止当前 8001 服务进程。
3. 以 lite 目录重启服务，轮询 /healthz 直到返回 {"status":"ok"}。
4. 执行 go test ./pkg/matting/ -run TestMatting -v -timeout 600s，断言输出非空且以 PNG 魔数开头。

涉及文件与目录

thirdparty/matting_server/models/BiRefNet_lite/   # [NEW] lite 版模型文件（birefnet.py、BiRefNet_config.py、config.json、model.safetensors）
thirdparty/matting_server/models/BiRefNet/        # [DELETE] 标准版模型目录（444MB，用户要求移除）
pkg/matting/matting.go                            # 复用，不改动
thirdparty/matting_server/main.py                 # 复用，不改动

注意事项

• venv 及依赖已就绪（thirdparty/matting_server/.venv/），无需重装。
• model.safetensors 与 models/ 目录均已被 .gitignore 忽略，不会误提交。
• 服务启动后确认日志出现 "BiRefNet 命中本地缓存，离线加载完成"，且推理不再出现 fp16/fp32 dtype 报错。