HivisionIDPhotos v1.3.1 配置参数详解

目标：HivisionIDPhotos 的全部可调行为分布在「两类服务的启动参数与环境变量 + 照片生成链路的请求参数 + 模型选择」三个层面，官方 README 只给了部署命令、API 文档与实际代码还有三处不一致。本篇基于官方仓库 v1.3.1 源码（app.py、deploy_api.py、demo/processor.py 参数定义）、官方 README 与 API 文档（2026-10-25 实查），以及一套真实部署环境的逐项实测，讲清 Web 服务（Gradio）与 API 服务（FastAPI）各自的配置载体与全部请求参数的取值、默认值、实测效果：/set_kb 的 KB 控制精确到字节、/watermark 的五个参数必须走 URL query、/idphoto_crop 只收 RGBA 透明图、face_align 在 v1.3.1 的真实默认值是 false 而非文档写的 true。部署过程见本专栏部署篇，项目定位与选型见本专栏介绍篇。

一、环境信息

本篇配置实测与取证环境如下，读者操作时请替换为自己的取值：

• 操作系统：Linux x86_64（Debian 系内核），4 vCPU / 纯 CPU 推理（无 GPU）
• HivisionIDPhotos 版本：v1.3.1（官方发布程序 linzeyi/hivision_idphotos:v1.3.1，编排双服务同版本）
• Web 服务（Gradio）：python3 -u app.py --host 0.0.0.0 --port 7860，服务内监听 7860，对外映射 8138，实测 http://localhost:8138 返回 HTTP 200
• API 服务（FastAPI）：python3 deploy_api.py，服务内监听 8080，对外映射 8139，实测 http://localhost:8139 返回 HTTP 200
• 监听确认（ss 回显，2026-10-25）：

LISTEN 0      4096         0.0.0.0:8138       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:8139       0.0.0.0:*

• 测试素材：官方示例人像 test0.jpg（209,022 字节）、纯空白图 blank.jpg、由 /idphoto 返回结果解码出的 RGBA 透明 PNG

取证方式说明：参数「官方定义」逐条对照仓库 v1.3.1 源码的函数签名（deploy_api.py 各接口的 Form()/query 默认值，与实测拉取的 http://localhost:8139/openapi.json schema 双重核对）；「实际行为」全部通过 curl 现场请求 8139 端口实测取证，回显原文见文中代码块，证据文件留存于本地 tmp/hivisionidphotos/（本文标注 c1_*.json 的为本次补测文件，其余为批次既有实测文件）。

二、配置体系总览

HivisionIDPhotos 没有配置文件，全部配置分布在三类载体上，生效时机与作用范围完全不同：

两类服务的分工与配置面：

• Web 服务（Gradio，app.py）：面向人的交互界面，配置面 = 3 个启动参数（--host/--port/--root_path）+ 4 个环境变量 + 页面上五大参数面板（核心参数/高级参数/美颜/水印/打印排版）。适合手工制证照。
• API 服务（FastAPI，deploy_api.py）：面向程序调用，没有启动参数、没有鉴权、官方未暴露 workers/CORS 配置项（v1.3.1 源码即单进程 uvicorn 启动，见第四章），配置面 = 4 个共用环境变量 + 7 个接口的请求参数。适合被第三方系统集成。

💡 两个服务用同一套程序包、读同一组环境变量、共用 hivision/creator/weights 目录下的同一批模型权重文件，因此「换模型」「开野兽模式」这类环境变量级配置改一次对两个服务同时生效；而「预设尺寸列表」「预设底色」这类 CSV 驱动的配置只影响 Web 页面下拉项。

环境变量总表

以下为 v1.3.1 官方 README 声明的全部环境变量（官方仓库 README「Docker 部署-环境变量」章节，2026-10-25 实查，master 分支与 v1.3.1 口径一致）：

除 Face++ 密钥外没有必填项——不设任何环境变量两个服务都能以默认行为跑起来，这也是它部署门槛低的原因。

三、Web 服务（Gradio）配置

启动参数

python app.py --help 实测回显（v1.3.1）：

