minsung
833816061b
docs: 집합 조정(M2) 보류 기록 + 반입 목록 실측 M2 는 교통시설물을 가르는 안까지 만들고 보류했다. 16장 실측으로 structure 1,079 -> utility pole 608 / streetlight pole 372 / road sign 358 / culvert 9, fence 702 -> guardrail 668 / fence 46 / roadside barrier 17 로 갈라지는 것을 확인했다 (라벨 14 -> 19종). 사용자 지시로 v4 로 되돌렸고 v5 는 보류 표시와 함께 남긴다. culvert 9개, roadside barrier 17개는 16장 기준 표본이 부족하다. 정정: "집합 없는 검출은 버려진다"는 앞선 판단은 틀렸다. merge_labels.py 의 merge_by_group 은 집합에 없는 라벨을 passthrough 로 그대로 통과시킨다. 16장 병합 결과에 orange traffic cone 114 개와 yellow safety cone 6 개가 독립 클래스로 살아 있다. [cone] 으로 묶으면 오히려 나란히 선 콘이 gap 2px 에서 한 덩어리가 되어 개수를 잃는다. envsetting.md 에 반입 목록을 실측 크기로 정리했다: git 으로 오는 것 (복사 금지) 손으로 복사할 것 체크포인트 3.3GB / BPE 1.4MB / JPEG 69장 1.2GB 복사하면 안 되는 것 venv(절대경로), output/, theater 뷰어 JPEG 55MB Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> @
244 lines
9.0 KiB
Markdown
244 lines
9.0 KiB
Markdown
# 다른 PC(RTX 4090)에 SAM 3.1 검출 환경 세우기 — 작업 지시 프롬프트
|
||
|
||
이 문서는 그대로 복사해서 새 PC 의 Claude Code(또는 사람)에게 주는 **작업 지시서**다.
|
||
아래 `---` 사이를 통째로 붙여넣으면 된다.
|
||
|
||
측정 근거: RTX 3060 12GB 에서 사진 1장 548초. 4090 24GB 추정 80~180초.
|
||
자세한 내역은 `docs/pilot/sam_merge.html` 의 단계 기록을 봐라.
|
||
|
||
---
|
||
|
||
## 지시
|
||
|
||
RTX 4090 이 달린 이 PC 에 드론 사진 SAM 3.1 검출 환경을 세워라.
|
||
목적은 사진 1장을 튜닝된 설정으로 검출해 3060 대비 실제 배속을 재는 것이다.
|
||
전체 블록 실행은 그 측정 뒤에 결정한다.
|
||
|
||
### 전제
|
||
|
||
- OS: Windows (원래 환경과 같음). Linux 면 경로 구분자만 바꿔라.
|
||
- GPU: RTX 4090 24GB. `nvidia-smi` 로 드라이버가 올라와 있는지 먼저 확인해라.
|
||
|
||
### 반입 목록 (실측 크기)
|
||
|
||
**git 으로 오는 것 — 복사하지 마라**
|
||
|
||
| 경로 | 리포 |
|
||
|---|---|
|
||
| `prompts/discovery_v4.txt` (94개 프롬프트) | railway-client, `sam31-coverage-tuning` 브랜치 |
|
||
| `prompts/wide_v1.txt` | 〃 |
|
||
| `configs/merge_groups_v4.txt` (현재 활성 집합 정의) | 〃 |
|
||
| `tools/*.py` 전부 | 〃 |
|
||
| `sam3/` 패키지 | sam31server |
|
||
| `configs/auto_labeling/segment_anything_3.yaml` | 〃 |
|
||
|
||
`merge_groups_v5.txt` 도 리포에 있지만 **보류 상태다. 쓰지 마라.** 활성은 v4 다.
|
||
|
||
**손으로 복사해야 하는 것 — git 에 없다**
|
||
|
||
| 항목 | 실측 크기 | 원본 위치 | 왜 git 에 없나 |
|
||
|---|---|---|---|
|
||
| SAM3.1 체크포인트 | **3.3 GB** | `C:\Users\<사용자>\.cache\huggingface\hub\models--facebook--sam3.1\` | `.gitignore` 가 `*.pt` 제외 |
|
||
| BPE 사전 `bpe_simple_vocab_16e6.txt.gz` | 1.4 MB | `sam31server\bpe_simple_vocab_16e6.txt.gz` | `.gitignore` 가 `*.gz` 제외 |
|
||
| 원본 JPEG `stage_BlockYYX\` 69장 | **1.2 GB** | `railway-client\output\sam3\stage_BlockYYX\` | `.gitignore:42` 가 `output/` 제외 |
|
||
|
||
체크포인트는 복사 대신 HuggingFace 에서 새로 받아도 된다
|
||
(`huggingface-cli download facebook/sam3.1`). 회선이 느리면 복사가 빠르다.
|
||
|
||
**복사하면 안 되는 것**
|
||
|
||
| 항목 | 이유 |
|
||
|---|---|
|
||
| `.venv\` | 절대경로가 박혀 있어 다른 PC 에서 깨진다. 새로 만들어라 |
|
||
| `output\` 의 나머지 (`tune_t64` 등) | 이쪽 PC 의 산출물이다. 4090 은 새로 만든다 |
|
||
| `docs\pilot\theater*\` | 뷰어 JPEG 55MB. `make_viewer.py` 로 다시 굽는다 |
|
||
|
||
### 1. 리포 2개 clone
|
||
|
||
두 리포를 **형제 폴더로** 두어라. `sam3_multi_prompt.py` 가 기본값으로
|
||
`../sam31server` 를 찾는다 (환경변수 `SAM31SERVER_DIR` 로 바꿀 수 있다).
|
||
|
||
```
|
||
D:\MYCLAUDE_PROJECT\
|
||
├── railway-client\
|
||
└── sam31server\
|
||
```
|
||
|
||
```bash
|
||
git clone https://gitea.hmac.kr/kimminsung/railway-client.git
|
||
git clone https://gitea.hmac.kr/kimminsung/sam31server.git
|
||
|
||
cd railway-client
|
||
git checkout sam31-coverage-tuning
|
||
```
|
||
|
||
**브랜치 체크아웃을 빠뜨리지 마라.** `main` 에는 튜닝된 프롬프트
|
||
(`prompts/discovery_v4.txt`)와 집합 정의(`configs/merge_groups_v4.txt`),
|
||
그리고 `--wide-in-tiles` 플래그가 없다.
|
||
|
||
`sam31server` 는 FastAPI 서버지만 **서버를 띄울 필요는 없다.**
|
||
검출 스크립트는 그 안의 `sam3` 패키지를 `sys.path` 로 직접 import 한다
|
||
(`tools/sam3_multi_prompt.py:28-33`). `app/` 은 안 쓴다.
|
||
|
||
### 2. Python 환경
|
||
|
||
venv 를 **복사하지 마라.** 절대경로가 박혀 있어 깨진다. 새로 만들어라.
|
||
|
||
원본 환경 (참고용, 실측):
|
||
- Python 3.12.8
|
||
- torch 2.10.0+cu126 (CUDA 12.6)
|
||
|
||
```bash
|
||
cd sam31server
|
||
python -m venv .venv
|
||
.venv\Scripts\activate
|
||
|
||
# torch 는 CUDA 버전에 맞춰 먼저 설치해라 (requirements.txt 의 torch>=2.4.0 보다 우선)
|
||
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126
|
||
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
`sam3` 는 pip 설치 대상이 아니다 (site-packages 에 없고 .pth 도 없다).
|
||
폴더가 있으면 된다. 의존성만 깔면 끝이다.
|
||
|
||
설치 확인:
|
||
```bash
|
||
.venv\Scripts\python.exe -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"
|
||
```
|
||
`True` 와 `NVIDIA GeForce RTX 4090` 이 나와야 한다.
|
||
|
||
### 3. 체크포인트 + BPE 사전 (git 에 없음, 실측 3.3GB + 1.4MB)
|
||
|
||
`.gitignore` 가 `*.pt`, `*.gz` 를 뺀다.
|
||
|
||
필요한 것:
|
||
- `sam3.1_multiplex.pt` — HuggingFace `facebook/sam3.1` (캐시 폴더 전체 3.3GB)
|
||
- `bpe_simple_vocab_16e6.txt.gz` (1.4MB)
|
||
|
||
받는 방법 둘 중 하나:
|
||
1. HuggingFace 에서 새로 받는다 (`huggingface-cli download facebook/sam3.1`)
|
||
2. 소스 PC 의 HF 캐시를 복사한다
|
||
(`C:\Users\<사용자>\.cache\huggingface\hub\models--facebook--sam3.1\...`)
|
||
|
||
경로 지정은 셋 중 하나 (앞이 우선):
|
||
1. CLI 인자 `--checkpoint` / `--bpe`
|
||
2. 환경변수 `SAM3_CHECKPOINT` / `SAM3_BPE`
|
||
3. `sam31server/configs/auto_labeling/segment_anything_3.yaml` 의
|
||
`params.model_path` / `params.bpe_path`
|
||
|
||
3번 파일에는 **원래 PC 의 절대경로가 적혀 있다.** 그대로 쓰면 파일을 못 찾는다.
|
||
환경변수로 덮거나 이 파일을 고쳐라.
|
||
|
||
### 4. 원본 사진 (git 에 없음, 실측 1.2GB)
|
||
|
||
`.gitignore:42` 가 `output/` 을 통째로 뺀다.
|
||
|
||
소스 PC 에서 복사해라:
|
||
```
|
||
railway-client/output/sam3/stage_BlockYYX/ JPEG 69장, 장당 14~23MB
|
||
```
|
||
SMB 공유, rsync, 외장 디스크 아무거나. 방법은 상관없다.
|
||
|
||
### 5. 시험 실행 — 사진 1장
|
||
|
||
```bash
|
||
set SAM31SERVER_DIR=D:\MYCLAUDE_PROJECT\sam31server
|
||
set SAM3_CHECKPOINT=<체크포인트 절대경로>
|
||
set SAM3_BPE=<BPE 절대경로>
|
||
|
||
cd D:\MYCLAUDE_PROJECT\railway-client
|
||
|
||
..\sam31server\.venv\Scripts\python.exe tools\sam3_multi_prompt.py ^
|
||
--input output\sam3\stage_BlockYYX\DJI_20250805165516_0654.JPG ^
|
||
--output output\sam3\gpu4090_test\DJI_20250805165516_0654_multi.json ^
|
||
--prompts prompts\discovery_v4.txt ^
|
||
--wide-prompts prompts\wide_v1.txt --wide-in-tiles ^
|
||
--cols 6 --rows 4 --conf 0.10 --merge ^
|
||
--batch 32
|
||
```
|
||
|
||
`--batch 32` 는 24GB 라서 가능하다. 3060 은 VRAM 때문에 16 이 한계였다.
|
||
OOM 이 나면 24 → 16 으로 낮춰라.
|
||
|
||
**비교 기준 (3060 실측, 같은 사진 0654):**
|
||
|
||
| 구간 | 3060 |
|
||
|---|---|
|
||
| 타일 패스 (24타일 × 6청크 = 144 forward) | 410초 |
|
||
| 통짜 패스 | 43초 |
|
||
| 모델 로딩 + NMS + 병합 + 저장 | 약 105초 |
|
||
| **합계** | **466~662초 (10장 평균 548초)** |
|
||
|
||
로그에 찍히는 `전체 1장 완료 — N초` 와 타일별 시간을 그대로 보고해라.
|
||
|
||
### 6. 결과 검증
|
||
|
||
무라벨(미검출) 지표를 재라. GPU 불필요:
|
||
|
||
```bash
|
||
python tools\coverage_stats.py ^
|
||
--run-dir output\sam3\gpu4090_test ^
|
||
--groups configs\merge_groups_v4.txt ^
|
||
--size 8192,5460
|
||
```
|
||
|
||
0654 는 3060 에서 **무라벨 5.0%** 가 나왔다. 4090 에서도 5% 근처여야 한다.
|
||
GPU 아키텍처가 달라 비트 단위로 같지는 않지만 소수점 아래에서만 달라야 한다.
|
||
**1%p 넘게 벌어지면 설정이 다른 것이니 멈추고 보고해라.**
|
||
|
||
### 7. 전체 블록 실행 (측정 뒤 지시 받고 할 것)
|
||
|
||
`--input` 을 **폴더**로, `--outdir` 로 주면 모델을 한 번만 로딩한다.
|
||
장별로 프로세스를 새로 띄우면 사진마다 60~90초를 로딩에 버린다.
|
||
|
||
```bash
|
||
..\sam31server\.venv\Scripts\python.exe tools\sam3_multi_prompt.py ^
|
||
--input output\sam3\stage_BlockYYX --outdir output\sam3\YYX_v4 ^
|
||
--prompts prompts\discovery_v4.txt ^
|
||
--wide-prompts prompts\wide_v1.txt --wide-in-tiles ^
|
||
--cols 6 --rows 4 --conf 0.10 --merge --batch 32
|
||
```
|
||
|
||
끝나면 집합 병합:
|
||
```bash
|
||
python tools\merge_labels.py --json <각 _multi.json> --groups configs\merge_groups_v4.txt --gap 2
|
||
```
|
||
|
||
### 8. 결과 회수
|
||
|
||
산출 JSON 만 가져오면 된다 — 장당 2~5MB, 69장 약 300MB.
|
||
집계·병합·뷰어 생성은 GPU 없이 원래 PC 에서 돌린다.
|
||
|
||
### 하지 말 것
|
||
|
||
- venv 복사 (절대경로 깨짐)
|
||
- `main` 브랜치로 실행 (튜닝 설정 없음)
|
||
- FastAPI 서버 기동 (이 작업에 불필요)
|
||
- 설정값 임의 변경. `--cols 6 --rows 4 --conf 0.10 --wide-in-tiles` 넷이
|
||
무라벨 16% → 3.6% 를 만든 조합이다. 하나라도 바꾸면 품질이 달라진다.
|
||
- 측정 안 한 수치 보고. 추정이면 추정이라고 써라.
|
||
|
||
---
|
||
|
||
## 부록: 이 설정이 나온 근거
|
||
|
||
BlockYYX 사진 8~16장 실측. 지표는 "무라벨 화면%" — 마스크 합집합으로 재서
|
||
겹침을 뺀 값이다.
|
||
|
||
| 단계 | 0654 | 0006 |
|
||
|---|---|---|
|
||
| 기준선 (conf 0.25, 타일 4×3, 통짜 분리) | 52.1% | 19.4% |
|
||
| `--wide-in-tiles` | 15.4% | 12.2% |
|
||
| 경계 띠 프롬프트 +5 (v3) | 14.9% | 11.9% |
|
||
| conf 0.25 → 0.10 | 9.5% | 5.8% |
|
||
| 프롬프트 +4 (v4) | 9.6% | 5.7% |
|
||
| 타일 4×3 → 6×4 | **5.0%** | **5.0%** |
|
||
|
||
기여도: 통짜→타일 −36.7pp · conf −5.4pp · 타일 세분화 −4.6pp ·
|
||
프롬프트 추가 −0.5pp. **프롬프트 추가는 거의 기여하지 않았다.**
|
||
|
||
원인은 통짜(1×1) 패스였다. `wide_v1.txt` 의 21개 프롬프트는 8192×5460 을
|
||
한 장으로 넣어 대상 하나에 인스턴스가 하나만 살아남았다 — 도로는 한쪽 차로만,
|
||
논은 한 필지만 잡혔다.
|