工业缺陷合成

给无缺陷照片合成逼真的缺陷，扩充 YOLO 训练集。背景、实验结论和路线见上一级目录的 项目详细说明文档.md。

方向	做法	入口
瓶体标签褶皱	无掩膜整图重绘 + 光场校正（demo 架构）	run.py demo-gen
PCB 缺陷	重绘局部裁块，差分定位后只贴回缺陷块	run.py pcb-web（网站）

安装

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

需要 Python 3.11。依赖版本已锁定；依赖文件只能写英文，中文 Windows 上 pip 按 GBK 读文件，有中文就会失败。密钥放环境变量 RELAY_API_KEY，不要写进文件。

瓶体生成

# 离线出计划，不调接口
.\.venv\Scripts\python.exe run.py demo-gen --products 500多效极润 --per-angle 125 --dry-run
# 后台生成，用任务计划运行，关掉终端不影响
.\.venv\Scripts\python.exe run.py demo-gen --products 500多效极润 --per-angle 125 --detach
# 离线重算指标和打分表
.\.venv\Scripts\python.exe run.py demo-report --run-dir <运行目录>
# 离线自检
.\.venv\Scripts\python.exe run.py demo-selftest

配置在 demo_pipeline.yaml。断点续跑：重新执行同一条命令。退出码和运维细节见说明文档第 13 节。

PCB 网站

$env:PCB_WEB_ACCESS_CODE = "<至少 8 位的访问码>"
.\.venv\Scripts\python.exe run.py pcb-web --host 0.0.0.0 --port 8000

配置在 pcb_web.yaml。只部署网站时用 requirements-web.txt。本机试用可以直接运行 tools\pcb_web_local.ps1。

PCB 缺陷库：参考缺陷存一次反复用，存放在 pcb_web_data/library/（不进 git，需要另外备份）。网页上可以从库里选或顺手入库，批量入库用命令：

.\.venv\Scripts\python.exe run.py pcb-lib add --image 缺陷.jpg --box x0,y0,x1,y1 --preset bridge
.\.venv\Scripts\python.exe run.py pcb-lib list

YOLO 类别编号全站固定：0 异物·黑色碎屑，1 异物·金属薄片，2 焊桥，3 引脚间锡条，4 其他缺陷。新类型只能加在 PRESETS 末尾。资源占用和部署注意事项见说明文档第 15 节。

缺陷库

.\.venv\Scripts\python.exe run.py inspect                   # 离线体检
.\.venv\Scripts\python.exe run.py build-catalog --dry-run   # 试算增量编目规模
.\.venv\Scripts\python.exe run.py build-catalog --classes 360森呼吸_角度1
.\.venv\Scripts\python.exe tools\verify_product_migration.py # 校验数据一致性

测试

.\.venv\Scripts\python.exe run.py demo-selftest
.\.venv\Scripts\python.exe -m unittest tests.test_pcb_web

编码注意

Windows PowerShell 5.1 按系统编码读无 BOM 的 .ps1：带中文的 .ps1 要存成 UTF-8 BOM，tools/add_ps1_bom.ps1 可以处理。改完含中文的文件后，用 Path(p).read_bytes().decode("utf-8") 校验一次。