빠른 참조

설치

git clone https://github.com/DevDnA/slm-factory.git
cd slm-factory
./setup.sh                    # uv 설치, 의존성, Ollama 모델 준비를 한 번에 처리

사전 준비

./setup.sh가 Ollama 모델 다운로드를 자동 처리합니다. 수동으로 실행하려면 아래 명령을 사용하세요.

ollama serve           # 별도 터미널에서 실행 (백그라운드 유지)
ollama pull qwen3.5:9b   # 기본 Teacher 모델 다운로드 (최초 1회, ./setup.sh가 자동 처리)

프로젝트 시작

# 1. 프로젝트 초기화
slf init my-project

# 2. 학습할 문서 복사
cp /path/to/documents/*.pdf my-project/documents/

# 3. 환경 점검 (선택 권장)
slf check

# 4. 실행 (택 1)
slf rag                # RAG + Teacher(9B) 즉시 시작 — 문서 적을 때
slf tune               # 파인튜닝 + RAG + Student(1B) — 문서 20건+

CLI 명령어 요약

모든 명령어에 --verbose (-v) 또는 --quiet (-q) 전역 옵션을 사용할 수 있습니다.

🚀 시작하기

./setup.sh가 slf 명령어를 자동 설치합니다. 설치 후 바로 사용할 수 있습니다.

⚙️ 파이프라인

📊 평가

🔧 도구

ℹ️ 정보

각 명령어의 전체 옵션은 CLI 레퍼런스를 참조하십시오.

파이프라인 단계

slf tune 실행 시 아래 순서로 진행됩니다. 상세한 단계 설명은 사용 가이드를 참조하십시오.

1. parse (필수) — PDF/HWPX/HTML/TXT/MD/DOCX/HWP 파싱 → output/parsed_documents.json
2. chunking (선택) — 긴 문서를 청크로 분할하여 QA 생성 범위 확장
3. generate (필수) — Teacher LLM으로 QA 쌍 생성 → output/qa_alpaca.json
4. validate (필수) — 규칙 + 임베딩 기반 QA 검증 및 필터링 → qa_alpaca.json 갱신
5. score (선택) — Teacher LLM 1~5점 품질 평가 → output/qa_scored.json
6. augment (선택) — 질문 패러프레이즈 데이터 증강 → output/qa_augmented.json
7. analyze (선택) — 통계 분석 보고서 생성 → output/data_analysis.json
8. convert (필수) — 채팅 템플릿 적용 JSONL 변환 → output/training_data.jsonl
9. train (필수) — LoRA 파인튜닝 → output/checkpoints/adapter/
10. export (필수) — 모델 병합 + Ollama Modelfile 생성 → output/merged_model/
11. eval (선택) — BLEU/ROUGE 평가 → output/eval_results.json
12. refine (선택) — Iterative Refinement (약점 QA 재생성 + 재학습)
13. autorag_export (선택) — RAG 인덱싱 데이터 내보내기 → output/autorag/
14. rag_index (선택) — Qdrant 벡터 인덱싱 → output/qdrant_db/

모든 선택 단계는 기본으로 활성화됩니다. 개별 비활성화는 project.yaml에서 enabled: false로 설정합니다.

자주 쓰는 워크플로우

1. 전체 자동 실행 (tune)

설정을 직접 제어하고 싶을 때 사용합니다.

slf tune

2. 단계별 실행 (tune --until)

특정 단계까지만 실행하고 결과를 확인한 후 다음 단계로 진행합니다.

slf tune --until parse
slf tune --until generate
slf tune --until validate
slf tune --until score
slf tune --until augment
slf tune --until convert
slf tune --until train
slf tune --until export
slf tune --until eval
slf tune --until rag_index

3. 기존 데이터로 학습만 (train --data)

이미 준비된 training_data.jsonl이 있거나 하이퍼파라미터를 반복 실험할 때 사용합니다.

slf train --data ./output/training_data.jsonl

4. 중단 후 재개 (--resume)

파이프라인이 중간에 중단된 경우, 중간 저장 파일에서 자동으로 재개합니다.

slf tune --resume
slf train --resume

5. 평가 및 비교 (eval run / eval compare)

학습 완료 후 모델 성능을 측정하고 Base 모델과 비교합니다.

# BLEU/ROUGE 평가
slf eval run --model my-project-model

# Base vs Fine-tuned 비교
slf eval compare \
  --base-model gemma:2b \
  --ft my-project-model

6. 전체 파이프라인 + RAG 채팅 (tune --chat)

SLM 학습부터 RAG 인덱싱, API 서버 시작까지 한 번에 실행합니다.

slf tune --chat

서버는 foreground로 실행됩니다. Ctrl+C로 종료할 수 있습니다.

출력 파일 구조

output/
├── parsed_documents.json       # 파싱된 문서 텍스트 및 메타데이터
├── qa_alpaca.json              # Teacher LLM이 생성한 QA 쌍 (Alpaca 형식)
├── qa_scored.json              # 품질 점수 평가를 통과한 QA 쌍
├── qa_augmented.json           # 데이터 증강이 완료된 QA 쌍
├── qa_reviewed.json            # TUI 수동 리뷰를 거친 QA 쌍
├── data_analysis.json          # 카테고리 분포, 길이 통계, 품질 경고
├── eval_results.json           # BLEU/ROUGE 평가 점수
├── compare_results.json        # Base vs Fine-tuned 비교 결과
├── training_data.jsonl         # 채팅 템플릿 적용된 최종 학습 데이터
├── checkpoints/
│   └── adapter/                # LoRA 어댑터 가중치 (PEFT 형식)
│       ├── adapter_config.json
│       └── adapter_model.safetensors
├── autorag/                    # RAG 인덱싱용 데이터 (corpus.parquet, qa.parquet)
├── qdrant_db/                  # RAG 벡터 인덱스 (Qdrant)
└── merged_model/               # 병합된 최종 모델 (HuggingFace 형식)
    ├── config.json
    ├── model.safetensors
    ├── tokenizer.json
    └── Modelfile               # Ollama 배포용 파일

설정 파일 골격

project.yaml의 최소 필수 설정입니다. 나머지는 기본값으로 동작합니다.

project:
  name: "my-project"
  language: "ko"                        # "ko", "en", "ja" 등

paths:
  documents: "./documents"
  output: "./output"

teacher:
  backend: "ollama"                     # "ollama" 또는 "openai"
  model: "qwen3.5:9b"
  api_base: "http://localhost:11434"
  temperature: 0.3

student:
  model: "google/gemma-3-1b-it"

export:
  ollama:
    model_name: "my-project-model"
    system_prompt: "당신은 도메인 전문 도우미입니다."

chunking:
  enabled: true
  chunk_size: "auto"      # 또는 정수 (예: 10000)
  overlap_chars: 500

전체 설정 옵션(scoring, augment, validation, training, LoRA 등)은 설정 레퍼런스를 참조하십시오.

트러블슈팅 빠른 해결

상세 해결 방법은 사용 가이드를 참조하십시오.

관련 문서