심청이 (simcheongi) — 안내견 로봇 주행 학생 모델: 추론 · 미세조정 · LoRA 코드

이 저장소에는 공개 가중치 model.safetensors(av3u, 파라미터 105,685,969개, fp32)를 불러와서 추론, 전체/부분 미세조정, LoRA 어댑터 학습·저장·불러오기·병합을 하는 코드가 들어 있습니다. 코드는 순수 PyTorch로 동작하며 CPU(fp32)에서도 돌아갑니다. CUDA는 선택입니다.

English summary: at the end.


모델 소개

안내견 로봇(차동 구동, 최고 0.25 m/s 정도로 운용)이 실내 복도를 주행하도록 학습한 주행 계획 학생 모델입니다. 카메라 4장, 라이다, 초음파, 자기 위치 이력, 경로를 받아서 앞으로 5초 동안의 궤적 50점을 냅니다.

항목 내용
구조 ViT-S/16 영상 인코더(DINOv2 배치) → 12층 백본(SISA2 믹서 9층 + KAIROS 어텐션 3층, 폭 640) → 6층 흐름 정합(flow matching) 플래너
크기 105,685,969 파라미터, fp32 safetensors 423 MB (텐서 513개)
입력 토큰 1,395개 = 과거 프레임 3장 × 153 + 현재 프레임 880 + 라이다 36 + 초음파 2 + 자기운동 2 + 명령 8 + 경로 8
출력 (50, 3) = 로봇 기준 x(앞, m), y(왼쪽, m), 방향(rad), t0 + 0.1 … 5.0 s (10 Hz) + 불확실도 · 명령 · 이유 머리(로그용)
결정 주기 학습 때 0.5 s마다 한 번 (0.2–0.5 s 범위의 자료 포함)
모드 복도 모드(mode 0, 기본·검증됨). 차량 모드(mode 1)도 들어 있지만 이 체크포인트에서는 검증하지 않았습니다

학습 계보 (모두 같은 구조, 앞 회차 가중치에서 이어서 학습): 복도 시뮬레이터 M100 → car1(차량 모드 추가) → CTL1 → od1 · od2 · od3(장애물·사람이 있는 복도 DAgger) → av1 → av2m → av2u(서 있는 사람을 비켜 가는 전문가 라벨) → av3u(바로 옆에 선 사람 배치 추가, 3,000 단계). av3u는 2026-11-19 실제 로봇 주행(서버 GPU 추론)에 쓴 모델입니다.

학습 자료는 연구실 건물 복도를 재구성한 장면을 렌더링한 시뮬레이터 자료와 그 위의 규칙 기반 전문가 궤적입니다 (DAgger 수집). 여기에 NVIDIA PhysicalAI-Autonomous-Vehicles 데이터셋의 사람 운전 기록(차량 모드 자료)도 섞었습니다: car1에서 처음 넣었고, 그 뒤 회차들도 계속 섞었으며, 공개 회차 av3u도 차량 몫 0.1로 섞어 학습했습니다(공개 가중치는 이 회차들에서 차례로 이어 학습한 것입니다). 학습 자료와 평가 세트는 공개하지 않습니다. 가중치 이용 조건은 LICENSE_WEIGHTS.md를 보세요.


설치

검증한 환경: Python 3.12, torch 2.8.0, transformers 5.14.1, safetensors 0.8.0, numpy 2.2.6, Pillow 12.0.0.

pip install -r requirements.txt        # 또는: pip install -e .
# 선택: flash-attn 2.8.3 (CUDA bf16에서 로봇과 비트 단위로 같은 플래너 어텐션), triton (학습 가속 --sisa2k)
  • transformers는 5.14.1로 고정하세요. 백본의 Qwen3.5 층(어텐션·MLP·RMSNorm·회전 임베딩)을 transformers에서 가져와 인스턴스 단위로 고쳐 씁니다. 다른 버전에서는 깨지거나 수치가 달라질 수 있습니다.
  • Pillow 버전도 입력의 일부입니다. 영상은 Pillow BICUBIC으로 줄이는데, 다른 Pillow 버전이나 cv2·torchvision 리사이즈를 쓰면 픽셀이 달라집니다.
  • 가중치는 Hugging Face koreashin/simcheongi에서 config.json과 model.safetensors를 자동으로 받습니다 (huggingface_hub). 인터넷이 없으면 두 파일을 한 폴더에 두고 그 경로를 넘기면 됩니다.

