spinxxxx/git-issues-priority-ko

Issue Priority Predictor (Korean)

커밋/이슈의 우선순위를 자동으로 예측하는 한국어/영어 지원 모델

Model Details

이 모델은 GitHub 커밋 텍스트를 기반으로 우선순위 점수(priority score)를 예측하는 다국어 모델입니다.

distilbert-base-multilingual-cased를 기반으로 하여, 한국어와 영어로 작성된 커밋 데이터를 사용해 파인튜닝되었습니다.

모델은 입력 텍스트에 대해 0~1 범위의 연속적인 점수를 출력하며, 점수가 높을수록 상대적으로 우선순위가 높음을 의미합니다. 최종적인 우선순위 클래스(HIGH / MED / LOW)는 서비스 환경에 맞는 후처리 정책을 통해 결정하는 것을 전제로 합니다.

Evaluation Metrics

아래 평가지표는 0~1로 스케일링된 우선순위 점수를 기준으로 산출되었습니다.

Loss: 0.0045

MAE (평균 절대 오차): 0.0122

RMSE (평균 제곱근 오차): 0.0150

Spearman 상관계수: 0.8473

Note 본 모델은 우선순위를 직접 분류(classification)하지 않고, 모델이 예측한 점수를 기반으로 도메인 정책(보안, 결제, 장애, 문서 변경 등)을 반영한 후처리를 적용하도록 설계되었습니다.

🚀 빠른 시작

모델 예측 (점수만 출력)

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch
import json

# 모델 로드
model_name = "your-username/issue-priority-ko"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)
model.eval()

# 예측 (점수만 출력)
text = "로그인 안됨, 토큰 만료 처리 필요"
inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=256)

with torch.no_grad():
    score_raw = model(**inputs).logits.item()  # 0~1 범위 점수

# 원래 스케일로 복원
with open("score_thresholds.json", "r", encoding="utf-8") as f:
    thresholds = json.load(f)

score = score_raw * (thresholds["train_max"] - thresholds["train_min"]) + thresholds["train_min"]

print(f"Predicted Score: {score:.4f}")

점수 → 클래스 변환 (후처리)

# 방법 1: to_priority 함수 사용 (권장)
from postprocess.to_priority import to_priority

# 기본 변환 (후처리 규칙 없음)
priority = to_priority(score=score, text=text)
print(f"Priority: {priority}")

# 후처리 규칙 포함 (옵션)
priority = to_priority(score=score, text=text, use_rules=True)
print(f"Priority (with rules): {priority}")

# 방법 2: 직접 변환
if score >= thresholds["q_high"]:
    priority = "HIGH"
elif score <= thresholds["q_low"]:
    priority = "LOW"
else:
    priority = "MED"

📋 모델 정보

항목	내용
기반 모델	distilbert-base-multilingual-cased
작업 유형	회귀 (Regression)
입력	커밋/이슈 제목 + 본문 텍스트
출력	우선순위 점수 (float)
클래스 변환	후처리로 수행 (to_priority() 함수)
언어	한국어, 영어
최대 길이	256 토큰

중요: 모델은 점수만 출력합니다. HIGH/MED/LOW 클래스 변환은 to_priority() 함수를 사용하세요.

🎯 주요 특징

1. 다국어 지원: 한국어와 영어 커밋/이슈 모두 처리 가능
2. 키워드 기반 후처리: postprocess/priority_rules.yaml로 규칙 커스터마이징
3. 배치 내 상대 정렬: 여러 이슈를 함께 비교하여 더 정확한 우선순위 예측
4. 경량 모델: DistilBERT 기반으로 빠른 추론 속도

📁 폴더 구조

issue-priority-ko/
├── README.md                # 이 파일
├── config.json              # 모델 설정
├── model.safetensors        # 모델 가중치
├── tokenizer.json           # 토크나이저
├── tokenizer_config.json
├── vocab.txt
├── score_thresholds.json    # 우선순위 변환 임계값
│
├── postprocess/             # 후처리 규칙 (옵션)
│   ├── to_priority.py        # 점수→클래스 변환 함수
│   ├── priority_rules.yaml  # 키워드 기반 규칙 (옵션)
│   └── README.md            # 후처리 설명
│
├── examples/                # 사용 예제
│   ├── input.json
│   └── output.json
│
└── requirements.txt         # 의존성 패키지

