第二步SAM模型接入
This commit is contained in:
Ukawka
@@ -363,8 +363,8 @@ POST /v1/responses
|
||||
= 可信的像素 mask + 透明拆件 + 隐藏区域补全 + 最终骨骼
|
||||
~~~
|
||||
|
||||
下一阶段应读取 <code>semantic-parts.json</code> 和 <code>segmentation-prompts.json</code>，仅使用 status=candidate 的语义、粗框和程序候选点。模型原始正负点不传给 SAM。候选始终 semantic_verified=false：框内可能混有多个部件，未来仍需要 mask 语义选择、越出角色 Alpha 比例等 QA。
|
||||
已实现的[第二阶段](2-segmentation-stage.md)读取 <code>source.png</code>、<code>semantic-parts.json</code> 和 <code>segmentation-prompts.json</code>，仅处理 status=candidate 的可见部件。SAM 图像概念接口接收文本和框；程序候选点参与返回 mask 的排序，不作为点提示传入此接口。模型原始正负点不传给 SAM。候选始终 semantic_verified=false：框内可能混有多个部件，Alpha、重叠和连通域检查不能替代语义复核。
|
||||
|
||||
已有 v1 结果可以通过 <code>--parts-file 旧计划.json --reference 原图.png --out-dir 新目录</code> 离线迁移与校验，不请求模型。迁移按 ID 推断骨骼/附件类型，袖子优先绑定同侧上臂，面部绑定头部；部分可见部件开启遮挡补全，骨骼连接处保守建议延展。这些推断在 notes 标注为待复核，不替代模型或人工判断。输入计划哈希和所有新产物参与 resume 校验。
|
||||
|
||||
<code>manifest.json</code> 当前只记录 SAM checkpoint 是否存在，<code>runtime_status</code> 仍为 <code>not_integrated</code>，不会加载权重或占用 GPU。
|
||||
第一阶段 <code>manifest.json</code> 只记录 SAM 路径信息，<code>runtime_status=local_subprocess_not_probed</code>，第一阶段不加载 SAM。第二阶段单独探测 Conda/CUDA、严格加载本地权重，并在自己的 manifest 中记录运行环境、权重哈希及子进程退出状态。
|
||||
|
||||
@@ -0,0 +1,108 @@
|
||||
# 第二阶段：本地 SAM 分割
|
||||
|
||||
本阶段读取第一阶段的语义计划，使用本地 SAM 3.1 图像检测分支生成部件 mask，从原图提取可见像素，并输出两张预览图。Python 固定使用 `ai-spine` Conda 环境，遵守 [AGENTS.md](../AGENTS.md)。
|
||||
|
||||
## 运行方式
|
||||
|
||||
在 `AI_spine` 目录执行：
|
||||
|
||||
```powershell
|
||||
conda run --no-capture-output -n ai-spine node .\tools\model-check.mjs `
|
||||
--stage segmentation `
|
||||
--input-dir .\output\sombrero-grounding-v2 `
|
||||
--out-dir .\output\sombrero-sam-local `
|
||||
--sam-dir F:/Study/SAM3
|
||||
```
|
||||
|
||||
输出目录必须是新目录。相同输入、代码、权重、参数及完整产物可加 `--resume` 复用；失败结果保留，另建目录重跑。独立分割不调用视觉 LLM 或图片编辑接口，不需要 API Key。
|
||||
|
||||
输入目录必须包含：
|
||||
|
||||
| 文件 | 要求 |
|
||||
| --- | --- |
|
||||
| `source.png` | 第一阶段预处理后的原尺寸 RGBA |
|
||||
| `semantic-parts.json` | 通过结构校验的 v2 语义计划 |
|
||||
| `segmentation-prompts.json` | 与计划 ID、画布匹配的程序候选提示 |
|
||||
|
||||
仅 `status=candidate` 的可见部件进入推理。hidden/blocked 记入跳过列表；无可用 SAM mask 的部件记录失败原因，不用矩形或候选点伪造分割。
|
||||
|
||||
可以在命令末尾加 `--dry-run` 检查代码路径、权重存在性、Conda、依赖导入和 CUDA；它不加载权重，因此不验证权重内容或完整推理显存需求。
|
||||
|
||||
如需从第一阶段接续运行，在原结构理解命令中使用 `--stop-after segment --sam-dir F:/Study/SAM3`。第二阶段输出到理解目录下的 `segmentation/`。原理解命令仍可能请求付费模型；已有计划优先使用上面的独立命令。
|
||||
|
||||
## 环境与权重
|
||||
|
||||
本机已经验证：Python 3.11、PyTorch `2.7.1+cu126`、torchvision `0.22.1+cu126`、NumPy `1.26.4`、OpenCV `4.11.0.86`、Windows Triton `3.3.1.post21`，GPU 为 RTX 3060 Laptop 6 GB。
|
||||
|
||||
环境补全命令见 [README](../README.md#python-与外部项目)，依赖记录在 [requirements.txt](../requirements.txt)。程序不会自动安装依赖、创建环境或切换到 CPU。
|
||||
|
||||
默认布局：
|
||||
|
||||
```text
|
||||
F:/Study/SAM3/
|
||||
sam3/ 源码仓库
|
||||
sam3/model_builder.py
|
||||
sam3.1checkpoint/
|
||||
sam3.1_multiplex.pt
|
||||
```
|
||||
|
||||
路径优先级为 CLI 覆盖、环境变量、配置默认值。`SAM_MODEL_DIR` 指定根目录，`SAM_CODE_DIR` 可单独指定源码仓库。若 `.env` 中仍是旧路径，修改为上述路径或显式传入 CLI 参数。
|
||||
|
||||
| 参数 | 含义 |
|
||||
| --- | --- |
|
||||
| `--sam-dir` | SAM 根目录 |
|
||||
| `--sam-code-dir` | 源码仓库目录，内部应包含 `sam3/model_builder.py` |
|
||||
| `--sam-checkpoint` | 本地权重文件 |
|
||||
| `--sam-confidence` | SAM 候选分数阈值，默认 0.2，不是语义正确率 |
|
||||
| `--sam-precision` | 默认 bf16 自动混合精度；可设 fp32，可能需要更多显存 |
|
||||
|
||||
Node 先启动环境探测子进程，再启动一次推理子进程。模型只加载到后者；没有监听端口或常驻服务，正常结束、报错、超时或收到取消信号后退出。推理超时为 20 分钟。禁用 Hugging Face 在线下载，权重只能来自本地。
|
||||
|
||||
`sam_runtime.py` 从 multiplex checkpoint 提取 `detector.*`。SAM 3.1 的检测分支有三个特征尺度；图像 builder 的第四尺度原本会被 scalp 丢弃，因此适配器移除该未使用尺度并取消 scalp。忽略视频交互/传播 neck，随后 `strict=True` 加载所有实际使用参数；结构不匹配会报错。未修改外部 SAM 源码。
|
||||
|
||||
保留 FP32 参数和复数位置编码缓冲区，仅在推理上下文开启 BF16 autocast。不能直接把整个模型转换为 BF16，这会破坏复数缓冲区及上游要求 FP32 的解码器路径。
|
||||
|
||||
## 提示、选择与质量检查
|
||||
|
||||
1. 在白色背景上合成参考图，保持原尺寸；GPU 只编码一次图像。
|
||||
2. 每个部件先用语义文本推理，再加入归一化粗框推理，保留两组候选。
|
||||
3. 根据模型分数、粗框内比例、越出角色 Alpha 的比例及候选点命中情况排序。拒绝前景不足 4 像素或框内比例低于 10% 的结果。
|
||||
4. 最终 mask 与原图 Alpha 前景取交集，从原图提取 RGB 和 Alpha，不重绘、不缩放。原始选中 mask 另存用于检查越界。
|
||||
5. 记录漏分、重叠、碎片化、候选点未覆盖，以及不同部件 mask IoU ≥ 0.8 的疑似重复。
|
||||
|
||||
当前使用的 SAM 图像概念接口接受文本与框，不接受点。第一阶段的 Alpha 候选点仅用于 mask 排序；模型原始点仍只用于第一阶段诊断。这次 mask 来自真实 GPU 模型推理。
|
||||
|
||||
粗框、候选点及模型分数都不能保证部件语义正确。因此所有结果保持 `quality_status=needs_review`、`semantic_verified=false`。重叠 mask 保留，未强行分配成互斥部件，也未补全遮挡纹理。人工复核通过后才能继续补全或导出。
|
||||
|
||||
## 输出
|
||||
|
||||
| 文件 | 内容 |
|
||||
| --- | --- |
|
||||
| `annotated.png` | 原尺寸角色图，各候选部件用不同半透明颜色叠加，透明背景显示为白色 |
|
||||
| `parts-sheet.png` | 白底拆解图，部件保持原尺寸、分开排布，并标注 ID 和颜色 |
|
||||
| `parts/<id>.png` | 紧裁剪的 RGBA 部件，保留原图像素及 Alpha |
|
||||
| `masks/<id>.png` | 原图尺寸黑白 mask，已裁掉 Alpha 背景 |
|
||||
| `candidates/<id>-raw.png` | 选中的 SAM 原始 mask，裁掉背景前 |
|
||||
| `unassigned-mask.png` | 白色表示没有被任何部件 mask 覆盖的角色像素 |
|
||||
| `overlap-mask.png` | 白色表示被多个部件 mask 覆盖的像素 |
|
||||
| `segmentation.json` | 裁剪坐标、拆解图坐标、颜色、质量指标、运行环境和模型加载信息 |
|
||||
| `candidate-diagnostics.json` | 两种提示的候选分数、排序、拒绝原因及最终选择 |
|
||||
| `report.html` | 两张预览、部件链接、告警、漏分及重复检查 |
|
||||
| `worker.log` / `worker-error.json` | 子进程日志 / 失败诊断（发生错误时） |
|
||||
| `manifest.json` | 状态、输入/代码/权重/产物哈希，完成时记录子进程已退出 |
|
||||
|
||||
`crop_xyxy` 使用原图坐标，右下角为开区间；`sheet_xyxy` 使用白底拆解图坐标。覆盖率是像素覆盖比例，不是准确率。
|
||||
|
||||
## 代码与验证记录
|
||||
|
||||
- [stages/segmentation-stage.mjs](../stages/segmentation-stage.mjs)：输入校验、Conda 子进程、哈希、缓存、日志和失败处理。
|
||||
- [sam_runtime.py](../sam_runtime.py)：环境探测和本地权重严格加载。
|
||||
- [sam_segment.py](../sam_segment.py)：GPU 推理、两组候选选择和诊断。
|
||||
- [segmentation_outputs.py](../segmentation_outputs.py)：mask QA、原像素拆件、两张预览和报告。
|
||||
- [tests/test_segmentation.py](../tests/test_segmentation.py)：Alpha 越界、候选选择、提示完整性、像素保真和重叠/重复检查。
|
||||
|
||||
2026-09-18 实测 `output/sombrero-grounding-v2` → `output/sombrero-sam31-v3`：28 个部件返回 mask，严格加载 1130 个检测参数/缓冲张量；推理及渲染约 11.64 秒（不含环境探测和加载权重），PyTorch 峰值已分配显存约 4.97 GiB，结束后无 SAM 子进程。
|
||||
|
||||
这组结果覆盖原图前景约 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` 哈希校验复用通过。测试通过仅验证程序行为，不表示上述分割质量合格。
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
本轮实现结构理解、图片编辑适配器、结构 JSON 校验、Alpha 几何校验、候选种子、诊断预览和实验缓存。几何层需要 Python 与 requirements.txt，不运行旧的“拆件图 → SIFT 定位”流程。
|
||||
|
||||
结构理解当前停在 `understand`；SAM 分割、掩码修正、隐藏部件合并、Spine 骨骼导出是后续阶段。图片编辑测试保存的是原始候选，不是验收通过的最终资产。
|
||||
结构理解支持停在 `understand`，也可通过 `--stop-after segment` 接续本地 SAM 分割，或使用 `--stage segmentation --input-dir` 独立执行第二阶段。掩码语义修正、隐藏部件合并、Spine 骨骼导出尚未完成。图片编辑测试保存的是原始候选，不是验收通过的最终资产。
|
||||
|
||||
## 环境与模型
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
```dotenv
|
||||
SPINE_UNDERSTANDING_MODEL=gpt-6-astra
|
||||
SPINE_COMPLETION_MODEL=qwen-image-3.0
|
||||
SAM_MODEL_DIR=F:/Study/sam3.1
|
||||
SAM_MODEL_DIR=F:/Study/SAM3
|
||||
```
|
||||
|
||||
不配置这三项时，`configs/astra-qwen.json` 已提供相同默认值。不会自动改写用户的 `.env`。
|
||||
@@ -153,13 +153,13 @@ node .\tools\model-check.mjs --stage completion --image .\local-part.png --promp
|
||||
|
||||
同一命令增加 `--resume`，仅当上次完整结束，且模型、协议、参数、提示词、Schema、源图、适配器代码和所有产物校验一致时复用。模型变化时要求新的输出目录，防止覆盖对照组。失败任务也保留原目录，使用新目录重跑。
|
||||
|
||||
本轮实现单阶段缓存；跨 SAM/补全/导出的依赖缓存留到后续阶段接入。对比补全模型时，固定相同局部画布、任务文本与掩码。
|
||||
理解、SAM 和补全探针各自记录独立缓存。SAM 额外校验输入计划、候选提示、本地源码和权重哈希。对比补全模型时，固定相同局部画布、任务文本与掩码。
|
||||
|
||||
显式 429/5xx 最多按配置重试，超时或网络断开不自动重试，因为服务端可能已经执行任务。完整请求不保证模型内容可复现；seed 只在提供方确认支持时放入 params，usage 不存在时记录 null，不估造价格或 token 数。
|
||||
|
||||
## SAM 路径
|
||||
|
||||
默认 `F:/Study/sam3.1`，检查 `sam3.1_multiplex.pt` 是否存在。该目录 README 明确说明它仅提供 checkpoint，不是可直接调用的推理服务。本轮仅记录路径和 checkpoint 存在性，状态为 `not_integrated`，不加载权重、不占用 GPU。
|
||||
默认根目录 `F:/Study/SAM3`：源码位于 `sam3/`，权重位于 `sam3.1checkpoint/sam3.1_multiplex.pt`。可通过 `--sam-dir`、`--sam-code-dir`、`--sam-checkpoint` 覆盖。独立分割无需中转站凭据，在 `ai-spine` Conda 临时子进程加载 GPU 模型，结束即退出。命令、权重适配及当前质量限制见[第二阶段文档](2-segmentation-stage.md)。
|
||||
|
||||
## 测试
|
||||
|
||||
|
||||
Reference in New Issue
Block a user