내 어노테이션으로 LLM 파인튜닝하기

v2.14.0의 새 기능

이 튜토리얼은 Potato 연구가 수집한 답으로 네 종류의 언어 모델을 학습시킵니다. llm-sft 트레이너는 작성된 답이나 수정된 에이전트 트레이스로 LLM을 파인튜닝하고, llm-dpo는 쌍별 선택으로 LLM을 튜닝하며, reward-model은 비교 결과로 스칼라 보상 모델을 학습시키고, prm-reward는 단계별 평가로 프로세스 보상 모델을 학습시킵니다. 이 페이지는 Potato에서 이미 선호 데이터나 트레이스 데이터를 수집하고 있으며, 데이터를 별도의 학습 스크립트로 내보내지 않고 그 레이블로 첫 모델을 얻으려는 팀을 위해 쓰였습니다. 각 섹션은 데이터를 만드는 스키마의 이름을 밝히고, Potato의 검증기를 통과하는 설정을 제시하며, 바꿀 만한 파라미터를 나열하고, 홀드아웃 점수가 무엇을 측정하는지와 예측이 사전 레이블로 어노테이터에게 돌아가는지를 설명합니다. 모델 학습 개요는 Training 페이지를 다루고, 첫 모델 학습시키기는 GPU가 필요 없는 분류기로 전체 루프를 실행합니다.

어노테이션 스키마별 트레이너

이 페이지의 모든 트레이너는 실행마다 어노테이션 스키마 하나로 학습하며, Training 페이지는 트레이너가 학습할 수 있는 스키마에만 그 트레이너를 제공합니다. 아래 표는 각 트레이너가 학습하는 스키마를 나열합니다.

시작하기 전에

Potato의 학습 extras는 네 트레이너를 위해 PyTorch, Transformers, PEFT를 설치합니다.

pip install "potato-annotation[train-llm]"
pip install "potato-annotation[train-text]"

첫 번째 extra는 llm-sft와 llm-dpo를, 두 번째는 reward-model과 prm-reward를 다룹니다. pip install "potato-annotation[train]"은 모든 학습 extras를 한 번에 설치합니다. 패키지가 없는 트레이너는 Training 페이지에 "not installed"로 표시되며, 패키지를 설치하는 명령도 함께 나옵니다.

각 트레이너는 train 분할에 항목이 20개보다 적으면 학습을 거부합니다(min_instances 파라미터). 기본 분할은 레이블이 달린 항목의 70%를 train에, 15%를 val에, 15%를 test에 두므로, 첫 실행 전에 레이블이 달린 항목 30개 정도를 준비하십시오. val과 test 항목은 학습에서 제외되어 모델의 점수를 매깁니다.

llm-sft와 llm-dpo는 Qwen/Qwen2.5-0.5B-Instruct에서, reward-model은 distilbert/distilroberta-base에서, prm-reward는 answerdotai/ModernBERT-base에서 시작합니다. LLM 트레이너는 GPU에서 실행되도록 만들어졌습니다. Potato를 실행하는 머신에 GPU가 없으면 원격 학습이 실행을 ssh로 GPU 서버에, 또는 SLURM 클러스터에 보냅니다.

선호와 재작성을 수집하는 연구

첫 번째 설정은 고객 지원 프롬프트마다 두 가지를 묻습니다. 어노테이터는 두 응답 중 더 나은 것을 고르고, 어시스턴트에게서 받고 싶은 답을 직접 씁니다. 선택은 llm-dpo와 reward-model을 학습시키고, 작성한 답은 llm-sft를 학습시킵니다. data/answers.jsonl의 각 줄에는 프롬프트와 두 응답이 들어 있습니다.

{"id": "q001", "prompt": "How do I reset my router to factory settings?", "responses": ["Hold the reset button on the back for 10 seconds until the lights blink, then wait two minutes for the router to restart.", "Routers can be reset. Check the manual."]}

이 설정은 프롬프트를 항목의 텍스트로, 두 응답을 카드 A와 B로 보여 줍니다.