빠른 시작

import numpy as np
from simcheongi import SimcheongiPolicy

pol = SimcheongiPolicy.from_pretrained("koreashin/simcheongi", device="cuda")   # GPU 없으면 device="cpu"

out = pol.plan(
    frames=[f_m15, f_m10, f_m05, f_now],   # RGB uint8 (720, 1280, 3) 4장: t0-1.5 / -1.0 / -0.5 / 0 s, 오래된 것부터
    lidar=lidar400,                        # (400,) m, i번 빔 = 정면에서 반시계로 i*0.9°, 0 = 반사 없음, 12 m 이내
    ego_history=poses,                     # (n, 4) 행 (t [s], x [m], y [m], yaw [rad]), 0.1 s 간격, 마지막 행 = 지금.
                                           #   주행 시작부터 전부(주행 직후가 아니면 최소 31행 = 3 s). t = 주행 시작부터 센 초처럼
                                           #   부를 때마다 늘어나는 시계 (마지막 행 = 0 인 상대 시각은 ValueError).
                                           #   yaw 는 감싼 값(-π…π)이어도 됨 (안에서 펼침)
    route=route_xy,                        # (m, 2) 같은 좌표계의 경로 폴리라인: ego_history 첫 행 자세에서
                                           #   1 m 안에서 시작해 목표까지 (전역 경로는 로봇 바로 뒤부터 잘라서)
    ultrasonic=us6,                        # (6,) m: 왼쪽, 앞왼쪽, 앞오른쪽, 오른쪽, 뒤왼쪽, 뒤오른쪽 (없으면 None = 4.0)
    session="robot1",                      # 주행마다 하나. 새 주행이면 pol.reset("robot1")
)
out.trajectory         # (50, 3) 로봇 기준 x 앞 m, y 왼쪽 m, 방향 rad — t0 + 0.1 … 5.0 s
out.trajectory_world   # (50, 3) ego_history 좌표계로 바꾼 같은 궤적
out.speed_hint         # |P(1.0 s) - P(0.1 s)| / 0.9 (로봇은 min(0.25, 이 값)을 속도로 보냈습니다)

합성 관측으로 바로 돌려 보기 (카메라 자료 필요 없음):

python examples/infer_synthetic.py                       # CPU면 결정 하나에 1.5–2초 정도
python examples/infer_synthetic.py --device cpu --model /path/to/local_dir