usage: app.py [-h] [--port PORT] [--host HOST] [--root_path ROOT_PATH]

  --port PORT           The port number of the server
  --host HOST           The host of the server
  --root_path ROOT_PATH
                        The root path of the server, default is None (='/'),
                        e.g. '/myapp'

• --port：服务监听端口，Gradio 默认 7860（README 默认访问地址即 http://127.0.0.1:7860）。本文实测编排显式写 --port 7860 并把对外 8138 映射进来。
• --host：监听地址。默认只听本机回环，自托管要局域网/外部访问必须显式 --host 0.0.0.0，否则映射了端口也连不上。
• --root_path：反代子路径场景使用，默认 None（即 /）。挂在网关的 /myapp 前缀下时设置它，页面静态资源路径才能正确拼接。

环境变量在 Web 侧的作用

• DEFAULT_LANG：页面语言下拉框的初始值。语言切换是页面上的即时选项，改环境变量只是换默认值。
• RUN_MODE=beast：野兽模式对 Web 侧同样生效——连续制照时省去反复加载模型的内存开销。实测环境未开启（默认模式），单张 test0.jpg 全链路 0.841s（抠图 0.329s + 美颜 0.007s + 人脸检测 0.502s + 后处理 0.003s，服务日志回显，检测模型为 retinaface-resnet50）。
• FACE_PLUS_API_KEY/SECRET：页面「人脸检测模型」下拉选 face_plusplus 时，服务端拿这两个变量去调旷视在线接口；不配密钥时选它即失败，离线的 mtcnn/retinaface 不受影响。

页面参数面板（请求参数的可视化等价物）

Web 页面的参数与 API 请求参数基本一一对应，但有三处 Web 独有或不同（依据 v1.3.1 demo/processor.py 参数定义与界面组件源码 ui_excerpt.txt、中文语言包 locales_zh.txt）：

三处需要注意的 Web/API 差异：

1. 美白强度（whitening）只在 Web 有：默认 2，API 的 /idphoto 没有对应参数，集成方无法通过 API 使用美白。
2. 水印透明度默认值不同：Web 页面默认 0.15，API /watermark 默认 0.5——同一张图两个入口默认水印深浅差一倍多。
3. 水印颜色默认值相反：Web 取色器默认 #FFFFFF（白），API 默认 #000000（黑）。

• 自定义尺寸的约束（页面提示原文）：「宽度不应大于长度；长度和宽度不应小于100，不大于1800。」即 px 输入被限制在 100~1800，API 侧虽然不校验这个范围，但超范围输出的构图没有业务意义。
• 自定义(mm) 的换算：mm 按 dpi 换算成 px，默认 35×25mm 在 300dpi 下即 413×295px（413÷300×25.4≈34.97mm），与一寸预设完全吻合。
• 预设列表可改：尺寸改 demo/assets/size_list_CN.csv（三列：名称、高、宽），颜色改 demo/assets/color_list_CN.csv（两列：名称、HEX），改完重启服务生效（官方 README FAQ）。实测程序包内两文件均在 demo/assets/ 下（413 字节与 99 字节，2026-10-25 取证）。

四、API 服务配置

启动与端口

• 启动命令只有 python deploy_api.py，没有任何命令行参数；v1.3.1 源码尾部即 import uvicorn 单进程启动，默认监听 8080（官方部署示例 8080:8080，实测编排把 8139 映射到 8080）。
• 官方未暴露 workers 数量、CORS、鉴权等任何服务级配置项：v1.3.1 没有多进程/多 worker 开关，并发能力受单进程 GIL 与模型推理限制；接口本身无任何认证（实测裸 curl 直接返回 200），上线必须靠网络层隔离——只在内网映射端口、不在网关暴露公网。这是它在生产形态上最重要的一个「没有的配置」。
• 自带交互式文档：/docs（Swagger UI，实测页面正常渲染）与 /openapi.json（实测可拉取完整参数 schema，本文各接口默认值即以此与源码双重核对）。探活可直接 GET 根路径看 200。

七个接口与参数总表

v1.3.1 实测 /openapi.json + deploy_api.py 源码，7 个接口的参数默认值全表（与官方 docs/api_CN.md 不一致处已用 ⚠ 标出，以实测为准）：

两个全局硬约束（实测踩坑点）