annotation_task_name: "Support answers: preferences and rewrites"
task_dir: .
data_files:
  - data/answers.jsonl
item_properties:
  id_key: id
  text_key: prompt
output_annotation_dir: annotation_output
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: pairwise
    name: preferred
    description: "Which response answers the question better?"
    mode: binary
    items_key: responses
    allow_tie: true
    tie_label: "No preference"
 
  - annotation_type: text
    name: rewrite
    description: "Write the answer you would want the assistant to give."
    multiline: true
    rows: 4
 
model_training:
  enabled: true
  writeback:
    schemas: [preferred]
    min_confidence: 0.7

text_key: prompt는 두 가지 이유로 중요합니다. 프롬프트는 어노테이터가 읽는 내용이면서 llm-sft가 질문 뒤에 붙이는 내용이기 때문입니다. items_key: responses는 쌍별 카드를 만드는 목록을 데이터 순서대로 지정하므로 A가 첫 번째 응답입니다. writeback.schemas에는 preferred만 있으므로 어노테이터는 모델의 선택을 보고 생성된 재작성은 보지 않습니다. 사전 레이블은 어노테이터를 앵커링하므로, llm-sft 실행의 홀드아웃 점수가 모델의 텍스트를 보여 줄 만하다고 뒷받침할 때에만 rewrite를 목록에 추가하십시오. min_confidence: 0.7은 모델이 덜 확신하는 예측을 화면에는 내보내지 않고 저장은 계속합니다. 서버를 시작하기 전에 Potato의 검증기로 설정을 확인하십시오.

python -m potato.validate_cli config.yaml --strict

Potato를 시작하고 프롬프트 30개 이상에 레이블을 단 다음, 관리자로 /admin/training을 여십시오. 아래 실행은 설정의 admin_api_key를 $KEY에 넣고 API로도 시작할 수 있습니다.

llm-sft로 지도 파인튜닝

llm-sft는 레이블이 달린 항목마다 학습 예시 하나를 만듭니다. 프롬프트는 스키마의 description(어노테이터가 본 질문) 뒤에 항목의 텍스트를 이은 것이고, 목표는 어노테이터가 쓴 답입니다. 손실은 답의 토큰에만 적용되므로 모델은 프롬프트를 반복하지 않고 답하는 법을 배웁니다. 기본적으로 모든 가중치 대신 LoRA 어댑터를 학습시킵니다.

Training 페이지에서 llm-sft와 rewrite 스키마를 고르고 Train now를 누르거나, 같은 실행을 API로 시작하십시오.

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "llm-sft", "schemas": ["rewrite"], "params": {"max_new_tokens": 256}}'

대부분의 실행은 이 표의 파라미터만 바꿉니다.

실행은 val 손실이 가장 낮은 체크포인트를 유지합니다. 체크포인트를 val로 골랐으므로 홀드아웃 점수는 test에서 읽습니다. 점수는 토큰 F1이며, 생성된 답과 작성된 답 사이에서 순서와 무관하게 겹치는 단어를 측정하고, 점수 옆에 정확히 일치하는 비율(exact match)도 함께 보고합니다. 토큰 F1은 올바른 단어를 엉뚱한 자리에 쓴 답에도 점수를 주므로 두 지표를 함께 읽으십시오.

모델은 모든 val 항목과 test 항목에 대해 답을 탐욕적으로 생성합니다. writeback.include_unlabeled: true이면 모델은 아무도 레이블을 달지 않은 항목에도 답합니다. 예측의 신뢰도는 모델이 생성한 토큰의 평균 확률이며, 모델 검토 대기열은 그 신뢰도로 정렬됩니다. rewrite가 writeback.schemas에 있으면 어노테이터가 항목을 열 때 생성된 답이 텍스트 상자를 채웁니다.

자유 텍스트는 항목당 어노테이터가 여럿인 경우에 잘 맞지 않습니다. aggregation 설정은 답을 단어 단위로 비교해 여러 답을 하나로 통합하는데, 작성된 두 답이 단어 단위로 일치하는 경우는 드뭅니다. text 스키마의 llm-sft에서는 항목당 작성자를 한 명으로 두면 단어 단위 비교를 피할 수 있습니다.

