first commit

2026-09-11 01:41:52 +08:00
commit 9f22e6ccae
263 changed files with 28935 additions and 0 deletions
@@ -0,0 +1,61 @@
+---
+name: matting_server_python_run
+overview: 与分类服务一致，为抠图服务（BiRefNet）补齐纯 Python 独立运行配套：新增 requirements.txt 依赖清单，并在 main.py 末尾添加 uvicorn 启动入口（端口 8001），使 `python main.py` 一条命令即可启动。
+todos:
+  - id: create-matting-requirements
+    content: 新建 thirdparty/matting_server/requirements.txt 依赖清单并添加 GPU 安装与模型手动下载说明注释
+    status: completed
+  - id: add-matting-start-entry
+    content: 在 main.py 末尾追加 uvicorn 启动入口（端口 8001）并做语法验证
+    status: completed
+---
+
+## 用户需求
+
+参照刚完成的分类服务改造，将抠图服务（BiRefNet 人像/衣物抠图）同样改造为纯 Python 独立运行，完全不依赖 Go 项目：
+
+- 新增 `requirements.txt` 依赖清单
+- 在 `main.py` 末尾添加启动入口，使 `python main.py` 一条命令即可启动服务
+
+不要求本地测试脚本和 README。
+
+## 核心功能
+
+- **依赖清单**：声明 torch、torchvision、transformers、fastapi、uvicorn、pillow 六个依赖及版本下限，并注明 GPU 用户需单独安装 CUDA 版 torch、BiRefNet_lite 模型文件需手动下载到 ./model/ 目录
+- **一键启动**：`python main.py` 直接以 0.0.0.0:8001 启动 FastAPI 服务，无需 `uvicorn main:app` 命令
+
+## 技术方案
+
+### 实现方式
+
+1. 新建 `thirdparty/matting_server/requirements.txt`，列出运行所需的 6 个第三方依赖，采用宽松下限版本避免锁死小版本：
+
+- torch>=2.0.0、torchvision>=0.15.0、transformers>=4.44.0、fastapi>=0.100.0、uvicorn>=0.23.0、pillow>=9.5.0
+- 与分类服务的差异：多一个 `torchvision`（transforms/ToPILImage 用到）；`transformers` 下限为 4.44.0（`AutoModelForImageSegmentation` 是该版本才引入的类，不能照抄分类服务的 4.30.0）
+- 文件内注释说明两点：PyPI 默认安装 CPU 版 torch，GPU 用户需按 PyTorch 官网命令单独安装对应 CUDA 版本；模型代码 `local_files_only=True`，需先将 BiRefNet_lite 模型文件手动下载放到 `./model/` 目录
+
+2. 修改 `main.py` 末尾（第 61-64 行 `/healthz` 路由之后）追加启动入口：
+
+```python
+if **name** == "**main**":
+import uvicorn
+
+uvicorn.run(app, host="0.0.0.0", port=8001)
+```
+
+- **关键点**：BiRefNet 模型在模块 import 时于模块级加载（`model`、`transform` 为模块级变量），必须直接传 `app` 对象调用 `uvicorn.run(app, ...)`，不能使用 `"main:app"` 字符串加 reload 方式，否则会导致模型重复加载
+- uvicorn 放在入口内局部 import，保持顶部 import 区原结构不变，改动最小化
+- 端口选用 8001，与分类服务的 8000 错开避免冲突（Go 侧目前无抠图服务端口配置，端口可自由选定）
+
+### 验证方式
+
+- `python3 -m py_compile main.py` 确认语法无误，验证后清理 `__pycache__`
+- 交付后运行验证：`pip install -r requirements.txt && python main.py`，访问 `http://localhost:8001/healthz` 返回 `{"status": "ok"}`
+
+### 目录结构
+
+```
+thirdparty/matting_server/
+├── main.py            # [MODIFY] 末尾追加 __main__ 启动入口，python main.py 直接启动（端口 8001）
+└── requirements.txt   # [NEW] 依赖清单（torch/torchvision/transformers/fastapi/uvicorn/pillow + GPU 与模型下载说明注释）
+```