1. 只收 multipart/form-data，不收 JSON body。用 application/json 提交参数（含 input_image_base64 字段）实测返回 Internal Server Error（api2_jsonbody.txt）；正确做法是把 base64 字符串作为 form 字段 input_image_base64 提交，实测成功（b64_req.json 请求 / b64_resp2.json 响应，返回与文件上传方式完全一致）。
2. base64 的收发格式不对称。请求时传裸 base64 串（实测请求体以 /9j/4AAQ 即 JPEG 魔数开头，不带 data:image/... 前缀）；响应里的 image_base64* 却统一带 data:image/png;base64, 前缀——即使实际字节是 JPEG（如 /add_background 的返回，实测前缀 png 而数据头 /9j/）。消费方解码时按逗号截断后直接 base64 decode，不要相信前缀里的 MIME 类型。

错误行为

• 人脸数 ≠ 1：/idphoto、/idphoto_crop 返回 {"status": false}（无图像字段），这是业务正常分支，客户端要按 status 判断而不是 HTTP 状态码。
• 输入通道不符：/idphoto_crop 要求 RGBA 四通道透明图，实测传 JPG 三通道图直接 Internal Server Error（c1_crop_jpg.txt，2026-10-25 现场复测，错误体无 JSON 详情）。这类 500 没有结构化错误信息，排查只能看服务日志。
• 参数类型错误：FastAPI 校验层返回 422 与 HTTPValidationError 详情，这是唯一有结构化错误体的异常路径。

五、抠图与人脸检测模型参数

模型选择是生成质量的第一个分叉口，human_matting_model 与 face_detect_model 两个参数在每个需要推理的接口上重复出现。以下体积为实测服务内权重文件字节数（assets_ls.txt，2026-10-25），精度/速度口径为官方 README：

人像抠图模型（human_matting_model，4 选 1）

💡 还有一个 mnn_hivision_modnet 只出现在命令行推理工具 inference.py 的模型选项里（--help 实测回显），API 的 4 个可选值中没有它——这是 MNN 轻量格式，移动端场景用。

选型建议（结合官方性能表与本次实测耗时）：常规批量出图用默认 modnet_photographic + mtcnn（内存 410MB 级、亚秒级推理，本次实测 API 全链路 0.321s）；换底色频繁的交互场景切 hivision_modnet；证件照对发丝边缘要求高、且机器内存 ≥8GB 空闲时才上 birefnet-v1-lite——6.2GB 的内存占用与 7 秒的 CPU 推理耗时决定了它不适合高并发在线服务。

人脸检测模型（face_detect_model，3 选 1）

mtcnn 精度不足的典型表现是正常单人照被判「人脸数不等于1」返回 status:false——页面提示语原文即建议「切换左侧不同的人脸检测模型」。自托管追求成功率的组合是 modnet_photographic + retinaface-resnet50：内存几乎不变（405MB vs 410MB），代价是单张多花约 0.3~0.7 秒。

六、照片生成链路参数详解

生成一张可用证件照的完整链路是：/idphoto（抠图+构图，出透明底照）→ /add_background（填底色）→ /generate_layout_photos（排版）或 /set_kb（压体积）。以下按参数逐个给出取值、默认与实测效果。

6.1 尺寸与 DPI：height / width / dpi

• height/width：标准照的像素高宽，默认 413×295（一寸）。API 只认 px；高清照按同比例放大生成（标准照由高清照缩放而来）。实测 /idphoto 默认参数返回标准照 PNG 元数据 413×295、高清照 4961×3514 量级（run_hd.png 492KB vs run_standard.png 297KB，2026-10-25）。
• dpi：默认 300，写入输出图像文件的分辨率元数据，不改变像素数，决定打印物理尺寸——413px @300dpi = 35mm 宽，这正是 mm 模式的换算依据。Web 侧可选 72~600；出打印稿保持 300，纯网页展示 72 即可缩小文件。
• 排版照的相纸尺寸由服务端内置（六寸相纸 1050×1499），height/width 只控制单张小照大小，排版布局自动计算，实测六寸排版输出 204800 字节 JPG（run_layout.jpg）。

6.2 背景色与渲染：color / render