llm-dpo로 선호 튜닝

Direct Preference Optimization(DPO)은 시작 모델의 고정된 참조 복사본과 비교하여, 선호하는 응답의 가능도를 다른 응답에 비해 높이도록 LLM을 학습시킵니다. llm-dpo는 A나 B로 답한 항목마다 예시 하나를 만듭니다. 프롬프트는 항목의 prompt 필드이거나, 항목에 있는 question, instruction, query, input, context 중 첫 번째 필드입니다. 동점 선택지로 답한 항목은 제외되는데, 동점은 어느 응답도 더 낫다고 표시하지 않기 때문입니다.

llm-dpo와 preferred 스키마를 고르거나, 위와 같은 요청에 "trainer": "llm-dpo"와 "schemas": ["preferred"]를 넣어 보내십시오. 기본 LoRA 어댑터를 쓰면 참조 모델은 어댑터를 끈 같은 모델이므로 두 번째 복사본이 메모리에 올라가지 않습니다. lora: false는 모든 가중치를 학습시키고 고정된 복사본을 참조로 유지하며, 이 복사본 때문에 메모리가 두 배가 됩니다.

실행은 val에서 DPO 손실이 가장 낮은 체크포인트를 유지하고, 실행 로그는 모델이 val에서 어노테이터의 선택을 얼마나 자주 선호하는지 보고합니다. 홀드아웃 점수는 동점으로 답하지 않은 항목에 대한 test 정확도이며, 정확도 옆에 macro-F1이 함께 표시됩니다. 예측은 학습된 모델이 선호하는 응답이고, 그 선호의 확률이 신뢰도입니다. 사전 레이블로서는 어노테이터가 항목을 열 때 선호하는 응답의 카드가 선택됩니다. 스키마에 randomize_order가 켜져 있으면 선택은 응답이 어노테이터에게 보이는 위치를 따라갑니다. 저장된 어댑터는 정책이기도 해서 PEFT로 불러오면 텍스트를 생성합니다. 선호 데이터를 수집하는 방법은 RLHF와 선호 데이터 수집과 쌍별 비교를 참고하십시오.

reward-model로 보상 모델

보상 모델은 RLHF, best-of-n 샘플링, 새 출력의 순위 매기기를 위해 응답을 숫자로 대응시킵니다. reward-model은 출력이 하나인 트랜스포머를 학습시켜 어노테이터가 선호한 응답이 더 높은 점수를 받게 합니다. 손실은 Bradley–Terry 손실인 -log sigmoid(r_winner - r_loser)이며, InstructGPT의 보상 모델링 손실입니다. 위의 preferred 스키마는 설정을 바꾸지 않고도 reward-model을 학습시킵니다. 비교형 스키마마다 학습 신호가 다릅니다.

항목에 프롬프트 필드가 있으면 각 보상은 프롬프트가 주어졌을 때의 응답에 대한 값입니다. 순위의 선택지는 스키마의 레이블이며, 각각 항목의 텍스트가 주어졌을 때 점수가 매겨집니다. 서버는 bws_config로 BWS 튜플을 만들므로, 서버 자체 데이터로 실행하면 튜플이 이미 있고 데이터 파일에는 튜플이 필요 없습니다.

예측은 스키마 자체의 질문에 답하므로 다른 스키마의 예측과 똑같이 점수가 매겨지고 되쓰입니다. 사전 레이블은 이진 선택이면 선택된 카드, 척도이면 슬라이더 위치, 순위이면 목록의 순서, BWS이면 선택된 최선과 최악입니다. 모든 예측에는 예측의 근거가 된 rewards도 저장됩니다. 의미가 있는 것은 보상 사이의 차이뿐입니다. 비교형 형식으로 데이터를 수집하는 방법은 쌍별 비교와 Best-Worst Scaling에서 비교합니다.

단계 평가와 수정을 수집하는 연구

