AnimationManager/matting-server

BiRefNet Matting 图像抠图服务

基于 FastAPI 的图像背景移除服务，使用 BiRefNet 模型进行高质量图像抠图。

环境要求

• Python 3.8 或更高版本
• Windows 系统（已配置 .bat 启动脚本）
• 建议使用 GPU（CPU 也可运行，但速度较慢）

项目结构

实际项目文件

birefnet-matting/
├── server.py              # FastAPI 服务器主程序
├── birefnet-matting.py    # BiRefNet 图像处理脚本
├── start-server.bat       # 启动服务器脚本
├── requirements_python.txt # Python 依赖
├── rec/                   # 服务器接收图片的文件夹
├── send/                  # 服务器处理结果的文件夹
└── BiRefNet/              # BiRefNet 模型目录

测试相关文件

birefnet-matting/
└── test-client/           # 测试客户端目录
    ├── test-client.py     # 测试客户端程序
    ├── start-test-client.bat  # 启动测试客户端脚本
    ├── test-send/         # 测试：要发送的图片文件夹
    └── test-rec/          # 测试：接收处理结果的文件夹

快速开始

1. 安装依赖

方式一：自动安装（推荐）

直接运行启动脚本，会自动创建虚拟环境并安装依赖：

• 运行 start-server.bat 会自动安装服务器依赖
• 运行 test-client/start-test-client.bat 会自动安装客户端依赖

方式二：手动安装

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境（Windows）
.venv\Scripts\activate

# 安装依赖
pip install -r requirements_python.txt
pip install -r BiRefNet\requirements.txt

2. 准备测试图片

将要处理的图片放入 test-client/test-send 文件夹。

支持的格式：.jpg, .jpeg, .png, .bmp, .webp, .tiff, .tif

3. 启动服务器

双击根目录下的 start-server.bat 启动 FastAPI 服务器。

• 服务器地址：http://localhost:8000
• API 文档：http://localhost:8000/docs
• 健康检查：http://localhost:8000/health

4. 运行测试

1. 进入 test-client 文件夹
2. 双击 start-test-client.bat 启动测试客户端
3. 按回车键开始处理
4. 处理结果会保存到 test-client/test-rec 文件夹

工作流程

1. 测试客户端 (test-client/test-client.py)
   ├─ 从 test-client/test-send 文件夹打包图片
   ├─ 生成 test-client/test-send/test_images.zip
   └─ 发送 POST 请求到服务器

2. 服务器 (server.py)
   ├─ 接收 zip 文件，保存到 rec 文件夹
   ├─ 解压到 rec 文件夹
   ├─ 调用 birefnet-matting.py 处理图片
   ├─ 处理结果保存到 send 文件夹
   ├─ 打包成 send/processed_images.zip
   └─ 返回 zip 文件

3. 测试客户端接收
   ├─ 接收处理后的 zip 文件
   └─ 解压到 test-client/test-rec 文件夹

API 接口

POST /api/process

接收 zip 图包，处理后返回处理后的 zip 文件。

请求：

• Content-Type: multipart/form-data
• 参数：file (zip 文件)

响应：

• Content-Type: application/zip
• 返回处理后的图片 zip 文件

GET /health

健康检查接口。

GET /docs

Swagger API 文档（自动生成）。

支持的图片格式

• .jpg, .jpeg
• .png
• .bmp
• .webp
• .tiff, .tif

使用说明

服务器端

• 启动：双击 start-server.bat
• 停止：在服务器窗口按 Ctrl+C
• 接收文件夹：rec/ - 服务器接收上传的图片
• 输出文件夹：send/ - 服务器处理后的图片和 zip 文件

测试客户端

• 启动：进入 test-client 文件夹，双击 start-test-client.bat
• 输入文件夹：test-client/test-send/ - 放入要处理的图片
• 输出文件夹：test-client/test-rec/ - 接收处理结果

注意事项

1. 启动顺序：必须先启动服务器，再运行测试客户端
2. 处理时间：处理大量图片时可能需要较长时间，请耐心等待
3. 输出格式：处理后的图片会保存为 PNG 格式（带透明背景）
4. 数量验证：服务器会自动验证接收和处理图片数量是否一致
5. 连接重试：测试客户端连接失败时会自动重试 3 次（每次间隔 1 秒）
6. 文件清理：每次处理前会自动清空相关文件夹，确保结果准确