최신 AI 에이전트 스킬 21선 7편, 로컬 모델을 직접 돌리고 배포하기

6편까지 문서를 다뤘다. 마지막 7편은 모델 그 자체다. 직접 돌리고, 배포하고, 가져온다. 세 스킬이 각각 그 단계 하나를 맡는다.

여기서부터는 다른 편과 성격이 다르다. 앞의 스킬들은 텍스트로 된 절차였다. 이 편은 하드웨어가 개입한다. VRAM이 몇 기가바이트 남았는지가 답을 바꾼다.

1. llama-cpp (v2.1.2)

mlops/inference 카테고리. Orchestra Research가 만들었다. 버전이 2.1.2로 가장 높다.

llama.cpp local GGUF inference + HF Hub model discovery.

언제 쓰는지

- CPU, Apple Silicon, CUDA, ROCm, Intel GPU에서 로컬 모델 실행
- 특정 Hugging Face 저장소에서 맞는 GGUF를 찾기
- Hub에서 llama-server나 llama-cli 명령을 만들기
- llama.cpp를 이미 지원하는 Hub 모델 검색
- 저장소에 있는 .gguf 파일과 크기 열거
- RAM이나 VRAM에 맞춰 Q4/Q5/Q6/IQ 변종 선택

다섯 번째 항목이 이 스킬을 만든 이유다. 모델을 고르는 게 어려운 게 아니라 양자화 단계를 고르는 게 어렵다.

모델 탐색은 URL부터

스킬이 지시를 한다.

hf, 파이썬, 커스텀 스크립트를 쓰기 전에 URL 경로를 우선한다.

1단계는 검색이다.

https://huggingface.co/models?apps=llama.cpp&sort=trending

모델 계열을 찾으려면 search=<term>을 붙인다. 크기 제한이 있으면 num_parameters=min:0,max:24B 같은 걸 쓴다.

2단계는 저장소 로컬 앱 뷰다.

https://huggingface.co/<repo>?local-app=llama.cpp

3단계부터가 이 스킬의 정수다.

로컬 앱 스니펫이 보이면 그것을 진실로 본다.
- 정확한 llama-server 또는 llama-cli 명령을 그대로 복사한다
- 권장 양자화를 HF에 표시된 대로 정확히 보고한다

여기서 "그대로 복사"가 중요하다. 사람이 읽고 자기 방식으로 고쳐 쓰는 순간 틀린다. HF가 그 저장소에 대해 계산한 명령이 저기 있다.

4단계는 하드웨어 호환 섹션을 읽는다.

Hardware compatibility 섹션에서 정확한 양자화 라벨과 크기를 우선한다.
범용 표보다 그 저장소 고유 라벨을 선호한다 (UD-Q4_K_M, IQ4_NL_XL 같은 것).
보이지 않으면 그 사실을 말하고 트리 API와 범용 가이드로 넘어간다.

5단계는 트리 API로 실제 존재를 확인한다.

https://huggingface.co/api/models/<repo>/tree/main?recursive=true
type이 "file"이고 path가 .gguf로 끝나는 항목만 남긴다.
path와 size를 파일명과 바이트 크기의 진실로 쓴다.
양자화 체크포인트와 mmproj-*.gguf 프로젝터 파일, BF16/ 샤드 파일을 분리한다.

여기서 mmproj 분리가 핵심이다. 비전 모델 저장소를 보면 프로젝터 파일이 몇 개 나온다. 이건 주 모델 파일이 아니다. 프로젝터까지 내려받으면 용량 두 배가 되고 에이전트는 그 사실을 모른다. 스킬이 명시적으로 분리하라고 한다.

6단계는 스니펫이 안 보일 때 복원한다.

# 축약 형태
llama-server -hf <repo>:<QUANT>

# 정확한 파일로
llama-server --hf-repo <repo> --hf-file <filename.gguf>

7단계가 마지막 가드다.

저장소가 이미 GGUF를 노출하지 않을 때만 Transformers 가중치 변환을 제안한다.

변환은 느리고 환경에 따라 품질이 떨어진다. GGUF가 이미 있는 저장소를 변환할 이유는 없다.

양자화 고르는 순서

스킬이 우선순위를 명시한다. 허프 페이지 먼저, 일반 휴리스틱은 두 번째.

- 사용자의 하드웨어 프로파일에 호환된다고 HF가 표시한 정확한 양자화를 선호한다
- 일반 채팅이면 Q4_K_M에서 시작
- 코드나 기술 작업이면 메모리가 되면 Q5_K_M 또는 Q6_K를 선호
- RAM이 아주 빠듯하면 Q3_K_M, IQ 변종, Q2 변종. 단 사용자가 적합을 품질보다 명시적으로 우선시한 경우에만
- 멀티모달 저장소는 mmproj-*.gguf를 별도로 언급한다. 프로젝터는 주 모델 파일이 아니다
- 저장소 고유 라벨을 정규화하지 않는다. 페이지가 UD-Q4_K_M라고 하면 UD-Q4_K_M로 보고한다