두 번째 설정은 에이전트 트레이스를 다룹니다. 어노테이터는 트레이스의 각 단계를 평가한 다음 틀린 단계를 고칩니다. 단계 평가는 prm-reward를 학습시키고, 수정은 llm-sft나 llm-dpo를 학습시킵니다. data/traces.jsonl의 각 줄에는 작업, 에이전트의 단계, 최종 답이 들어 있습니다.

{"id": "traj_001", "task_description": "Find the current weather in San Francisco and report the temperature.", "steps": [{"thought": "I should look up the current weather.", "action": "web_search(queyr='San Francisco weather')"}, {"thought": "Open the first result.", "action": "open_url(results[0])"}, {"thought": "Read the temperature from the page.", "action": "extract_text('.temp')"}], "final_answer": "It is sunny."}

트레이너는 항목의 task_description, task, text 필드에서 이 순서대로 작업을 읽습니다.

annotation_task_name: "Agent traces: step ratings and corrections"
task_dir: .
data_files:
  - data/traces.jsonl
item_properties:
  id_key: id
  text_key: task_description
output_annotation_dir: annotation_output
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: process_reward
    name: step_quality
    description: "Rate each step of the agent's trace"
    steps_key: steps
    step_text_key: action
    mode: per_step
    allow_neutral: true
    ai_prelabel: true
 
  - annotation_type: trajectory_edit
    name: corrected_trace
    description: "Fix the wrong steps, then correct the final answer"
    steps_key: steps
    step_text_key: action
    editable_fields: [action]
    show_diff: true
    edit_final_answer: true
    final_answer_key: final_answer
 
model_training:
  enabled: true
  writeback:
    schemas: [step_quality]
    include_unlabeled: true

allow_neutral: true가 있는 mode: per_step은 prm-reward가 학습하는 세 가지 평가를 제공합니다. ai_prelabel: true는 스키마에 "AI pre-label steps" 버튼을 추가하며, 학습된 평가는 이 버튼으로 나타납니다. writeback.schemas에는 step_quality만 있습니다. 여기에 corrected_trace를 적으면 서버가 시작되지 않으며, 검증기가 이유를 알려 줍니다.

model_training.writeback.schemas names 'corrected_trace', a trajectory_edit scheme, which has no prelabel display: its predictions are stored and scored but annotators would never see them. Leave it out of writeback.schemas.

llm-sft와 llm-dpo로 트레이스 고치기

trajectory_edit 답은 트레이스 한 쌍, 즉 에이전트의 원래 단계와 어노테이터가 수정한 뒤의 단계입니다. SFT/DPO를 위한 궤적 편집은 편집기를 다루고, 궤적 편집 게시글은 쌍이 학습 데이터가 되는 과정을 다룹니다. 두 트레이너 모두 아무도 편집하지 않은 트레이스는 제외합니다.

• **llm-sft**는 작업과 원래 단계를 프롬프트로, 수정된 단계를 목표로 삼아 모델이 트레이스를 고치는 법을 배웁니다. 각 단계는 Step N 뒤에 단계의 필드(action: ..., thought: ...)를 붙여 쓰며, 스키마에 final_answer_key가 있으면 마지막 단계 뒤에 최종 답이 이어집니다.
• **llm-dpo**는 작업을 프롬프트로, 수정된 단계를 선호하는 응답으로, 원래 단계를 다른 응답으로 삼습니다. 예측은 모델이 수정본(A)과 원본(B) 중 어느 쪽을 선호하는지를 말하며, 수정본이 있는 홀드아웃 트레이스에 대해서만 만들어집니다.

두 실행 모두 홀드아웃 점수로 closer_to_correction을 보고합니다. llm-dpo에서 이 점수는 모델이 수정본을 선호하는 홀드아웃 트레이스의 비율입니다. llm-sft에서는 작성된 단계가 토큰 F1 기준으로 원본보다 수정본에 더 가까운 트레이스의 비율이며, 점수 옆에 수정본에 대한 token_f1도 함께 보고합니다.

