한 줄 정의

llama-cli는 llama.cpp에 들어 있는 터미널용 추론 실행 파일이야. 띄어 쓴 llama cli도 보통 같은 도구를 가리켜. 모델 계열 이름이 아니라, GGUF 파일이나 Hugging Face 저장소를 받아 한 번의 명령으로 로컬에서 답을 뽑아 보는 도구라고 보면 돼.

가장 짧은 차이는 llama-server와 비교하면 보여. llama-cli -m my_model.gguf는 터미널에서 바로 모델을 실행하는 쪽이고, llama-server -hf ...는 앱이 호출할 수 있는 OpenAI 호환 API 서버를 여는 쪽이야. 둘 다 llama.cpp 생태계에 있지만, 첫 테스트와 운영 연결의 자리가 달라.

실제로 무엇을 하나

llama-cli가 하는 일은 모델 파일, 프롬프트, 실행 옵션을 한 명령줄에 묶어 로컬 LLM을 바로 돌리는 거야. llama.cpp README의 빠른 시작은 로컬 파일이면 llama-cli -m my_model.gguf, Hugging Face에서 바로 받을 때는 llama-cli -hf ggml-org/gemma-3-1b-it-GGUF처럼 시작해. GUI 없이도 모델이 열리는지, chat template이 맞는지, 속도와 메모리 조건이 버틸 만한지 먼저 확인할 수 있어.

Qwen 쪽 예시는 더 구체적이야. Qwen3-14B-GGUF 공식 카드는 llama.cpp 저장소 안에서 ./llama-cli -hf Qwen/Qwen3-14B-GGUF:Q8_0 --jinja --color -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 --presence-penalty 1.5 -c 40960 -n 32768 --no-context-shift처럼 실행하는 예시를 둬. 이 한 줄 안에 모델 저장소, 양자화 태그, chat template, GPU offload, 샘플링 값, context 길이, 출력 토큰 한도가 같이 들어가.

그래서 llama-cli는 앱 서버로 운영하기 전에 prompt, 양자화, context window, VRAM 여유를 직접 확인하는 첫 실행 단계에 가까워. 같은 Qwen3-14B라도 Q4_K_M 9GB 파일과 Q8_0 15.7GB 파일은 메모리와 답변 품질 기대가 달라. 먼저 터미널에서 이 조건을 바꿔 보고, 그다음 llama-server나 다른 서빙 런타임으로 옮기는 흐름이 자연스러워.

왜 중요한가

llama-cli가 중요한 이유는 로컬 모델 논의에서 “모델이 좋다”와 “내 장비에서 실제로 열린다” 사이를 빠르게 확인하게 해 주기 때문이야. llama.cpp는 C/C++ 기반 로컬 추론 프로젝트이고, README는 Apple Silicon, x86 AVX 계열, RISC-V, CUDA, HIP, Vulkan, SYCL, CPU+GPU 혼합 실행 같은 하드웨어 폭을 넓게 말해. 하지만 실제로 내 노트북이나 GPU 서버에서 돌아가는지는 명령을 한 번 쳐 봐야 감이 잡혀.

또 하나는 옵션이 결과를 크게 바꾼다는 점이야. llama.cpp는 1.5비트부터 8비트까지 정수 양자화를 다루고, Qwen3-14B-GGUF는 Q4_K_M, Q5_0, Q5_K_M, Q6_K, Q8_0 파일을 나눠 제공해. Q8_0을 고르면 더 큰 파일과 메모리를 쓰고, Q4_K_M을 고르면 시작은 쉬워지지만 품질과 반복 출력은 따로 재야 해. llama-cli는 이 선택을 터미널에서 바로 바꿔 볼 수 있는 자리야.

긴 문맥도 여기서 먼저 걸러져. Qwen3-14B 카드는 네이티브 context를 32,768토큰으로 적고, YaRN을 쓰면 131,072토큰까지 검증했다고 안내해. GGUF 카드의 long text 예시는 ./llama-cli ... -c 131072 --rope-scaling yarn --rope-scale 4 --yarn-orig-ctx 32768처럼 옵션을 넣어. 다만 같은 카드가 짧은 입력에서는 static YaRN을 무조건 켜지 말라고 경고하니까, 긴 문맥 숫자만 보고 기본값을 키우면 오히려 손해가 날 수 있어.

주의해서 볼 점

첫째, llama-cli는 모델 품질 보증서가 아니야. 같은 Qwen3-14B라도 원본 safetensors, GGUF Q4, GGUF Q8, LM Studio 실행, vLLM 서빙은 서로 다른 경로야. CLI에서 한 프롬프트가 괜찮았다고 해서 제품 서버에서 같은 지연 시간과 품질이 나온다고 보면 안 돼.

둘째, 서버 운영과 헷갈리면 안 돼. 자동화 앱이나 내부 서비스에서 호출해야 한다면 llama-cli보다 llama-server의 포트, /v1/chat/completions, 로그, 인증, 네트워크 노출을 봐야 해. CLI는 빠른 재현과 옵션 확인에 좋고, 장기 실행 서버의 장애 복구나 동시 요청 관리는 다른 문제야.

셋째, Hugging Face의 -hf 실행은 편하지만 재현성을 자동으로 보장하지 않아. 어떤 repo id와 태그를 받았는지, 어느 llama.cpp 빌드였는지, 모델 파일이 캐시에 남았는지, 프롬프트 템플릿이 바뀌었는지를 같이 기록해야 나중에 같은 결과를 다시 볼 수 있어.

넷째, thinking 모델을 돌릴 때는 출력 정책도 확인해야 해. Qwen3는 /think와 /no_think로 모드를 바꿀 수 있고, thinking이 켜지면 <think> 블록이 나올 수 있어. CLI에서는 화면에 보이는 문제지만, 앱으로 옮기면 로그 보관, 사용자 노출, 대화 히스토리 처리 문제가 돼.

관련 용어

  • llama.cpp: llama-cli가 속한 로컬 LLM 추론 엔진이야. CLI, server, GGUF 지원을 같은 생태계 안에서 봐야 해.
  • llama-server: 앱이 호출하는 OpenAI 호환 API 서버 쪽 실행 파일이야. llama-cli가 테스트와 재현이라면 llama-server는 연결과 운영에 더 가까워.
  • GGUF: llama-cli가 자주 여는 로컬 모델 파일 형식이야. 양자화, 메타데이터, 실행기 호환성을 같이 봐야 해.
  • Qwen3-14B-GGUF: 공식 카드가 llama-cli 실행 예시를 직접 제공하는 구체 모델 배포야. Q4와 Q8 선택이 메모리 판단으로 바로 이어져.
  • local-llm: llama-cli가 쓰이는 큰 문맥이야. 클라우드 API가 아니라 내 장비나 자체 서버에서 모델을 돌리는 흐름을 뜻해.
  • LM Studio: 같은 GGUF 모델을 GUI로 만져 보는 도구야. llama-cli는 더 직접적인 터미널 옵션 확인에 유리하고, LM Studio는 입문과 수동 테스트가 편하다.