우리 팀만의 vLLM 플러그인 만들기 2편 - 모델 변환부터 배포까지 AI-native로 자동화하기

vLLM 플러그인 2편으로, Hugging Face 모델을 vLLM 으로 변환하는 절차 자체를 Claude Code Skill 로 만들고 두 번의 시행착오를 거쳐 다듬어 온 기록이다. 모델 7개를 같은 절차로 변환했고, 지식 전달에 드는 호출당 토큰을 6,900개에서 170개로 97% 줄였다.

핵심 포인트

모델 변환은 단순 코드 마이그레이션이 아니다. 가중치는 유지하되 구현을 vLLM 실행 방식에 맞게 다시 쓰는 일이라 모델과 서빙 인프라 양쪽 지식이 필요하다.
그래서 모델 개발자 혼자도, MLOps 엔지니어 혼자도 하기 어렵다. 전자는 vLLM 풀링 인터페이스·IO Processor 를 모르고 후자는 가중치 구조와 Transformers·vLLM 구현의 미묘한 차이를 모른다.
여기에 vLLM 이 약 2주 간격으로 새 버전을 내며 인터페이스가 계속 바뀐다(3년간 v0.1 → v0.20). 사람이 매번 따라가기 어렵다.
`convert-vllm` 스킬은 다섯 하위 스킬로 나뉜다. 환경 구성 → 모델 변환 → IO Processor 개발 → 테스트·벤치마크 → MLflow 등록·PR 생성.
첫 모델에서 정리한 규칙 5개가 일곱 번째 모델을 거치며 **45개**로 늘었고, 축적된 규칙이 다음 변환에 쓰이며 점점 빨라졌다.

상세 정리

완전 자동이 아니라 협업 장치를 둘 설계했다.
① `plan.md` 승인 게이트: 처음부터 끝까지 맡기면 잘못된 판단을 늦게 발견하므로, 실행 전에 계획을 문서로 쓰게 하고 사람이 승인한 뒤에만 구현을 시작한다. 각 단계가 끝날 때마다 결과를 다시 확인한다.
② 구현과 검증의 컨텍스트 분리: **변환을 수행한 에이전트가 자기 결과를 검증할 때 자기 구현을 맞다고 전제해 오류를 놓치는 경향**을 관찰했다. 그래서 테스트 작성과 결과 검증은 별도 컨텍스트의 하위 에이전트가 맡는다.
`convert-model` 단계는 `config.json` 을 분석해 생성·풀링·분류 등 모델 유형을 판단하고, vLLM 용 설정 클래스·모델 클래스·가중치 적재 코드·등록 코드를 작성한다.
`develop-io-processor` 는 풀링 모델 등 일부에만 필요해 모델 유형에 따라 실행 여부가 자동으로 결정된다.
`test-and-benchmark` 의 핵심은 동등성(parity) 검증, 즉 Hugging Face 원본과 vLLM 변환본이 같은 출력을 내는지 확인하는 것이다.
변환 대상은 분류·NER·임베딩·ABSA·이미지 스코어링 등 서로 다른 유형 7개였다.
**시행착오 ① — 도구가 변하면 스킬도 변해야 한다**: 초기 버전에는 체크포인트 4개와 상태 필드 9개가 있었다. 당시 Claude Code 컨텍스트 상한이 200K 라 한 단계만 실행해도 가득 차, `--from=step` 으로 재개해야 했다.
1M 컨텍스트가 되자 전제가 무너졌다. 같은 변환이 압축 없이 한 세션에서 끝났고, 체크포인트를 제거하니 `SKILL.md` 가 492줄 → 332줄로 **33% 감소**했다. 세션당 5회 이상이던 컨텍스트 압축은 사라졌다.
즉 SKILL.md 의 3분의 1은 모델 변환 지식이 아니라 당시 컨텍스트 한계를 우회하는 임시 구조였고, 제약이 사라진 뒤에도 남아 복잡도만 높이고 있었다.
이 문제가 일회성이 아니라는 점도 짚는다. 최근 Claude 모델이 Opus 4.6 → 4.7 로 바뀌며 4.6 에서 동작하던 스킬 일부가 멈춘 사례가 있었다. **"기술 부채는 소스 코드에만 생기지 않는다."**
**시행착오 ② — 무엇을·언제·얼마나 줄지 설계해야 한다**: 처음에는 Claude Code 훅으로 도구 호출 직전마다 팀 지식 베이스 전체를 컨텍스트에 넣었다.
그 결과 호출당 약 6,900토큰이 추가됐고 22회 반복하면 같은 지식이 중복돼 약 15만 2천 토큰을 차지했다.
더 큰 문제는 양이 아니라 적합성이었다. 풀링 모델을 변환하는 중에 생성·임베딩·재순위화 규칙이 함께 들어가 에이전트가 엉뚱한 규칙을 참조하는 일이 생겼다.
결론이 분명하다. 컨텍스트 상한이 1M 으로 커져도 정보가 많아질수록 중요한 내용에 대한 주의가 분산되는 현상(attention dilution)은 남는다.
그래서 필요한 지식만 골라 읽는 스킬 방식으로 바꿔 호출당 170토큰으로 줄이면서 같은 목표를 더 잘 달성했다.
마지막으로 이 협업 방식을 저장소 경계 너머로 확장해, 사용자가 GitHub Issue 하나를 작성하면 변환부터 배포까지 이어지는 E2E 파이프라인을 만들었다.