• color：HEX 值、不带 #，默认 000000（黑）。常用预设：蓝 628bce、红 d74532、白 ffffff。实测 color=638cce 正常合成（c1_bg0.json）。
• render：底色渲染模式，实测三种模式对同一张透明照（413×295 RGBA PNG）的输出（2026-10-25 现场）：

⚠️ 渐变混的是白色，非所选底色的明暗变体；需要纯证件照（考试/签证）用 0，需要艺术照效果才用 1/2。

6.3 KB 压缩：kb（/set_kb，及各接口的 kb 参数）

KB 控制是 v1.3.1 最能打的一个能力：输出体积精确到字节级命中目标，双向生效——目标小于原文件时调压缩率，大于原文件时向文件头填充信息撑大。2026-10-25 现场实测（输入 test0.jpg 原始 209,022 字节）：

POST /set_kb  kb=50   → 输出恰好 51,200 字节 = 50.0 KB（c1_setkb50.json）
POST /set_kb  kb=500  → 输出恰好 512,000 字节 = 500.0 KB（c1_setkb500.json）

历史批次实测同样吻合：kb50.jpg 51,200 字节、run_setkb.jpg 20,480 字节（kb=20）、/add_background 传 kb=30 输出恰好 30,720 字节（c1_bg1kb.json）。即无论压缩还是填充，输出字节数 = kb×1024 精确命中。

• /set_kb 的 kb 默认 50（v1.3.1 实测，与官方文档「默认 None」不一致）。
• kb 参数在 /add_background、/generate_layout_photos、/watermark 上同机制（源码同一 resize_image_to_kb 路径），不传则不做任何 KB 调整。
• 实操建议：报名系统要求「不超过 50KB」时直接 kb=50 精确达标；要求「30~200KB 之间」时用 kb=100 一发命中，不要依赖客户端再压（二次压缩画质不可控）。

6.4 水印：/watermark 的七参数

⚠️ v1.3.1 的最大暗坑：size/opacity/angle/color/space 五个参数在 URL query 上（实测 /openapi.json 中 in: query），只有 text/input_image/input_image_base64/kb/dpi 在表单里。把它们塞进 form 字段会被静默忽略、返回默认值效果。官方 docs/api_CN.md 的 cURL 示例也是 query 传法，照抄示例才不会踩坑。

实测全参数调用（query 五项 + form 文本）成功返回（c1_wm.json，2026-10-25）：POST /watermark?size=40&opacity=0.2&angle=45&color=%23ffffff&space=50 + form text=QUZUO。另外 Web 侧水印透明度默认 0.15、颜色默认白色，与 API 默认（0.5/黑色）差异大，跨入口对齐效果时要显式传参。

6.5 裁剪模式：/idphoto_crop 与 hd

• /idphoto_crop 是「已抠图照片的重构图」入口：输入 RGBA 透明图（实测传 JPG 三通道直接 500，c1_crop_jpg.txt），按 height/width 与四个构图比例参数重新裁出标准+高清两张透明照，实测 RGBA PNG 输入返回 image_base64_standard 与 image_base64_hd（api2_crop_rgba.json）。适用场景：前端用 JS 换底色后需要重新出标准构图。
• hd：默认 true；设 false 时响应不含 image_base64_hd 字段（run_idphoto_nohd.json 实测只有 standard 一张），可省约 2/3 响应体量（实测 nohd 响应 209,088 B vs 全量 1,052,795 B，run_idphoto.json）。只需要标准照时务必关掉，直接省带宽。
• 构图四参数联动：head_measure_ratio（面部占画面比例，默认 0.2）、head_height_ratio（面部中心距顶比例，默认 0.45）、top_distance_max/min（头顶留白区间，默认 0.12/0.1）。默认值即中国一寸照标准构图，除非目标规格有明确要求（如某些签证头顶留白更小），否则不要动。

6.6 人脸对齐与美颜：face_align 与四个 strength

