CLI 명령어 레퍼런스
slm-factory의 모든 명령어와 옵션을 정리한 공식 레퍼런스입니다.
전역 옵션
모든 명령어 앞에 사용할 수 있는 옵션입니다.
slf [전역 옵션] <명령어> [옵션]
| 플래그 | 단축키 | 설명 |
|---|---|---|
--verbose |
-v |
DEBUG 레벨 로그를 출력합니다. 문제 진단 시 사용합니다. |
--quiet |
-q |
WARNING 이상의 로그만 출력합니다. 스크립트 자동화에 적합합니다. |
--version |
-V |
버전을 표시합니다. |
--help |
도움말을 출력합니다. | |
--install-completion |
현재 셸에 자동완성을 설치합니다. | |
--show-completion |
자동완성 스크립트를 출력합니다. |
--verbose와 --quiet를 동시에 지정하면 --verbose가 우선 적용됩니다.
명령어 목록
| 명령어 | 그룹 | 설명 |
|---|---|---|
init |
🚀 시작하기 | 새 프로젝트 디렉토리와 설정 파일을 생성합니다 |
check |
🚀 시작하기 | 설정 파일, 문서 디렉토리, Ollama 연결을 사전 점검합니다 |
rag |
🚀 시작하기 | RAG 웹 채팅 서비스 시작 (인덱스 자동 구축) |
tune |
⚙️ 파이프라인 | 전체 파이프라인 또는 지정 단계까지 실행합니다 |
train |
⚙️ 파이프라인 | LoRA 파인튜닝을 실행합니다 |
export |
⚙️ 파이프라인 | 훈련된 어댑터를 병합하고 Ollama Modelfile을 생성합니다 |
eval run |
📊 평가 | 학습된 모델을 BLEU/ROUGE 메트릭으로 평가합니다 |
eval compare |
📊 평가 | Base 모델과 Fine-tuned 모델의 답변을 나란히 비교합니다 |
tool review |
🔧 도구 | QA 쌍을 TUI에서 수동으로 승인/거부/편집합니다 |
tool convert |
🔧 도구 | QA 데이터를 훈련용 JSONL 형식으로 변환합니다 |
tool update |
🔧 도구 | 변경된 문서만 감지하여 증분 처리합니다 |
tool evolve |
🔧 도구 | 자동 진화 (증분→학습→품질게이트→배포) |
tool compare-data |
🔧 도구 | 두 QA 데이터셋의 품질 비교 |
tool export-autorag |
🔧 도구 | RAG 인덱싱용 데이터 내보내기 |
tool rag-index |
🔧 도구 | corpus.parquet을 Qdrant에 임베딩 적재 |
tool rag-serve |
🔧 도구 | RAG API 서버 시작 (Qdrant 검색 + Ollama 생성) |
tool eval-retrieval |
🔧 도구 | RAG 검색 품질 평가 (Hit Rate, MRR, Recall@K) |
status |
ℹ️ 정보 | 각 파이프라인 단계의 진행 상태를 표시합니다 |
clean |
ℹ️ 정보 | 중간 생성 파일을 정리합니다 |
version |
ℹ️ 정보 | slm-factory 버전을 출력합니다 |
🚀 시작하기
init
새로운 slm-factory 프로젝트를 초기화합니다. 프로젝트 디렉토리, documents/, output/ 하위 디렉토리, 기본 project.yaml 설정 파일을 생성합니다.
사용법
slf init <name> [OPTIONS]
인수
| 인수 | 필수 여부 | 설명 |
|---|---|---|
name |
필수 | 생성할 프로젝트 이름. 디렉토리명과 설정 파일의 project.name에 사용됩니다. |
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--path |
TEXT |
. |
프로젝트를 생성할 상위 디렉토리입니다. |
예시
# 현재 디렉토리에 my-project 생성
slf init my-project
# 특정 경로에 생성
slf init policy-assistant --path /workspace/projects
출력
✓ 프로젝트 'my-project'가 생성되었습니다: ./my-project
프로젝트 구조:
./my-project/
./my-project/documents/
./my-project/output/
./my-project/project.yaml
다음 단계:
1. ./my-project/documents 디렉토리에 학습할 문서(PDF, TXT 등)를 추가하세요
실행 (택 1):
slf rag RAG 채팅 즉시 시작 (30초)
slf tune 파인튜닝 + RAG + 채팅 (30분)
참고
- 지정 경로에
project.yaml이 이미 존재하면 덮어쓰기 여부를 확인하는 프롬프트가 표시됩니다. - 생성된
project.yaml의project.name과export.ollama.model_name에name인수가 자동으로 반영됩니다. - 설정 파일의 모든 옵션은 설정 레퍼런스를 참조하십시오.
check
프로젝트 설정과 실행 환경을 사전 점검합니다. 파이프라인 실행 전에 실행하여 문제를 미리 확인하십시오.
사용법
slf check [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. |
점검 항목
| 항목 | 설명 |
|---|---|
| 설정 파일 | project.yaml 로드 및 Pydantic 스키마 검증 |
| 문서 디렉토리 | paths.documents 디렉토리 존재 여부 및 파일 유무 확인 |
| 출력 디렉토리 | paths.output 디렉토리 쓰기 권한 확인 |
| Ollama 연결 | teacher.backend == "ollama"일 때 서버 연결 상태 확인 |
| 모델 사용 가능 | teacher.model이 Ollama에 다운로드되어 있는지 확인 |
| 학생 모델 | student.model이 HuggingFace Hub에서 접근 가능한지 확인 (게이트 모델인 경우 로그인 필요 안내) |
| 컴퓨팅 디바이스 | GPU(CUDA/MPS) 또는 CPU 감지. GPU 미사용 시 경고 |
| 학습 정밀도 | bfloat16/float16/float32 지원 여부 확인 |
| 4bit 양자화 | CUDA 환경에서 bitsandbytes 설치 여부 확인 (MPS는 N/A) |
종료 코드
| 코드 | 의미 |
|---|---|
0 |
모든 항목 통과 |
1 |
하나 이상의 항목 실패 또는 경고 |
예시
slf check --config my-project/project.yaml
출력 예시 (전체 통과)
slm-factory 환경 점검
┌────────────────┬────────┬────────────────────────────────┐
│ 항목 │ 상태 │ 상세 │
├────────────────┼────────┼────────────────────────────────┤
│ 설정 파일 │ OK │ ./my-project/project.yaml │
│ 문서 디렉토리 │ OK │ 3개 파일 (./documents) │
│ 출력 디렉토리 │ OK │ 쓰기 가능 (./output) │
│ Ollama 연결 │ OK │ v0.3.12 (http://localhost:11434)│
│ 모델 사용 가능 │ OK │ qwen3.5:9b │
│ 학생 모델 │ OK │ google/gemma-3-1b-it │
│ 컴퓨팅 디바이스│ NVIDIA GPU (CUDA) │ NVIDIA RTX 4090 │
│ 학습 정밀도 │ OK │ bfloat16 (bf16) │
│ 4bit 양자화 │ OK │ 사용 가능 │
└────────────────┴────────┴────────────────────────────────┘
모든 점검 통과!
rag
RAG 웹 채팅 서비스를 시작합니다. Qdrant 인덱스가 없으면 문서를 파싱하고 자동으로 구축합니다. 파인튜닝된 Student 모델이 Ollama에 등록되어 있으면 자동으로 해당 모델을 사용하고, 없으면 Teacher 모델(기본값: qwen3.5:9b)로 폴백합니다.
사용법
slf rag [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--chat/--no-chat |
BOOL |
True |
RAG 인덱스 구축 후 웹 채팅 서비스를 자동으로 시작합니다. --no-chat으로 인덱스 구축만 수행합니다. |
동작 방식
- 모델 자동 선택: ①
rag.ollama_model설정값 → ② Ollama에 등록된 파인튜닝 모델(export.ollama.model_name) → ③ Teacher 모델(teacher.model) 순으로 사용합니다. - Qdrant 인덱스(
output/qdrant_db/)가 이미 존재하면 즉시 서버를 시작합니다. - 인덱스가 없으면 문서 파싱 → RAG 데이터 내보내기 → Qdrant 인덱싱을 자동으로 수행한 후 서버를 시작합니다.
--no-chat사용 시 인덱스 구축만 수행하고 서버를 시작하지 않습니다.
예시
# 기본 실행 (인덱스 자동 구축 + 서버 시작)
slf rag
# 인덱스 구축만 수행 (서버 미시작)
slf rag --no-chat
# 특정 설정 파일 사용
slf rag --config my-project/project.yaml
--host와--port옵션이 필요한 경우slf tool rag-serve를 사용하십시오.
⚙️ 파이프라인
tune
문서 파싱부터 모델 배포까지 전체 파이프라인을 실행합니다. --until 옵션으로 특정 단계까지만 실행하고 중단할 수 있습니다.
사용법
slf tune [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--resume |
-r |
FLAG |
False |
중간 저장 파일에서 재개합니다. |
--chat/--no-chat |
BOOL |
True |
파이프라인 완료 후 RAG 웹 채팅 서비스를 자동으로 시작합니다. --no-chat으로 비활성화합니다. 서버는 foreground로 실행되며, Ctrl+C로 종료합니다. |
|
--from |
ENUM |
None |
지정된 단계부터 실행을 재개합니다. 이전 단계의 출력 파일이 필요합니다. | |
--until |
ENUM |
None |
지정된 단계까지만 실행합니다. 생략하면 전체 파이프라인을 실행합니다. |
**--until 단계 값**
PipelineStep 열거형 값을 사용합니다. 각 단계는 이전 단계의 출력을 입력으로 받습니다.
| 값 | 필수/선택 | 설명 | 생성 파일 |
|---|---|---|---|
parse |
필수 | 문서를 파싱하여 텍스트와 표를 추출합니다 | output/parsed_documents.json |
generate |
필수 | Teacher LLM으로 QA 쌍을 생성합니다 | output/qa_alpaca.json |
validate |
필수 | 규칙 기반 및 임베딩 기반으로 QA 쌍을 검증합니다 | output/qa_alpaca.json (갱신) |
score |
선택 | Teacher LLM이 QA 쌍을 1~5점으로 평가하고 저품질을 제거합니다 | output/qa_scored.json |
augment |
선택 | 질문을 다양한 표현으로 변형하여 데이터를 증강합니다 | output/qa_augmented.json |
analyze |
선택 | 카테고리 분포, 길이 통계 등 데이터 분석 보고서를 생성합니다 | output/data_analysis.json |
convert |
필수 | 채팅 템플릿 적용 JSONL 변환 | output/training_data.jsonl |
train |
필수 | LoRA 파인튜닝 | output/checkpoints/adapter/ |
export |
필수 | 모델 병합 + Ollama Modelfile 생성 | output/merged_model/ |
eval |
기본 활성 | BLEU/ROUGE 평가 | output/eval_results.json |
autorag_export |
기본 활성 | RAG 인덱싱 데이터 내보내기 | output/autorag/ |
rag_index |
기본 활성 | Qdrant 벡터 인덱싱 | output/qdrant_db/ |
--until을 생략하면 위 전체 12단계를 순서대로 실행합니다. 각 단계는 해당 설정의 enabled 값에 따라 실행 여부가 결정됩니다. Iterative Refinement(refine)는 --until로 지정할 수 없으며, pipeline.run() 내부에서 eval 단계 이후 refinement.enabled 설정에 따라 자동 실행됩니다.
**--resume 동작 방식**
출력 디렉토리에서 가장 최근 중간 저장 파일을 탐색하여 해당 단계부터 재개합니다.
| 발견된 파일 | 재개 단계 |
|---|---|
qa_augmented.json |
analyze부터 |
qa_scored.json |
augment부터 |
qa_alpaca.json |
validate부터 |
parsed_documents.json |
generate부터 |
| 없음 | 처음부터 |
예시
# 전체 파이프라인 실행
slf tune
# 문서 파싱만 실행
slf tune --until parse
# QA 생성까지 실행
slf tune --until generate
# 검증까지 실행
slf tune --until validate
# 품질 평가까지 실행
slf tune --until score
# 중단된 지점에서 재개
slf tune --resume
# 특정 단계까지 재개하며 실행
slf tune --until augment --resume
# 전체 파이프라인 + RAG 서버 자동 시작
slf tune --chat
# RAG 인덱싱까지 실행 (서빙은 별도)
slf tune --until rag_index
# 평가까지만 실행
slf tune --until eval
출력 예시 (전체 파이프라인)
slm-factory — 전체 파이프라인 시작 중...
✓ 5개 문서 파싱 완료
✓ 150개 QA 쌍 생성 완료
✓ 검증 완료: 132개 수락, 18개 거부
✓ 점수 평가: 120개 통과, 12개 제거
✓ 데이터 증강: 120개 → 360개
✓ 360개 QA 쌍 분석 완료
파이프라인 완료! 모델 저장 위치: ./my-project/output/merged_model
train
LoRA 파인튜닝을 실행합니다. --data로 기존 학습 데이터를 직접 지정하거나, 생략하면 파싱부터 변환까지 전체 전처리를 자동으로 실행합니다.
사용법
slf train [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--data |
TEXT |
None |
사전 생성된 training_data.jsonl 파일 경로입니다. 지정하면 전처리 단계를 건너뜁니다. |
|
--resume |
-r |
FLAG |
False |
중간 저장 파일에서 재개합니다. |
동작 방식
--data지정: 해당 JSONL 파일로 바로 학습을 시작합니다.--resume지정 (data 없음): 중간 저장 파일을 탐색하여 해당 단계부터 전처리를 재개한 뒤 학습합니다.- 옵션 없음: 파싱부터 변환까지 전체 전처리를 실행한 뒤 학습합니다.
예시
# 전체 전처리 후 학습
slf train
# 기존 학습 데이터로 학습만 실행
slf train --data ./my-project/output/training_data.jsonl
# 외부에서 준비한 데이터로 학습
slf train --data ./custom_data.jsonl
# 중단된 전처리부터 재개하여 학습
slf train --resume
출력
훈련 완료! 어댑터 저장 위치: ./my-project/output/checkpoints/adapter
참고
- 학습 하이퍼파라미터(
num_epochs,batch_size,learning_rate등)는project.yaml의training섹션에서 설정합니다. 설정 레퍼런스를 참조하십시오. - GPU 메모리 부족 시 해결 방법은 사용 가이드를 참조하십시오.
export
훈련된 LoRA 어댑터를 기본 모델에 병합하고 Ollama Modelfile을 생성합니다. 파이프라인 전체를 재실행하지 않고 내보내기만 단독으로 수행합니다.
사용법
slf export [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--adapter |
TEXT |
None |
어댑터 디렉토리 경로입니다. 미지정 시 output/checkpoints/adapter/를 사용합니다. |
예시
# 기본 어댑터 경로로 내보내기
slf export
# 특정 어댑터 경로 지정
slf export --adapter ./my-project/output/checkpoints/adapter
출력
내보내기 완료! 모델 저장 위치: ./my-project/output/merged_model
생성 파일:
output/merged_model/— HuggingFace 형식의 병합된 모델output/merged_model/Modelfile— Ollama 배포용 Modelfile
참고
- Ollama 배포 설정(
model_name,system_prompt등)은project.yaml의export.ollama섹션에서 설정합니다. 설정 레퍼런스를 참조하십시오.
📊 평가
eval run
학습된 모델을 QA 데이터로 평가합니다. BLEU와 ROUGE 메트릭을 계산하여 결과를 저장합니다.
사용법
slf eval run [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--model |
TEXT |
필수 | 평가할 Ollama 모델 이름입니다. | |
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--data |
TEXT |
None |
QA 데이터 파일 경로입니다. 미지정 시 출력 디렉토리에서 자동 감지합니다. |
--data 미지정 시 자동 감지 우선순위: qa_augmented.json → qa_scored.json → qa_alpaca.json
예시
# 기본 설정으로 평가
slf eval run --model my-project-model
# 특정 QA 데이터로 평가
slf eval run --model my-project-model --data ./my-project/output/qa_alpaca.json
출력
터미널에 BLEU/ROUGE 점수 요약을 출력하고, output/eval_results.json에 상세 결과를 저장합니다.
평가 완료! 결과: ./my-project/output/eval_results.json (50건)
참고
- 평가 대상 모델은 Ollama에 등록된 모델이어야 합니다.
ollama list로 확인하십시오. - 평가 설정(
output_file등)은project.yaml의eval섹션에서 설정합니다. 설정 레퍼런스를 참조하십시오.
eval compare
Base 모델과 Fine-tuned 모델의 답변을 동일한 질문으로 비교합니다. 파인튜닝 전후의 성능 차이를 확인할 때 사용합니다.
사용법
slf eval compare [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--base-model |
TEXT |
필수 | 비교 기준 모델 이름 (Ollama)입니다. | |
--ft |
TEXT |
필수 | 파인튜닝된 모델 이름 (Ollama)입니다. | |
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--data |
TEXT |
None |
QA 데이터 파일 경로입니다. 미지정 시 출력 디렉토리에서 자동 감지합니다. |
--data 미지정 시 자동 감지 우선순위: qa_augmented.json → qa_scored.json → qa_alpaca.json
예시
# Base 모델과 파인튜닝 모델 비교
slf eval compare \
--base-model gemma:2b \
--ft my-project-model
# 특정 QA 데이터로 비교
slf eval compare \
--base-model gemma:2b \
--ft my-project-model \
--data ./my-project/output/qa_alpaca.json
출력
터미널에 비교 요약을 출력하고, output/compare_results.json에 각 질문별 두 모델의 답변을 저장합니다.
비교 완료! 결과: ./my-project/output/compare_results.json (50건)
🔧 도구
tool review
생성된 QA 쌍을 TUI(텍스트 기반 UI)에서 하나씩 확인하며 승인, 거부, 편집합니다. 데이터 품질을 수동으로 관리할 때 사용합니다.
사용법
slf tool review [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--data |
TEXT |
None |
QA 데이터 파일 경로입니다. 미지정 시 출력 디렉토리에서 자동 감지합니다. |
--data 미지정 시 자동 감지 우선순위: qa_reviewed.json → qa_augmented.json → qa_scored.json → qa_alpaca.json
예시
# 자동 감지된 QA 데이터로 리뷰 시작
slf tool review
# 특정 파일로 리뷰 시작
slf tool review --data ./my-project/output/qa_alpaca.json
출력
TUI 종료 후 리뷰 결과를 출력합니다.
리뷰 완료! 승인: 98, 거부: 12, 대기: 5
생성 파일: output/qa_reviewed.json (승인된 QA 쌍만 포함)
tool convert
QA 데이터를 Student 모델의 채팅 템플릿이 적용된 훈련용 JSONL 형식으로 변환합니다. 파이프라인 전체를 재실행하지 않고 변환만 단독으로 수행합니다.
사용법
slf tool convert [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--data |
TEXT |
None |
QA 데이터 파일 경로 (qa_alpaca.json 또는 qa_augmented.json). 미지정 시 자동 감지합니다. |
**--data 미지정 시 자동 감지 우선순위**
출력 디렉토리에서 다음 순서로 파일을 탐색합니다.
qa_augmented.jsonqa_scored.jsonqa_alpaca.json
예시
# 자동 감지된 QA 데이터로 변환
slf tool convert
# 특정 파일로 변환
slf tool convert --data ./my-project/output/qa_augmented.json
출력
변환 완료! 훈련 데이터: ./my-project/output/training_data.jsonl (360개 쌍)
생성 파일: output/training_data.jsonl
tool evolve
문서 변경을 감지하고 증분 처리한 뒤, 자동으로 재학습 및 배포하는 통합 명령어입니다. 품질 게이트를 통과한 경우에만 새 모델을 배포하며, 진화 히스토리를 기록합니다.
사용법
slf tool evolve [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--force-update |
FLAG |
False |
변경 감지를 건너뛰고 모든 문서를 처리합니다. | |
--skip-gate |
FLAG |
False |
품질 게이트를 건너뛰고 무조건 배포합니다. |
5단계 진화 흐름
| # | 단계 | 설명 |
|---|---|---|
| 1 | 증분 업데이트 | 문서 변경을 감지하고 새 QA를 생성하여 기존 QA와 병합합니다 |
| 2 | 검증/점수/증강 | 병합된 QA를 검증하고, 선택적으로 점수 평가 및 데이터 증강을 실행합니다 |
| 3 | 학습/내보내기 | 전처리된 데이터로 LoRA 파인튜닝을 실행하고 모델을 병합합니다 |
| 4 | 품질 게이트 | 새 모델을 이전 모델과 비교하여 개선 여부를 판단합니다 (설정 가능) |
| 5 | 정리/완료 | 배포 성공 시 히스토리를 기록하고 이전 버전을 관리합니다 |
예시
# 기본 진화 (변경 감지 + 품질 게이트 적용)
slf tool evolve
# 모든 문서 재처리 (변경 감지 건너뜀)
slf tool evolve --force-update
# 품질 게이트 건너뜀 (무조건 배포)
slf tool evolve --skip-gate
# 모든 옵션 적용
slf tool evolve --force-update --skip-gate
출력 예시 (성공)
진화 시작: my-project
[1/5] 증분 업데이트
변경 문서: 2개 감지
새 QA: 40개 생성
전체 QA: 190개 (전략: append)
[2/5] 검증/점수/증강
검증: 190개 → 185개 (5개 거부)
점수 평가: 185개 → 175개 (10개 제거)
데이터 증강: 175개 → 525개
[3/5] 학습/내보내기
학습 완료: 20 에포크 (early stopping)
모델 병합 완료
[4/5] 품질 게이트
이전 모델: rougeL=0.45
새 모델: rougeL=0.48
개선율: +6.7% ✓ 통과
[5/5] 정리/완료
배포 완료: v20250220
이전 버전 보관: v20250219, v20250218, v20250217
히스토리 저장: evolve_history.json
진화 완료! 새 모델: my-project-model (v20250220)
출력 예시 (품질 게이트 실패)
[4/5] 품질 게이트
이전 모델: rougeL=0.45
새 모델: rougeL=0.44
개선율: -2.2% ✗ 실패
배포 취소됨. 이전 모델 유지: my-project-model (v20250219)
참고
- 진화 명령은
tool update+tune --until analyze+train+export+eval compare+ 버전 관리를 자동으로 수행합니다. - 품질 게이트 설정(
quality_gate,gate_metric,gate_min_improvement)은project.yaml의evolve섹션에서 설정합니다. 설정 레퍼런스를 참조하십시오. - 진화 히스토리는
evolve_history.json에 기록되며, 각 진화 단계의 메트릭과 타임스탬프를 포함합니다. --force-update사용 시 모든 문서를 재처리하므로 처리 시간이 증가합니다.--skip-gate사용 시 품질 검증 없이 배포되므로 신중하게 사용하십시오.- 품질 게이트 실패 시 새로 생성된 Ollama 모델은 자동으로 삭제(
ollama rm)되며 이전 모델이 유지됩니다.
tool compare-data
두 QA 데이터셋의 품질을 나란히 비교합니다. 파이프라인 설정 변경(청킹 활성화, 재생성 적용 등) 전후의 QA 품질 변화를 수치로 확인할 때 사용합니다.
사용법
slf tool compare-data [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--baseline |
-b |
TEXT |
필수 | 기준 QA 데이터 파일 경로입니다. |
--target |
-t |
TEXT |
필수 | 비교 대상 QA 데이터 파일 경로입니다. |
비교 항목
| 항목 | 설명 |
|---|---|
| 전체 QA 쌍 | 총 QA 수 비교 (증감 표시) |
| 원본/증강 QA 쌍 | 원본과 증강 QA 비율 변화 |
| 문서 소스 수 | QA가 생성된 문서 수 비교 |
| 답변 길이 통계 | 평균/최소/최대 답변 길이 변화 |
| 카테고리 분포 | 카테고리별 QA 수 비교 |
예시
# 청킹 전후 QA 품질 비교
slf tool compare-data \
--baseline ./output/qa_alpaca_before.json \
--target ./output/qa_alpaca.json
# 재생성 적용 전후 비교
slf tool compare-data \
-b ./output/qa_scored_v1.json \
-t ./output/qa_scored_v2.json
출력
Rich 테이블로 기본 통계, 답변 길이 변화, 카테고리 분포를 보여줍니다. 개선된 항목은 초록색, 악화된 항목은 빨간색으로 표시됩니다.
tool export-autorag
slm-factory의 파싱·QA 데이터를 RAG 인덱싱용 parquet 형식으로 내보냅니다. parsed_documents.json에서 문서 청크를 생성하고, QA 파일에서 평가 데이터를 추출하여 corpus.parquet과 qa.parquet을 생성합니다.
사용법
slf tool export-autorag [OPTIONS]
옵션
| 플래그 | 타입 | 기본값 | 설명 |
|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. |
--qa-file |
TEXT |
(자동 감지) | QA 데이터 파일 경로입니다. 지정하지 않으면 qa_scored.json → qa_validated.json → qa_alpaca.json 순서로 자동 탐색합니다. |
예시
# 기본 실행 (QA 파일 자동 탐색)
slf tool export-autorag
# QA 파일 직접 지정
slf tool export-autorag \
--qa-file ./output/qa_scored.json
출력
output/autorag/
├── corpus.parquet # 문서 청크 (검색 코퍼스)
└── qa.parquet # QA 평가 데이터
참고
corpus.parquet은parsed_documents.json의 텍스트를autorag_export.chunk_size단위로 분할하여 생성합니다. 청크 간 중첩은autorag_export.overlap_chars로 설정합니다.qa.parquet은 QA 쌍의 질문·답변·컨텍스트를 parquet 형식으로 변환합니다.- 상세 설정은 설정 레퍼런스의
autorag_export섹션을 참조하십시오.
tool rag-index
corpus.parquet을 sentence-transformers 모델로 임베딩한 뒤 Qdrant에 적재합니다. tool export-autorag로 생성한 코퍼스 데이터를 벡터 검색이 가능한 형태로 변환합니다.
사용법
slf tool rag-index [OPTIONS]
옵션
| 플래그 | 타입 | 기본값 | 설명 |
|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. |
--corpus-dir |
TEXT |
(자동 감지) | corpus.parquet이 있는 디렉토리 경로입니다. 기본값은 output/autorag입니다. |
예시
# 기본 실행
slf tool rag-index
# 코퍼스 디렉토리 직접 지정
slf tool rag-index --corpus-dir ./output/autorag
출력
Qdrant가 output/qdrant_db/에 생성됩니다. 임베딩 모델과 벡터DB 경로는 project.yaml의 rag 섹션에서 설정합니다.
참고
- 사전 조건:
tool export-autorag로corpus.parquet을 먼저 생성해야 합니다. - 임베딩 모델 기본값은
Qwen/Qwen3-Embedding-0.6B입니다. 비대칭 인코딩(prompt_name="query")으로 한국어 문서에 우수한 성능을 보입니다. uv sync --extra rag --extra validation으로 의존성을 설치하세요.- 기존 컬렉션에 재실행하면 upsert(갱신/추가)됩니다.
tool rag-serve
Qdrant 벡터 검색과 Ollama SLM 생성을 결합한 RAG API 서버를 실행합니다. tool rag-index로 구축한 벡터 DB에서 관련 문서를 검색하고, SLM이 문서 기반 답변을 생성합니다.
서버는 foreground로 실행됩니다.
Ctrl+C로 종료할 수 있습니다.
사용법
slf tool rag-serve [OPTIONS]
옵션
| 플래그 | 타입 | 기본값 | 설명 |
|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. |
--host |
TEXT |
(설정 파일 값) | 서버 바인드 호스트입니다. |
--port |
INT |
(설정 파일 값) | 서버 포트입니다. |
예시
# 기본 실행
slf tool rag-serve
# 포트 지정
slf tool rag-serve --port 9000
API 엔드포인트
| 메서드 | 경로 | 설명 |
|---|---|---|
POST |
/v1/query |
질의 → 문서 검색 → SLM 답변 생성 (stream: true로 SSE 스트리밍 가능) |
POST |
/v1/stream |
웹 채팅 UI 전용 SSE 스트리밍 엔드포인트 |
GET |
/chat |
내장 웹 채팅 UI (HTML 페이지) |
GET |
/health |
/health/ready의 별칭 — Qdrant 및 Ollama 연결 상태 확인 |
GET |
/health/ready |
Qdrant 및 Ollama 연결 상태 확인 (로드밸런서 헬스체크용) |
GET |
/health/live |
라이브니스 체크 — 서버 실행 중이면 항상 200 응답 |
API 호출 예시
# 일반 응답
curl -X POST http://localhost:8000/v1/query \
-H "Content-Type: application/json" \
-d '{"query": "도메인 질문", "top_k": 5}'
# SSE 스트리밍 응답 (토큰 단위 실시간 전송)
curl -N -X POST http://localhost:8000/v1/query \
-H "Content-Type: application/json" \
-d '{"query": "도메인 질문", "stream": true}'
응답 형식
{
"answer": "문서 기반 답변...",
"sources": [
{"content": "관련 문서 청크...", "doc_id": "...", "score": 0.85}
],
"query": "도메인 질문"
}
SSE 스트리밍 응답 형식 ("stream": true 요청 시)
data: {"token": "문서"}
data: {"token": " 기반"}
data: {"token": " 답변..."}
data: {"sources": [...], "query": "도메인 질문", "done": true}
참고
- 사전 조건:
tool rag-index로 Qdrant를 먼저 구축해야 합니다. - Ollama가 실행 중이어야 합니다 (
ollama serve). - SLM 모델은
rag.ollama_model또는export.ollama.model_name에서 결정됩니다. uv sync --extra rag --extra validation으로 의존성을 설치하세요.
tool eval-retrieval
RAG 검색 품질을 평가합니다. qa.parquet의 질문으로 Qdrant를 검색하고, 검색된 결과가 원본 문서를 얼마나 정확하게 찾아내는지 Hit@1, Hit@K, MRR(Mean Reciprocal Rank), Recall@K 메트릭으로 측정합니다.
사용법
slf tool eval-retrieval [OPTIONS]
옵션
| 플래그 | 타입 | 기본값 | 설명 |
|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. |
--top-k |
INT |
5 |
검색 결과 상위 K개를 평가 기준으로 사용합니다. |
--qa-file |
TEXT |
(자동 감지) | qa.parquet 파일 경로입니다. 미지정 시 output/autorag/qa.parquet을 자동으로 사용합니다. |
예시
# 기본 실행 (qa.parquet 자동 감지)
slf tool eval-retrieval
# 상위 10개 결과로 평가
slf tool eval-retrieval --top-k 10
# QA 파일 직접 지정
slf tool eval-retrieval --qa-file ./output/autorag/qa.parquet
참고
- 사전 조건:
tool export-autorag로qa.parquet을 생성하고,tool rag-index로 Qdrant를 구축해야 합니다. slf rag실행 시qa.parquet이 존재하면 자동으로 검색 평가를 수행하고 결과를 출력합니다.
tool update
문서 디렉토리를 스캔하여 변경된 파일만 감지하고, 새 QA를 생성하여 기존 QA와 병합합니다. 문서를 추가하거나 수정했을 때 전체 파이프라인을 재실행하지 않고 증분 처리할 수 있습니다.
사용법
slf tool update [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. |
동작 방식
IncrementalTracker가 각 문서 파일의 해시값을 계산합니다.- 이전 실행 시 저장된 해시값과 비교하여 변경된 파일을 감지합니다.
- 변경된 파일만 파싱하고 QA를 생성합니다.
project.yaml의incremental.merge_strategy설정에 따라 기존qa_alpaca.json과 병합합니다.
예시
# 변경된 문서만 증분 처리
slf tool update
출력
증분 업데이트: 2개 변경 문서 감지
증분 업데이트 완료! 변경 문서: 2개, 새 QA: 40개, 전체 QA: 190개 (전략: append)
변경된 문서가 없으면 "변경된 문서가 없습니다" 메시지를 출력하고 종료합니다.
참고
- 병합 전략(
merge_strategy)은project.yaml의incremental섹션에서 설정합니다. 설정 레퍼런스를 참조하십시오.
ℹ️ 정보
status
파이프라인 각 단계의 진행 상태를 확인합니다. 출력 디렉토리의 파일 존재 여부와 항목 수를 테이블로 표시합니다.
사용법
slf status [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. |
예시
slf status
출력 예시
파이프라인 진행 상태
┌──────────┬──────────────────────────┬────────┬──────────────┐
│ 단계 │ 파일 │ 상태 │ 건수 │
├──────────┼──────────────────────────┼────────┼──────────────┤
│ parse │ parsed_documents.json │ 존재 │ 5개 문서 │
│ generate │ qa_alpaca.json │ 존재 │ 150개 쌍 │
│ score │ qa_scored.json │ 없음 │ - │
│ augment │ qa_augmented.json │ 없음 │ - │
│ analyze │ data_analysis.json │ 없음 │ - │
│ convert │ training_data.jsonl │ 없음 │ - │
│ train │ checkpoints/adapter/ │ 없음 │ - │
│ export │ merged_model/ │ 없음 │ - │
└──────────┴──────────────────────────┴────────┴──────────────┘
다음 --resume 실행 시 validate부터 재개됩니다
모든 단계가 완료된 경우 "모든 단계가 완료되었습니다" 메시지를 출력합니다.
clean
출력 디렉토리의 중간 생성 파일을 정리합니다. 삭제 전 확인 프롬프트가 표시됩니다.
사용법
slf clean [OPTIONS]
옵션
| 플래그 | 단축키 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
--config |
TEXT |
project.yaml |
프로젝트 설정 파일 경로입니다. 현재 디렉토리부터 상위까지 자동 탐색합니다. | |
--all |
FLAG |
False |
출력 디렉토리의 모든 파일을 삭제합니다. | |
--yes |
-y |
bool |
false |
확인 없이 삭제합니다 |
**기본 동작 vs --all 동작**
| 동작 | 삭제 대상 |
|---|---|
기본 (--all 없음) |
qa_scored.json, qa_augmented.json, data_analysis.json |
--all |
출력 디렉토리(output/)의 모든 파일과 디렉토리 |
예시
# 중간 파일만 정리
slf clean
# 모든 출력 파일 정리 (학습 결과 포함)
slf clean --all
출력
삭제 대상:
./my-project/output/qa_scored.json
./my-project/output/qa_augmented.json
./my-project/output/data_analysis.json
삭제하시겠습니까? [y/N]:
삭제 결과
┌──────────────────────────────────┬────────┐
│ 파일 │ 상태 │
├──────────────────────────────────┼────────┤
│ ./my-project/output/qa_scored... │ 삭제됨 │
│ ... │ 삭제됨 │
└──────────────────────────────────┴────────┘
3개 항목 삭제 완료
version
slm-factory의 현재 버전을 출력합니다.
사용법
slf version
출력
slm-factory 0.1.0
출력 파일 구조
파이프라인 실행 후 output/ 디렉토리에 생성되는 파일 목록입니다.
output/
├── parsed_documents.json # parse 단계 출력
├── qa_alpaca.json # generate + validate 단계 출력
├── qa_scored.json # score 단계 출력 (선택)
├── qa_augmented.json # augment 단계 출력 (선택)
├── qa_reviewed.json # tool review 출력 (선택)
├── data_analysis.json # analyze 단계 출력 (선택)
├── eval_results.json # eval run 출력 (선택)
├── compare_results.json # eval compare 출력 (선택)
├── training_data.jsonl # convert 단계 출력
├── checkpoints/
│ └── adapter/ # train 단계 출력
│ ├── adapter_config.json
│ ├── adapter_model.safetensors
│ └── ...
├── autorag/ # tool export-autorag 출력 (선택)
│ ├── corpus.parquet # 문서 청크 (검색 코퍼스)
│ └── qa.parquet # QA 평가 데이터
├── qdrant_db/ # rag_index 단계 출력 (선택)
│ └── ... # Qdrant 벡터 인덱스
└── merged_model/ # export 단계 출력
├── config.json
├── model.safetensors
├── tokenizer.json
├── tokenizer_config.json
└── Modelfile
파일별 설명
| 파일 | 생성 명령 | 설명 |
|---|---|---|
parsed_documents.json |
tune --until parse |
원본 문서에서 추출한 텍스트, 표, 메타데이터입니다. --resume 시 파싱 단계를 건너뜁니다. |
qa_alpaca.json |
tune --until generate |
Teacher LLM이 생성한 QA 쌍입니다. Alpaca 형식(instruction, input, output)으로 저장됩니다. |
qa_scored.json |
tune --until score |
품질 점수 평가를 통과한 QA 쌍입니다. --resume 시 augment부터 재개합니다. |
qa_augmented.json |
tune --until augment |
데이터 증강이 완료된 QA 쌍입니다. --resume 시 analyze부터 재개합니다. |
qa_reviewed.json |
tool review |
TUI에서 수동 리뷰를 거친 QA 쌍입니다. 승인된 항목만 포함됩니다. |
data_analysis.json |
tune --until analyze |
카테고리 분포, 길이 통계, 데이터 품질 경고를 포함한 분석 보고서입니다. |
eval_results.json |
eval run |
BLEU/ROUGE 메트릭별 점수와 평균 점수를 포함한 평가 결과입니다. |
compare_results.json |
eval compare |
각 질문에 대한 Base 모델과 Fine-tuned 모델의 답변을 나란히 기록한 비교 결과입니다. |
training_data.jsonl |
tool convert |
Student 모델의 채팅 템플릿이 적용된 학습 데이터입니다. 각 줄은 {"text": "..."} 형식입니다. |
checkpoints/adapter/ |
train |
PEFT 형식의 LoRA 어댑터 가중치입니다. export 명령으로 기본 모델과 병합합니다. |
autorag/ |
tool export-autorag |
RAG 인덱싱용 parquet 데이터. corpus.parquet(문서 청크)과 qa.parquet(QA 평가 데이터)을 포함합니다. |
qdrant_db/ |
tool rag-index |
Qdrant 벡터 인덱스입니다. tool rag-serve가 이 디렉토리를 참조하여 유사도 검색을 수행합니다. |
merged_model/ |
export |
LoRA 어댑터가 병합된 최종 모델입니다. Modelfile로 Ollama에 즉시 배포할 수 있습니다. |