추론에서 꼭 알아야 할 것

  • 결정마다 표본 하나: 고정 잡음(torch.Generator 시드 42)에서 Euler 5단계로 뽑은 궤적 하나를 냅니다. 여러 표본의 평균이 아니고, 같은 입력이면 늘 같은 출력입니다.
  • 상태가 있습니다 (session별): 두 번째 라이다 회전 = 같은 세션 직전 결정의 스캔(첫 결정은 현재 스캔을 복제), 과거 프레임 특징 캐시(세션, 0.1 s 틱), 경로 진행 커서. 0.5 s마다 차례로 부르는 것이 학습과 같습니다.
  • 시각·이력·경로의 약속 (어기면 오류 없이 입력이 틀어지므로 코드가 검사합니다): ego_history의 t는 세션마다 늘어나는 시계 하나(주행 시작부터 센 초 권장, 같은 세션에서 늘지 않으면 ValueError), 이력은 31행(3 s) 이상 또는 주행 시작부터 전부(짧은데 이미 움직이고 있으면 경고), 경로는 첫 행 자세에서 1 m 안에서 시작(멀면 경고 후 가장 가까운 점에서 시작). 자세한 이유와 측정값은 docs/INFERENCE.md 2·3절.
  • 명령은 경로에서 학습 때 규칙으로 자동 계산합니다(5 s 앞 경로의 옆 벗어남 ±2 m → 좌/우, 아니면 1 m 현의 방향 오차

    20° → 좌/우). command="left" 등으로 직접 줄 수도 있고, route=None이면 학습된 '경로 없음' 토큰을 씁니다.

  • 좌표계: yaw는 로봇 몸(카메라)이 보는 방향이어야 합니다. 라이다는 로봇 중심(학습 로봇의 라이다 위치) 기준 반시계 각도로 바꿔 넣으세요(simcheongi.geometry.lidar_beams400). 학습 로봇은 라이다 0°가 정면에서 1.576° 돌아가 있어 angle_ccw = -angle_cw - 1.576으로 바꿨습니다.
  • 정밀도: CUDA는 bf16 autocast(SISA2 믹서만 fp32, TF32 끔), CPU는 전부 fp32입니다. 같은 입력에서 CPU와 GPU 궤적은 최대 약 8 mm 다릅니다(합성 관측 1개 기준). 로봇과 비트 단위로 같으려면 CUDA + bf16 + flash-attn 2.8.3이 필요합니다.
  • 속도(참고, n이 작음): H100 1결정 0.08 s(첫 호출은 워밍업 0.8 s), CPU 32스레드 1.5–2.0 s.
  • SimcheongiPolicy는 생성할 때 torch.backends TF32 설정을 끕니다(프로세스 전체에 적용).

더 자세한 입력 정의, 저수준 API(plan_request), 로봇에 붙이는 방법은 docs/INFERENCE.md에 있습니다.


미세조정

  1. 자료를 simcheongi-bc/1 형식으로 만듭니다 (docs/DATA_FORMAT.md). 결정 하나 = 학습 표본 하나, 정답 = 전문가(또는 사람) 궤적 (50, 3). 우리 내부 수집기 형식이면 tools/convert_internal.py로 바꿉니다.
  2. 학습합니다.
python train.py --data /data/my_bc --out runs/ft1 --steps 3000 --batch 32 --lr 1e-4 --warmup 100
# 여러 자료를 비율로 섞기:  --data /data/a:0.7,/data/b:0.3
# 일부 얼리기:             --freeze vit.,merger.
# 학습 가속(CUDA+triton):  --sisa2k ieee        (fp32 그대로, 아래 정밀도 설명)
  • 손실은 우리 회차 그대로입니다: 흐름 정합(x 매개화, 채널 가중 1·1·0.5) + 0.05 × 불확실도 NLL + 0.05 × 명령 CE(명령을 가린 표본만) + 0.05 × 이유 CE. 모든 항은 표본 가중치 weight로 가중 평균합니다.
  • 최적화: AdamW(0.9, 0.95), wd 0.05, ViT lr × 0.3, 워밍업 후 코사인(0.1배까지), clip 1.0, bf16, 그래디언트 체크포인트. av3u 회차 = --steps 3000 --batch 32 --lr 1e-4 --warmup 100.
  • 결과: runs/ft1/final/(config.json + model.safetensors, HF 배치와 같음) → SimcheongiPolicy.from_pretrained("runs/ft1/final"). 중간 저장 step_XXXXXX/, 이어하기 ckpt_last.pt(같은 --out으로 다시 실행), 로그 train_log.jsonl, 설정 run.json.
  • 검증 분할이 있으면 끝에 ADE/FDE(시드 42 고정 잡음, 서버와 같은 계획)를 냅니다: python eval_offline.py --data ... --model runs/ft1/final. 자료에 split이 없어 --val-frac로 나눴다면 eval_offline.py에도 같은 --val-frac와 --split-seed(둘 다 기본 0)를 주세요. 분할 시드는 학습 시드 --seed와 따로라서, --seed를 바꿔도 검증 에피소드는 그대로입니다.
  • 메모리·속도(H100, batch 32, 측정 6단계): 전체 미세조정 최대 10.7 GB·3.3 s/단계, --sisa2k ieee 9.5 GB·1.5 s/단계.