• face_align：人脸旋转对齐开关，v1.3.1 实测默认 false（源码 Form(False) + schema 一致；官方 api_CN.md 写的 face_alignment/默认 true 是文档滞后）。开启后对歪头照片做旋转矫正，实测同一张图输出 base64 长度 209,046（默认关）→ 199,630（开启），画面确有变化（run_align_default.json / run_align_align_true.json）。端正的正脸照开着没收益，还有极小概率把构图转过头，按需开启。
• 美颜四项：brightness_strength/contrast_strength/sharpen_strength/saturation_strength 默认全 0，正负双向（UI 滑条亮度 -525、对比度与饱和度 -1050、锐化 0~5）。API 无美白参数（见第三章）；轻度提亮可传 brightness_strength=2~5，官方示例给了 brightness_strength=10 的用法，实测 10 以内画质自然，过高会过曝。

6.7 排版照：/generate_layout_photos

输入已加底色的 RGB 图，按 height/width（单张小照尺寸）自动计算六寸相纸（1050×1499@300dpi）上的行列排布，一寸照实测排出 8 张/版。kb 参数可直接控制排版照体积（同 6.3 机制）。Web 侧打印排版 Tab 另支持五寸/A4/3R/4R 相纸（2024.11.20 更新引入），API 侧 v1.3.1 固定六寸。实测默认参数输出 204,800 字节 JPG（run_layout.jpg / layout_resp.json）。

6.8 一次完整链路的参数组合（实测模板）

# 第 1 步：生成透明底标准+高清照（默认模型组合，face_align 按需）
curl -s -X POST "http://127.0.0.1:8080/idphoto" \
  -F "input_image=@test0.jpg" \
  -F "height=413" -F "width=295" \
  -F "human_matting_model=modnet_photographic_portrait_matting" \
  -F "face_detect_model=retinaface-resnet50" \
  -F "hd=true" -F "dpi=300" -F "face_align=false"

# 第 2 步：给标准照填蓝色底并直接控到 100KB（standard 的 base64 存为 std.b64）
curl -s -X POST "http://127.0.0.1:8080/add_background" \
  -F "input_image=@std.png" -F "color=628bce" -F "render=0" -F "kb=100" -F "dpi=300"

# 第 3 步：六寸排版照，控到 500KB 以内
curl -s -X POST "http://127.0.0.1:8080/generate_layout_photos" \
  -F "input_image=@with_bg.jpg" -F "height=413" -F "width=295" -F "kb=500" -F "dpi=300"

七、生产环境配置模板

编排 environment 模板

在双服务编排的基础上，推荐显式声明四个环境变量（两个服务同组生效，按需取舍）：

services:
  hivision-web:
    # ...... 省略端口/网络等部署细节 ......
    command: python3 -u app.py --host 0.0.0.0 --port 7860
    environment:
      RUN_MODE: beast            # 内存 >=16GB 时开启，二次推理免加载
      DEFAULT_LANG: zh
      # FACE_PLUS_API_KEY: <仅在选用 face_plusplus 人脸检测时配置>
      # FACE_PLUS_API_SECRET: <与 KEY 成对>
    restart: unless-stopped

  hivision-api:
    command: python3 deploy_api.py
    environment:
      RUN_MODE: beast
    restart: unless-stopped

• RUN_MODE=beast 的取舍：官方建议内存 16GB 以上开启；内存紧张的小主机保持默认模式，代价只是每张照片多一次模型加载（本次实测默认模式下单张全链路 0.3~0.9s，可接受）。
• --host 0.0.0.0 不能省：Web 服务不写它只监听回环地址，端口映射后外部依旧无法访问（Gradio 默认行为的坑）。
• API 无鉴权，端口不要出公网：8139 这类映射只放内网/overlay 网络；需要公网服务时在网关层加认证转发，不要指望程序自带。
• 模型权重随程序包内置：v1.3.1 程序包已带全部 4 个抠图权重与 retinaface 权重（实测文件清单见第五章），无需额外挂载；自建部署才需要按官方 README 手动下载到 hivision/creator/weights/。

API 请求参数组合模板（按业务场景）

八、FAQ

Q1：/set_kb 传了 kb 但返回的文件大小不等于设定值？ 检查三件事：① 参数是不是放在 form（-F）里而不是 JSON body；② v1.3.1 的 KB 命中是精确到字节的，如果差了一个 data:image/png;base64, 前缀的长度，那是你把响应里的 base64 前缀也算进了体积——解码后的字节才是文件本体；③ 确认用的是 /set_kb（或带 kb 的接口）而不是客户端自行再压。

