Read Original
#DevOps

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

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

Summary

호출당 토큰 97% 절감! GitHub Issue 하나로 모델 변환부터 KServe 배포까지 끝내는 AI-native 파이프라인 구축기

Claude Code Skill과 GitOps를 결합해 복잡한 vLLM 모델 변환과 배포 프로세스를 분산형 지식 협업 구조로 자동화한 여정

본 아티클은 검색·추천 모델을 vLLM용 사용자 정의 플러그인으로 마이그레이션한 후, 모델 변환 및 배포의 까다로운 과정을 AI 에이전트로 완전 자동화한 경험을 다룹니다. 개발자들은 Claude Code Skill을 기반으로 복잡한 다섯 단계의 변환 흐름을 설계하고, 시행착오를 통해 컨텍스트 낭비를 줄이며 '스킬 기반 지식 호출 패턴'을 완성했습니다. 나아가 이 패턴을 GitOps 배포 환경과 결합하여 GitHub Issue 템플릿 하나로 E2E 배포를 달성한 구체적인 아키텍처와 인사이트를 제공합니다.

  • 01Hugging Face 모델의 vLLM 가중치 매핑 및 구조 변환을 자동화하는 5단계 convert-vllm Claude Code 스킬 설계
  • 02안정성 확보를 위해 plan.md 승인 게이트와 구현 및 검증 담당 에이전트의 실행 컨텍스트 분리 구현
  • 03컨텍스트 한계 우용을 위해 설계되었던 체크포인트 아키텍처를 제거하여 스킬 코드 33% 경량화 및 부채 해소
  • 04전체 지식을 통째로 넣는 훅 방식 대신 필요한 규칙만 선택 로딩하는 스킬 방식으로 전환하여 호출당 토큰 97% 절감
  • 05Supabase의 agent-skills 패턴을 차용하고 vllm_version과 검증 소스 코드 정보를 메타데이터로 추가해 규칙 신뢰성 극대화

RECOMMENDATION

vLLM 기반의 LLM/ML 모델 서빙 가속화에 관심이 있는 MLOps 팀이나, 복잡한 인프라 배포 프로세스를 AI 에이전트 및 GitOps와 결합하여 혁신하고자 하는 플랫폼 엔지니어들에게 적극 추천합니다.

The Problem

Hugging Face 모델을 vLLM 서빙 환경에 맞춰 변환하는 작업은 모델 가중치 매핑과 vLLM 인프라 패턴 양측의 지식이 필요하여 공백이 존재하고, 프레임워크가 2주 간격으로 빠르게 바뀌어 대응이 어렵다. 또한 초기 자동화 도입 당시에는 LLM의 컨텍스트 제약으로 복잡한 체크포인트 상태 관리 로직을 구현해야 했으며, 전체 지식을 강제로 컨텍스트에 주입하는 훅 방식이 심각한 토큰 낭비와 에이전트의 주의력 분산 문제를 유발했다.

The Solution

Claude Code Skill을 활용하여 모델 및 개발 환경 구축, 코드 변환, 입출력 프로세서 개발, 동등성 검증 및 벤치마크, PR 생성까지 이어지는 5단계 자동화 흐름인 convert-vllm 스킬을 구축했다. 도구의 컨텍스트 한계 극복에 맞춰 체크포인트 코드를 완전 제거하고, 전체 지식을 밀어 넣는 방식 대신 에이전트가 필요할 때 특정 지식 규칙만 선택해서 로드하는 스킬 기반 지식 전달 방식을 설계하였으며, 원격 저장소에서 플러그인을 불러올 수 있는 스킬 마켓플레이스 패턴으로 확장했다.

The Result

서로 다른 유형의 복잡한 모델 7개를 동일한 E2E 절차를 거쳐 안정적으로 가속 서빙 인프라에 배포하고, 변환 중 식별한 주의 사항을 45개의 실무 규칙 지식으로 정교화하여 축적했다. 에이전트 지식 호출에 소모되던 토큰 수를 기존 6,900개에서 170개로 97% 대폭 절감하였으며, 결과적으로 사용자가 GitHub Issue 하나만 생성하면 자동으로 배포 PR 생성까지 끝나는 AI-native 파이프라인을 완성했다.

Trade-off

AI 도구가 수시로 업데이트되고 새로운 모델 버전이 출시될 때마다 기존에 정상 동작하던 지식이나 스킬 코드의 일부가 비정상 작동할 수 있어 지속적인 관리 및 엔지니어링 리소스가 요구된다. 아울러 완전한 자율 에이전트 구동 대신 기획 및 동등성 검증의 매 단계에서 인간 엔지니어의 상시 검토와 승인을 거치는 승인 게이트를 활용하므로 인간의 작업 리소스 또한 일부 보수적으로 개입되어야 한다.

03

Key Concepts

Concept · 01

Claude Code Skill

Anthropic의 AI 코딩 에이전트 CLI인 Claude Code에서 반복적인 작업의 흐름과 검증 규칙을 마크다운 파일(SKILL.md)에 선언하여 필요시 에이전트가 이를 스스로 읽고 주도적으로 실행할 수 있게 하는 기능이다.

  • Hugging Face 아티팩트 다운로드부터 최종 배포 가이드 작성 및 PR 생성까지의 5단계 흐름을 convert-vllm 스킬로 정의함
  • 변환 절차 관리 스킬(convert-model)이 상황에 맞춰 베스트 프랙티스 스킬(vllm-best-practices)을 호출해 유기적으로 결합함
Concept · 02

GitOps

Git 저장소를 소프트웨어 시스템 배포의 단일 진실 공급원(SSOT)으로 채택하여, 인프라 및 애플리케이션 설정을 선언적 명세로 관리하고 이를 클러스터 상태와 지속적으로 일치시키는 운영 방식이다.

  • KServe 배포 명세서를 GitOps 저장소 내부에서 변경하고 이를 ArgoCD로 동기화하는 배포 파이프라인의 핵심 도구로 작동함
  • 사용자가 GitHub Issue를 작성하면 에이전트가 이를 분석해 GitOps 저장소에 배포 YAML 변경 PR을 자동으로 생성하도록 통합함
Concept · 03

Skill Marketplace Pattern

스킬을 제공하는 원격 Git 저장소를 마치 마켓플레이스나 라이브러리 패키지처럼 정의하여, 서로 다른 저장소에서 호출 주체가 필요한 스킬과 규칙을 네트워크 너머로 가져와서 사용할 수 있게 구성한 아키텍처 패턴이다.

  • GitOps 저장소 담당자와 vLLM 플러그인 도메인 담당자의 지식 경계를 독립적으로 보호하고 결합도를 제거하기 위해 채택함
  • GitOps 저장소의 배포 자동화 에이전트가 배포 스킬 실행 도중 원격 vLLM 저장소의 서빙 최적화 가이드 플러그인을 호출하여 지식을 조율함