작은 확인용 실행: bash examples/finetune_tiny.sh (합성 자료 20단계).


LoRA 어댑터

기본 가중치는 그대로 두고 작은 어댑터만 학습합니다. peft 없이 이 저장소의 simcheongi/lora.py로 합니다.

# 학습 (기본: rank 16, alpha 16, 백본 'layers.' + 플래너 'planner.'의 nn.Linear 132개 + 센서 인코더 사본)
python train_lora.py --data /data/my_bc --out runs/lora1 --steps 3000 --batch 32 --lr 2e-4

# 결과 어댑터: runs/lora1/final/{adapter_model.safetensors (16.8 MB), adapter_config.json}
# 병합해서 일반 모델로 만들기
python merge_lora.py --adapter runs/lora1/final --out runs/lora1_merged
# 평가
python eval_offline.py --data /data/my_bc --adapter runs/lora1/final

파이썬에서:

from simcheongi import SimcheongiPolicy, load_model, lora, save_pretrained

model = load_model("koreashin/simcheongi")
meta = lora.attach(model, rank=16, alpha=16)          # 기본 가중치 동결, 'lora.*'만 학습
# ... 학습 (simcheongi.losses.compute_loss) ...
lora.save_adapter(model, "my_adapter")

pol = SimcheongiPolicy.from_pretrained("koreashin/simcheongi", adapter="my_adapter")   # 어댑터를 얹어 추론
lora.merge(model); save_pretrained(model, "merged")   # 또는 병합 (W += (alpha/r)·B·A)
  • 처음(B = 0)에는 어댑터를 붙인 모델의 출력이 기본 모델과 비트 단위로 같습니다 (CPU·GPU 확인).
  • 학습되는 것은 lora.*뿐이고 기본 텐서 513개는 바뀌지 않습니다 (기본 설정 학습 파라미터 4,191,472개 = LoRA 3,322,416 + 센서 인코더 사본 869,056).
  • 팁: lr 2e-4(전체 미세조정의 2배), rank 16 / alpha 16에서 시작하세요. 자료가 적으면 rank 8, 바꿀 것이 많으면 32. ViT는 기본으로 제외합니다(--lora-include layers.,planner.,vit.로 넣을 수 있음). 센서 인코더 사본이 필요 없으면 --lora-clones "". 차량 모드를 그대로 지키려면 --lora-gate corridor.
  • 주의: 합성 자료 20단계만으로도 계획이 2 m 넘게 바뀌었습니다. 작은 자료로 오래 학습하면 원래 능력을 잃기 쉽습니다.
  • 병합 차이: CPU fp32에서는 최대 0.9–1.7e-5 m, CUDA bf16에서는 bf16 반올림 때문에 최대 1.8–2.9 cm(20단계 학습한 어댑터, 합성 관측 2결정, 두 번 실행).

자세한 설명: docs/LORA.md. 작은 확인용 실행: bash examples/lora_tiny.sh.


데이터 형식 (요약)

<root>/dataset.json                         {"format": "simcheongi-bc/1", ...}
<root>/index.jsonl                          에피소드마다 {"id", "n", "split": "train" | "val"}
<root>/episodes/<id>/steps.npz              결정별 배열
<root>/episodes/<id>/frames/<tick:05d>.jpg  RGB 1280x720 프레임 (tick = 0.1 s)

steps.npz 필수 키: frame_ticks (D,4), lidar (D,400), ultra (D,6), hist_rig (D,16,6), req_history (D,16,3), req_history_velocity (D,16,2), req_history_acceleration (D,16,2), ego_velocity (D,2), ego_acceleration (D,2), route_ahead (D,41,2), route_ahead_valid (D,41), cmd (D,), plan (D,50,3) — 선택: lidar_unknown, weight, reason, reason_weight, prev, mode. 각 배열의 정의와 로봇 기록에서 만드는 방법(simcheongi.geometry)은 docs/DATA_FORMAT.md를 보세요.