마지막 줄이 실전에서 시간을 아낀다. UD-Q4_K_M를 그냥 Q4_K_M으로 적으면 존재하지 않는 파일을 찾게 된다. 언더더로 정밀도를 올린 변종이라 성능이 더 좋은데, 이름을 정규화하면 그 이득을 잃는다.

여기서 하나 짚을 게 있다. 이 스킬의 v2.1.2는 탐색 절차가 정교하다. 에이전트가 "9B 모델 Q4_K_M으로 받아줘"라고 하면 어쨌든 아무거나 받아오기 쉽다. 이 스킬은 그걸 안 하게 만드는 장치다.

2. serving-llms-vllm (v1.0.1)

mlops/inference 카테고리. Orchestra Research.

vLLM: high-throughput LLM serving, OpenAI API, quantization.

언제 쓰는지

프로덕션 LLM API를 배포할 때, 추론 지연·처리량을 최적화할 때,
GPU 메모리가 제한된 상태에서 모델을 서빙할 때

처리량이 왜 다르냐면

vLLM은 PagedAttention(블록 기반 KV 캐시)과 continuous batching
(prefill과 decode 요청을 섞는 기법) 덕분에 표준 transformers 대비
24배 높은 처리량을 달성한다.

두 기법이 각각 다른 병목을 푼다. PagedAttention은 KV 캐시를 연속 메모리가 아니라 블록으로 관리해서 파편화 없애고 캐시 사용률을 올린다. continuous batching은 한 요청이 끝나야 다음 요청이 시작되는 걸 무시하고, decode 중인 요청 옆에 새 요청을 끼워 넣는다. 트래픽이 들어올수록 차이가 벌어진다.

기본 사용법

pip install vllm

오프라인 추론.

from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/Meta-Llama-3-8B-Instruct")
sampling = SamplingParams(temperature=0.7, max_tokens=256)

outputs = llm.generate(["Explain quantum computing"], sampling)
print(outputs[0].outputs[0].text)

OpenAI 호환 서버.

vllm serve meta-llama/Meta-Llama-3-8B-Instruct

from openai import OpenAI
client = OpenAI(base_url='http://localhost:8000/v1', api_key='EMPTY')
print(client.chat.completions.create(
    model='meta-llama/Meta-Llama-3-8B-Instruct',
    messages=[{'role': 'user', 'content': 'Hello!'}]
).choices[0].message.content)

api_key='EMPTY'가 눈에 띈다. 인증 없이 아무 문자열이나 받는다. 이건 로컬과 사내망 전용이다. 스킬이 그렇게 말하고 production 배포 예시를 앞에 둔다.

언제 뭘 쓰냐

이 스킬이 표로 정리해준다. 이 표가 이 편에서 제일 실용적이다.

앞의 여섯 편에서 다룬 스킬이 표에 들어있다. llama.cpp이 CPU·엣지 쪽이고 transformers가 연구 쪽이다. 그러니까 이 스킬 하나가 고르면 나머지 둘의 위치가 정해진다.

메모리 부족이 가장 흔한 문제

vllm serve MODEL \
  --gpu-memory-utilization 0.7 \
  --max-model-len 4096

VRAM이 모자나서 모델이 안 올라갈 때의 해법이다. GPU 메모리 사용률 상한을 내리고 컨텍스트 길이를 줄인다. 컨텍스트 길이가 KV 캐시 크기를 그대로 결정하므로 여기서 값을 내리는 게 가장 효과가 크다.

양자화(GPTQ, AWQ, FP8)를 쓸 수도 있다. 스킬이 지원 목록에 넣었다.

하드웨어 요구

- 소형 (7B~13B): A10 1장 (24GB) 또는 A100 1장 (40GB)
- 중형 (30B~40B): A100 2장 (40GB), 텐서 병렬 사용
- 대형 (70B 이상): A100 4장 (40GB) 또는 2장 (80GB), AWQ/GPTQ 사용

지원 플랫폼은 NVIDIA가 1순위고 AMD ROCm, Intel GPU, TPU가 뒤따른다. 즉 NVIDIA가 아니면 vLLM은 근거가 약하다. 그때는 llama.cpp가 맞다.

3. huggingface-hub (v1.0.1)

mlops 카테고리. Hugging Face가 직접 만들었다. 세 스킬 중 유일하게 공식 문서 소속이다.

HuggingFace hf CLI: search/download/upload models, datasets.

설치부터 짧다.

curl -LsSf https://hf.co/cli/install.sh | bash -s

그리고 스킬이 경고한다.

IMPORTANT: hf 명령은 이제 deprecated된 huggingface-cli를 대체한다.

옛 스크립트를 그대로 쓰면 명령을 못 찾는다. 게다가 huggingface-cli download는 여전히 설치된 환경이 많다. 이 구분이 헷갈리는데 새 명령으로 통일하라고 명시돼 있다.

인증은 HF_TOKEN 환경변수나 --token 플래그를 권한다.