trajectory_edit 실행의 예측은 저장되고 점수가 매겨지지만 어노테이터에게는 보이지 않습니다. 편집기는 언제나 에이전트의 원래 트레이스에서 시작하므로 이 페이지에는 예측된 재작성을 보여 줄 자리가 없습니다. 예측은 실행 페이지나 실행 디렉터리의 artifacts/predictions.jsonl에서 읽으십시오.

prm-reward로 단계 평가

프로세스 보상 모델은 PRM800K에서처럼 최종 답만이 아니라 트레이스의 단계를 평가합니다. prm-reward는 작업 뒤에 Step 1, Step 2 등이 이어지는 트레이스 전체를 하나의 입력으로 트랜스포머 인코더에 넣습니다. 인코더는 각 단계의 마지막 토큰에서 세 가지 평가를 학습하므로, 각 평가는 그 단계 앞의 단계들을 본 상태에서 이루어집니다. 아무도 평가하지 않은 단계는 손실에서 제외됩니다. 기본 모델인 answerdotai/ModernBERT-base는 8,192토큰 컨텍스트 때문에 선택되었습니다.

긴 트레이스는 마지막 단계를 잃습니다. max_length 토큰보다 긴 트레이스는 끝에서부터 잘리고, 잘린 지점 뒤의 단계는 학습되지도 평가되지도 않습니다. 실행 로그가 잃은 단계의 수를 셉니다. max_length가 모델이 담을 수 있는 길이보다 크면 실행은 경고와 함께 max_length를 모델의 한도로 낮추며, 대부분의 BERT 계열 인코더에서 한도는 512토큰입니다. 실행 로그에 잃은 단계가 보고되면 max_length를 높이고 더 긴 트레이스를 담는 컨텍스트를 가진 모델을 고르십시오.

홀드아웃 점수는 step_macro_f1이며, 평가된 모든 단계에 대한 세 가지 평가의 macro-F1입니다. 대부분의 트레이스에서 대부분의 단계는 correct이므로, 정확도는 "wrong"이라고 한 번도 말하지 않는 모델을 후하게 평가합니다. 실행은 step_accuracy와 first_error_accuracy도 보고하며, 후자는 모델이 처음으로 wrong이라 한 단계가 어노테이터가 처음으로 wrong이라 한 단계와 같은 트레이스의 비율입니다.

예측은 max_length에 들어가는 모든 단계를 평가하며, 각 평가의 확률이 그 평가의 신뢰도이고 가장 신뢰도가 낮은 단계가 트레이스의 신뢰도입니다. 스키마가 writeback.schemas에 있고 ai_prelabel: true이면 "AI pre-label steps" 버튼이 학습된 평가를 어노테이터가 확인하도록 제공합니다. 학습된 평가가 있는 항목에는 ai_support에 설정된 LLM 판정기를 호출하지 않습니다. 프로세스 보상 어노테이션은 스키마를 다루고, 프로세스 보상 모델 가이드는 데이터를 다룹니다.

QLoRA로 더 큰 모델 맞추기

QLoRA는 기반 모델의 가중치를 4비트로 불러오고 그 위에서 LoRA 어댑터를 학습시킵니다. llm-sft, llm-dpo, hf-text-classification, vlm-sft, reward-model은 lora: {quantize: 4bit}를 받고, prm-reward는 모델을 불러오기 전에 이 설정을 거부합니다. 모든 트랜스포머 실행이 끝에 기록하는 "Peak GPU memory" 줄을 보고 메모리를 계획하십시오. 설정 레퍼런스의 QLoRA 섹션은 기반 가중치가 불러와지는 방식과 8비트 옵션을 설명합니다.

위 설정에 이 블록을 추가하면 llm-sft의 기본값으로 QLoRA가 설정됩니다.

model_training:
  enabled: true
  trainer_params:
    llm-sft:
      model_name: Qwen/Qwen2.5-7B-Instruct
      lora: {quantize: 4bit}
      gradient_checkpointing: true

QLoRA에는 CUDA GPU와 그 머신의 CUDA에 맞는 bitsandbytes 빌드가 필요하며, pip install bitsandbytes로 설치합니다. 작동하는 GPU나 빌드가 없으면 실행은 모델을 불러오기 전에 검증 단계에서 멈춥니다.