한계와 주의

  • 안전 장치가 아닙니다. 로봇에서는 운전기(driver)의 자체 정지 규칙(실제 라이다·초음파 guard)이 늘 함께 돌았습니다. 이 모델의 궤적만으로 사람 곁을 주행하지 마세요.
  • 시뮬레이터로 학습했습니다. 장면은 연구실 건물 복도 재구성 렌더링, 정답은 규칙 기반 전문가입니다. 다른 건물·야외· 밤 조명·다른 카메라에서는 검증 범위가 작습니다.
  • 실제 사람의 라이다 모양에 약합니다 (2026-11-19 확인). 시뮬레이터의 사람은 꽉 찬 원판(빔 약 51개, 46°)인데 실제 사람은 다리 두 개(빔 약 25개, 40°, 틈 있음)로 보입니다. 다리 모양 사람을 넣은 시뮬레이션에서 av3u의 판단이 바뀐 비율은 0.105 ± 0.020(n=229)으로, 원판 사람일 때 0.960 ± 0.011(n=298)보다 크게 낮았습니다. 실녹화 재생(바로 옆에 선 사람)에서는 라이다에서 사람을 지워도 계획이 바뀌지 않았습니다(0/9). 즉 옆에 선 실제 사람을 라이다로 거의 피하지 못할 수 있습니다.
  • 입력 분포 차이: 로봇 주행 때 초음파 입력과 lidar_unknown은 실험실 지도에서 계산한 값이었고, 실제 라이다에서 반사가 없는 빔은 지도 값으로 채웠습니다. 지도가 없으면 lidar_unknown = 0, 초음파 = 실제 값 또는 4.0을 넣게 되므로 분포가 조금 다릅니다.
  • 차량 모드(mode 1)는 이 체크포인트에서 검증하지 않았습니다.
  • 현재 프레임은 정확히 1280x720이어야 합니다(내부에서 1280x704로 리사이즈). 줄인 영상을 넣지 마세요.
  • GPU 학습은 비트 단위로 재현되지 않습니다(SDPA flash 역전파·bicubic 보간 역전파가 비결정적). CPU에서는 재현됩니다.

파일 구성

경로 내용
simcheongi/policy.py SimcheongiPolicy (추론, 세션 상태)
simcheongi/model.py, car_mode.py, configs.py 모델 정의 (가중치를 학습한 코드와 산술이 같음; import 경로와 주석만 다름)
simcheongi/sk/ SISA2 믹서 · KAIROS 어텐션 파일 (학습 때 파일과 코드 동일; 주석의 내부 참조만 지움)
simcheongi/geometry.py, _bookkeeping.py, preprocess.py 입력 계산 (자기 이력 스플라인, 경로, 명령 규칙, 영상·라이다 전처리)
simcheongi/hub.py load_model / save_pretrained (config.json + model.safetensors)
simcheongi/data.py, losses.py, training.py 자료 형식·손실·학습 루프
simcheongi/lora.py LoRA attach / save / load / merge
simcheongi/sisa2k/ 선택: SISA2 믹서의 Triton 학습 가속 (--sisa2k ieee)
train.py, train_lora.py, merge_lora.py, eval_offline.py 명령행 도구
tools/convert_internal.py, tools/make_fake_dataset.py 자료 변환 · 합성 자료
examples/ 합성 추론, 작은 미세조정, 작은 LoRA
tests/test_package.py CPU 자체 시험 (작은 무작위 모델, 다운로드 없음)
config.json 모델 설정 (HF 저장소 루트에 model.safetensors와 나란히 둠)
LICENSE, LICENSE_WEIGHTS.md, NOTICE 코드 라이선스(Apache-2.0), 가중치 이용 조건, 제3자 고지