핵심 명령

hf download REPO_ID      Hub에서 파일 다운로드
hf upload REPO_ID        파일·폴더 업로드 (단일 커밋 권장, 큰 디렉터리는 재개 가능 업로드 처리)
hf upload-large-folder   [Deprecated] — hf upload를 쓸 것
hf sync                 로컬 디렉터리와 버킷 사이 동기화
hf env / hf version     환경·버전 확인

upload-large-folder가 deprecated로 표시돼 있는 게 중요하다. 예전 가이드를 따라가면 그 명령을 쓰게 된다.

저장소 관리

create / delete      저장소 생성·영구 삭제
duplicate            모델·데이터셋·Space를 새 ID로 복제
move                 네임스페이스 간 이동
branch / tag         Git 같은 참조 관리
delete-files         패턴으로 특정 파일 삭제

duplicate가 특히 유용하다.남의 저장소를 베이스로 파생 모델을 만들 때 쓴다. 포크보다 명확하다.

전문 허브 기능

Datasets: hf datasets list, info, parquet
SQL:     hf datasets sql SQL — 데이터셋 parquet URL에 DuckDB로 raw SQL 실행
Models:  hf models list, info
Papers:  hf papers ls — 오늘의 논문

hf datasets sql이 눈에 띈다. 파quet URL에 직접 SQL을 던진다. 데이터셋을 로컬에 안 받고 질의할 수 있다. 규모가 큰 데이터셋을 훑을 때 이게 빠르다.

Discussions와 PR.

list, create, info, comment, close, reopen, rename
diff    PR 변경 보기
merge   PR 확정

자신이 만든 모델 저장소에 사람들이 이슈를 남기는 그 흐름을 CLI로 다룬다.

인프라와 컴퓨트.

Endpoints: deploy, pause, resume, scale-to-zero, catalog
Jobs:     hf jobs uv (인라인 의존성으로 파이썬 실행), stats (자원 모니터링)
Spaces:   dev-mode, 핫 리로드

scale-to-zero가 실용적이다. Inference Endpoint를 쓰는 순간에만 비용을 내는 방식이다. 평소에는 꺼둔다.

저장소와 자동화.

Buckets:    create, cp, mv, rm, sync
Cache:      list, prune(떨어진 리비전 제거), verify(체크섬)
Webhooks:   create, watch, enable/disable
Collections: add-item, update, list

cache prune이 디스크 정리에서 유용하다. 나중에 하지만 모델 여러 개 받으면 캐시가 수십 GB가 된다.

전역 플래그

--format json    기계가 읽는 출력
-q / --quiet    ID만 출력

에이전트에게 --format json은 거의 필수다. 사람이 읽을 로그를 파싱하려고 하면 형식이 깨진다. 그리고 출력량을 줄이는 게 컨텍스트 절약이다.

확장도 있다.

Extensions: hf extensions install REPO_ID (GitHub 저장소에서 CLI 기능 확장)

이번 편 정리

셋이 국소에서 배포까지 이어지는 한 줄을 만든다. Hub에서 찾고(3), 양자화 단계를 골라 내려받고(1), 필요하면 고처리량으로 배포한다(2).

그리고 이 편이 다른 편과 다른 점이 하나 있다. 나머지 여섯 편은 "잘하기 위한 방법"을 다뤘고, 이 편은 "무엇을 골라야 하는가"를 다뤘다. 양자화 단계를 고르고, vLLM인지 llama.cpp인지 고르고, 하드웨어가 받쳐 주는지 확인한다. 기술 선택에는 정답이 없다. 대신 틀린 선택의 비용만 있다.

21선 전체 목록

여기까지 21개를 모두 다뤘다. 시리즈를 돌아보며 다시 묶으면 이렇다.

1편  스킬 basics        hermes-agent-skill-authoring, plan, computer-use
2편  코딩 위임          delegate-coding, delegate-debugging, test-driven-development
3편  디버깅            systematic-debugging, python-debugpy, node-inspect-debugger
4편  품질 관리          requesting-code-review, codebase-inspection, code-reference
5편  리서치            deep-web-investigation, grounded-citations, research-paper-writing
6편  문서·노트         notion, obsidian, nano-pdf
7편  모델 운영         llama-cpp, serving-llms-vllm, huggingface-hub

1편에서 스킬이 뭔지정의를 잡았고, 7편에서 모델을 고르는 법까지 왔는데 중간의 다섯 편은 전부 그 사이의 실무다. 위임하고, 검증하고, 고치고, 점검하고, 인용하고, 문서를 다루는 것.

여기서 공통으로 보인 게 하나 있다. 이 스킬들 다 에이전트가 사고 치는 지점을 미리 차단하도록 만들어졌다. 4편의 diff 안의 지시문, 5편의 원장 없는 인용, 6편의 공유 안 한 페이지가 404를 뱉는 일. 전부 "에이전트가 모르고 지나갈 지점"이다. 그 지점들을 하나씩 막아놓은 게 스킬의 정체다.