🔄 점수 → 클래스 변환

to_priority() 함수 사용

from postprocess.to_priority import to_priority

# 기본 변환 (threshold 기반)
priority = to_priority(score=0.82, text="로그인 에러 발생")

# 후처리 규칙 포함 (옵션)
priority = to_priority(score=0.82, text="로그인 에러 발생", use_rules=True)

# 배치 변환
from postprocess.to_priority import to_priority_batch
scores = [0.82, 0.75, 0.90]
texts = ["로그인 에러", "README 수정", "서버 다운"]
priorities = to_priority_batch(scores, texts, use_rules=True)

후처리 규칙 (옵션)

postprocess/priority_rules.yaml을 사용하여 키워드 기반 규칙을 적용할 수 있습니다.

규칙 예시:

• LOW 강제: readme, typo, 문서 → 무조건 LOW
• 최소 MED 보장: 장애, 에러, 로그인, 결제 → 최소 MED
• HIGH 부스트: 데이터 손실, 무한, critical → HIGH

자세한 내용은 postprocess/README.md를 참고하세요.

📊 성능 지표

지표	값
MAE	0.009 (스케일된 값 기준)
RMSE	0.015 (스케일된 값 기준)
Spearman Correlation	0.85

참고: 모델은 상대적 순위 예측에 더 적합합니다. 절대 점수보다는 배치 내 비교를 권장합니다.

💡 사용 팁

1. 단일 예측

# 모델 예측
text = "로그인 안됨"
inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=256)
with torch.no_grad():
    score_raw = model(**inputs).logits.item()

# 스케일 복원
score = score_raw * (thresholds["train_max"] - thresholds["train_min"]) + thresholds["train_min"]

# 클래스 변환
from postprocess.to_priority import to_priority
priority = to_priority(score=score, text=text, use_rules=True)

2. 배치 예측 (권장)

texts = ["이슈1", "이슈2", "이슈3"]
inputs = tokenizer(texts, return_tensors="pt", truncation=True, max_length=256, padding=True)

with torch.no_grad():
    scores_raw = model(**inputs).logits.squeeze(-1).numpy()

# 스케일 복원
scores = scores_raw * (train_max - train_min) + train_min

# 배치 내 상대 정렬 (quantile 기반)
from scipy.stats import rankdata
normalized = rankdata(scores, method='average') / len(scores)

# 상위 30% = HIGH, 하위 30% = LOW
q_high = np.percentile(normalized, 70)
q_low = np.percentile(normalized, 30)

3. 배치 예측 + 클래스 변환

# 배치 예측
texts = ["이슈1", "이슈2", "이슈3"]
inputs = tokenizer(texts, return_tensors="pt", truncation=True, max_length=256, padding=True)

with torch.no_grad():
    scores_raw = model(**inputs).logits.squeeze(-1).numpy()

# 스케일 복원
scores = scores_raw * (thresholds["train_max"] - thresholds["train_min"]) + thresholds["train_min"]

# 배치 클래스 변환
from postprocess.to_priority import to_priority_batch
priorities = to_priority_batch(scores, texts, use_rules=True)

for text, score, priority in zip(texts, scores, priorities):
    print(f"{priority}: {score:.4f} - {text}")

⚠️ 주의사항

1. 모델 출력: 모델은 점수만 출력합니다 (회귀 모델). 클래스 변환은 to_priority() 함수 사용
2. 스케일 복원 필수: 모델 출력은 0~1 범위입니다. score_thresholds.json으로 원래 스케일 복원 필요
3. 상대적 순위: 절대 점수보다는 배치 내 상대 비교가 더 정확
4. 후처리 규칙: priority_rules.yaml은 옵션입니다. 필요시에만 사용
5. 도메인 적응: 새로운 도메인에서는 재학습 또는 파인튜닝 권장

📚 예제

실제 사용 예제는 examples/ 폴더를 참고하세요.

• input.json: 입력 예제
• output.json: 출력 예제

🔗 관련 자료

• 변환 함수: postprocess/to_priority.py - 점수→클래스 변환
• 후처리 규칙 (옵션): postprocess/priority_rules.yaml
• 후처리 설명: postprocess/README.md

📄 라이센스

• Apache 2.0