argos-harness-qwen3.5-4b
Qwen3.5-4B 위에 학습한 LoRA 어댑터입니다. Argos v0.2 네이티브 에이전트 하네스의 29개 툴을 여러 턴에 걸쳐 정확히 호출하도록 SFT했습니다. 학습은 8GB 소비자 GPU(RTX 3060 Ti)에서 Unsloth 4bit QLoRA로 진행했습니다. llama.cpp / Ollama에서 바로 쓸 수 있는 Q4_K_M GGUF도 함께 제공합니다.
A LoRA adapter for Qwen3.5-4B, fine-tuned (SFT) to drive the 29-tool native agent harness of Argos v0.2, a personal study/project dashboard with channels, kanban, calendar, notes and LMS sync. Trained with Unsloth 4-bit QLoRA on a single 8 GB consumer GPU. A ready-to-run Q4_K_M GGUF is included.
| Base model | unsloth/Qwen3.5-4B (= Qwen/Qwen3.5-4B) |
| Adapter | LoRA r=16, α=32, dropout 0, all attention + MLP projections (q/k/v/o/gate/up/down_proj) of the language model |
| Training | Unsloth QLoRA (4-bit NF4) + TRL SFTTrainer, 2 epochs, batch 1 × grad-accum 8, peak LR 2e-4, linear schedule, warmup 5%, 98 optimizer steps, max seq len 4736, loss on assistant turns only |
| Data | 385 train / 65 eval conversations (~1.72M train tokens / epoch) |
| Final loss | train 0.0011 (last logged step; run average 0.0587) · eval 0.0032 |
| Hardware | 1 × RTX 3060 Ti 8 GB (WSL2), ~95 min |
| W&B | training 4vaun76g · eval SFT fs7qdlb7 · eval base 2nxzjvrh |
| Languages | Korean (primary user turns), English (tool schemas, code) |
Files
| Path | |
|---|---|
adapter_model.safetensors, adapter_config.json |
LoRA adapter (PEFT), 42.5 MB |
tokenizer*.json, chat_template.jinja, processor_config.json |
Qwen3.5 tokenizer / chat template used in training |
gguf/Qwen3.5-4B.Q4_K_M.gguf |
Merged (base + LoRA) model, Q4_K_M, 2.8 GB |
gguf/Qwen3.5-4B.BF16-mmproj.gguf |
Vision projector (Qwen3.5 is natively multimodal; optional, not fine-tuned) |
Argos 하네스 · The harness
Argos의 네이티브 하네스(backend/src/argos/harness.py)는 OpenAI 호환 chat.completions 또는 Anthropic Messages API로
모델 응답을 스트리밍 받으면서 툴 루프를 돌립니다. 툴은 read / write / destructive로 분류되고, 권한 모드와 경로 허용 목록에 따라
자동 실행되거나 사용자에게 인라인 승인을 받습니다. 깨진 툴 인자는 repair_json으로 복구하지만, 이 어댑터는
그런 복구가 필요 없도록 처음부터 올바른 툴과 인자를 내는 것을 목표로 합니다.
| 그룹 · Group | Tools |
|---|---|
| 조회 · Read | list_channels, get_today, get_schedule, search_notes, search_course_lms, search_knowledge, list_tasks, list_inbox, get_course_progress |
| 쓰기 · Write | create_channel, add_task, update_task, move_task, create_event, update_event, capture_note |
| 삭제 · Destructive (인라인 승인) | delete_task, delete_event, delete_file |
| 파일 · 셸 · Files & shell | read_file, list_dir, glob_files, grep_files, write_file, edit_file, run_command |
| 확장 · Extra | render_artifact, web_fetch, ask_agent |
학습 데이터 · Training data
training/generate_seed_data.py가 하네스의 실제 툴 스키마(argos.sft_export.tool_specs())로 생성한 합성 다중 턴 궤적입니다
(OpenAI messages + tools JSONL 형식이고, run_id 해시로 train/eval을 고정 분할). 실제 run을 내보내는 argos.sft_export와 같은 형식입니다.
- 385 train / 65 eval 대화, 대화당 최대 11개 메시지, 샘플당 약 4.2k–4.7k 토큰 (그중 system 프롬프트와 29개 툴 스키마가 약 4.05k)
- 29개 툴 전부 등장 (train 기준 툴 호출 1048회; 상위
add_task126,read_file76,render_artifact56,get_schedule54,create_event53,web_fetch49) - 시나리오: 할 일·일정·채널·노트·LMS 조회/수정, 작업 폴더 파일 탐색·편집·명령 실행,
에러 복구(툴이
오류: <Type>: …를 돌려주면 인자를 고쳐 재시도), 삭제 전 인라인 승인 흐름,render_artifact로 표·차트·Mermaid 인라인 시각화,ask_agent로 다른 에이전트에 위임,web_fetch, 그리고 툴이 필요 없는 일반 대화 턴(불필요한 툴 호출 억제)
학습 시 주의점 · Training notes
Qwen3.5로 같은 데이터를 학습할 때 확인된 함정 두 가지를 학습 스크립트에서 수정했습니다.
- 시퀀스 길이: 첫 어시스턴트 턴 앞의 프롬프트만 약 4.05k 토큰입니다.
max_seq_length=2048이면 어시스턴트 토큰이 하나도 학습되지 않고 system 프롬프트만 암기합니다(loss가 0.007로 떨어지지만 의미 없음). 그래서 4736으로 학습했고, 잘린 샘플은 없습니다. - 툴 인자 렌더링: OpenAI 형식의
tool_calls[].function.arguments는 JSON 문자열인데, Qwen3.x chat template은arguments가 dict일 때만<parameter=…>블록을 출력합니다. 문자열을 그대로 넘기면 모든 툴 호출이 인자 없이(<function=add_task></function>) 렌더링됩니다. 그래서 학습 전에json.loads로 dict로 바꿨습니다. (llama.cpp--jinja, vLLM 서빙 경로는 이 변환을 자체적으로 합니다.)
또한 loss의 약 94%가 매 샘플 동일한 system/툴 스키마 토큰에서 나오므로, Unsloth train_on_responses_only로 어시스턴트 턴만 학습했습니다
(툴 결과는 ChatML에서 user 턴으로 렌더링되므로 함께 마스킹됨).
9B(
Qwen3.5-9B)도 시도했지만 8GB GPU에는 들어가지 않았습니다. 248k 어휘의 bf16 embedding과 분리된lm_head만 약 4GB이고, 거기에 비전 타워가 더해집니다. 레이어 오프로딩(offload_layers="auto")을 써도, 4.7k 토큰 시퀀스의 logit 버퍼까지 더하면 들어가지 않았습니다.
평가 · Evaluation
training/eval_harness.py가 eval 대화의 각 어시스턴트 스텝마다 그 이전 맥락을 주고, 모델이 낸 다음 응답을 채점합니다.
Base와 SFT 모두 같은 eval 셋, 같은 서빙 조건(llama.cpp llama-server --jinja, Q4_K_M GGUF, CPU, temperature 0,
enable_thinking=false)에서 측정했습니다. 수치는 reports/eval-qwen3.5-4b-{base,sft}.json 원본 그대로입니다.
| 지표 · Metric | Base Qwen3.5-4B | SFT (this model) |
|---|---|---|
| JSON 유효율 · JSON validity | 98.9% | 98.9% |
| 툴 선택 정확도 · Tool selection | 73.6% | 98.9% |
| 스키마 준수율 · Schema compliance | 98.9% | 98.9% |
| 인자 완전 일치 · Exact argument match | 35.2% | 91.2% |
| 툴 없는 턴 정확도 · No-tool accuracy | 87.1% | 92.5% |
| 평가 스텝 수 · Steps | 182 tool + 93 no-tool | 182 tool + 93 no-tool |
Base는
unsloth/Qwen3.5-4B-GGUF의Qwen3.5-4B-Q4_K_M.gguf이고, SFT는 이 저장소의gguf/Qwen3.5-4B.Q4_K_M.gguf입니다. 둘의 양자화 파이프라인이 완전히 같지는 않습니다(Unsloth 배포본 vs.save_pretrained_gguf).
- JSON 유효율 / 스키마 준수 / 툴 선택: 툴을 불러야 하는 182개 스텝에서 올바른 툴 이름과 스키마에 맞는 JSON 인자를 냈는지. Base도 형식(JSON·스키마)은 잘 지키지만 어떤 툴을 부를지와 인자 값에서 크게 차이가 납니다.
- 인자 완전 일치: 기대 인자와 완전히 같은지. SFT의 불일치 16건은 주로
glob_files7(*.md/*.py를 찾아야 할 때*.txt패턴을 냄),add_task5(채널 이름 오선택),create_event2입니다. 툴은 맞고 인자 값만 다른 경우입니다. - 툴 없는 턴 정확도: 툴이 필요 없는 93개 스텝에서 툴을 부르지 않고 답했는지. SFT의 오류 7건은 답해야 할 때
get_today5회,web_fetch2회를 부른 경우입니다 (Base는 주로ask_agent7회,create_event3회).
사용법 · Usage
llama.cpp / Ollama (GGUF, 권장)
hf download sciencemj/argos-harness-qwen3.5-4b gguf/Qwen3.5-4B.Q4_K_M.gguf --local-dir .
# OpenAI 호환 서버 (툴 호출 파싱 포함)
llama-server -m gguf/Qwen3.5-4B.Q4_K_M.gguf --jinja -c 8192 --chat-template-kwargs '{"enable_thinking":false}'
학습 데이터의 어시스턴트 턴은 빈 <think></think> 블록을 쓰므로, enable_thinking=false로 서빙하는 것을 권장합니다.
system 프롬프트와 툴 스키마가 약 4k 토큰이므로 컨텍스트는 8k 이상으로 잡으세요.
Argos 설정 → 모델 연결에서: 종류 openai (OpenAI 호환), 주소 http://127.0.0.1:8080/v1, 에이전트 백엔드 native.
PEFT + Transformers
import json
from peft import PeftModel
from transformers import AutoModelForImageTextToText, AutoTokenizer
base_id = "unsloth/Qwen3.5-4B"
tok = AutoTokenizer.from_pretrained("sciencemj/argos-harness-qwen3.5-4b")
model = AutoModelForImageTextToText.from_pretrained(base_id, torch_dtype="auto", device_map="auto")
model = PeftModel.from_pretrained(model, "sciencemj/argos-harness-qwen3.5-4b")
tools = [...] # OpenAI-style tool schemas, e.g. argos.sft_export.tool_specs()
messages = [
{"role": "system", "content": "You are Argos, the user's study/project assistant. Use tools when needed."},
{"role": "user", "content": "내일 오후 3시에 운영체제 스터디 일정 잡아줘."},
]
# 과거 assistant 턴의 tool_calls[].function.arguments는 dict여야 합니다 (위의 학습 시 주의점 2 참고).
inputs = tok.apply_chat_template(messages, tools=tools, add_generation_prompt=True,
enable_thinking=False, return_tensors="pt").to(model.device)
out = model.generate(inputs, max_new_tokens=512)
print(tok.decode(out[0][inputs.shape[-1]:], skip_special_tokens=False))
Unsloth (4-bit, 8GB GPU)
from unsloth import FastLanguageModel
model, tok = FastLanguageModel.from_pretrained("sciencemj/argos-harness-qwen3.5-4b", max_seq_length=8192, load_in_4bit=True)
FastLanguageModel.for_inference(model)
재현 · Reproduce
# 학습 (8GB GPU)
uv run python train_sft.py --model unsloth/Qwen3.5-4B --train-file train.jsonl --eval-file eval.jsonl \
--output-dir outputs/qwen3.5-4b --max-seq-length 4736 --batch-size 1 --grad-accum 8 --epochs 2 --lr 2e-4 \
--wandb-project argos-sft
# 평가 (llama-server를 :8081에 띄운 뒤)
uv run python eval_harness.py --eval-file eval.jsonl --base-url http://127.0.0.1:8081/v1 --api-key x \
--model argos-qwen3.5-4b-sft --timeout 600
한계 · Limitations
- 학습·평가 데이터가 모두 합성 시드 궤적입니다. 실제 사용자 로그의 분포(긴 대화, 모호한 요청, 큰 툴 출력)에서는 수치가 낮을 수 있습니다. eval loss 0.003은 템플릿화된 데이터를 거의 외웠다는 뜻이기도 합니다.
- 툴 이름은 거의 완벽하게 고르지만, 인자 값(glob 패턴, 채널 이름)은 대화 맥락이 애매할 때 틀립니다.
- Argos 29개 툴 스키마에 맞춰 학습했습니다. 다른 툴 세트에서도 base보다 일반 툴콜 능력이 나아진다는 보장은 없습니다.
- 비전 타워는 학습하지 않았습니다(텍스트 전용 SFT).
- 삭제·쓰기 같은 부작용은 모델이 아니라 하네스의 권한 게이트가 막습니다. 이 어댑터를 권한 확인 없이 실행 환경에 연결하지 마세요.
- 라이선스는 base model(
Qwen/Qwen3.5-4B, Apache-2.0)을 따릅니다.
Framework versions
- PEFT 0.21.3 · TRL 1.15.0 · Transformers 5.17.0 · Unsloth 2026.11.6 · PyTorch 2.14.1 (CUDA 13.0)
- llama.cpp (GGUF export & eval serving)