carbix-v3

한국어 공과금 고지서(전기·가스·운송)에서 구조화 필드를 뽑아내는 VLM. Qwen/Qwen3-VL-4B-Instruct 를 LoRA SFT 로 파인튜닝한 뒤 병합하고 GGUF q8_0 으로 양자화했다. carbix-engine 의 로컬 추론 백엔드로 쓴다.

파일

파일	크기	용도
carbix-v3-q8.gguf	4.28 GB	서빙 가중치 (llama.cpp)
carbix-v3-mmproj.gguf	836 MB	비전 인코더(멀티모달 프로젝터) — 없으면 이미지 입력 불가
lora_adapter_v3/	144 MB	PEFT 어댑터 원본. 재병합·재학습용
test.jsonl	2.4 MB	평가셋 657건 + 학습에 실제로 쓴 프롬프트 (--prompt-from 용)

lora_adapter_v3/ 는 최종 산출물(adapter_model.safetensors)만 담았다. 학습 중간 체크포인트 3개(checkpoint-2750/3000/3125, 각 379MB, 옵티마이저 상태 포함)는 용량 대비 실익이 없어 제외했다. 최종 스텝은 checkpoint-3125 로 총 3,125 스텝이다.

실행

llama-server \
  -m carbix-v3-q8.gguf \
  --mmproj carbix-v3-mmproj.gguf \
  --host 127.0.0.1 --port 8001 \
  -ngl 99 -c 8192 --parallel 2 \
  --image-min-tokens 1024 \
  --jinja

OpenAI 호환 API 로 뜬다. carbix-engine 에서는:

python eval/predict_one.py --image bill.jpg --category gas \
  --base-url http://127.0.0.1:8001 --prompt-from test.jsonl

• -ngl 99 전체 레이어 GPU 오프로드. q8_0 + mmproj 는 L4 24GB 에 병렬 슬롯을 여러 개 띄워도 여유롭다.
• --image-min-tokens 1024 Qwen-VL 계열은 이미지 토큰이 1024 미만이면 정확도가 떨어진다는 llama.cpp 자체 경고를 반영한 값.
• --jinja 병합 모델의 chat_template.jinja 를 쓴다.

학습

항목	값
베이스	Qwen/Qwen3-VL-4B-Instruct
방법	LoRA SFT (transformers + peft 순정, train/train_hf.py)
LoRA	r=16, alpha=32, dropout=0.05, bias=none
target_modules	q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj
학습 파라미터	33,030,144 / 4,470,845,952 (0.74%)
옵티마이저	adamw_torch, lr 2e-4, cosine, warmup 5%, weight_decay 0.01
배치	1 × grad_accum 4 = effective 4
에폭	1 (12,500건 → 3,125 스텝)
정밀도	bf16, gradient checkpointing, 비전 타워 동결 안 함
하드웨어	GCP L4 24GB (g2-standard-4)
이미지 해상도	shortest_edge=784, longest_edge=1003520
peft	0.20.0

LoRA 값(r/alpha/dropout/target_modules)은 동봉한 lora_adapter_v3/adapter_config.json 실측이다. carbix-engine 의 train/train_hf.py 독스트링에는 alpha=16 이라고 적혀 있으나 낡은 기술이다 — argparse 기본값과 실제 학습 로그 모두 alpha=32 다.

데이터

carbix-augmentation 파이프라인이 생성한 합성 고지서. 실제 고객 문서는 쓰지 않았다.

	학습 12,500	검증 1,388 (실제 사용 300)
가스	10,681	1,207
운송	916	84
전기	903	97

성능

합성 테스트셋 (657건, test.jsonl)

모델	overall	평균 지연	에러
carbix-v3 GGUF q8_0 (llama.cpp)	99.43%	3.23s	0
carbix-v3 어댑터 직접 로드 (bf16, transformers)	98.68%	11.95s	0

재현

# 어댑터 → 병합 모델
CARBIX_MODEL_DIR=~/Projects/carbix-model python train/merge_lora.py

# 병합 모델 → GGUF + mmproj
python llama.cpp/convert_hf_to_gguf.py <merged_model> --outtype q8_0

라이선스

베이스 모델 Qwen/Qwen3-VL-4B-Instruct 의 라이선스를 따른다. (배포 전 확인 필요)