ziyu/AI_spine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

第三步补全接入

Browse Source
This commit is contained in:
Ukawka
2026-09-20 22:21:50 +08:00
parent f095c28858
commit 99d65377ab
14 changed files with 912 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/2-segmentation-stage.md
+2
View File
@@ -106,3 +106,5 @@ Node 先启动环境探测子进程，再启动一次推理子进程。模型只
这组结果覆盖原图前景约 67.18%，仍有 64286 像素未覆盖、30569 像素重叠。`shin_left` 和 `foot_left` 的 mask IoU 约 0.843，实际都分到了鞋子；躯干及其他肢体也存在碎片或错分。文本候选对照未解决这些问题。这说明推理和输出链路已跑通，但当前旧语义计划与提示策略尚不能产出合格的最终拆件；需要修正部件粗框并继续验证提示及 mask 语义。
同日 `conda run --no-capture-output -n ai-spine npm test` 的 17 项测试全部通过（包括 Python 分割回归用例）；真实产物 `--resume` 哈希校验复用通过。测试通过仅验证程序行为，不表示上述分割质量合格。
后续已接入[第三阶段部件补全](3-completion-stage.md)。该阶段直接读取本目录的 `source.png`、`semantic-parts.json`、`segmentation.json` 和全画布 `masks/`；保留本阶段的告警，不能通过生成隐藏纹理来修复错误的部件归属。
docs/3-completion-stage.md
+127
View File
@@ -0,0 +1,127 @@
# 第三阶段：部件补全
本阶段处理第一阶段声明的 `occlusion_fill`、`joint_extension_parent`、`joint_extension_child`，读取第二阶段的可见 mask，为部件生成局部画布，调用图片编辑模型并合并受限的新增像素。原图已可见区域的 RGBA 像素始终从原图恢复，不使用模型重绘的版本。
使用 [AGENTS.md](../AGENTS.md) 规定的 Conda `ai-spine` 环境，不需要额外安装依赖。第三阶段几何处理使用本地 Python；图片生成通过现有中转站 `images/edits` 接口完成。
切换 Tiantoken 中转站时，在命令中增加 `--config .\configs\tiantoken.json`，并删除示例中的 `--completion-model qwen-image-3.0`，或改为 `--completion-model gpt-image-2`。该配置读取独立的 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`，第三阶段默认 `gpt-image-2`。目前仅验证模型列表可访问，实际图片编辑能力尚未实测；`gpt-6-astra` 的 Responses 图片生成工具仍需另行适配。
## 命令
在 PowerShell 中进入项目并激活环境：
```powershell
Set-Location F:\Study\taonier\AI_spine
conda activate ai-spine
$runId = Get-Date -Format "yyyyMMdd-HHmmss"
```
只准备任务（离线、无需 API Key）：
```powershell
node .\tools\model-check.mjs --stage completion `
--input-dir .\output\sombrero-sam31-v3 `
--out-dir ".\output\$runId-prepare" `
--completion-model qwen-image-3.0 `
--prepare-only
```
真正调用模型补全一个部件，需要 `.env` 中的中转站地址与密钥，会产生图片请求：
```powershell
node .\tools\model-check.mjs --stage completion `
--input-dir .\output\sombrero-sam31-v3 `
--out-dir ".\output\$runId-complete-head" `
--completion-model qwen-image-3.0 `
--part head
```
`--part head --part neck` 指定多个部件。省略 `--part` 时处理所有可用且需要补全的部件，每个部件单独发出请求；当前模型配置 `n=1`。程序串行调用，沿用提供方的超时及显式 429/5xx 重试策略，超时/网络中断不自动重复生成。发生请求错误保留候选和诊断，停止后续部件。
离线导入已经生成的候选（无需 API Key）：
```powershell
node .\tools\model-check.mjs --stage completion `
--input-dir .\output\sombrero-sam31-v3 `
--out-dir ".\output\$runId-merge" `
--part head `
--candidates-dir .\completion-candidates
```
候选文件名为 `completion-candidates/head.png`，必须与对应任务的局部画布尺寸、坐标完全一致。准备与合并必须使用相同输入、`--completion-size` 和 `--extension-radius`。缺失候选记为 `missing_candidate`，不会联网补发。可将先前任务保存的原始候选复制为 `ID.png`，离线检查它，避免重复计费。
每个输出目录必须是新目录；`--resume` 仅复用已完整结束且输入、参数、源码和产物哈希一致的任务。准备模式与生成模式使用不同目录。失败任务不自动续发请求。
| 参数 | 作用 |
| --- | --- |
| `--input-dir` | SAM 输出目录，必须含 `source.png`、v2 计划、`segmentation.json`、`masks/<id>.png` |
| `--part ID` | 指定部件，可重复；省略时处理全部有补全需求的部件 |
| `--prepare-only` | 只准备画布、区域与提示词，不请求图片模型 |
| `--candidates-dir` | 离线读取 `ID.png` 候选，与 prepare-only 互斥 |
| `--completion-size` | 方形局部画布边长，默认 1024，128～4096；不缩放原像素 |
| `--extension-radius` | 新增区域距可见 mask 的最大距离，默认 32 像素，1～256 |
| `--completion-model` | 图片模型原始 ID，当前示例使用 qwen-image-3.0 |
| `--dry-run` | 检查输入文件、计划、参数和 Python 环境，不生成画布或请求模型 |
旧的 `--stage completion --image ... --prompt-file ...` 保留为独立接口探针，不能与 `--input-dir` 混用。`--stop-after` 目前仍只支持 understand/segment；第三阶段独立调用。
## 允许新增区域
候选不可以随意扩大部件。程序在原图坐标中构造以下区域，并始终排除原可见 mask：
- 遮挡补全：可见轮廓外 `extension-radius` 范围，与 `occluded_by` 指向的 SAM mask 的交集。
- 向父关节延展：同一距离范围，与本部件 `pivot_norm` 附近半径为 `extension-radius` 的圆盘的交集。
- 向子关节延展：同一距离范围，与直接子骨骼部件的 pivot 圆盘的交集。
这些是保守的几何候选区域，不是推断出的完整隐藏形状。缺少遮挡 mask、关节过远或没有子骨骼时，相应区域为空并记录告警。所有区域都为空时跳过该部件。完全隐藏或没有可见 SAM mask 的部件也跳过，不凭空生成完整肢体。
局部画布包含可见区域与允许新增区域，至少留 16 像素边距。`origin_xy` 记录局部左上角在原图中的坐标，可为负数；只有平移和补透明边，不进行缩放。所需范围放不下时失败，需增大画布。新增区域目前限定在原图画布范围内。
输入给模型的是白底可见部件。只有配置明确声明 `capabilities.mask=true` 时才发送 RGBA 编辑 mask（透明处可编辑）；只有 `multiple_images=true` 时才发送第二张局部原图参考。默认配置二者均为 false，不假定中转站支持这些能力。无论是否发送编辑 mask，返回候选都经过本地允许区域约束。
## 返回候选的检查和合并
1. 尺寸必须与局部画布完全一致。拒绝自动缩放、重定位或裁切来迎合返回图。
2. 已有透明背景保留；不透明白底使用边界连通近白区域去底。无法提取前景则拒绝。
3. 使用原部件 Alpha ≥240 的像素检查对齐：候选保留率至少 95%，RGB 平均绝对误差不大于 30。无不透明锚点则拒绝。这只能发现明显偏移或重绘，不能保证语义正确。
4. 只保留允许区域中的新增像素，并去掉与原可见部分不连通的新增块。越界和不连通像素数量写入 QA。没有新增像素则拒绝。
5. 原可见 mask 内 RGBA 逐像素恢复；候选仅提供新增像素。记录各补全子区域新增数量及 `unfulfilled_regions`，存在空缺的要求不会冒充已完成。
6. 每个返回候选分别检查，选择第一个通过几何条件的候选。输出始终 `semantic_verified=false`、`quality_status=needs_review`。
上游 SAM mask 有碎片、重复或语义错分时会原样影响补全，告警保存在 JSON 和报告中。颜色/位置检查也不能验证隐藏纹理是否合理。白底去除可能影响贴边白色细节，仍需人工检查。
## 产物
| 路径 | 内容 |
| --- | --- |
| `completion-plan.json` | 所有已准备任务、区域及跳过原因 |
| `tasks/<id>/input.png` | 发给模型的白底局部部件 |
| `tasks/<id>/visible.png` | 从原图保存的 RGBA 可见部件，合并时恢复像素 |
| `tasks/<id>/context.png` | 同坐标局部原图参考 |
| `tasks/<id>/edit-mask.png` | RGBA 编辑 mask，透明处允许编辑 |
| `tasks/<id>/allowed-mask.png` | 白色表示允许新增像素的区域 |
| `tasks/<id>/<补全字段>.png` | 三种补全要求各自的允许区域 |
| `tasks/<id>/task.json` / `prompt.txt` | 坐标、补全需求、上游告警 / 实际提示词 |
| `tasks/<id>/candidate-N.*` | 模型或离线导入的原始候选，拒绝时也保留 |
| `tasks/<id>/qa-N.json` | 单候选检查结果与拒绝原因 |
| `tasks/<id>/merged-N.png` | 通过几何检查后的局部 RGBA，已恢复可见像素 |
| `parts/<id>.png` | 被选中的补全候选，紧裁剪透明 PNG |
| `completion-result.json` | 每部件状态、候选 QA、原图裁剪坐标和输出路径 |
| `report.html` | 原可见部件、允许新增区域、补全候选和告警 |
| `manifest.json` | 运行模式、网络请求标记、输入/代码/产物哈希及计数 |
`parts/` 只包含本次被选中且通过几何检查的补全部件。无需补全、未选中和被拒绝的部件不会被伪装成新补全结果；最终组装需结合原 SAM 部件及这里的替换文件。Spine 导出尚未接入。
## 实现和验证
[stages/completion-stage.mjs](../stages/completion-stage.mjs) 调度准备、请求、候选检查及缓存；[completion_geometry.py](../completion_geometry.py) 实现区域构造、Alpha 提取、原像素恢复和报告；[providers/image-edits.mjs](../providers/image-edits.mjs) 复用现有图片接口。
测试覆盖原尺寸坐标映射、Alpha 保真、三个补全字段、越界裁剪、尺寸/位移/空白候选拒绝、离线模式、显式多图与 mask 能力、错误诊断和缓存失效。使用 `conda run --no-capture-output -n ai-spine npm test` 执行，不调用真实付费模型。
最初接入时，sombrero-sam31-v3 输出可离线准备 17 个补全任务，11 个部件因无需补全而跳过。当时验证了真实输入的画布准备与 mock 编辑响应的完整合并链路，尚未执行真实 Qwen 图片生成。
本轮验证结果：22 项 Node 测试通过（其中包含 7 个 Python 补全用例），真实输入的 `--prepare-only` 和 `--resume` 均成功。准备产物位于 `output/sombrero-completion-prepared-v2/`，打开其中 `report.html` 可检查每个部件的画布与允许新增区域。
2026-09-20 用户运行 `output/20260918-183532/sam` 的补全任务时，head 的真实响应同时含有有效 `url` 和空字符串 `b64_json`。原解码器将空字符串误当图片，报“不支持的 PNG/JPEG/WebP 格式”。已修复为空值时使用 URL 下载，并覆盖空串、空白字符串及 null 的回归测试；22 项测试通过。
本次已从保存的 `complete/tasks/head/response.raw.json` 下载原生成结果，没有再次调用生成接口。图片保存在同级 `complete-recovered-candidates/head.png`。真实输出为 2048×2048，输入画布为 1024×1024，因此离线合并被 `CANVAS_SIZE_MISMATCH` 拒绝，报告位于 `complete-recovered-head-check/report.html`。这次格式解析问题已解决，但尺寸约束尚未通过；不能把已有 1024 输入任务的候选直接改用 `--completion-size 2048` 合并，因为新画布的像素坐标也会变化。
docs/model-stages.md
+2 -2
View File
@@ -2,7 +2,7 @@
本轮实现结构理解、图片编辑适配器、结构 JSON 校验、Alpha 几何校验、候选种子、诊断预览和实验缓存。几何层需要 Python 与 requirements.txt，不运行旧的“拆件图 → SIFT 定位”流程。
结构理解支持停在 `understand`，也可通过 `--stop-after segment` 接续本地 SAM 分割，或使用 `--stage segmentation --input-dir` 独立执行第二阶段。掩码语义修正、隐藏部件合并、Spine 骨骼导出尚未完成。图片编辑测试保存的是原始候选，不是验收通过的最终资产。
结构理解支持停在 `understand`，也可通过 `--stop-after segment` 接续本地 SAM 分割，或使用 `--stage segmentation --input-dir` 独立执行第二阶段。第三阶段使用 `--stage completion --input-dir SAM目录` 完成部件画布准备、候选生成、限制新增区域和原像素恢复，详见[第三阶段文档](3-completion-stage.md)。掩码语义修正、补全的语义验收和 Spine 骨骼导出尚未完成。旧的 `--image --prompt-file` 图片编辑探针仍只保存原始候选。
## 环境与模型
@@ -153,7 +153,7 @@ node .\tools\model-check.mjs --stage completion --image .\local-part.png --promp
同一命令增加 `--resume`，仅当上次完整结束，且模型、协议、参数、提示词、Schema、源图、适配器代码和所有产物校验一致时复用。模型变化时要求新的输出目录，防止覆盖对照组。失败任务也保留原目录，使用新目录重跑。
理解、SAM 和补全探针各自记录独立缓存。SAM 额外校验输入计划、候选提示、本地源码和权重哈希。对比补全模型时，固定相同局部画布、任务文本与掩码。
理解、SAM、部件补全和补全探针各自记录独立缓存。SAM 额外校验输入计划、候选提示、本地源码和权重哈希；部件补全校验语义计划、所有输入 mask、画布参数、源码及离线候选哈希。对比补全模型时，固定相同局部画布、任务文本与掩码。
显式 429/5xx 最多按配置重试，超时或网络断开不自动重试，因为服务端可能已经执行任务。完整请求不保证模型内容可复现；seed 只在提供方确认支持时放入 params，usage 不存在时记录 null，不估造价格或 token 数。