시험: python tests/test_package.py (CPU 1–3분). 배포 전에 우리 쪽에서 확인한 것: 이 패키지의 추론이 내부 로봇 파이프라인과 합성 관측 3개 + 로봇 입력 빌더로 만든 관측 5개에서 CPU·GPU 모두 비트 단위로 같음(최대 차이 0.0), safetensors 왕복 sha256 동일, 손실·그래디언트가 내부 학습 코드와 같음(CPU 비트 동일), 변환한 자료 항목이 내부 로더와 비트 동일.


라이선스와 고지

  • 코드: Apache License 2.0 (LICENSE). 제3자 코드 고지는 NOTICE.
  • simcheongi/_qwen_drive_helpers.py는 Qwen-Drive-1.0(Copyright 2026 Alibaba Group Holding Limited, Apache-2.0)의 일부를 줄여서 옮긴 파일입니다. 백본 층은 실행할 때 transformers(Apache-2.0)에서 가져옵니다.
  • 가중치(model.safetensors): Apache-2.0이 아닙니다. 이용 조건은 LICENSE_WEIGHTS.md에 있습니다. ViT는 학습 전에 DINOv2 ViT-S/14(Meta, Apache-2.0)로 초기화했습니다. car1부터의 계보 회차들과 공개 회차 av3u(차량 몫 0.1)가 NVIDIA PhysicalAI-Autonomous-Vehicles 데이터셋의 사람 운전 기록을 섞어 학습했으므로, 이 가중치에는 그 데이터셋 약관이 적용됩니다.

English summary

simcheongi is the driving-planner student of a guide-dog robot (indoor corridors, ~0.25 m/s). Inputs: 4 RGB frames (1280x720, t0-1.5/-1.0/-0.5/0 s), a 400-beam lidar scan, 6 ultrasonic ranges, a 10 Hz pose history and a route polyline (the navigation command is derived from the route). Output: one deterministic 5 s trajectory of 50 waypoints (x forward, y left, heading) in the robot frame, sampled from fixed seed-42 noise with 5 Euler flow-matching steps. Architecture: ViT-S/16 + a 12-layer SISA2 / KAIROS backbone + a 6-layer flow-matching planner, 105.7 M parameters. Lineage: corridor-sim M100 → car1 → CTL1 → od1-3 → av1 → av2m → av2u → av3u (released, step 3000).

from simcheongi import SimcheongiPolicy
pol = SimcheongiPolicy.from_pretrained("koreashin/simcheongi", device="cuda")   # or "cpu"
out = pol.plan(frames, lidar, ego_history, route)    # out.trajectory: (50, 3)
  • Fine-tune: python train.py --data <simcheongi-bc/1 root> --out runs/ft1 (format: docs/DATA_FORMAT.md).
  • LoRA: python train_lora.py --data ... --out runs/lora1 (rank 16 on 132 backbone/planner linears + sensor-encoder copies, bit-identical to the base at init), merge_lora.py to fold it in.
  • Pin transformers 5.14.1 and Pillow 12.0.0. CPU runs in fp32; CUDA uses bf16 autocast with fp32 SISA2 mixers, TF32 off.
  • Limitations: simulator-trained; weak response to real people's two-leg lidar signature (found 2026-11-19); not a safety system — the robot's own stop rules are required; car mode not validated.
  • Inputs contract (checked in code): ego_history time = one increasing clock per session (seconds since the drive started recommended; a clock relative to now raises), >= 31 rows (3 s) or the whole drive, route starting within 1 m of ego_history[0]; wrapped yaw is unwrapped internally.
  • Code: Apache-2.0 (see NOTICE). Weights: NOT Apache-2.0 — see LICENSE_WEIGHTS.md; the lineage from car1 on and the released round av3u (car share 0.1) mixed human-driving records of the NVIDIA PhysicalAI-Autonomous-Vehicles dataset into training, so that dataset's license applies to the weights.
Downloads last month
-
Safetensors
Model size
0.1B params
Tensor type
F32
·
Video Preview
loading