--- title: "최신 AI 에이전트 스킬 21선 7편, 로컬 모델을 직접 돌리고 배포하기" date: 2026-10-01 model: hermes-agent category: guide summary: 에이전트 스킬 21선 마지막 편이다. GGUF 양자화 선택과 llama.cpp 로컬 추론, vLLM 고처리량 서빙, Hugging Face CLI를 정리한다. tags: agent-skills, llama-cpp, vllm, huggingface, quantization, guide author_type: human --- 6편까지 문서를 다뤘다. 마지막 7편은 모델 그 자체다. 직접 돌리고, 배포하고, 가져온다. 세 스킬이 각각 그 단계 하나를 맡는다. 여기서부터는 다른 편과 성격이 다르다. 앞의 스킬들은 텍스트로 된 절차였다. 이 편은 하드웨어가 개입한다. VRAM이 몇 기가바이트 남았는지가 답을 바꾼다. ## 1. llama-cpp (v2.1.2) `mlops/inference` 카테고리. Orchestra Research가 만들었다. 버전이 2.1.2로 가장 높다. ```text llama.cpp local GGUF inference + HF Hub model discovery. ``` ### 언제 쓰는지 ```text - 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부터 스킬이 지시를 한다. ```text hf, 파이썬, 커스텀 스크립트를 쓰기 전에 URL 경로를 우선한다. ``` 1단계는 검색이다. ```text https://huggingface.co/models?apps=llama.cpp&sort=trending ``` 모델 계열을 찾으려면 `search=`을 붙인다. 크기 제한이 있으면 `num_parameters=min:0,max:24B` 같은 걸 쓴다. 2단계는 저장소 로컬 앱 뷰다. ```text https://huggingface.co/?local-app=llama.cpp ``` 3단계부터가 이 스킬의 정수다. ```text 로컬 앱 스니펫이 보이면 그것을 진실로 본다. - 정확한 llama-server 또는 llama-cli 명령을 그대로 복사한다 - 권장 양자화를 HF에 표시된 대로 정확히 보고한다 ``` 여기서 "그대로 복사"가 중요하다. 사람이 읽고 자기 방식으로 고쳐 쓰는 순간 틀린다. HF가 그 저장소에 대해 계산한 명령이 저기 있다. 4단계는 하드웨어 호환 섹션을 읽는다. ```text Hardware compatibility 섹션에서 정확한 양자화 라벨과 크기를 우선한다. 범용 표보다 그 저장소 고유 라벨을 선호한다 (UD-Q4_K_M, IQ4_NL_XL 같은 것). 보이지 않으면 그 사실을 말하고 트리 API와 범용 가이드로 넘어간다. ``` 5단계는 트리 API로 실제 존재를 확인한다. ```text https://huggingface.co/api/models//tree/main?recursive=true type이 "file"이고 path가 .gguf로 끝나는 항목만 남긴다. path와 size를 파일명과 바이트 크기의 진실로 쓴다. 양자화 체크포인트와 mmproj-*.gguf 프로젝터 파일, BF16/ 샤드 파일을 분리한다. ``` 여기서 `mmproj` 분리가 핵심이다. 비전 모델 저장소를 보면 프로젝터 파일이 몇 개 나온다. 이건 주 모델 파일이 아니다. 프로젝터까지 내려받으면 용량 두 배가 되고 에이전트는 그 사실을 모른다. 스킬이 명시적으로 분리하라고 한다. 6단계는 스니펫이 안 보일 때 복원한다. ```bash # 축약 형태 llama-server -hf : # 정확한 파일로 llama-server --hf-repo --hf-file ``` 7단계가 마지막 가드다. ```text 저장소가 이미 GGUF를 노출하지 않을 때만 Transformers 가중치 변환을 제안한다. ``` 변환은 느리고 환경에 따라 품질이 떨어진다. GGUF가 이미 있는 저장소를 변환할 이유는 없다. ### 양자화 고르는 순서 스킬이 우선순위를 명시한다. 허프 페이지 먼저, 일반 휴리스틱은 두 번째. ```text - 사용자의 하드웨어 프로파일에 호환된다고 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. ```text vLLM: high-throughput LLM serving, OpenAI API, quantization. ``` ### 언제 쓰는지 ```text 프로덕션 LLM API를 배포할 때, 추론 지연·처리량을 최적화할 때, GPU 메모리가 제한된 상태에서 모델을 서빙할 때 ``` ### 처리량이 왜 다르냐면 ```text vLLM은 PagedAttention(블록 기반 KV 캐시)과 continuous batching (prefill과 decode 요청을 섞는 기법) 덕분에 표준 transformers 대비 24배 높은 처리량을 달성한다. ``` 두 기법이 각각 다른 병목을 푼다. PagedAttention은 KV 캐시를 연속 메모리가 아니라 블록으로 관리해서 파편화 없애고 캐시 사용률을 올린다. continuous batching은 한 요청이 끝나야 다음 요청이 시작되는 걸 무시하고, decode 중인 요청 옆에 새 요청을 끼워 넣는다. 트래픽이 들어올수록 차이가 벌어진다. ### 기본 사용법 ```bash pip install vllm ``` 오프라인 추론. ```python 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 호환 서버. ```bash vllm serve meta-llama/Meta-Llama-3-8B-Instruct ``` ```python 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 배포 예시를 앞에 둔다. ### 언제 뭘 쓰냐 이 스킬이 표로 정리해준다. 이 표가 이 편에서 제일 실용적이다. | 상황 | 도구 | | --- | --- | | 프로덕션 API 배포 (초당 100건 이상) | vLLM | | OpenAI 호환 엔드포인트 | vLLM | | GPU 메모리는 부족한데 큰 모델 필요 | vLLM | | 다중 사용자 애플리케이션 | vLLM | | CPU·엣지 추론, 단일 사용자 | llama.cpp | | 연구, 프로토타이핑, 일회성 생성 | transformers | | NVIDIA 전용, 절대 최고 성능 필요 | TensorRT-LLM | | 이미 허프 생태계를 쓰고 있음 | TGI | 앞의 여섯 편에서 다룬 스킬이 표에 들어있다. llama.cpp이 CPU·엣지 쪽이고 transformers가 연구 쪽이다. 그러니까 이 스킬 하나가 고르면 나머지 둘의 위치가 정해진다. ### 메모리 부족이 가장 흔한 문제 ```bash vllm serve MODEL \ --gpu-memory-utilization 0.7 \ --max-model-len 4096 ``` VRAM이 모자나서 모델이 안 올라갈 때의 해법이다. GPU 메모리 사용률 상한을 내리고 컨텍스트 길이를 줄인다. 컨텍스트 길이가 KV 캐시 크기를 그대로 결정하므로 여기서 값을 내리는 게 가장 효과가 크다. 양자화(GPTQ, AWQ, FP8)를 쓸 수도 있다. 스킬이 지원 목록에 넣었다. ### 하드웨어 요구 ```text - 소형 (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가 직접 만들었다. 세 스킬 중 유일하게 공식 문서 소속이다. ```text HuggingFace hf CLI: search/download/upload models, datasets. ``` 설치부터 짧다. ```bash curl -LsSf https://hf.co/cli/install.sh | bash -s ``` 그리고 스킬이 경고한다. ```text IMPORTANT: hf 명령은 이제 deprecated된 huggingface-cli를 대체한다. ``` 옛 스크립트를 그대로 쓰면 명령을 못 찾는다. 게다가 `huggingface-cli download`는 여전히 설치된 환경이 많다. 이 구분이 헷갈리는데 새 명령으로 통일하라고 명시돼 있다. 인증은 `HF_TOKEN` 환경변수나 `--token` 플래그를 권한다. ### 핵심 명령 ```text 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로 표시돼 있는 게 중요하다. 예전 가이드를 따라가면 그 명령을 쓰게 된다. ### 저장소 관리 ```text create / delete 저장소 생성·영구 삭제 duplicate 모델·데이터셋·Space를 새 ID로 복제 move 네임스페이스 간 이동 branch / tag Git 같은 참조 관리 delete-files 패턴으로 특정 파일 삭제 ``` `duplicate`가 특히 유용하다.남의 저장소를 베이스로 파생 모델을 만들 때 쓴다. 포크보다 명확하다. ### 전문 허브 기능 ```text 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. ```text list, create, info, comment, close, reopen, rename diff PR 변경 보기 merge PR 확정 ``` 자신이 만든 모델 저장소에 사람들이 이슈를 남기는 그 흐름을 CLI로 다룬다. 인프라와 컴퓨트. ```text Endpoints: deploy, pause, resume, scale-to-zero, catalog Jobs: hf jobs uv (인라인 의존성으로 파이썬 실행), stats (자원 모니터링) Spaces: dev-mode, 핫 리로드 ``` `scale-to-zero`가 실용적이다. Inference Endpoint를 쓰는 순간에만 비용을 내는 방식이다. 평소에는 꺼둔다. 저장소와 자동화. ```text Buckets: create, cp, mv, rm, sync Cache: list, prune(떨어진 리비전 제거), verify(체크섬) Webhooks: create, watch, enable/disable Collections: add-item, update, list ``` `cache prune`이 디스크 정리에서 유용하다. 나중에 하지만 모델 여러 개 받으면 캐시가 수십 GB가 된다. ### 전역 플래그 ```text --format json 기계가 읽는 출력 -q / --quiet ID만 출력 ``` 에이전트에게 `--format json`은 거의 필수다. 사람이 읽을 로그를 파싱하려고 하면 형식이 깨진다. 그리고 출력량을 줄이는 게 컨텍스트 절약이다. 확장도 있다. ```text Extensions: hf extensions install REPO_ID (GitHub 저장소에서 CLI 기능 확장) ``` ## 이번 편 정리 | 스킬 | 버전 | 하는 일 | | --- | --- | --- | | llama-cpp | 2.1.2 | GGUF 양자화 선택과 llama.cpp 로컬 추론, URL 우선 탐색 | | serving-llms-vllm | 1.0.1 | PagedAttention·continuous batching 고처리량 서빙 | | huggingface-hub | 1.0.1 | hf CLI로 모델·데이터셋 검색·다운로드·업로드 | 셋이 국소에서 배포까지 이어지는 한 줄을 만든다. Hub에서 찾고(3), 양자화 단계를 골라 내려받고(1), 필요하면 고처리량으로 배포한다(2). 그리고 이 편이 다른 편과 다른 점이 하나 있다. 나머지 여섯 편은 "잘하기 위한 방법"을 다뤘고, 이 편은 "무엇을 골라야 하는가"를 다뤘다. 양자화 단계를 고르고, vLLM인지 llama.cpp인지 고르고, 하드웨어가 받쳐 주는지 확인한다. 기술 선택에는 정답이 없다. 대신 틀린 선택의 비용만 있다. ## 21선 전체 목록 여기까지 21개를 모두 다뤘다. 시리즈를 돌아보며 다시 묶으면 이렇다. ```text 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를 뱉는 일. 전부 "에이전트가 모르고 지나갈 지점"이다. 그 지점들을 하나씩 막아놓은 게 스킬의 정체다.