Q2：/watermark 传了 size/opacity 等参数，水印效果却像默认值？ 这五个参数（size/opacity/angle/color/space）在 v1.3.1 是 URL query 参数，放 form 会被静默忽略（第六章 6.4）。正确写法 POST /watermark?size=40&opacity=0.2&angle=45&color=%23ffffff&space=50，text/kb/dpi 留在表单。注意 color 这里要带 #（URL 里编码为 %23）。

Q3：/idphoto_crop 一直 500 Internal Server Error？ 输入必须是 RGBA 四通道透明图（抠图接口的输出），实测传普通 JPG 三通道图直接 500 且无错误详情（c1_crop_jpg.txt）。先用 /idphoto 或 /human_matting 拿透明照，把返回的 base64 解码存成 PNG 再投喂。

Q4：用 JSON 直接 POST 参数全部 500？ v1.3.1 只接受 multipart/form-data，包括 input_image_base64 也要作为表单字段提交（api2_jsonbody.txt 实测 500；b64_resp2.json 实测 form 方式成功）。要程序化集成，把 base64 裸串（不带 data: 前缀）放进 form 字段即可。

Q5：明明是单人照，却返回 {"status": false}？ 人脸检测没检出恰好 1 张脸。默认 mtcnn 精度较低，先换 retinaface-resnet50（离线、内存几乎不涨）重试；照片过小、侧脸严重时考虑裁剪主体后再传；实在不行启用 face_plusplus（需配 FACE_PLUS_API_KEY/SECRET 环境变量，走在线检测）。

Q6：文档里 face_alignment 参数为什么我传了没生效？ v1.3.1 实际参数名是 face_align，默认 false（源码与 /openapi.json 双重确认），官方 api_CN.md 的 face_alignment/默认 true 是文档与代码不同步。传 face_alignment=true 会被 FastAPI 忽略，对齐并不生效。

Q7：birefnet-v1-lite 一张图要 7 秒还吃 6GB 内存，正常吗？ 正常。官方性能参考即 6.20GB 内存、7.063s（纯 CPU）。它是四个抠图模型里精度最好的，也是唯一支持 NVIDIA GPU 加速的（需约 16GB 显存与 onnxruntime-gpu）。在线高并发服务建议退回 modnet_photographic（亚秒级、410MB 内存），把 birefnet 留给离线精修。

Q8：想加一个自己的尺寸/底色预设怎么办？ 改 demo/assets/size_list_CN.csv（名称,高,宽）与 color_list_CN.csv（名称,HEX）后重启 Web 服务（官方 README FAQ）。这两个 CSV 只驱动 Web 页面下拉项；API 调用方自己在请求参数里传 height/width/color 即可，不依赖预设。

Q9：服务需要预热吗？为什么第一张特别慢？ 默认模式下每次请求都会加载/释放模型，冷启动首张最慢（本次实测 Web 端首张全链路 0.841s）。批量出图前设 RUN_MODE=beast 让模型常驻内存（官方建议 16GB+ 内存），二次推理明显提速；改环境变量后需重启服务进程生效。

九、参考链接

• 官方仓库（v1.3.1 源码 app.py/deploy_api.py/demo/processor.py 与 README 均已逐节核对）：https://github.com/Zeyi-Lin/HivisionIDPhotos （查询日期 2026-10-25）
• 官方 API 参数文档（与本文实测差异处以实测为准）：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/master/docs/api_CN.md （查询日期 2026-10-25）
• Face++ 人脸检测接入文档：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/master/docs/face%2B%2B_CN.md 、Face++ 官方接口文档 https://console.faceplusplus.com.cn/documents/4888373
• 官方发布程序（Docker Hub）：https://hub.docker.com/r/linzeyi/hivision_idphotos/tags
• 预设尺寸/颜色列表：https://github.com/Zeyi-Lin/HivisionIDPhotos/tree/master/demo/assets
• 本地实测证据目录：tmp/hivisionidphotos/（c1_*.json 为 2026-10-25 现场补测，其余为批次实测）
• 本专栏系列：介绍篇与部署篇见本专栏《HivisionIDPhotos》下的介绍与部署文章。