2. 安装步骤

2.1 基础安装

# 克隆项目
git clone https://github.com/hivisionai/hivisionidphoto.git
cd hivisionidphoto

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

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/MacOS:
source venv/bin/activate

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

2.2 Docker 安装

# 拉取镜像
docker pull hivisionai/hivisionidphoto:latest

# 运行容器
docker run -d \
  --name hivisionidphoto \
  -p 7860:7860 \
  hivisionai/hivisionidphoto:latest

运行方式

3.1 Python API 调用

from hivisionidphoto import IDPhotoMaker

# 初始化
maker = IDPhotoMaker()

# 生成证件照
result = maker.make_id_photo(
    image_path="input.jpg",
    size="1寸",
    bg_color="蓝色",
    num_copies=1
)

# 保存结果
result.save("output.jpg")

3.2 Gradio 网页界面

# 启动 Gradio 服务
python web_ui.py

启动后访问 http://localhost:7860 即可使用网页界面。

3.3 命令行使用

# 基础用法
python cli.py --input input.jpg --size 1寸 --bg-color 蓝色

# 高级用法
python cli.py \
  --input input.jpg \
  --size 2寸 \
  --bg-color 白色 \
  --copies 4 \
  --beautify \
  --output output.jpg

4. 常用配置

4.1 配置文件说明

配置文件位于 config.yaml ，主要包含：

• 模型选择
• 图像参数
• 服务配置
• 性能调优

model:
  segmentation: "modnet"  # 可选: modnet, rmbg, birefnet
  face_detection: "mtcnn"  # 可选: mtcnn, retinaface, facepp
  
processing:
  image_size: 1024
  beautify: false
  
server:
  host: "0.0.0.0"
  port: 7860
  
performance:
  beast_mode: false  # 是否启用内存常驻加速
  gpu_id: 0  # GPU设备ID，-1表示使用CPU

4.2 自定义证件照尺寸

在 sizes.json 中添加自定义尺寸：

{
  "custom_size": {
    "width": 413,
    "height": 626,
    "dpi": 300,
    "name": "自定义尺寸"
  }
}

常见问题

1. 内存不足

• 降低处理图片的分辨率
• 关闭 Beast Mode
• 使用较轻量级的模型

2. GPU 相关

• 确保已安装 CUDA 和 cuDNN
• 检查 GPU 显存占用
• 适当调整批处理大小

3. 图片质量问题

• 调整光线和背景
• 使用更高质量的输入图片
• 尝试不同的模型组合

性能优化建议

1. CPU 优化

• 启用 Beast Mode 实现内存常驻
• 使用轻量级模型如 RMBG
• 适当降低处理分辨率

2. GPU 加速