실행을 Hugging Face Hub에 게시하기

모델이 Potato 서버에 있는 성공한 실행에는 실행 페이지에 Publish to the Hugging Face Hub가 있습니다. 푸시는 모델과, 실행에서 작성된 README.md 모델 카드를 업로드합니다. 카드에는 트레이너, 기반 모델과 어댑터, 스키마와 레이블, 분할 크기, 홀드아웃 점수와 그 점수가 무엇으로 측정되었는지, 실행 ID와 번들 ID가 들어 있습니다. LoRA 실행은 어댑터만 저장했으므로 Hub 저장소에는 어댑터가 있고, 카드는 어댑터를 얹을 기반 모델을 알려 줍니다.

토큰은 브라우저에 두지 않습니다. Hugging Face 설정에서 쓰기 토큰을 만들고, Potato를 시작하기 전에 서버 환경에 넣으십시오.

export HF_TOKEN=hf_your_write_token
potato start config.yaml

양식은 환경 변수의 이름(기본값은 HF_TOKEN)을 보여 주고, 저장소 이름을 두 번 묻고, Private을 기본으로 체크해 둡니다. Hugging Face Hub에 게시하기는 올라가는 파일, 푸시 전의 점검, 모델 카드의 라이선스를 나열합니다. 같은 푸시를 API로 하는 방법은 다음과 같습니다.

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs/RUN_ID/push-to-hub \
  -d '{"repo_id": "your-org/support-dpo", "confirm_repo_id": "your-org/support-dpo", "private": true, "licence": "apache-2.0"}'

이 라우트는 커밋과 함께 201을 반환합니다. fetch_artifacts: false로 원격 호스트에 남겨 둔 모델은 Potato 서버에서 푸시할 수 없으며, 실행 페이지가 모델이 있는 곳을 알려 줍니다. 게시한 모델에서 능동 학습 루프로 넘어가려면 루프 속의 모델로 이어 가십시오.

더 읽어보기

• 모델 학습 설정: 모든 model_training 키, 홀드아웃 점수, 되쓰기, 라우트.
• 트레이너: 작업별로 묶은 트레이너 38개 전체.
• 원격 학습: ssh를 통한 GPU 서버, SLURM 클러스터, 폴링 에이전트.
• 에이전트 궤적 어노테이션: Potato에서 트레이스 데이터 수집하기.
• 업스트림 레퍼런스 섹션: llm-sft, llm-dpo, 에이전트 트레이스, prm-reward, reward-model, QLoRA, Hub 게시.

참고문헌

• Dettmers, T., Pagnoni, A., Holtzman, A., and Zettlemoyer, L. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. arXiv:2305.14314. arxiv.org/abs/2305.14314
• Hu, E. J., Shen, Y., Wallis, P., Allen-Zhu, Z., Li, Y., Wang, S., Wang, L., and Chen, W. (2021). LoRA: Low-Rank Adaptation of Large Language Models. arXiv:2106.09685. arxiv.org/abs/2106.09685
• Lightman, H., Kosaraju, V., Burda, Y., Edwards, H., Baker, B., Lee, T., Leike, J., Schulman, J., Sutskever, I., and Cobbe, K. (2023). Let's Verify Step by Step. arXiv:2305.20050. arxiv.org/abs/2305.20050
• Ouyang, L., Wu, J., Jiang, X., Almeida, D., Wainwright, C. L., Mishkin, P., Zhang, C., Agarwal, S., Slama, K., Ray, A., Schulman, J., Hilton, J., Kelton, F., Miller, L., Simens, M., Askell, A., Welinder, P., Christiano, P., Leike, J., and Lowe, R. (2022). Training Language Models to Follow Instructions with Human Feedback. arXiv:2203.02155. arxiv.org/abs/2203.02155
• Rafailov, R., Sharma, A., Mitchell, E., Ermon, S., Manning, C. D., and Finn, C. (2023). Direct Preference Optimization: Your Language Model is Secretly a Reward Model. arXiv:2305.18290. arxiv.org/abs/2305.18290