railway-client/docs/envsetting.md

다른 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\

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)

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 도 없다). 폴더가 있으면 된다. 의존성만 깔면 끝이다.

설치 확인:

.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장

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 불필요:

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초를 로딩에 버린다.

..\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

끝나면 집합 병합:

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 을 한 장으로 넣어 대상 하나에 인스턴스가 하나만 살아남았다 — 도로는 한쪽 차로만, 논은 한 필지만 잡혔다.