맥에서 시작하는 로컬 AI

클라우드 AI는 써봤지만, 내 맥에서 직접 모델을 돌리는 건 처음인 사람을 위한 입문서.

한 장씩 따라오면 끝에 가서는 모델을 받고, 돌리고, 업무에 붙이는 일이 자연스러워집니다.

이 책은 무엇인가

ChatGPT나 Claude 같은 클라우드 AI 대신 내 맥북 안에서 도는 AI 를 다루는 법을 처음부터 끝까지 안내합니다.

토큰·파라미터 같은 기본 단어부터, 모델을 받는 곳, 돌리는 도구, 프롬프트 작성, 사내 챗봇·코딩 어시스턴트·회의록 자동화까지 한 권으로 모두 다룹니다.

수학과 논문은 거의 없습니다. 대신 결정 트리·체크리스트·실습 이 매 장 끝에 있습니다.

누구를 위한 책인가

• 회사 코드·문서를 외부 AI에 보내기 곤란한 개발자
• 민감한 자료를 매일 AI에 던지고 싶은 기획자·작가·연구자
• 사내 챗봇·요약기를 만들어야 하는 사내 도구 담당자
• AI를 진지하게 배우려는 학습자
• API 비용을 줄이고 싶은 자동화 운영자

반대로 “월 구독비는 부담 없고, 데이터를 외부에 보내도 무방하다“면 이 책을 굳이 읽지 않아도 됩니다.

다 끝내면 가능한 것

• ✅ Hugging Face의 모델 페이지 30초 만에 해독
• ✅ 내 맥 메모리에 맞는 모델·양자화 선택
• ✅ Ollama·LM Studio·MLX 자유롭게 사용
• ✅ OpenAI 호환 API로 외부 도구를 로컬 모델에 연결
• ✅ 임베딩·RAG·Function Calling·MCP 구축
• ✅ VS Code 코딩 어시스턴트 셋업
• ✅ 사내 RAG 챗봇 구축
• ✅ 회의록 자동화 파이프라인 운영
• ✅ 자기만의 모델 평가 셋 유지

전제 환경

Windows·Linux는 다루지 않습니다. 가격·모델 이름·정책은 2026년 시점 기준입니다.

책의 구조

각 장은 같은 틀로 구성됩니다.

1. 이 장의 목표 — 무엇을 알게 되는가
2. 본문 — 개념과 예시
3. 이 장에서 기억할 한 가지 — 핵심 한 문장
4. 손으로 해볼 것 — 5~15분짜리 미니 실습
5. 다음 장 예고

처음 보는 분은 순서대로 읽으세요. 앞 장에 나온 용어를 뒷 장이 전제합니다.

학습 경로 가이드

📚 목차

1부 · 로컬 AI 시작 전 알아야 할 개념

이 부를 마치면 모델 페이지의 숫자가 모두 읽힙니다.

• 1장 · 왜 로컬 AI인가
• 2장 · AI는 어떻게 글자를 만들어내는가
• 3장 · 토큰과 파라미터, 모델의 단위
• 4장 · 모델 크기와 메모리
• 5장 · 양자화, 모델 다이어트의 마법
• 6장 · 컨텍스트와 KV Cache
• 7장 · 토큰 속도와 메모리 대역폭

2부 · 모델 고르고 받기

이 부를 마치면 Hugging Face에서 길을 잃지 않습니다.

• 8장 · Hugging Face 완전 정복
• 9장 · 모델 종류
• 10장 · 파일 포맷 (Safetensors / GGUF / MLX)
• 11장 · 모델 이름 해독법
• 12장 · 라이선스, 회사에서 써도 되는 모델
• 13장 · 벤치마크 읽는 법
• 14장 · Dense와 MoE

3부 · 도구 익히기

이 부를 마치면 내 맥에서 모델이 실제로 돕니다.

• 15장 · 터미널 최소한
• 16장 · LM Studio로 시작하기
• 17장 · Ollama로 터미널과 API 다루기
• 18장 · llama cpp 깊이 가기
• 19장 · MLX와 Apple Silicon 가속
• 20장 · 백엔드 비교와 선택 가이드

4부 · 활용 기본기

이 부를 마치면 같은 모델에서 더 좋은 답을 뽑습니다.

• 21장 · 프롬프트 엔지니어링 기초
• 22장 · 시스템 프롬프트와 Chat Template
• 23장 · Temperature와 샘플링 파라미터
• 24장 · Stop, Max tokens, Streaming

5부 · 실무에 붙이기

이 부를 마치면 내 업무 도구가 로컬 AI와 대화합니다.

• 25장 · OpenAI 호환 API로 외부 도구 연결
• 26장 · 임베딩과 RAG
• 27장 · 벡터 DB 입문
• 28장 · Function Calling과 Tool Use
• 29장 · Agent의 구조와 위험
• 30장 · MCP (Model Context Protocol)
• 31장 · 멀티모달, 비전과 음성 모델

6부 · 심화

이 부는 선택입니다. 더 깊이 가고 싶을 때 봅니다.

• 32장 · 파인튜닝 입문, LoRA와 QLoRA
• 33장 · 양자화와 변환 직접 해보기
• 34장 · 환각과 Alignment 그리고 거절
• 35장 · HarmBench와 안전성 평가

7부 · 실전 시나리오

이 부를 마치면 실제 업무 도구 3개를 손에 쥐게 됩니다.

• 36장 · Mac 메모리 관리 실전
• 37장 · 실전 ① VS Code 코딩 어시스턴트
• 38장 · 실전 ② 사내 RAG 챗봇
• 39장 · 실전 ③ 회의록 요약 파이프라인
• 40장 · 모델 테스트 루틴 만들기
• 41장 · 트러블슈팅 25선

8부 · 마무리

• 42장 · 자주 하는 오해 정리
• 43장 · 모델 선택 의사결정 트리
• 44장 · 앞으로 공부할 것들

일러두기

• 모든 도구·CLI·단축키 예시는 macOS / zsh 기준입니다.
• 모델 메모리 표기는 맥 통합 메모리 기준입니다.
• 가격·정책·모델 이름은 2026년 시점입니다. 최신 정보는 각 제공자의 공식 문서를 함께 확인하세요.
• 코드 블록 안의 $ 는 zsh 프롬프트 를 뜻하니, 실제로 입력할 때는 빼고 치세요.
• 본문에서 자주 등장하는 표준 환경 은 M5 Pro 64GB 통합 메모리 입니다. 다른 환경이면 메모리·속도 표를 본인 사양에 맞춰 환산하세요.

시작하기

처음 보는 분이라면

1장 · 왜 로컬 AI인가 부터 순서대로.

도구부터 빨리 만져보고 싶다면

16장 · LM Studio로 시작하기 → 17장 · Ollama

먼저 손에 익힌 뒤 1~7장으로 돌아와 개념 채우기.

회사에 도입하려는 분이라면

12장 · 라이선스 와 35장 · 안전성 평가 를 먼저.

실전 도구만 빨리 만들고 싶다면

7부의 셋 중 하나만 골라 시작 후 필요한 앞 장으로 점프하세요.

• 37장 · VS Code 코딩 어시스턴트
• 38장 · 사내 RAG 챗봇
• 39장 · 회의록 요약 파이프라인

한 줄 요약

로컬 AI는 도구가 아니라 인프라가 됩니다.

클라우드 AI는 빨라서 좋고, 로컬 AI는 내 것이라서 좋습니다. 둘을 같이 쓰면서 회사 데이터·시간·결정을 내 손에 다시 가져오는 여정 — 이 책은 그 시작 지점입니다.

준비됐다면 1장 · 왜 로컬 AI인가 으로.

1장. 왜 로컬 AI인가?

이 장의 목표 로컬 AI가 정확히 뭔지, 왜 굳이 내 컴퓨터에서 AI를 돌리는 사람들이 있는지, 그리고 나에게 맞는 길인지 판단할 수 있게 됩니다.

1.1 일단 “로컬 AI“가 뭔가요?

지금 우리가 흔히 쓰는 AI는 거의 다 클라우드 AI입니다.

• ChatGPT
• Claude
• Gemini
• Copilot

이 친구들은 모두 누군가의 거대한 서버 안에 살고 있습니다.

여러분이 질문을 적으면 그 글자가 인터넷을 타고 OpenAI나 Anthropic, Google의 데이터센터까지 갔다가, 거기서 답을 만들어 다시 여러분 화면으로 돌아옵니다.

로컬 AI는 이걸 내 컴퓨터 안에서 끝내는 것입니다.

[클라우드 AI]
내 컴퓨터 ─→ 인터넷 ─→ 거대한 서버(GPU 수천 장) ─→ 답변 ─→ 내 화면

[로컬 AI]
내 컴퓨터 ──────────────→ 답변 ──────────────→ 내 화면
       (모델이 이 안에 들어 있음)

서버에 보내지 않습니다. 인터넷이 끊겨도 동작합니다. 비용도 따로 안 나갑니다.

대신 내 컴퓨터가 그 일을 직접 해야 합니다.

1.2 왜 사람들이 로컬 AI를 쓰는가

다섯 가지 진짜 이유가 있습니다.

어느 하나라도 마음에 와닿는다면, 여러분도 로컬 AI를 배울 가치가 있습니다.

① 보안 — 내 데이터가 밖으로 안 나간다

회사 코드, 회의록, 고객 정보, 의료 기록, 법무 자료.

이런 걸 ChatGPT 입력창에 붙여 넣기가 꺼림칙한 분이 많습니다. 회사 정책상 금지된 곳도 많고요.

로컬 AI는 그 데이터가 내 컴퓨터 안에서만 처리되고 끝납니다. 외부로 한 글자도 안 나갑니다.

② 비용 — 한 번 받아두면 끝

ChatGPT Plus나 Claude Pro 같은 구독이 매달 20달러쯤 합니다. API로 자동화를 돌리면 토큰 단위로 또 돈이 나갑니다.

로컬 AI는 모델을 한 번 받으면 그 뒤로는 전기료 외에는 돈이 안 듭니다.

하루에 1만 번 질문해도 추가 요금이 0원입니다.

③ 오프라인 — 인터넷이 없어도 동작

비행기 안, 산속, 사내망만 되는 환경, 외국 출장에서 갑자기 끊긴 와이파이.

로컬 AI는 인터넷 없이도 그냥 돌아갑니다.

④ 통제 — 모델을 마음대로 바꿀 수 있다

클라우드 AI는 어느 날 갑자기 답변 스타일이 바뀌거나, 거절이 까다로워지거나, 가격이 오를 수 있습니다.

모델 자체가 “회사 자산“이라 내가 어쩔 수가 없습니다.

로컬 AI는 내가 받은 모델을 그대로 보관할 수 있고, 내 데이터로 추가 학습(파인튜닝)도 시킬 수 있습니다.

시스템 프롬프트도, 안전장치 강도도, 출력 길이도 전부 내가 정합니다.

⑤ 학습 — AI의 작동 원리를 손으로 만져본다

이건 좀 다른 종류의 이유인데, 의외로 큽니다.

클라우드 AI만 쓰면 AI는 그냥 “마법의 검은 상자“입니다.

로컬 AI는 모델 파일을 직접 받고, 메모리에 올려보고, 양자화 버전을 바꿔보면서 AI가 실제로 어떻게 굴러가는지를 손끝으로 익히게 됩니다.

앞으로 어떤 AI 도구를 쓰든 이 감각이 큰 자산이 됩니다.

1.3 그런데 솔직히 단점도 있습니다

이 책이 로컬 AI를 권하는 책이긴 해도, 거짓말은 하지 않겠습니다.

① 최상위 클라우드 모델보다는 보통 살짝 부족합니다

GPT-5, Claude Opus 4, Gemini 2.5 같은 최상위 모델은 수십~수천억 원어치 GPU에서 돌아갑니다.

내 노트북에서 그걸 그대로 따라잡진 못합니다.

다만 2025년 들어 격차가 빠르게 좁혀졌습니다.

32B급 좋은 로컬 모델은 1~2년 전 GPT-4 수준 정도까지는 이미 따라왔습니다.

“일상 업무에 충분한가“라는 기준이라면, 답은 점점 “예“가 되고 있습니다.

② 속도가 클라우드만큼 빠르진 않습니다

ChatGPT는 답변이 폭포처럼 쏟아집니다.

로컬 AI는 모델 크기에 따라 한 줄씩 천천히 흐르는 느낌이 더 강합니다.

작은 모델은 빠르고, 큰 모델은 느립니다.

③ 처음 셋업이 클릭 한 번이 아닙니다

ChatGPT는 가입하고 끝입니다.

로컬 AI는 “어떤 모델을 받지?”, “어떤 형식으로?”, “메모리는 충분한가?” 같은 결정을 내가 해야 합니다.

이 책의 절반은 그 결정을 자신 있게 내릴 수 있게 해주는 게 목적입니다.

④ 컴퓨터가 좀 필요합니다

낡은 노트북이나 메모리 8GB짜리에서는 솔직히 쾌적하지 않습니다.

그래도 의외로 진입선은 낮습니다 — 다음 절에서 확인합니다.

1.4 그래서, 누가 쓰면 좋은가

다음 중 하나라도 해당하면 이 책이 도움이 됩니다.

• 개발자 회사 코드를 외부 AI에 넣기 곤란한 사람
• 연구자·기획자·작가 민감한 초안이나 자료를 매일 AI에 던지고 싶은 사람
• 사내 도구 만드는 사람 회사 안에서만 도는 챗봇/요약기를 구축해야 하는 사람
• AI를 진지하게 배우려는 사람 “어떻게 작동하는지” 손으로 만져보고 싶은 사람
• 비용이 부담되는 사람 자동화를 많이 돌리는데 API 비용이 부담스러운 사람
• 오프라인 환경이 잦은 사람 폐쇄망, 보안 환경, 출장이 많은 사람

반대로 “월 20달러는 쓸 수 있고, 회사 데이터를 외부에 보내도 문제없고, 최고 품질이면 충분하다“라면,

솔직히 클라우드 AI만 써도 됩니다. 그건 그것대로 좋은 선택입니다.

이 책은 “두 가지를 같이 쓰면 된다” 는 입장입니다.

• 클라우드 AI는 최고 품질이 필요할 때
• 로컬 AI는 보안·비용·통제가 중요할 때

1.5 내 맥에서 가능한가? (대충 감)

이 책은 맥(Apple Silicon) 기준으로 진행합니다.

M1·M2·M3·M4·M5 시리즈 어디든 괜찮습니다.

맥의 큰 장점이 하나 있는데, 통합 메모리(Unified Memory) 구조 덕분에 같은 GB 메모리여도 일반 PC보다 큰 모델을 올리기 쉽습니다.

자세한 메모리 계산은 4장과 5장에서 합니다.

여기서는 “내 맥에서 시작은 할 수 있는가” 만 봅니다.

참고 위 숫자에 나오는 “7B”, “14B” 같은 표기는 3장에서 자세히 풉니다. 지금은 “숫자가 클수록 똑똑하지만 무겁다” 정도만 기억하면 됩니다.

통합 메모리 16GB 이상이면 이 책의 대부분을 즐겁게 따라올 수 있습니다.

1.6 클라우드 AI와 로컬 AI, 한 표로

둘은 경쟁자가 아닙니다. 같이 쓰는 도구입니다.

이 장에서 기억할 한 가지

로컬 AI는 “내 컴퓨터 안에서 끝나는 AI“입니다.

클라우드 AI보다 좋아서 쓰는 게 아니라, 클라우드 AI가 못 채워주는 것 (보안·비용·통제·오프라인·학습) 을 채우려고 씁니다.

손으로 해볼 것

이 장은 개념이 메인이라 무거운 실습은 없습니다.

대신 다음 두 가지만 해두면 다음 장이 훨씬 매끄러워집니다.

1. 내 맥 사양 확인

좌상단 사과 메뉴 → 이 Mac에 관하여 를 눌러보세요.

• 칩 (예: Apple M5 Pro)
• 메모리 (예: 64GB)

이 두 가지를 메모해두세요. 5장에서 다시 씁니다.

2. 클라우드 AI에 다음 질문을 던져 보세요 (아무 모델이나 좋습니다)

“내가 ChatGPT에 절대 붙여넣고 싶지 않은 우리 회사·내 개인 자료가 뭐가 있을까?”

머릿속에 답이 나오면, 그게 여러분이 로컬 AI를 쓸 첫 번째 이유입니다.

다음 장에서는 AI(LLM)가 도대체 어떻게 글자를 만들어내는지 30분 정도로 훑어봅니다.

토큰·파라미터 같은 단어가 본격적으로 나오기 시작합니다.

2장. AI는 도대체 어떻게 글자를 만들어내는가

이 장의 목표 ChatGPT나 로컬 AI가 “어떻게 사람처럼 글을 쓰는지” 그 원리를 큰 그림으로 이해합니다.

수학은 안 나옵니다. 대신 앞으로 이 책에서 만날 모든 용어가 여기서 한 번씩 미리 등장합니다.

2.1 AI는 “생각“하지 않습니다. “예측“합니다

먼저 충격적인 사실 하나.

ChatGPT도, Claude도, 우리가 받을 로컬 모델도 문장을 “생각해서” 쓰는 게 아닙니다.

이들이 실제로 하는 일은 딱 하나입니다.

“지금까지의 글자를 보고, 그 다음에 올 가장 그럴듯한 글자를 골라라.”

그게 전부입니다.

예를 들어 여러분이 이렇게 입력했다고 합시다.

오늘 날씨는

모델은 속으로 이런 생각을 합니다.

다음에 올 단어로 뭐가 제일 그럴듯할까?

  "맑습니다"  → 가능성 35%
  "흐립니다"  → 가능성 22%
  "춥습니다"  → 가능성 15%
  "비가"      → 가능성  9%
  "치킨"      → 가능성  0.01%
  ...

이 중에서 하나를 골라 출력합니다.

오늘 날씨는 맑습니다

그러고는 끝이 아니라, 방금 자기가 출력한 글자까지 포함해서 다시 다음을 예측합니다.

오늘 날씨는 맑
   ↓
다음은? → "습"

오늘 날씨는 맑습
   ↓
다음은? → "니"

오늘 날씨는 맑습니
   ↓
다음은? → "다"

이걸 끝없이 반복합니다.

이게 다입니다.

2.2 “그게 어떻게 지능이 되죠?”

처음 들으면 다들 이렇게 반문합니다.

“고작 다음 글자 맞히기인데 어떻게 코딩하고, 번역하고, 농담까지 하지?”

핵심은 이겁니다.

다음 글자를 진짜 잘 맞히려면, 그 앞 문장의 의미를 이해해야 합니다.

예를 들어 보겠습니다.

A: "어제 회의 어땠어요?"
B: "사장님이 화나셔서 분위기가 ___"

빈칸에 올 단어를 진짜로 잘 맞히려면 뭘 알아야 할까요?

• “회의“가 뭔지 알아야 하고
• “사장님이 화나셨다“가 부정적 상황이라는 걸 알아야 하고
• 한국어 어법을 알아야 하고
• “분위기“라는 단어 뒤에 자주 오는 표현을 알아야 합니다

이걸 다 종합해야 “얼어붙었어요” 같은 그럴듯한 답이 나옵니다.

즉:

“다음 글자 잘 맞히기“라는 단순한 과제를 진짜 잘하려면, 결과적으로 세상을 이해하게 됩니다.

이게 LLM의 신기한 성질입니다.

아주 단순한 과제를 아주 많은 글에 대해 아주 큰 규모로 시켰더니, 부산물로 지능 비슷한 게 생겼습니다.

2.3 토큰 — 모델이 진짜로 다루는 단위

방금 “다음 글자“라고 했는데, 사실 모델은 글자 단위로 다루지 않습니다.

토큰(token) 이라는 단위로 다룹니다.

토큰은 글자보다는 크고 단어보다는 작은 조각입니다.

영어 예시:

"unbelievable"
     ↓
[ "un", "believ", "able" ]

한국어 예시:

"오늘 날씨는 맑습니다"
     ↓
[ "오늘", " 날씨", "는", " 맑", "습니다" ]

모델마다 토큰을 쪼개는 방식이 다릅니다. 같은 문장이어도 모델이 다르면 토큰 수가 다릅니다.

지금 단계에서 기억할 건 이거 하나입니다.

모델이 보는 세상은 “글자“가 아니라 “토큰“입니다.

토큰은 3장에서 더 깊이 봅니다.

2.4 그러면 이 모델은 어떻게 만들어졌나?

여기서부터가 정말 중요합니다.

같은 “다음 토큰 예측 기계“인데 어떤 모델은 멍청하고 어떤 모델은 똑똑한 이유,

그리고 같은 모델인데도 “Base”, “Instruct”, “Chat” 같은 여러 버전이 존재하는 이유가 여기서 결정됩니다.

LLM은 보통 3단계를 거쳐서 만들어집니다.

[1단계] 사전학습  →  세상의 글을 다 읽음
   ↓
[2단계] 지도학습  →  "이런 질문엔 이렇게 답해" 가르침
   ↓
[3단계] 정렬학습  →  "이런 답은 좋고, 이런 답은 나쁘다" 교정

하나씩 봅니다.

1단계 — 사전학습 (Pre-training)

인터넷의 거의 모든 글을 보여주고 “다음 토큰을 맞혀라” 라고 시키는 단계입니다.

• 위키백과
• 책, 논문
• 코드 저장소(GitHub)
• 뉴스 기사
• 포럼, 블로그
• …

이런 글을 수조 개 토큰 단위로 읽힙니다.

이 단계는 돈과 시간이 어마어마하게 듭니다. GPU 수천 장을 몇 달 동안 돌립니다.

이 단계를 마친 모델을 Base 모델 이라고 부릅니다.

Base 모델의 특징:

• 글은 그럴듯하게 잇습니다
• 그런데 질문에 답을 잘 못합니다
• “한국의 수도는?” 이라고 물으면 “한국의 수도는?” 으로 이어 쓸 수도 있습니다
• 그냥 다음 토큰만 맞히는 데 익숙해서요

즉 Base 모델은 재료입니다. 바로 쓰기엔 아직 다듬어지지 않은 상태입니다.

2단계 — 지도학습 (SFT, Supervised Fine-Tuning)

이번에는 “질문 ↔ 모범 답안” 쌍을 잔뜩 보여줍니다.

질문: 한국의 수도는?
답:   서울입니다.

질문: 다음 코드를 설명해줘. ...
답:   이 코드는 ...

사람이 직접 쓴 모범 답안이거나, 다른 좋은 AI가 만든 답안을 사용합니다.

이 과정을 거치면 모델은 점점:

• “질문이 오면 답을 한다”
• “지시가 오면 따른다”

는 패턴을 익히게 됩니다.

이 단계를 거친 모델을 Instruct 모델 또는 Chat 모델 이라고 부릅니다.

우리가 ChatGPT에서 익숙하게 보는 “질문하면 답하는 모델” 이 단계까지 와야 만들어집니다.

3단계 — 정렬학습 (Alignment, RLHF 등)

마지막으로 모델에게 취향과 매너를 가르칩니다.

같은 질문에 대해 모델이 답안 A, B 두 개를 만들었을 때, 사람이 평가합니다.

질문: "내가 회사에서 화났는데 어떡하지?"

답안 A: "그냥 다 때려쳐."
답안 B: "잠깐 자리를 비우고 산책을 권합니다.
         이유는 ..."

→ 사람: B가 더 좋음

이런 비교를 수십만 번 시켜서 모델을 교정합니다.

이 단계에서 모델은 이런 걸 배웁니다.

• 위험한 요청은 거절한다
• 정중하게 답한다
• 모르면 모른다고 한다
• 너무 길거나 짧지 않게 답한다

이 단계가 약하면 모델이 막말을 하거나, 이상한 답을 자신만만하게 합니다.

이 단계가 너무 세면 멀쩡한 질문에도 자꾸 거절합니다.

이걸 alignment(정렬) 이라고 부릅니다.

영어로는 보통 RLHF (Reinforcement Learning from Human Feedback) 또는 DPO 같은 기법으로 합니다.

지금은 이름까지 외울 필요는 없습니다.

2.5 그래서 모델 이름이 그렇게 복잡했던 거구나

Hugging Face 같은 사이트에서 모델을 찾으면 이런 이름을 자주 봅니다.

Qwen3-32B
Qwen3-32B-Instruct
Qwen3-32B-Chat

이제 차이를 짐작할 수 있을 겁니다.

초보자 기준 한 줄 결론 모델을 받을 때는 거의 항상 Instruct 또는 Chat 이 붙은 걸 받으면 됩니다.

Base는 “재료“라서 그대로 쓰면 답이 이상하게 나옵니다.

이 얘기는 9장에서 다시 자세히 다룹니다.

2.6 그럼 “32B” 이런 숫자는 뭐죠?

자주 보는 표기입니다.

Qwen3-32B
Llama-3-70B
Gemma-3-27B

B는 Billion(10억) 이라는 뜻이고, 모델 안에 들어있는 “숫자(파라미터)“의 개수를 가리킵니다.

7B    →  약 70억 개
14B   →  약 140억 개
32B   →  약 320억 개
70B   →  약 700억 개

파라미터는 모델이 학습하면서 결정한 가중치 숫자들입니다.

쉽게 말하면:

모델 안에 있는 “세상에 대한 지식이 적힌 숫자 메모” 가 몇 개냐.

• 숫자가 많을수록 보통 더 똑똑합니다
• 숫자가 많을수록 더 무겁습니다
• 숫자가 많을수록 더 큰 메모리가 필요합니다

이 숫자가 왜 메모리와 직결되는지는 4장 에서 직접 계산해봅니다.

2.7 한 장면 요약

지금까지를 한 그림으로 정리하면 이렇게 됩니다.

                ┌─────────────────────┐
                │  내가 입력한 글자    │
                └──────────┬──────────┘
                           │
                ┌──────────▼──────────┐
                │  토큰으로 쪼갬       │   ← 2.3절
                └──────────┬──────────┘
                           │
                ┌──────────▼──────────┐
                │  모델이 "다음 토큰"  │   ← 2.1절
                │   예측              │
                └──────────┬──────────┘
                           │
                ┌──────────▼──────────┐
                │  방금 만든 토큰을    │
                │  다시 입력에 붙임    │   ← 2.1절
                └──────────┬──────────┘
                           │
                       (반복)
                           │
                ┌──────────▼──────────┐
                │  최종 답변           │
                └─────────────────────┘

그리고 이 “모델“은 사실

[Base] 사전학습   →  글을 잘 잇는 기계
       ↓
[+SFT] 지도학습   →  질문에 답하는 기계
       ↓
[+정렬] 정렬학습  →  안전하고 매너 있는 기계

이 단계를 거쳐 만들어진 결과물입니다.

이 장에서 기억할 한 가지

LLM은 “다음 토큰을 예측“하는 기계입니다.

다만 그 단순한 과제를 인터넷 규모로 시키고(=사전학습), 질문/답 형태로 다듬고(=SFT), 사람 취향에 맞게 정렬(=alignment) 했더니 결과적으로 우리가 보는 ChatGPT가 됐습니다.

그래서 모델을 받을 때 Base / Instruct / Chat 같은 꼬리표가 붙고, 7B / 14B / 32B 같은 크기가 붙는 겁니다.

손으로 해볼 것

이번에도 가볍게 두 가지만 해보세요.

1. 토큰 직접 보기

브라우저에서 다음 사이트에 들어가 보세요.

tiktokenizer.vercel.app

(실시간으로 문장을 토큰으로 쪼개주는 사이트입니다. 가입은 필요 없습니다.)

거기에 다음 문장을 그대로 넣어보세요.

나는 오늘 회사에서 ollama로 로컬 AI를 처음 돌려봤다.

영어 문장도 한 번 넣어보세요.

I tried running a local AI model on my Mac for the first time today.

같은 길이의 한국어가 영어보다 토큰이 더 많이 쪼개진다는 걸 보게 될 겁니다.

이게 나중에 “왜 한국어는 더 느린가“의 이유가 됩니다.

2. 모델 한 개 이름 뜯어보기

Hugging Face에서 아무 모델이나 골라보세요. 예: Qwen3-30B-A3B-Instruct-2507

이름을 보면서 머릿속으로 답을 만들어보세요.

• 이건 Base인가, Instruct인가, Chat인가?
• 파라미터는 몇 B인가?
• 회사에서 그대로 쓸 만한가? (직감으로)

답이 안 나와도 괜찮습니다. 앞으로 11장(모델 이름 해독법)까지 가면 자연스럽게 다 풀립니다.

다음 장에서는 “토큰“과 “파라미터“를 본격적으로 숫자와 함께 봅니다.

“내 맥의 메모리 64GB에 32B 모델이 들어가긴 하는 건가?” 같은 질문에 직접 답할 수 있게 됩니다.

3장. 토큰과 파라미터, 모델의 단위

이 장의 목표 2장에서 잠깐 본 토큰과 파라미터(B) 를 이제 정식으로 정리합니다.

이 두 가지만 알면 앞으로 만나게 될 거의 모든 숫자가 머릿속에서 그림으로 보입니다.

3.1 토큰 — 모델이 보는 단위

복습부터.

모델은 글자나 단어가 아니라 토큰 이라는 단위로 글을 봅니다.

"오늘 날씨는 맑습니다"
        ↓
[ "오늘", " 날씨", "는", " 맑", "습니다" ]

토큰은 보통 다음 중 하나입니다.

• 자주 등장하는 단어 통째로 (“the”, “ AI“)
• 자주 등장하는 접두/접미 (“ing”, “ un“)
• 한 글자

영어처럼 알파벳이 적은 언어는 한 토큰이 보통 한 단어에 가까운 반면,

한국어·일본어·중국어는 한 글자 또는 그보다 잘게 쪼개지는 일이 많습니다.

한국어가 영어보다 토큰이 많은 이유

같은 문장을 영어와 한국어로 비교해 봅니다.

영어:  "I love local AI."
        → [ "I", " love", " local", " AI", "." ]   (5 토큰)

한국어: "저는 로컬 AI를 좋아합니다."
        → [ "저", "는", " 로", "컬", " AI", "를",
            " 좋", "아", "합", "니다", "." ]       (11 토큰)

같은 의미인데 한국어가 토큰을 두 배 넘게 씁니다.

이게 나중에 이런 결과로 이어집니다.

• 한국어 답변이 영어보다 느리게 느껴짐
• 같은 8K 컨텍스트인데 한국어로는 더 적은 정보만 들어감

3.2 토큰 수 = 시간 = 메모리

토큰이 늘어나면 정확히 세 가지가 늘어납니다.

요점:

클라우드 AI에서 토큰은 “돈“이고, 로컬 AI에서 토큰은 “시간 + 메모리“입니다.

그래서 로컬 AI에서는 “답변을 짧게 해줘” “불필요한 인사말 빼” 같은 요청이 의외로 큰 차이를 만듭니다.

3.3 파라미터 — 모델 안의 “지식 메모”

이번엔 모델의 크기 표시입니다.

Qwen3-32B
Llama-3-70B
Gemma-3-27B

여기서 B 는 Billion(10억) 입니다.

무엇이 70억 개라는 걸까요?

답: 가중치(weight) 라는 숫자입니다.

가중치는 학습할 때 결정된 “세상에 대한 메모” 같은 숫자입니다.

쉬운 비유:

모델 = 거대한 엑셀 시트
파라미터 = 그 시트에 적힌 숫자들

70억 개의 숫자가 모두 합쳐져 “다음 토큰을 예측하는 데 쓰이는 규칙” 을 만들어냅니다.

3.4 파라미터가 많으면 뭐가 좋고 뭐가 나쁜가

좋은 점

• 더 많은 지식을 담을 수 있음
• 더 복잡한 추론이 가능
• 더 다양한 분야를 다룰 수 있음

나쁜 점

• 더 많은 메모리가 필요
• 더 느림 (매 토큰마다 모든 숫자를 봐야 함)
• 다운로드 크기가 큼
• 발열·배터리 소모가 큼

“그럼 무조건 큰 게 좋나요?”

아닙니다.

같은 32B여도 더 잘 만든 32B 가 더 못 만든 70B를 이기는 일이 요즘은 흔합니다.

특히 2025~2026년 모델들은 “잘 다듬은 작은 모델“이 더 인기입니다.

로컬 AI 입문자의 황금 영역 7B ~ 32B

이 범위 안에서 양자화·튜닝을 잘 고르는 게 무거운 70B를 끙끙대며 돌리는 것보다 훨씬 실용적입니다.

3.5 같은 32B인데 왜 어떤 건 20GB이고 어떤 건 64GB인가?

이게 처음 보면 정말 헷갈리는 부분입니다.

Qwen3-32B (원본, FP16)         →  약 64GB
Qwen3-32B (Q8 양자화)          →  약 35GB
Qwen3-32B (Q4 양자화)          →  약 20GB

같은 모델인데 파일 크기가 다릅니다.

이유는 숫자 하나를 표현하는 데 몇 비트(bit)를 쓰느냐 가 다르기 때문입니다.

이 부분이 5장에서 다룰 양자화 이야기입니다.

지금은 이 한 줄만 머리에 넣어두세요.

같은 파라미터 수여도 “한 숫자를 얼마나 정밀하게 저장하느냐” 에 따라 파일 크기와 메모리 사용량이 크게 달라진다.

3.6 그래서 모델 크기를 보면 뭐가 보여야 하는가

이제 모델 이름을 보면 이런 정보가 머릿속에서 자동으로 뜹니다.

Qwen3-32B-Instruct

• 32B → 파라미터 약 320억 개, 원본 파일은 60~64GB쯤, Q4로 줄이면 20GB 정도
• Instruct → 질문에 답하도록 다듬어진 버전 (2장 §2.4)

Llama-3-70B-Chat

• 70B → 큰 모델, 원본 140GB+, Q4여도 40GB 정도라 64GB 맥에서는 무겁게 돈다
• Chat → 대화용으로 정렬까지 마친 버전

Qwen3-30B-A3B-Instruct

• 30B 인데 A3B 가 붙음 → MoE 구조(14장)에서 활성 파라미터가 3B 라는 의미
• 메모리는 30B만큼 먹지만 계산량은 3B에 가까움

이 장에서 기억할 한 가지

토큰 = 모델이 읽고 쓰는 단위. 파라미터 = 모델 안의 “지식 숫자” 개수.

토큰이 많을수록 시간·메모리가 늘고, 파라미터가 많을수록 보통 똑똑해지지만 무거워집니다.

그리고 같은 파라미터 수여도 저장 방식(양자화)에 따라 메모리·속도가 크게 달라집니다.

손으로 해볼 것

1. 한·영 토큰 수 직접 비교

tiktokenizer.vercel.app 에 들어가서 다음 두 문장을 차례로 넣어보세요.

저는 오늘 회사에서 처음으로 로컬 AI를 돌려봤습니다.

I ran a local AI on my Mac for the first time today.

같은 의미인데 한국어 토큰 수가 얼마나 더 많은지 직접 보세요.

2. Hugging Face에서 모델 크기 감 잡기

huggingface.co 에서 Qwen3 를 검색해보세요.

7B, 14B, 32B 모델 페이지를 열어 Files and versions 탭에서 원본 파일 용량을 확인하세요.

같은 시리즈인데 파라미터 수가 늘어날 때 파일 크기가 어떻게 늘어나는지 보세요.

다음 장에서는 “내 맥의 64GB 메모리에 32B 모델이 정말 들어가는가?” 를 직접 계산해봅니다.

이때부터 양자화의 필요성이 본격적으로 보이기 시작합니다.

4장. 모델 크기와 메모리, 내 맥에 들어갈까?

이 장의 목표 모델 이름만 보고 “내 맥에서 돌까?” 를 30초 만에 가늠할 수 있게 됩니다.

계산식 하나만 외우면 됩니다.

4.1 한 줄 계산식

모델이 메모리에 차지하는 크기는 대략 이렇게 계산합니다.

필요 메모리(GB) ≈ 파라미터 수(B) × 한 숫자의 비트 수 / 8

/ 8 인 이유는 8비트 = 1바이트 이기 때문입니다.

예시.

32B 모델, 한 숫자를 16비트로 저장(FP16)
→ 32 × 16 / 8 = 64GB

32B 모델, 한 숫자를 4비트로 저장(Q4)
→ 32 × 4 / 8 = 16GB

이게 4장의 거의 전부입니다.

4.2 표 한 장으로 정리

파라미터 × 비트 / 8 을 미리 다 계산해 둔 표입니다.

주의 이 숫자는 모델 가중치만의 크기입니다. 실제 실행할 때는 여기에 여유 메모리가 더 필요합니다.

4.3 실제 메모리는 여기에 +α

실행할 때는 가중치 외에도 다음이 필요합니다.

실사용 메모리 ≈ 가중치 + KV Cache + 런타임 오버헤드 + macOS·앱 메모리

• KV Cache 대화가 길어질수록 늘어남 (6장에서 자세히)
• 런타임 오버헤드 추론 엔진이 기본으로 잡는 메모리
• macOS·앱 메모리 보통 4~8GB는 시스템·브라우저·IDE가 씀

거친 어림셈:

실사용 메모리 ≈ 가중치 × 1.3 + 6GB

예시. 32B Q4를 8K 컨텍스트로 돌리면:

가중치 16GB × 1.3 + 6GB ≈ 26~28GB

64GB 맥에서는 여유 있습니다.

70B Q4를 같은 조건으로 돌리면:

35GB × 1.3 + 6GB ≈ 51~52GB

64GB 맥에서 돌긴 도는데 빡빡합니다. 브라우저 켜놓고 IDE 켜놓으면 swap이 발생합니다.

4.4 맥 통합 메모리의 이점

일반 PC에서는

시스템 RAM ≠ GPU VRAM

이 둘이 따로따로 존재합니다.

GPU에 24GB VRAM이 있어도 거기에 안 들어가면 모델이 못 돌거나 극단적으로 느려집니다.

맥은 다릅니다.

통합 메모리(Unified Memory)
= CPU 메모리 = GPU 메모리

CPU도 GPU도 같은 메모리 풀 을 봅니다.

그래서 64GB 맥은 이론상 64GB 가까이를 모델에 할당할 수 있습니다.

실제로는 macOS와 앱들이 좀 잡고 있으니 대략 50GB 정도는 모델에 쓸 수 있다 고 보면 됩니다.

4.5 내 맥 기준 권장 영역

16GB 통합 메모리

18~24GB

32~36GB

48GB

64GB ★ (이 책의 표준 환경)

96GB+

70B Q4~Q5도 본격 실용 영역입니다.

4.6 30초 메모리 점검 체크리스트

모델 받기 직전에 매번 머릿속으로 한 번씩 돌리세요.

1. 이 모델 몇 B인가?
2. 어떤 양자화인가? (Q4? Q5?)
3. B × 비트 / 8 으로 가중치 크기 계산
4. 거기에 × 1.3 + 6GB 해서 실사용 메모리 어림
5. 내 맥 통합 메모리에서 빼면 여유가 얼마인가?
6. 여유가 10GB 미만 이면 컨텍스트를 줄이거나 양자화를 한 단계 내림

이 장에서 기억할 한 가지

모델 메모리 = 파라미터 × 비트 / 8 + 여유

한 숫자를 16비트로 저장하면 무겁고, 4비트로 압축하면 메모리는 1/4이 됩니다.

다음 장의 양자화가 바로 이 압축 기술입니다.

손으로 해볼 것

1. 내 맥에서 한 번에 모델 1개 올릴 수 있는 최대 크기 계산

activity monitor(활성 상태 보기) 앱을 열어 메모리 → 사용 중인 메모리 를 확인하세요.

가용 메모리 = 통합 메모리 - 사용 중인 메모리 - 안전 마진 4GB

이게 모델에 쓸 수 있는 대략적인 한계입니다.

가용 메모리를 × 1 로 보면 가중치 한도가 나옵니다.

2. 모델 후보 3개 골라보기

Hugging Face에서 아무 양자화 모델을 골라 파일 크기를 확인해보세요.

예를 들어:

• Qwen3-7B-Instruct-Q4_K_M.gguf
• Qwen3-14B-Instruct-Q4_K_M.gguf
• Qwen3-32B-Instruct-Q4_K_M.gguf

내 맥에 들어갈 후보를 3개 적어두세요. 17장(Ollama)에서 실제로 받습니다.

다음 장에서는 Q4, Q5, Q8 같은 양자화의 정체 와 어떤 양자화를 받아야 하는가 를 봅니다.

이걸 알면 모델 파일 이름이 모두 읽힙니다.

5장. 양자화, 모델 다이어트의 마법

이 장의 목표 Q4_K_M, Q5_K_M, Q8_0 같은 파일 이름이 무슨 뜻인지 모두 읽히게 됩니다.

그리고 어떤 양자화를 받아야 하는지 자신 있게 고를 수 있게 됩니다.

5.1 양자화가 뭔가?

모델 안의 숫자(파라미터)는 원래 고정밀 실수 입니다.

3.141592653589793
-0.000273841920
2.718281828459045
...

이런 숫자가 수십~수백억 개 들어있습니다.

문제는 이걸 고정밀로 저장하면 너무 큽니다.

그래서 사람들이 생각했습니다.

“어차피 마지막 자리 몇 개는 결과에 영향이 거의 없는데, 좀 잘라서 저장하면 안 될까?”

이게 양자화입니다.

[원본 FP16]              [Q4 양자화]
3.141592653589793   →    3.14
-0.000273841920     →    0
2.718281828459045   →    2.72

비유하자면:

사진을 16비트 RAW로 저장하다가 JPEG로 압축한 것과 비슷합니다.

약간의 화질 손실은 있지만, 사람이 보기엔 거의 차이가 없습니다.

5.2 비트 수와 메모리

4장에서 본 식의 핵심 변수입니다.

필요 메모리 ≈ 파라미터 수 × 비트 수 / 8

비트가 줄면 메모리가 줄지만 품질 손실도 커집니다.

5.3 품질-메모리 그래프

대충 이런 모양입니다.

품질
 ↑
 │  FP16 ●━━━━━━━━━━━━━━━━━ (거의 100%)
 │       │
 │   Q8  ●  (99%+)
 │       │
 │   Q6  ●  (98%)
 │       │
 │   Q5  ●  (96%)
 │       │
 │   Q4  ●  (93%) ★ 실사용 균형점
 │       │
 │   Q3  ●  (85%)
 │       │
 │   Q2  ●  (60~70%, 종종 망가짐)
 │       │
 └───────●─────────────────────→ 메모리 사용량

여기서 보이는 게 있죠.

• FP16 → Q8 으로만 줄여도 메모리가 절반
• 품질 손실은 1~2% 수준에 불과
• Q4 까지는 거의 일직선 으로 효율적
• Q3 이하 부터는 손실이 가파르게 커짐

5.4 Q4_K_M 같은 이름은 또 뭔가

GGUF 파일을 받다 보면 이런 이름을 봅니다.

Qwen3-32B-Instruct-Q4_K_M.gguf

Q4 까지는 알겠는데 K_M 이 뭘까요?

같은 4비트여도 압축 방법이 여러 가지이기 때문입니다.

고민될 때 답 Q4_K_M 또는 Q5_K_M 둘 중 하나만 받으세요. 95% 경우 정답입니다.

K 는 일종의 “더 똑똑한 양자화 알고리즘“이고, S/M/L 은 그 안에서도 더 적게/중간/많이 정보를 보존한다는 뜻입니다.

5.5 그러면 뭘 받아야 하는가

내 맥 메모리에 따라 답이 정해집니다.

핵심 원칙

메모리에 여유가 있으면 한 단계 위 양자화를 선택 같은 모델이라면 Q5_K_M > Q4_K_M > Q3_K_M 순으로 더 좋음

모델 크기별 추천

한 줄 정리

• 이 책의 표준 환경(64GB 맥) 에서는 32B-Q4_K_M 또는 32B-Q5_K_M 이 메인.
• 빠른 응답이 필요하면 14B-Q5_K_M 또는 8B-Q8_0.
• 70B는 체험용으로만.

5.6 양자화에 대한 흔한 오해

“Q4면 25% 성능밖에 안 나오는 거 아냐?”

아닙니다.

비트가 1/4 이 되었다고 지능이 1/4 이 되는 게 아닙니다.

실험적으로 Q4_K_M은 FP16 대비 체감 품질의 90~93% 정도를 유지합니다.

특히 일반 대화·요약·번역·코드 설명에서는 거의 차이를 못 느낍니다.

“그럼 Q2 받으면 70B도 돌릴 수 있겠네?”

이론상 가능하지만, Q2부터는 답이 자주 무너집니다.

• 같은 단어 반복
• 갑자기 영어/중국어 섞임
• 한국어 어순 망가짐

특히 한국어처럼 학습량이 영어보다 적은 언어는 저비트 양자화에서 먼저 깨집니다.

“양자화는 GPU 메모리 절약용 아닌가?”

GPU·CPU 가리지 않고 효과가 있습니다.

게다가 양자화된 모델은 메모리 대역폭 도 적게 씁니다. 즉 속도까지 빨라집니다.

이건 7장에서 다시 봅니다.

5.7 Apple Silicon에서의 양자화 — MLX 양자화 한마디

맥 전용 프레임워크 MLX 는 자체 양자화 형식을 씁니다.

GGUF의 Q4_K_M 에 해당하는 게 MLX에서는 보통 4bit 또는 q4 로 표기됩니다.

mlx-community/Qwen3-32B-Instruct-4bit
mlx-community/Qwen3-32B-Instruct-8bit

GGUF의 K_M 같은 세분화는 적지만 Apple Silicon에 더 최적화되어 있어서 같은 4bit여도 더 빠를 수 있습니다.

자세한 비교는 19장(MLX), 20장(백엔드 비교)에서.

이 장에서 기억할 한 가지

양자화 = 모델 안의 숫자를 더 적은 비트로 저장하는 압축 기술.

메모리·속도가 줄고, 품질 손실은 Q4까지는 거의 무시 가능합니다.

표준 추천: Q4_K_M 또는 Q5_K_M.

손으로 해볼 것

1. 같은 모델의 양자화 버전 비교

Hugging Face에서 다음을 검색해보세요.

Qwen3-32B-Instruct GGUF

bartowski 나 unsloth 같은 유명 양자화 배포자의 페이지가 나옵니다.

Files 탭을 열면 같은 모델의 양자화 종류가 죽 나열되어 있습니다.

Q2_K   →  약 12GB
Q3_K_M →  약 15GB
Q4_K_M →  약 20GB
Q5_K_M →  약 23GB
Q6_K   →  약 27GB
Q8_0   →  약 35GB

이걸 보면서 “내 맥에는 어떤 게 맞을까” 혼자 답을 내보세요.

2. 받을 모델 1개 결정

내 맥 메모리 기준으로 실제로 받아볼 모델을 하나 정해두세요.

추천 후보:

• 64GB 맥 → Qwen3-32B-Instruct-Q4_K_M
• 32GB 맥 → Qwen3-14B-Instruct-Q5_K_M
• 16GB 맥 → Qwen3-8B-Instruct-Q5_K_M

이건 17장에서 Ollama로 직접 받습니다.

다음 장에서는 컨텍스트 길이와 KV Cache 를 다룹니다.

“왜 긴 문서를 넣으니까 갑자기 느려지지?” 의 답이 거기 있습니다.

6장. 컨텍스트와 KV Cache

이 장의 목표 “컨텍스트 길이가 128K” “32K context window” 같은 표기를 정확히 읽게 됩니다.

그리고 왜 긴 문서를 넣으면 갑자기 느려지는지, 그 정체를 알게 됩니다.

6.1 컨텍스트 윈도우 = 모델의 “단기 기억”

모델은 한 번에 볼 수 있는 토큰 양이 정해져 있습니다.

이걸 컨텍스트 윈도우(context window) 라고 합니다.

예를 들어 “컨텍스트 8K” 라면 이 안에 들어와야 할 게:

시스템 프롬프트       ← "너는 ~한 어시스턴트야"
+ 이전 대화 기록
+ 내가 방금 넣은 질문/문서
+ 모델이 만들 답변(생성 예정 토큰까지 포함)
─────────────────────
≤ 8,000 토큰

전부 합쳐서 8,000토큰을 넘으면 앞 내용이 잘려나가거나, 모델이 “이전 대화를 기억 못 함” 같은 일이 발생합니다.

컨텍스트는 “한 번의 대화에서 모델이 볼 수 있는 양” 입니다. 영구 기억이 아닙니다. 새 대화를 시작하면 다 잊습니다.

6.2 흔한 컨텍스트 길이

요즘 모델들의 표준입니다.

컨텍스트 = 클수록 좋다, 는 절대 아닙니다.

이유를 다음 절에서 봅니다.

6.3 KV Cache — 컨텍스트의 “메모리 비용”

모델은 답변을 한 토큰씩 만듭니다. 매 토큰을 만들 때마다 이전 토큰 전부를 다시 참고합니다.

그런데 매번 처음부터 계산하면 너무 느립니다.

그래서 이전 토큰들에 대한 계산 중간 결과를 메모리에 저장해둡니다.

이게 KV Cache 입니다.

(K, V는 Key, Value의 약자입니다. 이름은 외우지 않아도 됩니다.)

문제는 이것입니다.

KV Cache는 컨텍스트가 길어질수록 메모리를 더 잡아먹습니다.

거친 어림셈입니다.

(정확한 값은 모델 구조·양자화에 따라 달라집니다)

즉 컨텍스트를 키우는 건 공짜가 아닙니다. 모델 가중치 외에 별도 메모리 가 추가됩니다.

6.4 그래서 실제로 메모리 계산은?

4장 어림셈을 보강합니다.

실사용 메모리 ≈ 가중치 + KV Cache + 런타임 + 시스템

예시. 64GB 맥에서 32B Q4를 128K 컨텍스트로 돌리고 싶다면?

가중치 16GB
+ KV Cache 32GB
+ 런타임 4GB
+ 시스템 6GB
────────────
≈ 58GB

가능은 하지만 거의 한계입니다. 브라우저·IDE까지 켜놓으면 swap이 터집니다.

같은 모델을 16K 컨텍스트로 돌리면?

16 + 4 + 4 + 6 ≈ 30GB

훨씬 여유롭습니다.

결론 일반 대화나 코드 질문 정도면 16K~32K 면 충분합니다. 128K는 정말 필요할 때만.

6.5 Prefill vs Decode — 두 종류의 속도

긴 문서를 넣었을 때 느림에는 두 단계가 있습니다.

1단계: Prefill (입력 읽기)

내가 넣은 입력을 모델이 처음 통째로 읽어들이는 단계.

2만 토큰짜리 문서를 붙여넣음
       ↓
모델이 "이 2만 토큰을 다 읽어야" 답을 시작할 수 있음
       ↓
사용자 화면에서 보기엔 "한참 멈춰있는 시간"

이 시간이 prefill 시간 입니다.

2단계: Decode (답변 생성)

읽기를 마친 뒤 한 토큰씩 답을 뱉어내는 단계.

여기서 우리가 보는 초당 토큰 수(tokens/sec) 가 측정됩니다.

[Prefill: 8초]  [Decode: 첫 토큰부터 흐름]
████████░ → 안녕하세요. 회의록을 요약해드릴게요. ...

“이 모델 30 tokens/sec야” 라는 말은 거의 항상 decode 속도 입니다. Prefill 속도는 그것보다 보통 더 빠르지만, 입력이 크면 그 빠른 속도로도 시간이 꽤 걸립니다.

6.6 그럼 컨텍스트를 어떻게 잡아야 하나?

목적별 권장값입니다.

도구별 기본 컨텍스트

• Ollama: 메모리에 따라 자동으로 다르게 잡습니다. 64GB 맥이면 보통 32K~256K 사이로 시작합니다.
• LM Studio: 모델 로드 시 슬라이더로 직접 설정합니다. 처음에는 8K나 16K 권장.

도구별 설정 방법은 16~17장에서 다룹니다.

6.7 “긴 컨텍스트인데 왜 모델이 까먹지?”

128K 컨텍스트라고 표시된 모델이라도, 긴 입력을 주면 중간 내용을 놓치는 일이 자주 있습니다.

이를 “lost in the middle” 현상이라고 부릅니다.

입력:
  앞부분 (잘 기억함)
  ...
  중간 부분 (자주 잊음)   ← ★
  ...
  뒷부분 (잘 기억함)

원인은 단순합니다.

모델이 학습할 때 본 데이터는 대부분 짧은 글이었기 때문입니다.

긴 입력에서 핵심을 끝까지 잘 다루는 능력은 모델마다 편차가 큽니다.

이걸 측정하는 벤치마크가 따로 있습니다: Needle in a Haystack(NIAH) 같은 것들. 13장(벤치마크 읽는 법)에서 다시 봅니다.

이 장에서 기억할 한 가지

컨텍스트는 공짜가 아닙니다.

길게 잡으면 KV Cache 메모리가 그만큼 늘고, 긴 입력은 prefill 시간 도 길어집니다.

일반 업무라면 16K~32K 에서 시작하고, 정말 필요할 때만 늘리세요.

손으로 해볼 것

1. 컨텍스트 1K 차이가 만드는 KV Cache 차이 계산

내 후보 모델(예: 32B Q4)을 가정하고, 다음 컨텍스트에서 KV Cache 메모리를 어림셈 해보세요.

• 8K
• 32K
• 128K

각 경우 가중치 + KV Cache 합계가 내 맥 메모리의 몇 %인지 계산해보세요.

2. 토크나이저 사이트로 “내 회의록 한 편“이 몇 토큰인지 확인

평소에 자주 쓰는 회의록 한 편을 tiktokenizer.vercel.app 에 붙여넣어 보세요.

회의록 한 편이 약 몇 토큰인지 알면, 앞으로 “컨텍스트 몇 K가 필요한지” 직감으로 잡힙니다.

다음 장에서는 “이 모델 몇 tokens/sec 나와요?” 의 진짜 정체를 봅니다.

메모리 대역폭이 왜 속도를 좌우하는지, 같은 32B 모델이 맥마다 왜 다른 속도가 나오는지, 이유가 보입니다.

7장. tokens/sec와 메모리 대역폭

이 장의 목표 “초당 30 토큰”, “tps 12.5” 같은 표기의 의미와, 내 맥에서 어떤 속도가 나올지 예측하는 감을 잡습니다.

메모리 대역폭이라는 단어와 친해집니다.

7.1 tokens/sec란?

1초에 모델이 몇 개의 출력 토큰을 만드는지 나타내는 단위입니다.

20 tokens/sec
→ 1초에 20개 토큰
→ 100토큰 답변에 약 5초
→ 500토큰 답변에 약 25초

체감 기준입니다.

한국어는 영어보다 토큰이 더 쪼개진다 (3장) 는 걸 기억하세요.

같은 30 tokens/sec여도 한국어로 답변할 때는 체감이 절반 정도 입니다.

7.2 속도를 결정하는 진짜 요인

대부분 사람들이 처음에 짐작하는 건 이렇습니다.

"CPU/GPU가 빠르면 빠를 거다"

반은 맞고 반은 틀립니다.

LLM 추론에서 가장 중요한 건 메모리 대역폭(Memory Bandwidth) 입니다.

이유는 단순합니다.

모델은 매 토큰을 만들 때마다 모델 가중치 전체를 메모리에서 읽어들여야 합니다.

32B Q4 모델이 16GB라면, 매 토큰마다 16GB를 다 훑어야 합니다.

초당 토큰 수 ≈ 메모리 대역폭 / 모델 크기

이 식이 핵심입니다.

7.3 맥 통합 메모리 대역폭

같은 64GB여도 맥 모델마다 메모리 대역폭이 다릅니다.

(정확한 값은 칩 세대·구성마다 다름. Apple 공식 스펙 참조.)

기억할 건 이겁니다.

같은 메모리 용량(예: 64GB)이어도, Pro/Max에 따라 속도 차이가 두 배 이상 납니다.

7.4 내 맥에서 나올 속도 어림셈

핵심 식 한 번 더.

이론 최대 tokens/sec ≈ 메모리 대역폭(GB/s) / 모델 크기(GB)

예시. 32B Q4(약 16GB) 모델을:

이건 이론 최대치 입니다. 실제로는 70~80% 정도 나오는 게 보통입니다.

같은 식으로 70B Q4(약 35GB)는:

70B는 빠른 칩이 있어도 답답할 수 있다는 게 보이죠.

7.5 양자화가 속도에도 영향을 준다

5장에서 양자화는 메모리를 줄이는 기술이라고 했습니다. 한 가지가 더 있습니다.

양자화는 속도도 빠르게 합니다.

이유는 위 식 그대로입니다.

초당 토큰 수 ≈ 메모리 대역폭 / 모델 크기

모델 크기가 줄어들면 같은 대역폭에서 더 빨라집니다.

32B 기준 어림:

속도가 부족하면 양자화를 한 단계 더 줄이는 것도 방법. 단, Q3 이하는 품질 손실에 주의 (5장).

7.6 Decode 속도 vs Prefill 속도

6장에서 본 두 단계 다시 짚어봅니다.

긴 문서 분석에서는 prefill이 더 답답할 수 있습니다.

[입력 20K 토큰 prefill 12초] [답변 decode 4초]
                            ↑
                         답변이 빨리 끝나도
                         처음 멈춰있는 시간이 더 길게 느껴짐

해결책

• 컨텍스트를 필요한 만큼만 (6장)
• 시스템 프롬프트를 짧게
• 같은 문서를 여러 번 묻는다면 컨텍스트 캐싱(22장) 활용

7.7 속도를 실제로 측정해보기

Ollama에서는 다음 명령으로 응답 속도를 즉시 볼 수 있습니다.

$ ollama run qwen3:32b --verbose

--verbose 옵션을 붙이면 응답 후 이런 통계가 찍힙니다.

total duration:       8.4s
load duration:        50ms
prompt eval rate:     180 tokens/s   ← prefill
eval rate:            18.2 tokens/s  ← decode

여기서 eval rate 가 우리가 신경 쓰는 그 값입니다.

LM Studio에서는 화면 우하단에 실시간 속도가 그래프로 표시됩니다 (16장).

7.8 속도가 갑자기 느려질 때 점검 리스트

평소 20 tok/s가 잘 나오던 모델이 오늘은 갑자기 5 tok/s로 떨어졌다면?

1. 컨텍스트가 갑자기 커졌나? 대화가 길어지면 KV Cache 누적으로 느려집니다.
2. 메모리 압박이 있나? 활성 상태 보기에서 swap 사용량 확인.
3. 모델이 두 개 동시 로드돼 있나? ollama ps 로 확인.
4. macOS가 절전 모드인가? 배터리 사용 시 GPU 클럭이 떨어집니다.
5. 외장 디스플레이가 4개 이상 연결됐나? 드물지만 GPU 자원 분산 영향이 있습니다.

이 장에서 기억할 한 가지

tokens/sec ≈ 메모리 대역폭 / 모델 크기

그래서 양자화를 더 줄이거나, 모델 크기를 줄이면 보통 비례해서 빨라집니다.

맥 칩의 Pro/Max 등급은 메모리 대역폭 차이가 결정적입니다.

손으로 해볼 것

1. 내 맥 메모리 대역폭 확인

Apple 지원 사이트에서 내 맥 모델을 검색하고 메모리 대역폭(Memory Bandwidth) 값을 메모하세요.

예) M5 Pro 64GB → 약 300 GB/s

2. 이론 최대 속도 계산해보기

내 맥의 대역폭 ÷ 후보 모델 크기 를 계산하세요.

• 8B Q4 (약 4GB)
• 14B Q4 (약 7GB)
• 32B Q4 (약 16GB)

각각 몇 tok/s 가 나올지 어림셈해보세요.

17장에서 Ollama로 실제 모델을 돌려보고 예측 vs 실측 을 비교할 겁니다.

여기까지가 1부의 끝 입니다.

이제 모델 페이지의 거의 모든 숫자를 읽을 수 있습니다.

다음 장(2부 시작)부터는 Hugging Face에서 모델을 받는 법 을 실전 화면 기준으로 다룹니다.

8장. Hugging Face 완전 정복

이 장의 목표 Hugging Face 모델 페이지를 처음 봤을 때 어디를 어떤 순서로 봐야 하는지 알게 됩니다.

안에 적힌 영어 표현 30가지가 한국어로 들립니다.

8.1 Hugging Face가 뭔가

한 줄 요약:

AI 모델의 GitHub.

전 세계 연구자·회사가 모델을 올리고 공유하는 거대한 저장소입니다.

huggingface.co

이 사이트가 사실상 로컬 AI의 입구입니다.

크게 4가지가 올라옵니다.

1. Models — 모델 파일들
2. Datasets — 학습용 데이터
3. Spaces — 모델을 웹앱처럼 돌려보는 곳
4. Papers — 관련 논문

우리가 자주 쓰는 건 Models 입니다.

8.2 모델 페이지 한눈에 보기

예시. Qwen/Qwen3-32B-Instruct 페이지에 들어가면 이런 구조가 보입니다.

┌─────────────────────────────────────────┐
│  Qwen / Qwen3-32B-Instruct              │  ← ① 소유자 / 모델명
│  [Like] [Follow]                        │
├─────────────────────────────────────────┤
│  Model card | Files | Community         │  ← ② 탭
├─────────────────────────────────────────┤
│  Tags: text-generation, ko, en, ...     │  ← ③ 태그
│  License: apache-2.0                    │  ← ④ 라이선스
│  Downloads: 1.2M                        │
├─────────────────────────────────────────┤
│  README (모델 카드 본문)                │  ← ⑤ 모델 카드
└─────────────────────────────────────────┘

순서대로 살펴봅니다.

8.3 ① 소유자 / 모델명

Qwen / Qwen3-32B-Instruct
└──┘   └──────────────────┘
소유자     모델명

소유자는 보통 회사나 개인입니다.

팁: 모델을 받을 때 누가 올린 것인지 확인하는 습관을 들이세요. 같은 모델이라도 변환본 품질이 다릅니다.

8.4 ② 탭 — 모델 카드 / Files / Community

Model card

모델 설명서입니다. 어떤 모델이고, 어떻게 쓰는지, 라이선스가 뭔지.

Files and versions

여기가 실전입니다.

실제 모델 파일 목록이 보입니다.

config.json                   ← 모델 구조 설정
generation_config.json        ← 기본 생성 옵션
tokenizer.json                ← 토큰화 규칙
tokenizer_config.json         ← 토크나이저 설정
model-00001-of-00014.safetensors   ← 원본 가중치 조각
model-00002-of-00014.safetensors
...
model.safetensors.index.json

Community

질문·이슈·논의가 올라오는 탭. 모델을 받기 전에 알려진 버그를 빠르게 확인할 수 있습니다.

8.5 ③ 태그 보는 법

페이지 위쪽에 줄줄이 붙어있는 태그입니다.

자주 보는 것들:

빠른 필터링 팁 검색창 옆 필터에서 GGUF 만 켜면 로컬 실행 가능한 모델만 나옵니다.

8.6 ④ 라이선스

회사에서 쓸 거라면 여기를 가장 먼저 보세요.

흔한 라이선스:

자세한 비교는 12장 에서.

8.7 ⑤ 모델 카드 — 어디를 읽나

모델 카드는 길고 복잡합니다. 초보자라면 다음 4가지만 보세요.

1. Intended use / 사용 권장 사항

이 모델이 무엇을 잘하는지.

2. Limitations / 한계

이 모델이 잘 못하는 것. 한국어가 약하다거나, 코드를 못 짠다거나.

3. How to use / 사용 예제

transformers 코드가 적혀 있더라도 Chat template 이라는 항목이 보이면 22장에서 꺼낼 정보입니다.

4. Quantization / 양자화 버전 안내

원본 페이지 하단이나 README에 “Quantized versions” 또는 “GGUF version” 링크가 종종 있습니다.

거기로 들어가면 보통 bartowski, unsloth, mlx-community 같은 양자화 배포자 페이지로 연결됩니다.

8.8 같은 모델, 여러 버전 — 누구를 받아야 하나

대규모 인기 모델이면 보통 이런 구도가 됩니다.

Qwen/Qwen3-32B-Instruct           ← 원본 (Safetensors, 60GB+)
  ↓
unsloth/Qwen3-32B-Instruct-GGUF   ← GGUF 양자화 (Q4~Q8)
bartowski/Qwen3-32B-Instruct-GGUF ← 또 다른 GGUF 배포자
mlx-community/Qwen3-32B-Instruct-4bit  ← MLX 변환

목적별 추천:

• Ollama / LM Studio 쓰는 사람 → GGUF 받으세요. bartowski 또는 unsloth 추천.
• MLX 쓰는 사람 → mlx-community/ 페이지 받으세요.
• 연구·파인튜닝 할 사람 → 원본 Safetensors.

8.9 모델 검색 잘하는 팁

좌측 검색창에서 단순 키워드보다 필터 를 활용하세요.

추천 필터 조합:

Task:        Text Generation
Library:     Transformers / GGUF
Languages:   Korean
Sort:        Trending

또는

Sort: Most Downloads
Sort: Recently Updated

Trending 으로 두고 일주일에 한 번 둘러보면 지금 뜨는 모델이 보입니다.

8.10 다운로드 받을 때 알아둘 것

큰 모델은 파일 크기가 수십~수백 GB입니다.

• 안정된 와이파이에서 받기
• 외장 SSD에 받는 게 편함 (특히 256GB 맥)
• huggingface-cli 가 가장 안정적

설치는 한 줄:

$ pip install -U huggingface_hub

다운로드는:

$ huggingface-cli download \
    bartowski/Qwen3-32B-Instruct-GGUF \
    Qwen3-32B-Instruct-Q4_K_M.gguf \
    --local-dir ./models

이런 식으로 받으면 됩니다. (실제 실습은 17장.)

이 장에서 기억할 한 가지

Hugging Face 모델 페이지에서는 5가지만 순서대로 봅니다.

1. 소유자 (누가 올렸나)
2. 라이선스 (회사에서 써도 되나)
3. 태그 (GGUF/MLX 있나, 한국어 되나)
4. Files 탭 (어떤 파일을 받을 수 있나)
5. 모델 카드의 Limitations (한계는 뭔가)

손으로 해볼 것

1. Hugging Face 계정 만들기

huggingface.co/join 에서 무료 계정 만드세요. 일부 모델은 로그인이 필요합니다 (예: Meta Llama 시리즈).

2. 후보 모델 페이지 3개 비교

다음 3개 페이지를 띄워놓고 비교해보세요.

• Qwen/Qwen3-32B-Instruct
• meta-llama/Llama-3.1-8B-Instruct
• google/gemma-3-27b-it

각각의:

• 라이선스
• 파일 크기
• 지원 언어
• Community 탭 이슈 개수

를 표로 만들어보세요.

이게 습관이 되면 새 모델을 만났을 때 30초 안에 판단이 섭니다.

다음 장에서는 Base / Instruct / Chat / Coder / Reasoning / VL / Embedding 모델 종류를 한 번에 정리합니다.

이름만 봐도 “이건 내가 쓸 수 있는 거다” “이건 아직 아니다” 판단이 섭니다.

9장. 모델 종류 — Base / Instruct / Coder / Reasoning / Vision / Embedding

이 장의 목표 모델 이름 끝에 붙는 꼬리표들을 모두 구분하게 됩니다.

같은 시리즈라도 어떤 건 대화용, 어떤 건 코드용, 어떤 건 그림용입니다. 잘못 받으면 답이 이상하게 나옵니다.

9.1 한 표로 보는 모델 종류

하나씩 봅니다.

9.2 Base 모델 — 재료

2장에서 본 그 단계입니다.

사전학습만 한 모델 = Base

특징:

• 인터넷의 글을 잘 이어 씁니다
• 질문에 답을 잘 못합니다
• “한국의 수도는?” 이라고 물으면 “한국의 수도는?” 하고 똑같이 이어 쓸 수 있습니다

언제 쓰나:

• 내 데이터로 파인튜닝 할 때 (32장)
• 특수 목적의 모델을 처음부터 만들 때

보통 사람은 거의 안 씁니다.

9.3 Instruct 모델 — 표준 대화용

이게 여러분이 받을 모델의 95% 입니다.

지시사항을 따르도록 튜닝된 버전.

Qwen3-32B-Instruct
Llama-3.1-8B-Instruct
Gemma-3-27B-it      ← "it" 도 instruct의 한 표기

• 질문에 답합니다
• 명령을 따릅니다
• 회사 업무·일반 대화에 무난

기본 추천

9.4 Chat 모델 — 대화 강화판

Instruct에 한 발짝 더 나아간 버전.

Qwen3-32B-Chat
Llama-3-8B-Chat

• 다중 턴 대화에 더 자연스러움
• 시스템 프롬프트·역할극 잘함

Instruct와 Chat은 모델에 따라 거의 같은 의미 로 쓰이기도 합니다.

둘 중 뭐 받지? 같은 시리즈에 둘 다 있으면 Chat. 보통은 Instruct만 있는 경우가 많습니다.

9.5 Coder / Code — 개발자용

코드에 특화된 튜닝.

Qwen2.5-Coder-32B-Instruct
DeepSeek-Coder-V2-Instruct
CodeLlama-34B-Instruct

특징:

• 함수 작성·디버깅 강함
• 여러 언어 지원 (Python, TS, Go, Rust, PHP, …)
• 일반 대화는 보통 모델보다 어색할 수 있음
• 수십 종의 프로그래밍 언어를 본 모델

VS Code의 Continue.dev 같은 코딩 어시스턴트(37장) 에서 주로 씁니다.

9.6 Reasoning / Thinking — 추론용

답을 바로 내지 않고, 생각 과정을 길게 적어가며 답하는 모델.

DeepSeek-R1
Qwen3-32B-Thinking
QwQ-32B
o1-style models

특징:

[질문] 1, 1, 2, 3, 5, 8 다음 숫자는?

[모델 출력]
<think>
이 수열을 분석해보자.
1, 1, 2, 3, 5, 8
2 = 1 + 1
3 = 1 + 2
5 = 2 + 3
8 = 3 + 5
즉 피보나치 수열이다.
다음은 5 + 8 = 13
</think>

13입니다.

• 수학·논리·복잡 디버깅에 강함
• 답이 나올 때까지 시간이 오래 걸림
• 출력 토큰이 많이 나옴 (속도 체감 느림)
• 모델 카드에 <think> 같은 특수 토큰이 정의됨

언제 쓰나:

• 어려운 수학·코딩 문제
• 복잡한 의사결정 분석
• 빠른 대화엔 부적합

9.7 VL / Vision — 그림도 보는 모델

이미지를 입력으로 받을 수 있는 모델.

Qwen2.5-VL-32B-Instruct
LLaVA-1.6-34B
Llama-3.2-Vision-11B-Instruct
Gemma-3-27B-it (이미지 지원)

활용:

• 스크린샷 분석
• 차트·그래프 해석
• 표 → 텍스트 변환
• OCR 보조
• UI 디자인 피드백

주의: GGUF가 비전을 지원하려면 일반 모델보다 약간 복잡한 셋업이 필요합니다. LM Studio·Ollama는 31장에서 자세히.

9.8 Audio / STT / TTS — 음성

회의록 자동화·받아쓰기 도구에 많이 씁니다. 31장에서 다룹니다.

9.9 Embedding 모델 — 검색용 별종

이건 글을 쓰는 모델이 아닙니다. 문장을 숫자 벡터로 바꾸는 모델입니다.

예시:

"오늘 회의 어땠어?"
        ↓ (embedding 모델)
[0.12, -0.45, 0.88, ..., 0.03]   (수백~수천 차원의 벡터)

비슷한 의미를 가진 문장끼리 가까운 벡터 가 됩니다.

이걸 이용해서 의미 기반 검색 을 합니다.

RAG(26장)의 핵심 부품입니다.

대표 모델:

BAAI/bge-m3
intfloat/e5-mistral-7b-instruct
nomic-embed-text
jina-embeddings-v3

Instruct 모델 대신 받지 마세요. 이건 답을 만들 수 없습니다.

9.10 Reranker — 검색 결과 정리하는 모델

Embedding으로 1차 후보를 찾은 뒤 진짜 관련도 높은 순서로 다시 정렬하는 모델.

RAG의 검색 품질을 한 단계 끌어올립니다.

BAAI/bge-reranker-v2-m3
jina-reranker-v2

27장에서 다시 다룹니다.

9.11 그 외 자주 보는 꼬리표

9.12 그래서 나는 뭘 받아야 하나?

케이스별 한 줄 처방

이 장에서 기억할 한 가지

모델 받기 직전에 꼬리표를 꼭 확인하세요.

Base / Instruct / Coder / Reasoning / VL / Embedding… 이 중 잘못 받으면 답이 안 나오거나 엉뚱한 결과가 나옵니다.

헷갈리면 Instruct 가 안전한 출발점입니다.

손으로 해볼 것

1. 같은 시리즈의 변종 비교

Hugging Face에서 Qwen3 를 검색하고 다음 변종 페이지를 차례로 띄워보세요.

• Qwen3-32B (Base)
• Qwen3-32B-Instruct
• Qwen3-32B-Thinking
• Qwen2.5-VL-32B-Instruct
• Qwen2.5-Coder-32B-Instruct

각 페이지 첫 줄에 적힌 차이점을 메모해보세요.

2. 내 업무에 맞는 모델 종류 결정

다음 빈칸을 채워보세요.

내 주된 목적:           __________________
받을 모델 종류:         Instruct / Coder / Reasoning / VL / ...
보조로 받을 모델:       (RAG라면 Embedding 추가)

이 결정은 17장에서 실제 다운로드로 이어집니다.

다음 장에서는 Safetensors / GGUF / MLX 파일 포맷의 차이를 봅니다.

같은 모델인데 어떤 형식으로 받아야 내 도구에서 도는지가 결정됩니다.

10장. 파일 포맷 — Safetensors / GGUF / MLX

이 장의 목표 모델을 받을 때 어떤 형식의 파일을 받아야 내 도구에서 도는지 가 자동으로 매칭됩니다.

“왜 받았는데 안 돌지?” 가 사라집니다.

10.1 왜 같은 모델이 여러 형식인가?

같은 모델이라도 어떤 런타임에서 돌릴 거냐에 따라 포맷이 다릅니다.

비유:

같은 영화도 mp4, mkv, mov, webm으로 받을 수 있는 것과 같음

가장 흔히 만나는 세 종류만 알면 됩니다.

10.2 Safetensors — 원본 가중치

Hugging Face의 표준 모델 형식.

model-00001-of-00014.safetensors
model-00002-of-00014.safetensors
...
model.safetensors.index.json

여러 조각으로 쪼개져 있습니다.

특징:

• 원본 정밀도 (FP16, BF16)
• 파일 크기가 큼
• 파이썬 transformers 라이브러리로 바로 로드
• 양자화 안 된 상태
• 로컬에서 직접 돌리기엔 무거움

언제 받나:

• 직접 양자화하거나 변환하고 싶을 때 (33장)
• 파인튜닝 할 때 (32장)
• transformers 코드로 실험할 때

초보자는 거의 받을 일이 없습니다.

10.3 GGUF — 로컬 AI의 표준

llama.cpp 진영의 단일 파일 포맷.

Qwen3-32B-Instruct-Q4_K_M.gguf   ← 파일 하나

특징:

• 단일 파일 (보통 4~40GB)
• 메타데이터·토크나이저·가중치가 다 들어있음
• 양자화에 최적화 (Q4/Q5/Q8 등)
• macOS 포함 거의 모든 OS에서 동작
• Ollama, LM Studio, llama.cpp가 모두 사용

언제 받나:

• LM Studio로 돌릴 때 ✅
• Ollama로 돌릴 때 ✅
• 거의 모든 로컬 AI 도구 ✅

이 책의 표준 포맷입니다.

GGUF 파일 이름 해독

Qwen3-32B-Instruct-Q4_K_M.gguf
└──┘  └─┘  └──────┘  └────┘
모델  크기   종류     양자화

• 모델 시리즈: Qwen3
• 파라미터 크기: 32B
• 종류: Instruct (9장)
• 양자화: Q4_K_M (5장)
• 확장자: .gguf

10.4 MLX — Apple Silicon 전용

Apple이 직접 만든 머신러닝 프레임워크의 모델 형식.

mlx-community/Qwen3-32B-Instruct-4bit
├── config.json
├── tokenizer.json
├── model.safetensors          ← 형식은 같지만 양자화됨
├── tokenizer_config.json
└── special_tokens_map.json

특징:

• Apple Silicon에 직접 최적화
• 같은 4bit여도 GGUF보다 빠를 수 있음
• 폴더(여러 파일)로 받음
• mlx-lm 라이브러리 또는 LM Studio(MLX 백엔드)로 실행
• 윈도우·리눅스에서는 사용 불가

언제 받나:

• 맥에서 최대 속도를 뽑고 싶을 때
• MLX 기반 도구를 쓸 때 (19장)

2025년부터 LM Studio가 MLX를 정식 지원하면서 맥 사용자의 매력적 선택지가 되었습니다.

10.5 그 외 만나게 될 포맷들

자주 보지만 깊이 알 필요는 없는 형식들.

맥에서 로컬 AI를 한다면 결국 GGUF 또는 MLX 둘 중 하나입니다.

10.6 도구 ↔ 포맷 매칭표

요약

• GGUF: 거의 모든 도구에서 됨
• MLX: LM Studio·mlx-lm에서 빠름
• Safetensors: 직접 변환·실험용

10.7 같은 모델, 어떤 페이지로 가야 하나

Qwen3-32B-Instruct 를 예로 들면:

원본 Safetensors
└─ Qwen/Qwen3-32B-Instruct           ← 큰 원본 (60GB+)

GGUF 양자화 배포자
├─ bartowski/Qwen3-32B-Instruct-GGUF
├─ unsloth/Qwen3-32B-Instruct-GGUF
└─ Qwen/Qwen3-32B-Instruct-GGUF      ← 공식 GGUF가 있는 경우도 있음

MLX 변환본
└─ mlx-community/Qwen3-32B-Instruct-4bit

목적별로:

• LM Studio / Ollama 사용자 → GGUF 양자화 배포자 페이지
• MLX 도구 / 빠른 속도 원하는 맥 사용자 → mlx-community
• 연구·파인튜닝 → 원본 Safetensors

10.8 신뢰할 수 있는 양자화 배포자

GGUF는 누구나 만들 수 있어서 누가 만들었느냐가 중요합니다.

검증된 배포자:

처음 보는 배포자라면 Community 탭의 후기를 한 번 확인하세요.

10.9 GGUF 파일 어디에 저장하나?

LM Studio·Ollama는 자동으로 관리해주지만, 원리를 알면 디스크 정리가 쉽습니다.

$ du -sh ~/.lmstudio/models ~/.ollama/models

이 명령으로 얼마나 차지하는지 확인 가능.

용량 부족하면 사용 안 하는 모델은 17장에서 어떻게 지우는지 봅니다.

이 장에서 기억할 한 가지

맥에서는 결국 GGUF 또는 MLX 둘 중 하나입니다.

• 호환성·도구 다양성: GGUF
• 속도·맥 최적화: MLX

Safetensors는 양자화·파인튜닝 할 때만 받습니다.

손으로 해볼 것

1. 같은 모델의 세 포맷 페이지를 직접 비교

다음 세 페이지를 띄워보세요.

• Qwen/Qwen3-8B-Instruct (Safetensors 원본)
• bartowski/Qwen3-8B-Instruct-GGUF (GGUF)
• mlx-community/Qwen3-8B-Instruct-4bit (MLX)

각각의 파일 목록과 총 크기를 비교해보세요.

2. 받기 직전 결정 한 줄 적기

내가 쓸 도구:              LM Studio / Ollama / mlx-lm / 기타
그에 맞는 포맷:            GGUF / MLX
받을 모델:                 ___________________
양자화 (5장):              Q4_K_M / Q5_K_M / 4bit
배포자:                    bartowski / unsloth / mlx-community / ...

이걸 들고 17장으로 가면 됩니다.

다음 장에서는 모델 이름을 처음부터 끝까지 해독하는 법 을 한 번에 정리합니다.

DeepSeek-R1-Distill-Qwen-32B-Q5_K_M-128K.gguf 같은 이름도 무서워지지 않습니다.

11장. 모델 이름 해독법

이 장의 목표 처음 보는 모델 이름이 와도 30초 안에 정체를 파악 할 수 있게 됩니다.

이 장의 결과는 곧 이 책 1~10장의 종합 응용입니다.

11.1 이름은 보통 7가지 정보로 만들어진다

길고 복잡해 보이는 이름도 다음 7개 정보를 조립한 것입니다.

①모델시리즈 ②버전 ③파라미터수 ④유형 ⑤특수기법 ⑥양자화 ⑦포맷

전부 다 적힌 경우는 드물고, 관련된 것만 골라 적습니다.

11.2 예제 1 — Qwen3-32B-Instruct

Qwen 3 - 32B - Instruct
└──┘ │   └─┘   └──────┘
①    ②   ③     ④

→ “Qwen 시리즈 3세대, 320억 파라미터, 일반 대화용”

11.3 예제 2 — Qwen3-32B-Instruct-Q4_K_M.gguf

Qwen3-32B-Instruct - Q4_K_M . gguf
└─────────────────┘  └────┘   └──┘
       기존 정보       ⑥양자화    ⑦포맷

→ “위 모델의 4비트 양자화 GGUF 파일”

11.4 예제 3 — meta-llama/Llama-3.1-8B-Instruct

meta-llama / Llama-3.1-8B-Instruct
└────────┘   └───┘ └─┘ └─┘ └──────┘
 소유자        ①   ②   ③    ④

소유자가 meta-llama 라는 건 원본이라는 뜻입니다 (10장).

11.5 예제 4 — Gemma-3-27B-it

Gemma - 3 - 27B - it
└───┘   │   └─┘   └┘
 ①      ②   ③    ④

it 표기는 Google·Gemma 시리즈에서 잘 씁니다. 9장에서 본 그 꼬리표입니다.

11.6 예제 5 — Qwen3-30B-A3B-Instruct-2507

Qwen3 - 30B - A3B - Instruct - 2507
└──┘    └─┘   └─┘   └──────┘   └──┘
 ①+②    ③    ⑤        ④       날짜

새로운 게 두 개 등장.

→ “총 30B인데 매 토큰마다 3B만 깨어남. 2025년 7월 버전 Instruct”

날짜 표기는 모델 카드를 잘 안 보면 “같은 모델인데 두 개?” 혼란이 와서 붙는 일이 많습니다.

11.7 예제 6 — DeepSeek-R1-Distill-Qwen-32B

DeepSeek - R1 - Distill - Qwen - 32B
└──────┘   └┘   └─────┘   └──┘   └─┘
   ①       ②      ⑤        ?     ③

→ “DeepSeek R1의 능력을 Qwen 32B에 옮겨 담은 reasoning 모델”

Distill: 큰 선생 모델의 답안으로 작은 학생 모델을 가르치는 기법. “큰 모델 똑똑함을 압축한 작은 모델” 이라고 보면 됩니다.

11.8 예제 7 — bartowski/Llama-3.3-70B-Instruct-Q5_K_L-GGUF

bartowski / Llama-3.3-70B-Instruct - Q5_K_L - GGUF
└───────┘   └─────────────────────┘  └────┘   └──┘
 소유자          기존 정보             ⑥양자화   포맷

처음 보는 양자화 Q5_K_L 도 5장에 나왔던 S/M/L 의 L 입니다. “같은 Q5 중에서도 Large = 정보를 더 많이 보존” 한 버전.

→ “bartowski가 양자화한 Llama 3.3 70B Instruct, Q5_K_L GGUF”

11.9 예제 8 — mlx-community/Qwen2.5-VL-32B-Instruct-4bit

mlx-community / Qwen2.5 - VL - 32B - Instruct - 4bit
└───────────┘   └────┘   └┘   └─┘   └──────┘   └──┘
   소유자        ①+②     ④     ③       ④       ⑥

→ “Qwen 2.5 VL 32B의 MLX 4비트 버전, 이미지 입력 가능”

11.10 자주 헷갈리는 표기 정리

11.11 30초 해독 절차

이름이 길고 무서워 보이면 왼쪽부터 한 토막씩 끊어 읽으세요.

[소유자] / [시리즈]-[버전]-[크기]-[유형]-[특수]-[양자화].[포맷]

읽어가며 머리에 떠올릴 질문:

1. 누가 올렸나? (원본/양자화 배포자)
2. 어떤 시리즈인가? (Qwen, Llama, …)
3. 몇 B인가? (메모리 계산용 — 4장)
4. 무슨 용도인가? (Instruct? Vision? Reasoning?)
5. 특수 기법? (Distill, MoE A_B, Thinking?)
6. 양자화? (Q4_K_M 등 — 5장)
7. 포맷? (GGUF / MLX / Safetensors — 10장)

11.12 실전 — 모르는 이름 만났을 때

이 책에 안 나온 이름이 와도 당황하지 마세요.

Phi-4-mini-Reasoning-4B-Q4_K_M.gguf

해독:

• Phi: Microsoft 시리즈
• 4: 4세대
• mini: 작은 버전
• Reasoning: 추론 모델
• 4B: 40억 파라미터
• Q4_K_M: 4비트 양자화
• gguf: GGUF 포맷

→ “Microsoft Phi 4세대 소형 추론 모델, 40억 파라미터, 4비트 양자화 GGUF”

이 정도 추론이 30초 안에 되면 이 책 1부·2부가 잘 들어온 겁니다.

이 장에서 기억할 한 가지

모델 이름은 7개 필드의 조립체: 시리즈 / 버전 / 크기 / 유형 / 특수 / 양자화 / 포맷.

왼쪽부터 토막내서 읽으면 모르는 이름도 거의 다 풀립니다.

손으로 해볼 것

다음 모델 이름을 각각 해독해보세요. 답은 모델 카드를 열어보면 확인할 수 있습니다.

1. Qwen3-14B-Instruct
2. mistralai/Mixtral-8x7B-Instruct-v0.1
3. unsloth/DeepSeek-R1-Distill-Qwen-14B-GGUF
4. mlx-community/Llama-3.3-70B-Instruct-4bit
5. bartowski/Qwen2.5-Coder-32B-Instruct-Q5_K_L.gguf

처음에는 답이 안 나와도 좋습니다. 3개 정도부터 막힐 텐데, 3장(파라미터), 9장(유형), 10장(포맷), 14장(MoE) 을 다시 한 번씩 펼쳐보세요.

다음 장에서는 라이선스 를 정면으로 봅니다.

“이 모델 회사에서 써도 되는 거 맞아?” 라는 질문에 답할 수 있게 됩니다.

12장. 라이선스 — 회사에서 써도 되는 모델 가리기

이 장의 목표 라이선스 한 줄만 보고 “이거 회사에서 써도 되겠다 / 안 되겠다” 를 판단할 수 있게 됩니다.

변호사 수준이 아니라, 개발자 수준의 실용 판단 기준입니다.

12.1 왜 이게 중요한가

회사에서 로컬 AI를 도입할 때 가장 많이 막히는 게 라이선스입니다.

• 무료라고 받았는데 상업적으로 쓰면 안 되는 경우
• 출력에 출처 표기를 해야 하는 경우
• 회사 규모가 너무 크면 별도 계약이 필요한 경우
• 데이터를 학습에 다시 쓰면 안 되는 경우

한 번 정리해두면 평생 든든합니다.

12.2 라이선스 한눈에 보기

자주 만나는 라이선스 8종.

※ 가 붙은 것들은 조건부 OK 입니다.

12.3 ✅ 자유롭게 쓸 수 있는 라이선스

Apache 2.0

• 가장 사업 친화적
• 수정·배포·상업적 사용 자유
• 출처 표기 필요 (보통 NOTICE 파일에)
• 코드·모델 모두에서 가장 흔함

대표 모델:

Qwen3 시리즈 (일부)
Mistral 7B (오리지널)
DeepSeek 일부

MIT

• Apache보다 더 짧고 간결
• 거의 같은 효력
• 한 줄: “마음대로 써, 책임은 안 짐”

대표 모델:

Phi-4
일부 Mistral 모델
다수의 임베딩 모델

이 두 라이선스가 붙어있으면 회사에서 거의 무조건 OK 입니다.

12.4 ⚠ 조건부 OK — Llama 라이선스

Meta의 Llama 시리즈는 자체 라이선스(Llama 3 / 3.1 / 3.3 Community License) 를 씁니다.

일반 회사라면 다 통과합니다. 단, “Built with Meta Llama 3” 같은 표기를 잊지 마세요.

대표 모델:

meta-llama/Llama-3.3-70B-Instruct
meta-llama/Llama-3.1-8B-Instruct

12.5 ⚠ 조건부 OK — Gemma 라이선스

Google의 Gemma 시리즈도 자체 라이선스(Gemma Terms of Use) 를 씁니다.

Prohibited Use Policy는 “무기·차별·기만·아동 안전 위반” 같은 일반적인 금지사항입니다.

대표 모델:

google/gemma-3-27b-it
google/gemma-3-9b-it

12.6 ⚠ 조건부 OK — Qwen / DeepSeek 등

알리바바의 Qwen, DeepSeek 등은 모델마다 라이선스가 약간 다릅니다.

• 대부분은 Apache 2.0 이나 자체 라이선스
• 일부 큰 모델은 상업적 사용 시 별도 신청
• 모델 카드 라이선스 칸을 꼭 확인

대표 케이스:

Qwen3-32B-Instruct           →  Apache 2.0  ✅
Qwen-Max (상업 API)          →  자체 라이선스

12.7 ❌ 회사에서 쓰면 안 되는 라이선스

CC-BY-NC (Non-Commercial)

NC 가 핵심입니다.

비상업적 용도만 가능.

회사 업무에 쓰면 라이선스 위반입니다. 취미나 연구라면 OK.

흔히 보이는 변종:

cc-by-nc-4.0
cc-by-nc-sa-4.0

일부 모델의 research only 표기

모델 카드에:

"This model is for research purposes only."

이런 문장이 보이면 회사 업무에 쓰면 안 됩니다.

Uncensored / Abliterated 변종

라이선스 자체는 원본을 따르지만, 안전장치를 제거한 모델은 회사 도입에 부적합 입니다.

- 사내 챗봇·고객 응대에 절대 안 됨
- 거부 회로가 우회되어 위험 발언이 그대로 나옴
- 컴플라이언스 이슈 큼

12.8 △ OpenRAIL — 책임 있는 사용

OpenRAIL-M 같은 라이선스는 사용 목적 제한 이 있습니다.

금지된 용도 예:

• 사람 차별·해코지
• 의료 진단 (의사 감독 없이)
• 군사 활용

회사가 이런 용도가 아니라면 보통 OK입니다.

12.9 회사 도입 체크리스트

새 모델 도입 전에 묻는 5가지.

1. 라이선스가 뭔가?
   • Apache 2.0 / MIT → 거의 OK
   • Llama / Gemma → 조건부 OK
   • CC-BY-NC → ❌
2. 출처 표기가 필요한가?
   • 사내 도구 어딘가에 표기 가능 위치 확보
3. 회사 규모 제한이 있는가?
   • Llama: 월 7억 MAU 초과 시 별도 계약
4. 출력물의 권리는?
   • 대부분 자유롭게 사용 가능
   • 다른 LLM 학습에 쓰는 건 제한 있을 수 있음
5. 금지된 사용 목적은?
   • 의료·법률 자동 결정·감시 등 주의

12.10 한국 회사가 흔히 빠지는 함정

“오픈소스 = 무료 = 마음대로 OK” 함정

오픈소스 라이선스도 의무가 있습니다. 출처 표기 안 하면 라이선스 위반 입니다.

“어차피 사내용인데 누가 알겠어” 함정

라이선스 위반은 추후 외부 공개·소스 감사 때 드러납니다. 파이프라인 깨고 다시 만드는 게 비용 더 큽니다.

“양자화 모델은 라이선스 다르겠지” 함정

아닙니다. 양자화 모델은 원본 라이선스를 그대로 따릅니다. bartowski 가 양자화한 Llama 모델도 Llama 라이선스를 따릅니다.

“파인튜닝하면 내 모델 되겠지” 함정

베이스 모델 라이선스를 여전히 따라야 합니다. Llama 베이스로 파인튜닝하면 결과물도 Llama 라이선스.

이 장에서 기억할 한 가지

회사 도입 라이선스 한 줄 결정 트리

1. Apache 2.0 / MIT → ✅ 그냥 쓰세요
2. Llama / Gemma / Qwen → ✅ 단, 표기·정책 확인
3. CC-BY-NC / research only → ❌ 회사에서 쓰지 마세요
4. Uncensored / Abliterated → ❌ 회사에서 쓰지 마세요

손으로 해볼 것

1. 후보 모델 라이선스 메모표 만들기

지금까지 봐온 모델들을 표로 정리하세요.

2. 회사 표기 위치 미리 정해두기

만약 사내 챗봇에 로컬 AI를 쓸 거라면, 다음 중 어디에 라이선스 표기를 둘지 정해두세요.

• README에 “Built with Llama” 한 줄
• 챗봇 푸터에 “Powered by …” 한 줄
• 사내 위키에 모델 출처 페이지

다음 장에서는 벤치마크 점수 읽는 법 입니다.

“이 모델 MMLU 75점인데 좋은 거야?” 같은 질문에 답할 수 있게 됩니다.

13장. 벤치마크 읽는 법

이 장의 목표 모델 카드의 점수표를 읽고 “이 모델이 뭘 잘하고 뭘 못하는지” 를 자기 눈으로 평가할 수 있게 됩니다.

“MMLU 1등!“에 휘둘리지 않게 됩니다.

13.1 벤치마크가 뭔가?

모델의 객관적 실력을 재기 위해 미리 만들어둔 시험 문제 세트입니다.

예:

MMLU 시험 문제 예
─────────────────
주제: 미국사
문제: 1776년에 일어난 사건은?
선택지: A. 독립선언 B. 남북전쟁 C. ...
정답: A

이런 문제 수천~수만 개를 모델에 풀게 하고 점수(정답률)를 매깁니다.

13.2 자주 보는 벤치마크 10가지

모델 카드에 가장 많이 등장하는 것들.

일반 지식·언어이해

수학

코딩

추론·지시 따르기

한국어

멀티모달

긴 컨텍스트

13.3 점수의 일반적 감각

점수만 보면 막막하니 대략 감각을 잡아둡니다.

MMLU (보통 0~100)

50점대 → 약함 (작은 옛 모델)
60점대 → 평범
70점대 → 좋음 (요즘 8B 모델 수준)
80점대 → 매우 좋음 (32B급 좋은 모델)
85점 이상 → 최상위 (GPT-5, Claude Opus 4 등)

HumanEval

30~50% → 옛 모델
50~70% → 평범한 코딩 모델
70~85% → 좋은 코딩 모델 (Qwen Coder 32B)
85% 이상 → 매우 좋음

GSM8K

50% 이하 → 수학 약함
70~85% → 평범
90% 이상 → 잘함
95% 이상 → 매우 잘함 (Reasoning 모델)

숫자 자체보다 “동급 모델끼리의 비교“가 중요합니다. 같은 8B 모델끼리 비교해야 의미가 있습니다.

13.4 벤치마크의 함정 3가지

점수를 너무 믿으면 다칩니다.

함정 1 — Data Contamination(데이터 오염)

벤치마크 문제가 모델 학습 데이터에 이미 들어있을 수 있습니다.

이러면 모델이 “푼” 게 아니라 “외운” 거에 가깝습니다.

새 벤치마크일수록 신뢰도 높음 오래된 벤치마크는 의심하기

함정 2 — Overfitting to Benchmark

회사들이 벤치마크 점수를 올리려고 그 시험을 잘 보도록 따로 튜닝합니다.

학교에서 모의고사만 잘 보는 학생 같습니다.

실전 업무에선 점수만큼 안 좋을 수 있습니다.

함정 3 — 평가 방식 차이

같은 MMLU여도

• 객관식만? CoT(생각 과정) 포함?
• 5-shot? Zero-shot?
• 평균? 가중치?

방식이 다르면 점수가 5~10점씩 출렁입니다.

같은 모델, 같은 시험인데 누가 측정했냐에 따라 결과가 다를 수 있습니다.

13.5 벤치마크보다 좋은 것 — 내 작업 테스트

결국 가장 정확한 벤치마크는 “내 업무 질문에 대한 답“입니다.

이걸 위해 나만의 테스트 셋을 만들어두면 좋습니다.

자주 묻는 형태로 10~20개:

• 회사 도메인 질문 5개
• 코드 작성 3개
• 문서 요약 3개
• 한국어 작문 3개
• 환각 테스트 (모르는 사실) 2개
• 거절 테스트 (위험 질문) 2개

이걸 새 모델이 나올 때마다 똑같이 시켜보면 나에게 맞는 모델을 점수표 없이 가릴 수 있습니다.

(40장에서 다시 자세히)

13.6 신뢰할 만한 리더보드

벤치마크 점수를 모아 보여주는 사이트들.

가장 추천:

• lmarena.ai — 사용자가 두 답변을 직접 비교 투표 점수 조작에 강함

13.7 모델 카드 점수표 읽기 실전

대표적인 점수표 형태.

| Benchmark    | Score |
|--------------|-------|
| MMLU         | 83.5  |
| MMLU-Pro     | 68.2  |
| GSM8K        | 92.1  |
| HumanEval    | 85.4  |
| MATH         | 65.3  |
| IFEval       | 79.0  |

이걸 읽는 법.

1. 내 용도와 관련된 줄만 본다
   • 코딩 → HumanEval, LiveCodeBench
   • 수학 → GSM8K, MATH
   • 일반 지식 → MMLU
   • 지시 따르기 → IFEval
2. 동급 모델과만 비교
   • 같은 8B / 32B / 70B 끼리
3. 출처를 본다
   • 회사가 자체 보고 vs 제3자 측정
4. 약점도 찾는다
   • 모델 카드에 빠진 벤치마크가 의심스러우면 외부 확인

13.8 흔히 좋아 보이지만 못 미더운 표

가끔 모델 카드에 이런 표가 있습니다.

Qwen3-32B (Ours) ─────  85.5
GPT-5             ─────  82.0
Claude Opus 4     ─────  78.0
Llama 3.3 70B    ─────  75.0

오케이, 의심해봅니다.

• 측정 시기는?
• 평가 방식은 동일?
• 자체 보고 점수?
• 그 모델들이 한 달 전 버전 아닌가?

회사가 자기 모델 점수를 직접 발표하면 항상 의심.

가장 안전한 비교는 다시 한 번:

• lmarena.ai 의 실사용자 투표
• 내 테스트 셋(40장)으로 직접 비교

이 장에서 기억할 한 가지

벤치마크는 참고용 1, 결정적 근거 0.

동급 모델 사이의 비교에서만 의미 있고, 내 업무 질문 10개 가 항상 더 정확합니다.

점수가 비슷하면 lmarena.ai 의 사람 투표를 보세요.

손으로 해볼 것

1. 같은 크기 두 모델 비교 표 만들기

Qwen3-32B-Instruct 와 Llama-3.3-70B-Instruct 의 모델 카드 점수를 다음 표에 옮겨보세요.

같은 32B 모델끼리 / 같은 70B 모델끼리도 한 번씩 비교해보세요.

2. lmarena.ai 둘러보기

lmarena.ai 에 들어가서 같은 질문에 두 모델이 답하는 걸 보고 어느 쪽이 더 마음에 드는지 투표해보세요.

5~10번 반복하면 “리더보드 점수 vs 내 취향“이 달라질 수 있다는 걸 체감하게 됩니다.

다음 장에서는 Dense 모델과 MoE 모델의 차이 를 정리합니다.

“30B인데 활성 파라미터 3B” 같은 표기를 한 번에 이해할 수 있게 됩니다.

14장. Dense vs MoE

이 장의 목표 Qwen3-30B-A3B, Mixtral-8x7B 같은 표기를 만나도 메모리와 속도가 어떻게 다른지 한 번에 그림이 그려지게 됩니다.

14.1 두 가지 구조

LLM의 내부 구조는 크게 두 가지로 나뉩니다.

[Dense]                     [MoE (Mixture of Experts)]
모델 전체가                   "전문가" 여러 개로 쪼개짐
한 덩어리                     매번 일부만 깨어남

이름은 어렵게 들리지만 핵심은 하나입니다.

매 토큰을 만들 때 모델 안의 “얼마만큼“이 일하는가.

14.2 Dense 모델 — 전부 다 일한다

지금까지 우리가 본 모델 대부분은 Dense 입니다.

[Dense 32B]
한 토큰을 만들 때마다
32B 가중치를 거의 다 사용

장점:

• 구조가 단순
• 예측 가능
• 만들기 쉬움

단점:

• 큰 모델일수록 무거움
• 매 토큰마다 모든 가중치를 메모리에서 읽어야 함

대표 예:

Qwen3-32B
Llama-3.3-70B
Gemma-3-27B

14.3 MoE 모델 — “전문가“만 깨어난다

MoE는 모델 안에 여러 명의 전문가 가 있고, 질문에 따라 일부 전문가만 일을 합니다.

[MoE 30B-A3B]
총 30B 안에 "전문가" 128명
한 토큰을 만들 때마다 그중 8명만 깨어남
실제 계산 = 약 3B 분량

비유:

회사 전 직원이 출근은 했지만, 한 번에 일하는 건 8명뿐.

자료실(메모리) 자리는 모두가 차지하지만, 점심값(계산 비용)은 8명만 든다.

14.4 MoE의 진짜 의미

자주 오해하는 부분.

오해 — “MoE는 작은 모델처럼 가볍다”

틀렸습니다.

매 토큰마다 깨어나는 건 일부지만, 전체 전문가 가중치는 메모리에 항상 올라와 있어야 합니다.

30B-A3B 모델
가중치 크기   → 30B (전부 메모리에 있어야 함)
계산량        → 3B 수준만

즉:

• 메모리 사용량 → 30B 만큼
• 속도 → 3B 만큼 빠름

14.5 그럼 MoE는 왜 좋은가?

장점:

• 속도가 빠르다 (같은 메모리에서 더 큰 모델의 지식 활용)
• 성능 대비 효율적
• 대규모 사용처(서버)에서 유리

단점:

• 메모리 절약은 안 됨
• 학습이 까다로움
• 같은 양자화여도 결과가 Dense보다 들쭉날쭉할 때 있음

로컬 환경에서는 다음과 같이 봅니다.

• 32GB 맥 → Dense 8B Q5 vs MoE 30B-A3B Q4 메모리 비슷, 속도는 MoE가 더 빠를 수 있음
• 단, 32GB에 30B MoE는 빡빡할 수 있어 주의

14.6 MoE 표기 해독

Qwen3-30B-A3B
└──┘ └─┘ └─┘
시리즈 총  활성
       30B 3B

다른 표기 방식:

Mixtral-8x7B-Instruct
└────┘ └───┘
시리즈  8명 × 7B 짜리 전문가

이 모델은 전문가 8명, 각 7B.

• 총 가중치 ≈ 47B (공유 부분 있어 8 × 7B 보다 적음)
• 활성 = 2명 × 7B ≈ 13B 계산량

14.7 같은 메모리 — Dense vs MoE 비교

64GB 맥에서 Q4 양자화 기준, 대략적인 비교.

MoE의 마법: 메모리는 큰 모델만큼 먹지만 속도는 작은 모델급.

단, 한국어처럼 학습량이 적은 언어는 MoE에서 가끔 답이 들쭉날쭉할 수 있어 같은 시리즈의 Dense와 한 번 비교해보는 게 안전.

14.8 어떨 때 MoE를 받나?

MoE가 좋은 상황

• 속도가 중요
• 메모리는 여유
• 영어·중국어 작업이 메인
• 같은 메모리에서 더 많은 지식 원함

Dense가 좋은 상황

• 메모리가 빠듯
• 답변 안정성 우선
• 한국어 비중이 크고 모델이 작은 경우
• 다중 모달·특수 분야 모델 (대부분 Dense)

14.9 대표 MoE 모델들

2025~2026 기준 자주 보는 MoE.

14.10 64GB 맥에서 MoE를 어떻게 선택하나

추천 시나리오.

이 장에서 기억할 한 가지

Dense: 모델 전체가 매번 일함 — 무겁고 안정적. MoE: 일부 전문가만 깨어남 — 빠르지만 메모리는 그대로.

MoE 표기 핵심: 총-A활성 — 메모리는 총, 속도는 활성.

손으로 해볼 것

1. MoE 모델 페이지 직접 비교

다음 두 모델의 페이지를 띄워놓고 파일 크기·컨텍스트·벤치마크 점수를 비교해보세요.

• Qwen3-32B-Instruct (Dense)
• Qwen3-30B-A3B-Instruct (MoE)

2. 동일 메모리 시뮬레이션

내 맥 메모리에서 위 두 모델을 Q4로 돌린다고 가정하고 다음을 어림셈 해보세요.

• 메모리 사용 (4장 식)
• 속도 (7장 식 + MoE는 활성 파라미터로 계산)

이런 감각이 잡히면 다음 부에서 실제로 받을 때 “왜 이게 더 빠를까?” 가 미리 보입니다.

여기서 2부가 끝납니다.

여기까지 잘 따라왔다면 이제 Hugging Face의 거의 모든 모델 페이지를 처음 보는 모델이라도 해독할 수 있습니다.

다음 부에서는 드디어 내 맥에서 모델을 직접 돌립니다. 3부 시작은 터미널 기본기부터입니다.

15장. 터미널 최소한

이 장의 목표 Ollama·MLX·llama.cpp 같은 도구를 쓸 때 더는 터미널이 무섭지 않게 됩니다.

명령어 20개만 익히면 됩니다.

15.1 터미널이 뭔가

맥을 글자로 조작하는 창입니다.

Finder (마우스로 클릭)  ↔  터미널 (글자로 명령)

같은 일을 하는 두 방식 중 하나입니다.

로컬 AI 도구의 80%는 처음 한두 번은 터미널을 거쳐야 합니다.

15.2 터미널 여는 법

방법 두 가지.

1. Spotlight 검색
   • Cmd + Space → “terminal” 입력 → Return
2. Launchpad → 기타 → 터미널

요즘은 더 예쁘고 빠른 Warp, iTerm2, 또는 macOS 기본 터미널의 후속 Ghostty도 인기.

이 책에서는 기본 Terminal.app 또는 zsh 기준으로 설명합니다.

처음 열면 이런 게 떠 있습니다.

kjj@MacBookPro ~ %

코드 블록에서는 $ 또는 % 로 시작하는 줄이 명령이고, 나머지는 출력입니다. 실제 입력 시 $ / % 는 빼고 칩니다.

15.3 첫 5개 명령어 — 위치와 파일

pwd — 지금 어디?

$ pwd
/Users/kjj

ls — 여기 뭐 있어?

$ ls
Applications  Desktop  Documents  Downloads ...

자주 쓰는 옵션:

$ ls -lh        # 자세히 + 사람이 읽기 쉬운 크기
$ ls -lha       # 숨김 파일까지

cd — 이동

$ cd Documents
$ cd ~/Downloads   # 홈 기준 절대 경로
$ cd ..            # 한 단계 위로
$ cd -             # 직전 위치로

mkdir — 폴더 만들기

$ mkdir local-ai

open — Finder로 열기

$ open .       # 현재 위치를 Finder에서 열기
$ open ~/.ollama   # Ollama 폴더 열기

15.4 두 번째 5개 — 파일 보기·찾기

cat — 파일 내용 보기

$ cat README.md

less — 길면 한 페이지씩

$ less very-long.log
# q 누르면 종료

head / tail — 앞·뒤만

$ head -n 20 server.log
$ tail -n 50 server.log
$ tail -f server.log    # 실시간 새 로그

grep — 글자 검색

$ grep "ERROR" server.log
$ grep -r "TODO" ~/Code  # 폴더 안 전부

which — 이 명령어 어디 있어?

$ which python3
/opt/homebrew/bin/python3

15.5 세 번째 5개 — 시스템 상태

top / htop

지금 무슨 프로세스가 도는가.

$ top
# q 누르면 종료

htop 은 더 보기 좋음 (brew install htop 필요).

df -h — 디스크 남은 용량

$ df -h
Filesystem    Size   Used  Avail  Capacity
/dev/disk1   500Gi  120Gi  380Gi    25%

du -sh — 폴더 크기

$ du -sh ~/.ollama/models
84G   /Users/kjj/.ollama/models

free 또는 vm_stat — 메모리

macOS에는 free 가 없습니다. 활성 상태 보기 앱을 쓰는 게 편하지만 터미널로 확인하려면:

$ vm_stat

또는 더 쉽게:

$ top -l 1 | grep PhysMem
PhysMem: 38G used (5G wired), 26G unused.

kill — 프로세스 종료

$ kill -9 12345     # PID 12345인 프로세스 강제 종료

PID는 top 이나 ps aux 로 확인.

15.6 네 번째 5개 — 다운로드·네트워크

curl — URL에서 데이터 가져오기

$ curl https://example.com

옵션:

$ curl -O https://example.com/file.gguf   # 파일로 저장
$ curl -L ...                              # 리다이렉트 따라가기
$ curl -s ...                              # 진행 표시 숨김

wget — 또 다른 다운로드 도구

기본 macOS에는 없음. 설치:

$ brew install wget

ping

$ ping google.com

ifconfig 또는 ipconfig getifaddr en0 — 내 IP

$ ipconfig getifaddr en0
192.168.0.42

lsof -i :PORT — 이 포트 누가 쓰고 있어?

$ lsof -i :11434
COMMAND   PID  USER ...
ollama    1234 kjj  ...

15.7 Homebrew 설치 — 맥의 패키지 매니저

로컬 AI 도구를 받을 때 거의 항상 거치는 길.

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

한 번 설치하면 다음처럼 씁니다.

$ brew install wget
$ brew install htop
$ brew install ollama        # 이렇게도 받을 수 있지만 GUI 앱 권장
$ brew upgrade               # 전체 업데이트
$ brew list                  # 깔린 것 보기
$ brew uninstall wget        # 삭제

15.8 Python 환경 — 가상환경

MLX 같은 Python 도구를 쓸 때 시스템 Python을 더럽히지 않기 위해 가상환경을 씁니다.

$ mkdir ~/Developer/local-ai
$ cd ~/Developer/local-ai

$ python3 -m venv .venv      # 가상환경 생성
$ source .venv/bin/activate  # 진입
(.venv) $ pip install mlx-lm

(.venv) $ deactivate         # 나가기

가상환경에 들어가면 프롬프트 앞에 (.venv) 가 표시됩니다.

15.9 환경변수와 PATH

처음에는 몰라도 되지만, 도구 설치 후 “command not found” 가 뜨면 PATH 문제입니다.

$ echo $PATH
/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:...

zsh 설정 파일은 ~/.zshrc.

$ open ~/.zshrc

자주 추가하는 줄:

export PATH="/opt/homebrew/bin:$PATH"

수정 후:

$ source ~/.zshrc    # 변경 즉시 적용

15.10 알아두면 편한 zsh 단축키

15.11 모르겠으면 --help 또는 man

거의 모든 명령어에 도움말이 있습니다.

$ curl --help
$ man curl       # q 로 종료

이 장에서 기억할 한 가지

이 책에서 자주 쓸 명령은 결국 10개입니다.

pwd ls cd mkdir open cat tail grep curl top

나머지는 필요할 때 검색하면 됩니다.

손으로 해볼 것

1. 로컬 AI 작업 폴더 만들기

$ mkdir -p ~/Developer/local-ai
$ cd ~/Developer/local-ai
$ pwd
$ open .

이 폴더가 앞으로 모든 실습의 베이스가 됩니다.

2. Homebrew 설치 확인

$ which brew

경로가 나오면 OK. “not found” 가 나오면 15.7 절을 참고해 설치하세요.

3. 디스크·메모리 상태 점검

$ df -h
$ top -l 1 | grep PhysMem

내 맥에 모델 받을 여유가 얼마나 있는지 확인.

다음 장에서는 LM Studio — 가장 친절한 로컬 AI GUI 도구로 첫 모델을 받고 돌려봅니다.

설치부터 첫 질문까지 15분이면 됩니다.

16장. LM Studio — GUI로 시작하기

이 장의 목표 15분 안에 내 맥에서 첫 로컬 AI 응답을 받는 것이 목표입니다.

가장 친절한 GUI 도구 LM Studio로 시작합니다.

16.1 LM Studio가 뭔가?

로컬 AI를 마우스 클릭만으로 다루게 해주는 앱.

• 모델 검색
• 모델 다운로드
• 모델 로드/언로드
• 채팅 인터페이스
• API 서버 기능
• GGUF · MLX 모두 지원

처음 로컬 AI를 만지는 사람에게는 LM Studio가 가장 부드러운 시작입니다.

16.2 설치

lmstudio.ai 에 들어가서 Download for macOS (Apple Silicon) 버튼.

다운로드된 .dmg 를 열고 Applications 폴더로 드래그.

Launchpad 또는 Spotlight 에서 “LM Studio” 검색 → 실행.

16.3 첫 실행 — 화면 구성

좌측 사이드바에 5개 아이콘이 있습니다.

[💬] Chat        — 대화
[🔍] Discover    — 모델 찾기·다운로드
[📁] My Models   — 받아둔 모델 목록
[🔧] Developer   — 로컬 API 서버
[⚙️] Settings    — 환경 설정

처음 할 일은 Discover 입니다.

16.4 첫 모델 다운로드 — Discover 탭

검색창에 다음을 넣어보세요.

Qwen3-8B-Instruct

이 책의 표준 첫 모델은 8B Q4_K_M 입니다.

오른쪽에 양자화별 파일 목록이 보입니다.

Q2_K       Q3_K_M   Q4_K_S   ★Q4_K_M★   Q5_K_M   Q6_K   Q8_0

별표로 추천된 양자화가 나옵니다. 보통 Q4_K_M 입니다.

다운로드 버튼을 누르면 진행 바가 흐릅니다.

8B Q4는 약 5GB. 32B Q4는 약 20GB. 안정된 와이파이에서 받으세요.

16.5 MLX 버전을 받을지 GGUF를 받을지

LM Studio는 둘 다 받을 수 있습니다. 검색 결과 옆에 GGUF 또는 MLX 태그가 보입니다.

처음에는 GGUF로 시작합시다. 19장에서 MLX 버전을 추가로 받아 비교해봅니다.

16.6 첫 채팅 — Chat 탭

다운로드가 끝나면 Chat 탭으로 갑니다.

상단 중앙에 모델 선택 드롭다운.

[Select a model to load ↓]

방금 받은 모델을 고르면 오른쪽에 로드 옵션 패널이 떠요.

Context Length:  [ 8192 ]
GPU Offload:     [ Max ]
CPU Threads:     [ Auto ]
KV Cache (FP16): [ ON ]

처음에는 그대로 두고 Load Model 클릭.

수 초~십수 초 후 메모리에 올라옵니다.

이제 아래 입력창에 질문을 적어보세요.

한국어로 자기 소개 한 문장 해줘.

답이 흐르면 성공입니다.

16.7 답변 화면에서 보이는 정보

응답이 완료되면 작은 글씨로 다음 정보가 뜹니다.

First token: 0.4s  •  Speed: 21.3 tok/s  •  92 tokens

이걸 보면서 내 맥의 실제 성능을 측정할 수 있습니다.

16.8 LM Studio 채팅 화면의 유용한 기능

• System Prompt 입력 (좌측 또는 상단)
• Temperature, Top-P 조절 (우측)
• 컨텍스트 길이 변경 (모델 재로드 필요)
• Conversation branching — 답변에서 분기
• 이미지 첨부 (VL 모델일 경우)
• 모델 비교 모드 (같은 질문에 두 모델 동시)
• Markdown 렌더링, 코드 하이라이트

16.9 컨텍스트 길이 — 빨리 만지는 법

상단 모델 이름 옆 ⚙ Configure 클릭 → Context Length 슬라이더.

너무 크게 잡으면 KV Cache로 메모리가 폭주합니다 (6장). 처음에는 8K~16K 권장.

16.10 API 서버 — Developer 탭

LM Studio의 진짜 강점: 클릭 한 번으로 OpenAI 호환 API 서버가 됩니다.

좌측 Developer 탭 → 상단 Start Server.

Status: Running on http://localhost:1234

이제 다음 명령으로 외부에서 호출 가능:

$ curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-8b-instruct",
    "messages": [
      {"role": "user", "content": "안녕"}
    ]
  }'

이건 25장(OpenAI 호환 API)에서 본격 다룹니다.

16.11 자주 만나는 LM Studio 문제

“Out of memory” 떠요

컨텍스트를 줄이세요. 또는 한 단계 아래 양자화로 다시 받으세요.

너무 느려요

• 채팅 기록이 길어졌나? → 새 채팅 시작
• 다른 모델이 로드돼 있나? → 언로드
• 컨텍스트가 너무 큰가? → 줄이기
• MLX 버전이 있나? → 그쪽 받아 비교

한국어가 깨져요

• 양자화가 너무 낮음 (Q3 이하)
• 모델 자체의 한국어가 약함 (모델 카드 확인)
• Chat Template이 잘못 적용 (22장)

16.12 LM Studio의 한계

처음에는 좋지만 점점 답답해질 수도 있습니다.

• 자동화·스크립트는 Ollama·llama.cpp가 더 편함
• 일부 최신 모델은 LM Studio 업데이트 지연
• 큰 워크로드를 백그라운드로 돌리기엔 무거움

그래도 처음 한 달은 LM Studio로 학습하세요. 다른 도구도 결국 같은 원리입니다.

이 장에서 기억할 한 가지

첫 로컬 AI 응답까지 15분.

1. LM Studio 설치
2. Discover에서 8B Q4_K_M 다운로드
3. Chat에서 Load
4. 질문하면 답이 흐름

손으로 해볼 것

1. 내 맥의 표준 모델 받아 첫 대화

위 16.4 절 표에서 내 맥에 맞는 모델 하나 받기.

다음 질문을 차례로 던져 보세요.

1. 한국어로 자기 소개 한 문장 해줘.
2. 1과 2를 합하면? (수학 기초)
3. Python으로 1~10 출력하는 코드 한 줄 짜줘.
4. 너 한국어 잘하는 편이야? 솔직하게.

응답마다 First token / Speed 값을 메모해두세요.

2. 같은 질문으로 양자화 비교 (선택)

여유 메모리가 있다면 Q4_K_M 과 Q5_K_M 을 모두 받아 같은 질문에 답을 비교해 보세요.

품질 vs 속도 트레이드오프를 직접 체감할 수 있습니다.

다음 장에서는 Ollama — 터미널과 API 중심의 로컬 AI 도구를 다룹니다.

자동화나 사내 도구에 붙일 거라면 거의 항상 Ollama가 더 편합니다.

17장. Ollama — 터미널/API로 다루기

이 장의 목표 터미널과 API로 로컬 AI를 다루는 표준 도구 Ollama 를 익힙니다.

이걸 알면 자동화·사내 도구·Agent까지 길이 열립니다.

17.1 Ollama가 뭔가?

명령어 한 줄로 모델을 받고, 돌리고, API로 제공.

$ ollama run gemma3

이 한 줄이면 모델을 받아 채팅 모드로 들어갑니다.

LM Studio가 마우스 중심이라면, Ollama는 터미널·API 중심.

특징:

• 백그라운드 데몬으로 항상 떠있음
• localhost:11434 에서 자동 API 서버
• OpenAI 호환 엔드포인트 제공
• Continue.dev, VS Code 확장, Open WebUI 등 거의 모든 클라이언트와 호환

17.2 설치

ollama.com/download 에서 macOS 버전 다운로드.

.dmg 를 열고 Ollama.app 을 Applications 로 드래그.

처음 실행하면 메뉴바에 작은 라마 아이콘이 뜹니다. 이게 백그라운드 데몬입니다.

확인:

$ ollama --version
ollama version is 0.x.x

17.3 첫 모델 — pull → run

받기

$ ollama pull qwen3:8b

이름:태그 형식입니다. 태그 는 보통 모델 크기.

자주 쓰는 태그:

qwen3:8b
qwen3:32b
gemma3:27b
llama3.3:70b
deepseek-r1:14b
mistral:7b

바로 실행

$ ollama run qwen3:8b
>>> 한국어로 자기 소개 한 문장 해줘.

대화창에 그대로 글자가 흐릅니다.

종료: /bye 또는 Ctrl + D.

17.4 모델 목록·삭제·정보

ollama list 예:

NAME              SIZE     MODIFIED
qwen3:8b          4.7GB    1일 전
qwen3:32b         20.4GB   3시간 전
gemma3:27b        15.6GB   2일 전

17.5 응답 속도 측정 — --verbose

7장에서 본 그 값들을 직접 볼 수 있는 옵션.

$ ollama run qwen3:32b --verbose
>>> 한국어로 자기 소개 한 문장 해줘.

저는 Qwen3 모델입니다...

total duration:       3.2s
load duration:        53ms
prompt eval count:    18 tokens
prompt eval rate:     245 tokens/s
eval count:           42 tokens
eval rate:            17.5 tokens/s

17.6 API — localhost:11434

Ollama가 켜져 있으면 자동으로 다음 주소가 열려 있습니다.

http://localhost:11434

가장 기본 호출:

$ curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "한국어로 자기 소개 한 문장 해줘.",
  "stream": false
}'

응답:

{
  "model": "qwen3:8b",
  "response": "저는 Qwen3 모델입니다...",
  "done": true,
  ...
}

"stream": true 로 하면 토큰이 흐르듯 한 줄씩 옵니다.

17.7 OpenAI 호환 엔드포인트

이게 Ollama의 킬러 기능입니다.

POST http://localhost:11434/v1/chat/completions

OpenAI 형식 그대로 받습니다.

$ curl http://localhost:11434/v1/chat/completions -d '{
  "model": "qwen3:8b",
  "messages": [
    {"role": "system", "content": "너는 친절한 어시스턴트야."},
    {"role": "user", "content": "안녕"}
  ]
}'

OpenAI SDK 코드의 base_url 만 바꾸면 그대로 로컬 모델로 동작합니다.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # 아무 값
)

resp = client.chat.completions.create(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "hi"}],
)
print(resp.choices[0].message.content)

이 한 가지가 Continue.dev, Open WebUI, n8n, LangChain 등 거의 모든 도구를 로컬 AI로 돌릴 수 있게 해줍니다.

25장에서 본격 다룹니다.

17.8 컨텍스트 길이 늘리기

Ollama는 모델 메모리에 따라 자동으로 컨텍스트를 다르게 잡습니다.

기본값을 바꾸려면:

$ OLLAMA_CONTEXT_LENGTH=32768 ollama serve

또는 모델 단위로 Modelfile 작성 (다음 절).

17.9 Modelfile — 모델 커스터마이즈

Ollama는 모델을 살짝 변형해 별도 이름으로 저장할 수 있습니다.

Modelfile 한 줄 예:

FROM qwen3:32b
PARAMETER num_ctx 32768
PARAMETER temperature 0.4
SYSTEM "너는 우리 회사의 한국어 챗봇이야. 정중하게 답해."

빌드:

$ ollama create my-qwen -f Modelfile

실행:

$ ollama run my-qwen

용도:

• 사내 시스템 프롬프트 고정
• 응답 길이·창의성 미리 설정
• 회의록 요약 전용 / 코드 리뷰 전용 등 변형

17.10 모델 저장 위치 관리

기본 위치:

~/.ollama/models/

용량 확인:

$ du -sh ~/.ollama/models/
84G   /Users/kjj/.ollama/models/

다른 디스크로 옮기고 싶으면:

$ export OLLAMA_MODELS=/Volumes/External/ollama-models

~/.zshrc 에 추가하면 영구 적용.

17.11 외장 모델 — GGUF 직접 임포트

Hugging Face에서 받은 GGUF 파일을 Ollama로 등록할 수도 있습니다.

# Modelfile.import
FROM ./Qwen3-32B-Instruct-Q4_K_M.gguf

$ ollama create custom-qwen -f Modelfile.import
$ ollama run custom-qwen

17.12 자주 쓰는 Ollama 운영 명령 모음

$ ollama list                       # 받은 모델
$ ollama ps                         # 떠있는 모델
$ ollama run qwen3:8b               # 실행
$ ollama run qwen3:32b --verbose    # 속도 보면서 실행
$ ollama pull gemma3:27b            # 받기
$ ollama rm gemma3:27b              # 삭제
$ ollama stop qwen3:32b             # 메모리에서 내림
$ ollama serve                      # 데몬 직접 실행 (수동)

17.13 Ollama vs LM Studio — 언제 무엇을?

두 도구는 같이 깔아둘 수 있습니다. LM Studio로 모델 탐색하고, Ollama로 자동화에 붙이는 것이 흔한 조합.

이 장에서 기억할 한 가지

Ollama = 터미널 + API 표준.

ollama run <모델>           # 채팅
http://localhost:11434/v1/...   # OpenAI 호환 API

이걸 알면 자동화·Agent·IDE 통합의 문이 열립니다.

손으로 해볼 것

1. 첫 모델 실행 & 속도 측정

$ ollama run qwen3:8b --verbose
>>> 한국어로 자기 소개 한 문장 해줘.

eval rate 값을 16장 LM Studio에서 받은 값과 비교해보세요.

2. API 호출

$ curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [{"role": "user", "content": "안녕"}]
  }'

JSON으로 답이 오면 성공.

3. Modelfile로 사내 챗봇 가짜 만들기

FROM qwen3:8b
SYSTEM "너는 우리 회사의 친절한 사내 비서야.
한국어로만 답하고, 회사 이름은 '비트북'이야."
PARAMETER temperature 0.5

my-bitbook 같은 이름으로 빌드하고 실행해보세요.

다음 장에서는 llama.cpp — Ollama·LM Studio가 내부적으로 쓰는 더 깊은 층의 엔진을 다룹니다.

깊이 가고 싶을 때만 봐도 됩니다.

18장. llama.cpp — 더 깊이 가고 싶을 때

이 장의 목표 Ollama·LM Studio가 그 아래에서 무엇을 쓰는지 알게 됩니다.

그리고 사내 서버에 단독 추론 엔진을 띄울 때, 또는 새 모델이 GGUF로 막 풀렸을 때 직접 다룰 수 있게 됩니다.

일반 사용자라면 이 장은 참고용으로 봐도 됩니다.

18.1 llama.cpp가 뭔가?

C++로 짠 로컬 LLM 추론 엔진.

• GGUF 포맷의 표준 구현체
• macOS·리눅스·윈도우·iOS·안드로이드까지 지원
• Ollama, LM Studio가 내부적으로 llama.cpp 기반
• 가장 빠른 업데이트 (새 모델 지원 1~2일 안에)

로컬 LLM 생태계의 심장.

18.2 왜 직접 쓰나?

이미 Ollama가 있는데도 llama.cpp를 직접 만지는 이유:

• Ollama·LM Studio가 아직 지원 안 하는 신규 모델 빠르게 시험
• 세부 옵션 (KV cache 정밀도, GPU 레이어 수 등) 직접 조정
• 벤치마크·실험
• 리눅스 서버에 단독 띄우기
• 임베디드·iOS 빌드
• 학습 목적

일반 사용자라면 Ollama로 충분합니다.

18.3 macOS 설치

가장 빠른 방법:

$ brew install llama.cpp

확인:

$ llama-cli --version

또는 직접 빌드 (최신 기능 필요 시):

$ git clone https://github.com/ggml-org/llama.cpp
$ cd llama.cpp
$ make

Apple Silicon은 Metal 가속이 자동으로 활성화됩니다.

18.4 첫 실행

GGUF 파일 하나가 필요합니다 (10장).

Hugging Face에서 받기:

$ huggingface-cli download \
    bartowski/Qwen3-8B-Instruct-GGUF \
    Qwen3-8B-Instruct-Q4_K_M.gguf \
    --local-dir ./models

채팅 모드 실행:

$ llama-cli \
    -m ./models/Qwen3-8B-Instruct-Q4_K_M.gguf \
    -p "한국어로 자기 소개 한 문장 해줘." \
    -n 200

18.5 자주 쓰는 옵션

$ llama-cli \
    -m ./models/Qwen3-8B-Instruct-Q4_K_M.gguf \
    -p "한국어로 인사해줘." \
    -n 200 \
    -c 8192 \
    -t 8 \
    -ngl 99 \
    --temp 0.4 \
    --top-p 0.9

18.6 채팅 모드 — -cnv

ChatGPT처럼 대화 인터페이스:

$ llama-cli \
    -m ./models/Qwen3-8B-Instruct-Q4_K_M.gguf \
    -cnv

-cnv (conversation) 옵션이 핵심.

종료: Ctrl + C.

18.7 서버 모드 — llama-server

API 서버로도 띄울 수 있습니다.

$ llama-server \
    -m ./models/Qwen3-32B-Instruct-Q4_K_M.gguf \
    -c 16384 \
    -ngl 99 \
    --host 0.0.0.0 \
    --port 8080

이러면 http://localhost:8080 에 API가 열립니다.

OpenAI 호환 엔드포인트도 제공:

$ curl http://localhost:8080/v1/chat/completions -d '{
  "model": "any",
  "messages": [{"role": "user", "content": "안녕"}]
}'

18.8 성능 측정 — llama-bench

$ llama-bench \
    -m ./models/Qwen3-32B-Instruct-Q4_K_M.gguf \
    -p 512 \
    -n 128

이 명령은 prefill·decode 속도를 자동으로 측정합니다.

| model         | size | pp 512  | tg 128 |
|---------------|------|---------|--------|
| qwen3 32B Q4_K_M | 18GB | 250 tok/s | 19 tok/s |

pp = prompt processing (prefill) tg = text generation (decode)

내 맥의 진짜 성능을 잴 때 표준 도구.

18.9 KV Cache 정밀도 조정

긴 컨텍스트에서 메모리를 아끼고 싶을 때:

$ llama-cli ... --cache-type-k q8_0 --cache-type-v q8_0

KV Cache를 8비트로 저장 → 메모리 절반. 품질은 거의 차이 없음.

64K 이상 컨텍스트에서는 권장.

18.10 임베딩도 가능

llama.cpp는 임베딩 모델도 돕니다.

$ llama-embedding \
    -m ./models/bge-m3-Q8_0.gguf \
    -p "오늘 회의 어땠어?"

결과로 숫자 벡터가 출력됩니다. 26장(RAG)에서 다시 봅니다.

18.11 양자화 직접 해보기

원본 모델을 받아 직접 양자화할 수 있습니다.

# 1. Safetensors → F16 GGUF
$ python3 convert_hf_to_gguf.py \
    /path/to/Qwen3-8B-Instruct \
    --outfile qwen3-8b-f16.gguf \
    --outtype f16

# 2. F16 → Q4_K_M
$ llama-quantize qwen3-8b-f16.gguf qwen3-8b-Q4_K_M.gguf Q4_K_M

자세한 건 33장.

18.12 Apple Silicon에서의 llama.cpp

• Metal 가속이 기본
• -ngl 99 로 모든 레이어 GPU로
• M4 Max 이상에서 큰 차이 체감
• M5에서는 추가 개선 빠르게 반영됨

18.13 Ollama와 비교

결론: 일반 작업은 Ollama, 깊은 실험은 llama.cpp.

이 장에서 기억할 한 가지

llama.cpp는 로컬 LLM 생태계의 엔진.

Ollama·LM Studio가 그 위에 얹힌 GUI/CLI 래퍼.

직접 쓰면 속도·옵션·신규 모델에서 가장 빠른 길이 됩니다.

손으로 해볼 것

1. llama-bench 로 내 맥 벤치 찍기

이미 받아둔 GGUF 모델로:

$ llama-bench -m ./models/Qwen3-8B-Instruct-Q4_K_M.gguf

7장에서 계산한 어림값과 비교해보세요.

2. llama-server 띄워 OpenAI 호환 호출

$ llama-server -m ./models/Qwen3-8B-Instruct-Q4_K_M.gguf -c 8192

다른 터미널 창에서:

$ curl http://localhost:8080/v1/chat/completions \
  -d '{
    "model": "any",
    "messages": [{"role":"user","content":"안녕"}]
  }'

다음 장에서는 MLX / mlx-lm — Apple Silicon에 특화된 프레임워크로 같은 모델을 더 빠르게 돌려봅니다.

GGUF vs MLX 속도 차이를 직접 체감하게 됩니다.

19장. MLX / mlx-lm — Apple Silicon 가속

이 장의 목표 맥에서만 누릴 수 있는 빠른 추론 프레임워크 MLX를 직접 만져봅니다.

같은 모델이 GGUF 대비 얼마나 더 빨라지는지 체감하게 됩니다.

19.1 MLX가 뭔가?

Apple이 직접 만든 머신러닝 프레임워크.

• Apple Silicon에 최적화된 연산
• NumPy 비슷한 Python API
• macOS·iPadOS·iOS 모두에서 동일 코드
• 통합 메모리 활용 효율적
• Apple ML Research 팀이 직접 개발

LLM 추론용 패키지:

mlx-lm

이게 우리가 쓸 도구입니다.

19.2 왜 MLX인가?

같은 양자화여도 GGUF보다 빠를 수 있음.

(대략. 모델·셋업에 따라 변동)

이유: Metal·ANE·통합 메모리에 더 직접적으로 매핑되기 때문.

19.3 설치

$ mkdir -p ~/Developer/local-ai-mlx
$ cd ~/Developer/local-ai-mlx

$ python3 -m venv .venv
$ source .venv/bin/activate

(.venv) $ pip install -U mlx-lm

15.8 절의 가상환경 방법을 그대로 따릅니다.

19.4 첫 실행

(.venv) $ mlx_lm.generate \
    --model mlx-community/Qwen3-8B-Instruct-4bit \
    --prompt "한국어로 자기 소개 한 문장 해줘." \
    --max-tokens 200

모델이 처음이라면 자동으로 다운로드됩니다.

결과 끝에 성능 통계가 찍힙니다.

Prompt: 18 tokens, 320 tokens-per-sec
Generation: 124 tokens, 78 tokens-per-sec

Generation 의 tok/s 가 우리가 보는 decode 속도.

19.5 채팅 모드

(.venv) $ mlx_lm.chat \
    --model mlx-community/Qwen3-8B-Instruct-4bit

exit 또는 Ctrl+C 로 종료.

19.6 OpenAI 호환 서버

(.venv) $ mlx_lm.server \
    --model mlx-community/Qwen3-32B-Instruct-4bit \
    --port 8080

이러면 http://localhost:8080 에 OpenAI 호환 API.

$ curl http://localhost:8080/v1/chat/completions \
  -d '{
    "model": "qwen",
    "messages": [{"role":"user","content":"안녕"}]
  }'

Ollama·LM Studio와 같은 형식이므로 클라이언트 코드를 그대로 쓸 수 있습니다.

19.7 mlx-community — MLX 모델 저장소

Hugging Face의 mlx-community 가 MLX 변환본 모음입니다.

검색 팁:

• 원하는 모델 이름 뒤에 -4bit, -8bit 붙여서 검색
• 또는 Hugging Face에서 mlx 필터

자주 받는 모델:

mlx-community/Qwen3-8B-Instruct-4bit
mlx-community/Qwen3-14B-Instruct-4bit
mlx-community/Qwen3-32B-Instruct-4bit
mlx-community/Llama-3.3-70B-Instruct-4bit
mlx-community/gemma-3-27b-it-4bit

19.8 직접 변환·양자화

MLX 모델이 없으면 직접 변환할 수도 있습니다.

(.venv) $ mlx_lm.convert \
    --hf-path Qwen/Qwen3-32B-Instruct \
    --mlx-path ./models/Qwen3-32B-Instruct-4bit \
    -q

8bit로 하고 싶으면 -q --q-bits 8.

자세한 건 33장.

19.9 LM Studio에서 MLX 쓰기

코드 안 만지고도 MLX를 쓰는 가장 쉬운 길:

LM Studio.

검색 시 MLX 태그 필터를 켜면 됩니다.

LM Studio Discover →
검색창 옆 필터 →
"MLX" 활성화

받아서 채팅 탭에서 로드하면 끝. GGUF랑 똑같이 씁니다.

19.10 Ollama에서 MLX 쓰기

2025년부터 Preview로 지원합니다.

$ OLLAMA_MLX=1 ollama serve

이렇게 띄우면 Ollama가 가능한 모델은 MLX로 돌립니다. 2026년 시점에서는 정식 지원에 가까워졌습니다.

19.11 MLX vs GGUF — 어느 쪽을 쓰나

이 책의 권장: 처음 한 달은 GGUF로 익히고, 같은 모델을 MLX로 받아 속도 비교를 한 번씩 해보세요.

19.12 자주 만나는 MLX 문제

“tokenizer 오류” 나요

mlx-lm 버전을 최신으로:

$ pip install -U mlx-lm

Chat template이 적용 안 돼요

22장의 chat template 개념이 잘못 들어간 경우. 모델 카드에서 권장 template 확인.

메모리가 갑자기 커져요

MLX는 컨텍스트 키울 때 메모리 폭이 큽니다. 8K → 16K로 시작하세요.

이 장에서 기억할 한 가지

MLX = 맥에서만 누리는 속도.

같은 4bit 모델이 GGUF보다 빠른 경우가 많습니다. 도구는 mlx-lm (CLI/API) 또는 LM Studio (GUI).

손으로 해볼 것

1. GGUF vs MLX 속도 비교

같은 모델의 두 버전을 받고 같은 질문을 던져 속도를 측정하세요.

# GGUF (Ollama 또는 llama-cli)
$ ollama run qwen3:8b --verbose

# MLX
$ mlx_lm.generate --model mlx-community/Qwen3-8B-Instruct-4bit \
    --prompt "한국어로 자기 소개 한 문장 해줘."

표를 만들어보세요.

2. mlx_lm.server 띄워보기

$ mlx_lm.server --model mlx-community/Qwen3-8B-Instruct-4bit --port 8080

다른 터미널에서:

$ curl http://localhost:8080/v1/chat/completions \
  -d '{
    "model": "any",
    "messages":[{"role":"user","content":"안녕"}]
  }'

다음 장에서는 지금까지 본 도구들을 정리합니다.

언제 어떤 도구를 쓰는지 한 번에 정리되는 비교표·결정 트리.

20장. 백엔드 비교와 선택 가이드

이 장의 목표 16~19장에서 배운 도구들을 한 표로 정리 합니다.

“내 상황엔 뭐가 맞지?” 질문에 30초 안에 답을 낼 수 있게 됩니다.

20.1 도구들이 같은 층이 아니다

가장 흔한 오해.

“Ollama vs llama.cpp vs LM Studio 뭐가 빠르지?”

이 질문 자체가 약간 어긋납니다.

[프레임워크 층]
  - llama.cpp (GGUF 추론 엔진)
  - MLX (Apple Silicon용 ML 엔진)

[런타임·매니저 층]
  - Ollama        ← llama.cpp 기반
  - mlx-lm        ← MLX 기반

[GUI/IDE 층]
  - LM Studio     ← GGUF + MLX 둘 다 사용
  - Open WebUI    ← Ollama 등에 연결
  - Continue.dev  ← IDE 통합 (37장)

같은 층끼리만 비교가 의미 있습니다.

20.2 한 표로 보는 비교

20.3 속도 비교 (맥 통합 메모리 기준)

같은 32B Q4 모델 기준 대략적인 비교.

MLX 계열이 약 20~30% 빠른 경향. 단, 갓 나온 모델은 GGUF 지원이 먼저인 경우가 많음.

20.4 결정 트리 — 처음 받을 때

지금 처음 시작하나?
├─ 예 → LM Studio + GGUF
└─ 아니오 ↓

자동화·사내 API 필요한가?
├─ 예 → Ollama
└─ 아니오 ↓

최대 속도 원하나?
├─ 예 → MLX (mlx-lm 또는 LM Studio MLX)
└─ 아니오 ↓

신규 모델 즉시 테스트?
├─ 예 → llama.cpp 직접
└─ 아니오 → Ollama (기본 추천)

20.5 상황별 추천 조합

입문자 (1~2주차)

LM Studio + GGUF Q4_K_M

• 마우스로 모든 것
• 8B → 14B → 32B 비교
• 첫 채팅·첫 코드 질문

일상 사용자 (2~4주차)

LM Studio (GUI 비교용) + Ollama (자동화·API)

• 두 도구 같이 깔아둠
• 새 모델은 LM Studio로 검색·테스트
• 자주 쓰는 건 Ollama API로 연결

개발자·코딩 어시스턴트 (37장)

Ollama + Continue.dev (VS Code 통합)

• 백그라운드 데몬으로 항상 떠있음
• IDE에서 단축키 한 번에 호출

사내 챗봇·RAG 서버 (38장)

Ollama (서버) + Open WebUI (사내 웹앱)

• 사내망에 두기 좋음
• 다중 사용자 지원

속도 마니아 (M Max/Ultra)

mlx-lm + 직접 변환

• 19장 방법으로 직접 4bit 변환
• 같은 모델 GGUF vs MLX 차이 확인

연구자·파인튜닝 준비

mlx-lm (학습) + llama.cpp (양자화) + Hugging Face Hub

• 32, 33장에서 본격 다룸

20.6 메모리 활용 비교

같은 모델·같은 컨텍스트에서 도구별 메모리 사용량 (대략).

큰 차이는 없지만, LM Studio가 GUI 메모리 때문에 살짝 큼.

20.7 API 호환성

거의 모든 도구가 OpenAI 호환 엔드포인트를 제공합니다.

같은 OpenAI SDK 코드로 어디든 붙일 수 있습니다 (25장).

20.8 모델 보관 위치 비교

주의: 같은 모델을 여러 도구에서 받으면 중복 저장. 디스크가 빠르게 차오릅니다.

대처:

• 모델 한 개를 받은 뒤 ollama create -f Modelfile 로 다른 도구에 등록
• 외장 SSD 활용 (OLLAMA_MODELS=/Volumes/External/...)

20.9 업데이트 빈도 비교

따라서:

• 새 모델이 떴는데 Ollama·LM Studio에 없으면
• llama.cpp로 직접 GGUF를 받아 돌리거나
• LM Studio가 별도 GGUF 임포트 기능 제공
• 또는 ollama create -f Modelfile 로 추가 (17.11)

20.10 이 책에서의 표준 조합

이후 장들에서 별다른 언급이 없으면 다음 조합을 가정합니다.

- 학습·비교:  LM Studio + GGUF
- 자동화·API: Ollama (OpenAI 호환 모드)
- 속도 실험:  mlx-lm 또는 LM Studio MLX

3부의 16, 17, 19장이 이 세 도구를 다룬 이유입니다.

이 장에서 기억할 한 가지

도구는 층이 다르다.

층	도구
엔진	llama.cpp / MLX
매니저	Ollama / mlx-lm
GUI	LM Studio

처음에는 LM Studio + Ollama 두 개면 충분합니다.

손으로 해볼 것

1. 내 상황에 맞는 조합 결정

다음 빈칸을 채워보세요.

내 주된 용도:        _______________
주로 쓸 GUI:         LM Studio / Open WebUI / 없음
주로 쓸 API:         Ollama / LM Studio / llama-server / mlx-lm.server
속도 우선?:          예 / 아니오
포맷:                GGUF / MLX

2. 두 도구를 동시에 띄워보기

# 터미널 1
$ ollama serve   # (이미 떠 있다면 생략)

# 터미널 2
$ lmstudio       # GUI 실행

같은 모델을 양쪽에서 띄워두면 이중 메모리 가 든다는 걸 활성 상태 보기로 확인.

여기까지가 3부의 끝 입니다.

여기까지 마치면 로컬에서 모델이 실제로 돕니다.

다음 부(4부)에서는 같은 모델에서 더 좋은 답을 뽑는 법 — 프롬프트와 옵션 — 을 다룹니다.

21장. 프롬프트 엔지니어링 기초

이 장의 목표 같은 모델에서 2배 좋은 답 을 뽑아내는 입력 작성 기술을 익힙니다.

마법이 아니라 요령 입니다.

21.1 왜 프롬프트가 중요한가

모델 입장에서 보면 우리는 매번 “빈 종이“를 던지는 것과 같습니다.

"코드 짜줘"
→ 모델: 어떤 언어? 어떤 스타일? 누구한테 보여줄?

좋은 프롬프트는 이 빈 공간을 채워주는 일입니다.

같은 모델로 같은 작업을 시켜도 프롬프트만 바꿔서 결과 품질이 2~3배 차이 납니다.

21.2 프롬프트의 4가지 요소

좋은 프롬프트는 보통 다음 4가지가 있습니다.

1. 역할(Role)     - "너는 누구야"
2. 작업(Task)     - "무엇을 해줘"
3. 맥락(Context)  - "이런 상황이야"
4. 형식(Format)   - "이렇게 답해줘"

비교 예.

❌ 나쁜 예:

이거 정리해줘.

✅ 좋은 예:

[역할] 너는 회사 임원에게 전달할 보고서를 만드는 비서야.
[작업] 아래 회의록을 임원용 5줄 요약으로 정리해.
[맥락] 회의 참석자는 개발팀 5명, 주제는 다음 분기 로드맵이었어.
[형식] 다음 형식으로:
  - 결정 사항 (불릿)
  - 다음 액션 (불릿)
  - 리스크 (불릿)

[원문]
...

21.3 효과 큰 패턴 10가지

① 역할 부여

너는 시니어 백엔드 엔지니어야.
PHP 코드 리뷰를 부탁할게.

모델이 답변 톤·깊이를 자동으로 맞춥니다.

② 단계별 사고 요청 (Chain of Thought)

답을 내기 전에 단계별로 분석해줘.
그 다음 최종 답을 적어줘.

특히 수학·디버깅에서 정답률이 올라갑니다. Reasoning 모델(9장)에는 이미 적용된 패턴.

③ 예시 제공 (Few-shot)

다음 예시처럼 변환해줘.

입력: "오늘 회의 끝나고 점심 같이 먹자"
출력: {"intent": "request_meal", "time": "after_meeting"}

입력: "내일 3시까지 보고서 보내주세요"
출력: {"intent": "request_document", "deadline": "tomorrow_15:00"}

입력: "{사용자 입력}"
출력:

JSON·태그·분류 같은 정형 출력에 강력.

④ 명시적 부정 (Negative)

다음을 답변에 포함하지 마:
- 인사말
- "물론입니다" 같은 서두
- 답변 끝의 추가 설명

답이 깔끔해집니다.

⑤ 형식 지정

다음 JSON 형식으로만 답해. 다른 설명 없음.

{
  "summary": "...",
  "actions": ["...", "..."],
  "risks": ["...", "..."]
}

자동화 파이프라인에 핵심.

⑥ 길이 제한

3문장 이내로 답해.

또는

200자 이내, 마크다운 없이.

로컬 AI에서는 속도와도 직결됩니다.

⑦ 모를 때 모른다고

확실하지 않으면 "모르겠다"라고 답해.
추측은 표시해줘.

환각(34장) 줄이는 가장 쉬운 방법.

⑧ 한국어 강제

모든 답변은 한국어로만.
영어 단어는 필요할 때만 괄호로.

다국어 모델이 자꾸 영어로 답할 때.

⑨ 사용자 페르소나

나는 PHP 8년차 개발자야.
초보자 설명 빼고 핵심만.

수준 맞춤.

⑩ 자기 검토 요청

답을 적은 뒤에,
스스로 검토해서 빈틈을 한 줄로 적어줘.

품질이 한 단계 올라갑니다.

21.4 안 좋은 패턴 5가지

① 모호한 명령

❌ “잘 정리해줘” → “잘“이 뭔지 모름.

② 다중 작업 한 번에

❌ “이거 요약하고, 키워드 뽑고, 영어로 번역하고, JSON으로” → 결과가 무너집니다. 한 번에 하나 가 원칙.

③ 모순된 지시

❌ “짧게 자세히 설명해줘” → 두 지시가 충돌.

④ 부정만 잔뜩

❌ “이거 하지 마, 저거 하지 마, 그것도 하지 마…” → 모델이 뭘 해야 할지 모름. 원하는 것도 함께 적기.

⑤ 너무 친절한 인사

❌ “안녕하세요 모델님. 부탁드려도 될까요? 가능하시다면…” → 응답이 늘어지고 토큰 낭비. 직접·간결 이 더 좋은 답을 부릅니다.

21.5 한국어 프롬프트 특수 팁

존댓말 vs 반말

모델은 입력 톤을 그대로 반영하는 경향.

• 반말로 물으면 → 답도 캐주얼
• 존댓말로 물으면 → 답도 격식

회사용이라면 시스템 프롬프트에:

모든 답변은 정중한 존댓말로.

영어 단어 섞임 방지

작은 한국어 모델은 가끔 영어 단어로 튕깁니다.

모든 답은 한국어로만 작성해.
영어 단어는 한국어 음차로 적어줘.
예: "API" → "API(에이피아이)"

한국어가 약한 모델은 영어 프롬프트로

체감 품질이 더 좋을 때가 있습니다.

You: Write a Korean summary of:
     [한국어 원문]

21.6 코드 작업 프롬프트 템플릿

가장 자주 쓸 두 가지.

리팩터링

[역할] 너는 시니어 PHP 엔지니어야.
[작업] 아래 코드를 SOLID 원칙에 맞게 리팩터링해.
[제약]
  - 동작은 절대 바뀌면 안 됨
  - 변수명은 한 번에 의미가 보이게
  - 100자 이내 함수로
[형식]
  - 변경 전후 diff 형식으로
  - 끝에 "변경 이유 1줄씩" 정리

[코드]
...

디버깅

[작업] 아래 에러의 원인 후보 3개를 우선순위로 말해줘.
[정보]
  - 환경: macOS 15, PHP 8.3
  - 재현: 로그인 직후 100% 발생
  - 로그:
    ...
[형식]
  1. 가장 가능성 높은 원인
  2. 검증 방법
  3. 대안 시나리오

21.7 회사 업무 프롬프트 템플릿

회의록 요약

다음 회의록을 임원 보고용으로 정리해.

[형식]
- 결정 사항 (불릿)
- 액션 아이템 (담당자/기한 포함)
- 보류 사항 (불릿)
- 다음 회의 안건 (불릿)

가능하면 5줄 이내. 추측 금지. 명시되지 않은 건 "미정".

[원문]
...

메일 초안

다음 상황에 맞는 한국어 메일 초안을 써줘.

상황: 외주사에 추가 비용 요청을 정중하게 거절
관계: 1년 이상 거래
톤: 정중하지만 단호

[형식]
- 제목
- 본문 5문단 이내
- 인사말 / 본문 / 마무리

---

21.8 프롬프트 디버깅 — 답이 이상할 때 점검

답이 의도와 다르면 이 순서로 점검.

1. 모델이 본 입력을 그대로 출력시켜봄

   내가 너에게 준 지시를 그대로 다시 적어줘.
   

   → 모델이 잘못 읽고 있는지 확인.
2. 시스템 프롬프트가 충돌하는지 확인 (22장)
3. Temperature를 0.2까지 내려보기 (23장)
4. 출력 형식을 더 엄격하게 (“JSON만, 다른 텍스트 금지”)
5. 예시 1~3개 추가 (Few-shot)

이 장에서 기억할 한 가지

좋은 프롬프트의 4요소: 역할 / 작업 / 맥락 / 형식

그리고 한 번에 한 작업 만. 부정 지시보다 원하는 것을 적습니다.

손으로 해볼 것

1. 같은 작업 — 나쁜 vs 좋은 프롬프트

LM Studio에서 같은 모델에 다음 두 프롬프트를 차례로 던지고 답을 비교하세요.

A.

이 회의록 정리해줘.
[회의록 원문]

B.

[역할] 너는 임원 보고용 요약 비서야.
[작업] 아래 회의록을 5줄 이내로 정리해.
[형식]
- 결정 사항 (불릿)
- 액션 아이템 (담당자 포함)
[제약] 추측 금지. 명시 안 된 건 "미정".

[회의록 원문]

두 답의 길이·정확도·구조 차이를 메모.

2. 내 업무 프롬프트 3종 만들어두기

자주 쓰는 작업 3가지를 골라 21.6, 21.7 절을 본떠 템플릿을 만들어두세요.

• 회의록 요약 템플릿
• 코드 리뷰 템플릿
• 메일 초안 템플릿

스니펫·메모 앱에 저장해두면 일상이 바뀝니다.

다음 장에서는 시스템 프롬프트와 Chat Template 을 봅니다.

같은 프롬프트인데 도구마다 다르게 들리는 이유, 모델이 갑자기 “AI assistant“라고 자기 소개하는 이유가 거기 있습니다.

22장. 시스템 프롬프트와 Chat Template

이 장의 목표 “분명히 한국어로 답하라고 했는데 영어가 나와요” “Cursor에선 되는데 Ollama에선 답이 이상해요”

이런 일의 90%는 Chat Template 문제입니다. 이걸 이해하고 넘어갑니다.

22.1 시스템 프롬프트 — 모델의 “성격 설정”

채팅에는 보통 세 종류의 역할이 있습니다.

system    — 모델의 성격·규칙
user      — 사용자 메시지
assistant — 모델의 답

시스템 프롬프트는 대화 전체에 영향을 주는 지시입니다.

OpenAI 형식 예:

{
  "messages": [
    {"role": "system", "content": "너는 한국어로만 답하는 시니어 엔지니어야."},
    {"role": "user",   "content": "Python에서 비동기란 뭐야?"}
  ]
}

시스템 프롬프트는:

• 대화가 길어져도 효과 유지
• 사용자 프롬프트보다 우선 적용
• 모델 입장에선 “법“에 가까움

22.2 시스템 프롬프트로 가능한 것

• 언어 강제: “모든 답변은 한국어”
• 톤 설정: “정중한 존댓말로”
• 역할 고정: “너는 비트북 회사의 사내 비서”
• 거절 정책: “회사 보안 이슈가 의심되면 답변 거절”
• 출력 형식: “항상 JSON으로 답해”

22.3 시스템 프롬프트 작성 팁

짧고 명확하게

❌ “너는 매우 친절하고 똑똑하며 정확하고 자세하고…” → 길어질수록 약발이 떨어집니다.

✅ “너는 비트북 회사의 한국어 사내 비서야. 정중한 존댓말로 답해.”

우선순위 명시

여러 규칙이면 번호를 매기세요.

규칙:
1. 모든 답은 한국어 존댓말.
2. 모르는 내용은 "모르겠습니다"로.
3. 회사 기밀 의심되면 답변 거절.

길이도 모델과 균형

간단한 8B 모델 → 시스템 프롬프트 짧게 (200자 이내)
큰 32B+ 모델   → 시스템 프롬프트 길어도 잘 따름

22.4 Chat Template — 모델이 진짜 보는 입력

여기가 중요한 부분입니다.

OpenAI 형식의 메시지는 모델이 직접 보지 않습니다.

각 모델마다 정해진 Chat Template 으로 한 덩어리 텍스트로 변환되어 들어갑니다.

예시. Qwen3의 Chat Template:

<|im_start|>system
너는 한국어로 답하는 비서야.<|im_end|>
<|im_start|>user
안녕<|im_end|>
<|im_start|>assistant

마지막 줄이 비어있는 이유?

모델이 이 위치부터 다음 토큰을 예측 하기 시작하기 때문입니다.

Llama 3의 Chat Template은 또 다릅니다:

<|begin_of_text|><|start_header_id|>system<|end_header_id|>
너는 한국어로 답하는 비서야.<|eot_id|><|start_header_id|>user<|end_header_id|>
안녕<|eot_id|><|start_header_id|>assistant<|end_header_id|>

같은 의미의 대화도 모델마다 완전히 다른 모양의 토큰 시퀀스가 됩니다.

22.5 Chat Template이 잘못 적용되면

증상이 무서울 정도로 다양합니다.

• “AI assistant” 라며 자기 소개부터 시작
• 답을 하다가 다음 사용자 차례를 자기가 채움
• 시스템 프롬프트를 무시
• 답변이 끝나지 않고 무한 반복
• 한국어 / 영어가 섞임

원인은 거의 다 잘못된 chat template.

Qwen 모델에 Llama 템플릿 적용  →  답이 이상해짐
Base 모델에 Chat 템플릿 적용   →  답이 깨짐

22.6 어디서 적용되나?

좋은 소식: 대부분의 도구가 자동으로 처리 해줍니다.

문제가 되는 건 보통:

• llama.cpp 직접 호출
• 옛 GGUF 파일 (tokenizer_config 누락)
• 직접 OpenAI 호환 클라이언트를 짤 때 base 모델에 chat 형식으로 호출

22.7 모델 카드에서 Chat Template 찾기

Hugging Face 모델 페이지의 “Files and versions” → tokenizer_config.json 을 열면 이런 게 보입니다.

{
  "chat_template": "{% if messages[0]['role'] == 'system' %}...",
  ...
}

이 안에 Jinja2 템플릿으로 모양이 정의되어 있습니다.

또는 README의 “Chat Format” 또는 “Usage” 섹션에 명시되어 있습니다.

직접 살 일은 별로 없지만, “내 코드가 이상해질 때” 한 번씩 들여다보세요.

22.8 직접 호출할 때 안전한 방법 (Python)

transformers 라이브러리는 모델별 chat template을 알아서 적용합니다.

from transformers import AutoTokenizer

tok = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B-Instruct")

messages = [
    {"role": "system", "content": "너는 한국어로 답해."},
    {"role": "user",   "content": "안녕"},
]

prompt = tok.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
print(prompt)

이 출력이 위 22.4 절의 그 모양입니다.

add_generation_prompt=True 가 중요: “이제 모델이 말할 차례” 표시를 끝에 붙여줍니다.

22.9 컨텍스트 캐싱

대화가 길어지면 prefill이 매번 느려집니다.

같은 시스템 프롬프트 + 같은 앞부분 대화 → 결과 같음.

그래서 도구들이 이전 KV Cache를 재활용 합니다.

시스템 프롬프트를 자주 바꾸지 않을수록 prefill 비용을 절약할 수 있습니다.

22.10 시스템 프롬프트 실전 모음

사내 비서 (38장과 연결)

당신은 비트북 회사의 사내 비서입니다.

규칙:
1. 모든 답은 한국어 존댓말.
2. 회사 내부 자료에 없는 내용은 "확인 필요"로 표시.
3. 사람·계정 정보는 절대 추측하지 않음.

코딩 어시스턴트 (37장과 연결)

You are a senior software engineer.
Respond in Korean for explanations,
but keep code, file paths, and shell commands in their original form.

Rules:
1. No unnecessary preamble.
2. When unsure, say so. Don't fabricate APIs.
3. Suggest tests when modifying logic.

JSON 출력기

모든 답은 다음 JSON으로만:
{
  "summary": "...",
  "tags": ["...", "..."],
  "confidence": 0.0-1.0
}

다른 텍스트 절대 금지. 코드블록도 금지.

이 장에서 기억할 한 가지

모델은 OpenAI 형식 메시지를 직접 안 본다.

Chat Template으로 모델별 모양의 텍스트로 변환된 뒤에야 본다.

답이 이상하면 가장 먼저 잘못된 template을 의심하세요.

손으로 해볼 것

1. 시스템 프롬프트 효과 체감

LM Studio에서 같은 8B 모델에 두 번 같은 질문.

A. 시스템 프롬프트 비움:

사용자: 안녕

B. 시스템 프롬프트:

너는 비트북 회사의 한국어 사내 비서야.
정중한 존댓말로만 답해.

같은 사용자 메시지로 답을 비교하세요.

2. apply_chat_template 출력 확인 (선택)

가상환경에서:

(.venv) $ pip install transformers

위 22.8 코드를 실행해서 모델이 진짜로 보는 텍스트가 어떻게 생겼는지 직접 확인.

다음 장에서는 Temperature, Top-p, Top-k — “창의성 슬라이더“의 정체를 봅니다.

23장. Temperature, Top-p, Top-k

이 장의 목표 채팅 도구의 슬라이더들이 뭘 하는지 정확히 알게 됩니다.

“코드 작업엔 0.2, 글쓰기엔 0.7” 라는 말의 근거를 머릿속으로 그릴 수 있게 됩니다.

23.1 다음 토큰 예측의 진짜 모습

2장에서 봤습니다.

모델은 다음 토큰의 확률 분포를 만듭니다.

다음 토큰 후보:
  "맑습니다"  → 0.35
  "흐립니다"  → 0.22
  "춥습니다"  → 0.15
  "비가"      → 0.09
  "치킨"      → 0.0001
  ...

그러면 어떤 토큰을 고를까요?

이걸 정하는 게 샘플링(sampling) 입니다.

• 가장 확률 높은 거만 고르기 → 항상 같은 답, 따분함
• 다양하게 고르기 → 창의적이지만 들쭉날쭉

이 균형을 조절하는 손잡이가 Temperature, Top-p, Top-k 입니다.

23.2 Temperature — 창의성 손잡이

확률 분포를 얼마나 평평하게 / 뾰족하게 만들지 정합니다.

[Temperature 0.0]   (가장 뾰족)
"맑습니다" 0.99
"흐립니다" 0.01
나머지     0

[Temperature 1.0]   (원래 분포)
"맑습니다" 0.35
"흐립니다" 0.22
...

[Temperature 1.5]   (평평)
"맑습니다" 0.18
"흐립니다" 0.16
"치킨"     0.05
...

한 줄 감각

23.3 Top-k — 상위 k개만 고려

[Top-k = 5]
상위 확률 5개 후보만 남기고 나머지 무시
그 안에서 (Temperature 적용 후) 샘플

이상한 토큰이 우연히 고름당하는 것을 막아줍니다.

• 너무 작으면(k=1) → 항상 1등만 (Temperature=0과 비슷)
• 너무 크면(k=100) → 효과 거의 없음

보통 기본값(40~50) 그대로 두면 됨.

23.4 Top-p (Nucleus) — 누적 확률 컷오프

[Top-p = 0.9]
확률이 큰 순으로 더해가다가
누적 0.9가 될 때까지의 후보만 남김

예:

"맑습니다" 0.35  → 누적 0.35
"흐립니다" 0.22  → 누적 0.57
"춥습니다" 0.15  → 누적 0.72
"비가"     0.09  → 누적 0.81
"안개"     0.07  → 누적 0.88
"화창함"   0.06  → 누적 0.94  ← 여기까지

이 6개 중에서 (Temperature 적용 후) 샘플.

Top-p 가 Top-k 보다 똑똑한 이유: 확률이 들쭉날쭉한 상황에 자동 적응.

• 1등이 압도적으로 높으면 적은 후보만
• 비슷비슷하면 많은 후보를 다 고려

23.5 Top-p vs Top-k — 동시에 쓰면

대부분의 도구는 둘 다 적용합니다.

1. Top-k 로 N개로 줄임
2. Top-p 로 누적 확률 안의 후보만 남김
3. Temperature 적용해서 분포 조정
4. 그 분포에서 확률대로 하나 뽑음

둘 다 동시에 쓰는 게 표준.

23.6 그 외 자주 보는 손잡이

Repeat Penalty (Frequency Penalty)

같은 단어 반복을 막는 페널티.

0.0  → 페널티 없음 (모델이 같은 단어 반복할 수 있음)
1.1  → 약간 (기본)
1.3  → 강함 (반복 거의 없음)

Q4 양자화처럼 작은 모델에서 “같은 문장 무한 반복“이 나오면 Repeat Penalty 를 1.1 → 1.2 로 올려보세요.

Min-p

Top-p 의 변종. 1등 확률 대비 일정 비율 이상 후보만 남김.

새 모델이 추천하는 경우도 있음.

Seed

같은 시드 → 같은 결과. 재현 가능성이 필요할 때.

23.7 작업별 추천 조합

Reasoning 모델 주의: Temperature 0으로 두면 추론 과정이 짧아지거나 망가질 수 있음. 모델 카드의 권장값을 따르세요.

23.8 도구별 설정 위치

LM Studio

채팅 화면 우측 Inference 패널.

• Temperature
• Top-P
• Top-K
• Repeat Penalty

Ollama

CLI에서 직접 변경:

$ ollama run qwen3:8b
>>> /set parameter temperature 0.3
>>> /set parameter top_p 0.9

Modelfile에 고정:

FROM qwen3:8b
PARAMETER temperature 0.3
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.1

OpenAI 호환 API

JSON 본문에 그대로 넣음:

{
  "model": "qwen3:8b",
  "messages": [...],
  "temperature": 0.3,
  "top_p": 0.9
}

23.9 같은 손잡이가 한국어에 미치는 영향

한국어는 영어보다 토큰 분포가 얇은 꼬리를 가집니다.

즉:

• Temperature를 올리면 영어보다 더 빨리 망가집니다.
• Top-p 를 너무 크게 두면 이상한 한자·영어 토큰 이 끼어듭니다.

권장:

한국어 작업 → Top-p 0.9~0.95, Temperature 0.7 이하

23.10 흔한 증상 대응

이 장에서 기억할 한 가지

Temperature: 창의성 조절. Top-p / Top-k: 후보 범위 제한.

• 코드·정확성 → 낮게 (0.1~0.3)
• 글쓰기 → 보통 (0.5~0.7)
• 창작 → 높게 (0.8+)

한국어는 영어보다 한 단계 낮게 잡으세요.

손으로 해볼 것

1. 같은 질문, Temperature 3종

LM Studio에서 같은 질문을 세 번 보내되, Temperature만 다르게.

질문: "맥북에서 로컬 AI 시작하는 법 알려줘"

• Temperature 0.0
• Temperature 0.5
• Temperature 1.0

답의 표현·길이·창의성 차이를 메모하세요.

2. JSON 출력 안정화

다음 시스템 프롬프트로 강제 JSON:

모든 답은 다음 JSON으로만:
{"summary": "...", "tags": ["...", "..."]}
다른 텍스트 절대 금지.

• Temperature 0.7 → 깨질 확률 높음
• Temperature 0.1 → 안정적

각각 5번씩 던져 형식이 얼마나 안정적인지 확인.

다음 장에서는 Stop 토큰, Max tokens, Streaming 같은 실전 옵션들을 정리합니다.

자동화 파이프라인을 만들 때 꼭 필요합니다.

24장. Stop 토큰, Max tokens, Streaming

이 장의 목표 코드로 모델을 호출할 때 답변을 원하는 곳에서 끊고, 흘리고, 제한하는 옵션들을 정리합니다.

24.1 왜 이걸 알아야 하나

채팅 UI에서는 자동으로 잘 처리되지만, 자동화 파이프라인 에서는 직접 설정해야 합니다.

• 답이 너무 길어서 비용·시간 폭주
• 답이 중간에 잘림
• 답이 끝나야 하는데 계속 이어 씀
• 사용자가 답을 실시간으로 보고 싶어함

이걸 컨트롤하는 게 이 장의 옵션들.

24.2 Max tokens — 출력 길이 한도

모델이 만들 최대 토큰 수.

OpenAI 호환 API:

{
  "model": "qwen3:8b",
  "messages": [...],
  "max_tokens": 500
}

너무 크게 잡으면:

• 답이 끝나도 모델이 계속 만들려고 함 (보통 stop 조건으로 끊김)
• prefill 이후 메모리 여유가 줄어듦

너무 작으면 답이 잘려서 끝납니다.

24.3 Stop 토큰 — 여기서 끊어줘

특정 토큰·문자열이 나오면 즉시 중단.

API:

{
  ...
  "stop": ["</answer>", "###", "사용자:"]
}

활용 예:

• JSON 응답에서 추가 텍스트 막기: "stop": ["```", "\n\n"]
• 다중 턴 대화에서 다음 사용자 차례 막기: "stop": ["User:", "사용자:"]
• 마크다운 헤더 이후 잘라내기: "stop": ["\n# "]

22장의 Chat Template이 잘못되면 모델이 자기 입으로 다음 사용자 차례를 만들기도 합니다. Stop 토큰으로 방어할 수 있습니다.

24.4 EOS / EOT — 모델이 직접 끝내는 토큰

모델 학습 시 정해둔 “여기가 답의 끝” 신호 토큰.

Qwen3        →  <|im_end|>
Llama 3      →  <|eot_id|>
Mistral      →  </s>
Gemma 3      →  <end_of_turn>

도구가 이걸 자동으로 인식해서 답을 끝냅니다.

문제는 잘못된 chat template 으로 호출하면 이 토큰을 모델이 안 만들고 무한 생성합니다.

24.5 Streaming — 한 토큰씩 흘리기

ChatGPT처럼 답이 흐르는 효과.

{
  ...
  "stream": true
}

응답이 Server-Sent Events 형식으로 한 청크씩 옵니다.

data: {"choices":[{"delta":{"content":"안"}}]}
data: {"choices":[{"delta":{"content":"녕"}}]}
data: {"choices":[{"delta":{"content":"하"}}]}
...
data: [DONE]

장점:

• 첫 토큰까지 빨라 사용자 체감 ↑
• 긴 답변도 즉시 보기 시작

단점:

• 클라이언트 코드가 약간 복잡
• 분류·JSON 작업에선 무의미

24.6 OpenAI SDK로 streaming 받기

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)

stream = client.chat.completions.create(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "긴 답변 부탁"}],
    stream=True,
    max_tokens=500,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

이게 가장 일반적인 패턴.

24.7 Timeout — 멈춰버린 모델 막기

긴 컨텍스트나 메모리 부족 시 모델이 무한 대기할 수 있습니다.

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
    timeout=60.0,   # 60초
)

또는 요청별:

resp = client.chat.completions.create(
    ...,
    timeout=30.0,
)

사내 도구라면 반드시 timeout 설정.

24.8 Retry — 실패 시 재시도

OpenAI SDK 기본 재시도가 있지만 가끔 조정 필요.

client = OpenAI(
    ...,
    max_retries=2,
)

재시도 시 주의:

• streaming + 재시도 는 중복 응답 가능
• 재시도 가능한 오류(5xx)만 재시도하게
• Idempotency: 같은 입력 → 같은 결과를 기대할 때만

24.9 Tools / Function calling — 미리보기

모델이 함수를 호출 할 수도 있게 하는 옵션.

{
  "messages": [...],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "도시 날씨 조회",
        "parameters": {...}
      }
    }
  ]
}

응답에는 보통 텍스트 대신 tool_calls 가 옵니다.

{
  "tool_calls": [
    {"name": "get_weather", "arguments": {"city": "Seoul"}}
  ]
}

본격적인 내용은 28장.

24.10 응답 형식 — JSON 모드

OpenAI 호환 도구 일부는 JSON 강제 모드를 제공합니다.

{
  "response_format": {"type": "json_object"}
}

지원 여부는 모델·도구마다 다름.

지원 안 하면 시스템 프롬프트 + Temperature 0.1 로 대체.

24.11 자주 만나는 함정

답이 잘림

max_tokens 가 너무 작음. 또는 출력에 stop sequence가 잘못 잡힘.

답이 안 끝남

• chat template 문제 (22장)
• stop 토큰 누락
• max_tokens 너무 큼

JSON이 가끔 깨짐

• Temperature ↓
• 시스템 프롬프트에 “JSON만” 강조
• Few-shot 예시 1~2개 추가
• 도구가 지원하면 response_format 사용

Streaming이 화면에서 끊겨 보임

• 클라이언트 버퍼링 문제
• flush=True 또는 Server-Sent Events 정상 처리 확인

24.12 실전 — 자동화 호출 한 줄 정리

자동화에서 자주 쓰는 안전한 호출 템플릿.

resp = client.chat.completions.create(
    model="qwen3:8b",
    messages=messages,
    max_tokens=500,
    temperature=0.2,
    top_p=0.9,
    stream=False,        # 단일 응답
    timeout=30.0,
    stop=["사용자:", "User:"],
)
text = resp.choices[0].message.content.strip()

UI 응답이라면 stream=True 로 바꿈.

이 장에서 기억할 한 가지

자동화 호출에서 거의 항상 설정해야 할 것:

• max_tokens (출력 길이 한도)
• temperature (23장)
• timeout (멈춤 방지)

사용자 UI라면 추가로 stream=True.

손으로 해볼 것

1. max_tokens 효과 확인

같은 질문에 max_tokens 만 다르게:

for limit in [30, 200, 1000]:
    resp = client.chat.completions.create(
        model="qwen3:8b",
        messages=[{"role":"user","content":"한국 역사를 길게 설명해줘"}],
        max_tokens=limit,
    )
    print(limit, ":", resp.choices[0].message.content[:80], "...")

2. Streaming 직접 받기

24.6 코드를 그대로 실행해서 ChatGPT처럼 답이 흐르는 걸 보세요.

여기까지가 4부의 끝 입니다.

같은 모델을 가지고 더 좋은 답을 뽑는 기술 4가지를 익혔습니다.

다음 부(5부)에서는 로컬 AI를 내 업무 도구에 직접 연결하기 시작합니다. OpenAI 호환 API부터 RAG, Agent, MCP까지 갑니다.

25장. OpenAI 호환 API로 외부 도구 연결

이 장의 목표 “ChatGPT를 쓰는 도구“라면 그 안에 들어가는 모델을 내 맥의 로컬 모델로 바꾸는 법을 익힙니다.

이 한 가지만 알면 시중 AI 도구의 70%가 로컬화 가능합니다.

25.1 핵심 한 줄

OpenAI API의 base_url 만 바꾸면 로컬 모델로 동작합니다.

OpenAI:

https://api.openai.com/v1

Ollama:

http://localhost:11434/v1

LM Studio:

http://localhost:1234/v1

같은 형식이라 나머지 코드는 그대로.

25.2 왜 이게 가능한가

대부분 도구가 OpenAI SDK를 사용합니다.

이때 도구가 보는 건:

POST {base_url}/chat/completions

그래서 base_url 만 바꾸면 그 자리에 어떤 모델이 있든 통신이 됩니다.

Ollama·LM Studio·llama-server·mlx-lm.server 모두 OpenAI 호환 엔드포인트를 제공합니다 (20장).

25.3 가장 쉬운 예 — curl 한 번

$ curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {"role": "system", "content": "너는 한국어로 답해."},
      {"role": "user",   "content": "안녕"}
    ]
  }'

응답:

{
  "id": "...",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 무엇을 도와드릴까요?"
      }
    }
  ]
}

이게 다입니다.

25.4 Python — OpenAI SDK

가장 흔한 방법.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",   # 아무 문자열이나 OK
)

resp = client.chat.completions.create(
    model="qwen3:8b",
    messages=[
        {"role": "system", "content": "너는 한국어로 답해."},
        {"role": "user",   "content": "안녕"},
    ],
)

print(resp.choices[0].message.content)

OpenAI 코드 예제를 인터넷에서 찾았다면 api_key 와 base_url 두 줄만 바꿔주면 됩니다.

25.5 Node.js — openai 패키지

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:11434/v1",
  apiKey: "ollama",
});

const resp = await client.chat.completions.create({
  model: "qwen3:8b",
  messages: [
    { role: "user", content: "안녕" },
  ],
});

console.log(resp.choices[0].message.content);

25.6 어떤 도구들이 base_url 변경을 지원하나?

생각보다 많습니다.

IDE / 개발 도구

• Continue.dev (VS Code, JetBrains)
• Cursor (일부 모드)
• Cline (VS Code 자율 코딩)
• Aider (터미널 페어 프로그래밍)
• Zed AI

채팅 UI

• Open WebUI — ChatGPT 같은 웹 UI
• LibreChat
• AnythingLLM

자동화·워크플로

• n8n
• Make / Zapier 일부 노드
• LangChain / LangGraph
• LlamaIndex

Agent 프레임워크

• Auto-GPT 계열
• CrewAI
• LangGraph

이 모든 도구가 base_url 한 줄로 로컬 모델을 받아들입니다.

25.7 Continue.dev (VS Code 통합) 예

~/.continue/config.json 또는 GUI 설정:

{
  "models": [
    {
      "title": "Qwen3 32B (Local)",
      "provider": "openai",
      "model": "qwen3:32b",
      "apiBase": "http://localhost:11434/v1",
      "apiKey": "ollama"
    }
  ]
}

이러면 VS Code 안에서 ChatGPT 자리에 내 로컬 모델이 들어옵니다.

자세한 셋업은 37장.

25.8 Open WebUI — 사내 ChatGPT 만들기

ChatGPT 같은 웹 인터페이스를 사내 서버에 띄울 수 있습니다.

$ docker run -d -p 3000:8080 \
    -e OPENAI_API_BASE_URL=http://host.docker.internal:11434/v1 \
    -e OPENAI_API_KEY=ollama \
    -v open-webui:/app/backend/data \
    --name open-webui \
    ghcr.io/open-webui/open-webui:main

브라우저로 http://localhost:3000 접속하면 ChatGPT 같은 화면으로 로컬 모델과 대화 가능.

사내망에 띄우면 팀원 모두가 쓸 수 있습니다.

자세한 셋업은 38장.

25.9 표준이 아닌 부분 — 도구마다 다를 수 있음

OpenAI 호환 이지만, 100%는 아닙니다.

차이가 자주 나는 부분:

기본 채팅은 어디서나 됩니다. 고급 기능은 도구별 문서를 한 번씩 확인.

25.10 환경변수로 분리

코드에 base_url을 박지 말고 환경변수로:

# ~/.zshrc
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_API_KEY="ollama"

from openai import OpenAI
client = OpenAI()  # 환경변수 자동 사용

이러면 로컬 / 클라우드 전환이 환경변수 한 줄로 끝.

25.11 보안 — 사내 사용 시

기본 Ollama·LM Studio API는 localhost 만 듣습니다.

다른 컴퓨터에서 접근하려면 추가 설정:

# Ollama가 모든 인터페이스에서 듣게
$ OLLAMA_HOST=0.0.0.0:11434 ollama serve

⚠ 주의:

• 사내망에 노출하면 누구나 API 호출 가능
• 별도 인증 게이트(예: Nginx + Basic Auth)를 앞에 두기
• 또는 사내망 VPN 안에서만 접근 가능하게

38장에서 자세히.

25.12 한 도구에서 여러 모델 라우팅

같은 base_url 안에서 모델 이름만 바꿔서 호출하면 됩니다.

resp = client.chat.completions.create(model="qwen3:8b",  ...)
resp = client.chat.completions.create(model="qwen3:32b", ...)
resp = client.chat.completions.create(model="gemma3:27b", ...)

Ollama 같은 매니저는 자동으로 모델 로드/언로드 합니다. 단, 메모리에 한 번에 하나만 올라옴 (기본 설정).

25.13 실전 — 회사 도구를 로컬화하는 순서

가장 흔한 도입 순서.

① 일단 OpenAI 형식 API를 쓰는 도구인지 확인
   - 설정에 "OpenAI API Key" 항목이 있으면 거의 OK

② 그 도구가 base_url 변경을 지원하는지 확인
   - 보통 "Base URL", "API Endpoint" 같은 항목

③ Ollama 또는 LM Studio API 서버 켜기

④ base_url, api_key, model 세 가지만 바꿔서 저장

⑤ 작은 모델(8B)로 먼저 동작 확인

⑥ 잘 되면 큰 모델로 교체

이 장에서 기억할 한 가지

base_url 한 줄만 바꾸면 됩니다.

https://api.openai.com/v1
          ↓
http://localhost:11434/v1

나머지 코드·도구는 그대로.

손으로 해볼 것

1. Python 한 번 호출

가상환경에서:

(.venv) $ pip install openai

25.4 절 코드를 그대로 실행하세요. 답이 출력되면 성공.

2. 환경변수 설정

$ export OPENAI_BASE_URL="http://localhost:11434/v1"
$ export OPENAI_API_KEY="ollama"
$ python3 -c "from openai import OpenAI; print(OpenAI().chat.completions.create(model='qwen3:8b', messages=[{'role':'user','content':'안녕'}]).choices[0].message.content)"

이 한 줄이 동작하면 자동화 준비 완료.

다음 장에서는 RAG (Retrieval Augmented Generation) — 내 문서를 모델이 참고하게 하는 가장 흔한 실무 패턴을 봅니다.

26장. 임베딩과 RAG, 내 문서로 답하게 하기

이 장의 목표 회사 위키, 사내 매뉴얼, 회의록 등 내 문서를 AI가 참고해서 답하게 만드는 기술, RAG 의 원리를 끝까지 이해합니다.

26.1 왜 RAG 인가

문제 상황.

"우리 회사의 휴가 정책 알려줘"
        ↓
모델: "일반적으로 회사들은 ..." (헛소리)

모델은 우리 회사 내부 문서를 본 적이 없습니다.

해결책 두 가지.

RAG가 압도적으로 흔한 이유:

• 문서가 자주 바뀌어도 즉시 반영
• 모델 학습 안 함 (시간·비용·하드웨어 절약)
• 출처 명시 가능
• 작은 모델로도 동작

26.2 RAG의 큰 그림

[사용자 질문]
       │
       ▼
[질문을 벡터로 변환]   ← 임베딩 모델
       │
       ▼
[벡터 DB에서 비슷한 문서 찾기]
       │
       ▼
[관련 문서 + 질문을 LLM에 같이 전달]
       │
       ▼
[LLM이 그 문서 보면서 답]

이게 다입니다.

26.3 임베딩 — 의미를 숫자로

문장을 벡터 로 바꾸는 모델 (9장).

"휴가 정책 알려줘"
        ↓
[0.12, -0.45, 0.88, ..., 0.03]

비슷한 의미는 가까운 벡터 가 됩니다.

"휴가 정책 알려줘"      → [0.12, -0.45, ...]
"휴가는 어떻게 신청해?"  → [0.13, -0.41, ...]  (가까움)
"점심 메뉴 추천해"      → [-0.55, 0.66, ...] (멀음)

벡터 간 거리 또는 코사인 유사도 로 가까움을 잼.

26.4 대표 임베딩 모델

대부분 수백 MB ~ 2GB. LLM보다 훨씬 가볍습니다.

Ollama로 받기:

$ ollama pull bge-m3
$ ollama pull nomic-embed-text

26.5 임베딩 API

Ollama:

$ curl http://localhost:11434/api/embeddings -d '{
  "model": "bge-m3",
  "prompt": "휴가 정책 알려줘"
}'

{
  "embedding": [0.123, -0.456, 0.789, ...]
}

OpenAI 호환 형식:

$ curl http://localhost:11434/v1/embeddings -d '{
  "model": "bge-m3",
  "input": "휴가 정책 알려줘"
}'

26.6 청킹(Chunking) — 문서를 잘게 자르기

큰 문서를 통째로 넣으면

• 임베딩이 부정확해지고
• 컨텍스트가 폭주합니다

→ 잘게 잘라서 각 조각의 벡터를 저장.

[원본 문서]
"인사 규정 ... (5,000자) ..."

       ↓ 청킹 (예: 500자 단위)

[조각 1] "인사 규정 ... 휴가는 ..."
[조각 2] "휴가 신청은 ... "
[조각 3] "병가는 ..."
...

청크 크기:

• 너무 작음(100자) → 맥락 부족
• 너무 큼(2000자) → 한 조각에 여러 주제 섞임
• 권장: 300~800자, 약간 겹치게(overlap)

26.7 벡터 DB — 청크를 저장·검색

수만 개 청크 벡터를 어떻게 빨리 검색?

→ 벡터 DB 가 해줍니다 (27장에서 본격).

작은 프로젝트면 그냥 SQLite/JSON도 OK.

이름      | 청크 텍스트  | 벡터
---------+-----------+--------------
chunk_001 | "휴가는 ..." | [0.12, ...]
chunk_002 | "병가는 ..." | [-0.34, ...]
...

질문이 오면:

1. 질문도 임베딩 → 벡터
2. DB에서 가장 가까운 N개 청크 찾기
3. 그 청크들을 LLM 프롬프트에 첨부

26.8 RAG 프롬프트 패턴

청크를 찾은 다음 LLM에게 줄 프롬프트.

[시스템]
다음 "근거"만 보고 한국어로 답하세요.
근거에 없는 내용은 "확인 필요"라고 답하세요.

[근거]
[1] (chunk_023) "정직원의 연차는 1년 만근 시 15일이며..."
[2] (chunk_047) "휴가 신청은 사내 그룹웨어에서..."
[3] (chunk_005) "연차 사용은 부서장 승인 후..."

[질문]
정직원 연차는 몇 일이야?

[답변]

이렇게 주면 모델은 거의 환각 없이 답합니다.

핵심 규칙: “근거에 없으면 모른다고 답해” 한 줄이 환각을 막는 가장 큰 장벽.

26.9 가장 작은 RAG 코드 (Python)

from openai import OpenAI
import numpy as np

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 1. 문서 청크
docs = [
    "정직원의 연차는 1년 만근 시 15일이며...",
    "휴가 신청은 사내 그룹웨어에서...",
    "병가는 진단서가 필요하며...",
    "사내 식사 보조비는...",
]

# 2. 모든 청크 임베딩
def embed(text):
    r = client.embeddings.create(model="bge-m3", input=text)
    return np.array(r.data[0].embedding)

doc_vecs = [embed(d) for d in docs]

# 3. 검색
def search(query, k=2):
    qv = embed(query)
    sims = [np.dot(qv, dv) / (np.linalg.norm(qv) * np.linalg.norm(dv)) for dv in doc_vecs]
    idx = np.argsort(sims)[::-1][:k]
    return [docs[i] for i in idx]

# 4. RAG 답변
def rag_answer(query):
    chunks = search(query)
    context = "\n".join(f"[{i+1}] {c}" for i, c in enumerate(chunks))
    messages = [
        {"role": "system", "content": "다음 근거만 보고 한국어로 답해. 없으면 '확인 필요'."},
        {"role": "user",   "content": f"[근거]\n{context}\n\n[질문]\n{query}"},
    ]
    resp = client.chat.completions.create(model="qwen3:8b", messages=messages)
    return resp.choices[0].message.content

print(rag_answer("정직원 연차는?"))

이 60줄이 RAG의 본질입니다.

26.10 RAG의 자주 만나는 함정

① 검색이 정확하지 않음

• 청크가 너무 큼 → 잘게 쪼개기
• 임베딩이 약함 → bge-m3 같은 다국어 강한 모델로
• 질문이 모호함 → Hybrid Search (키워드 + 벡터) 병행

② 모델이 근거 무시하고 학습 지식으로 답함

• 시스템 프롬프트를 더 강하게: “근거에 명시되지 않은 내용은 절대 추가하지 않음”
• 작은 모델일수록 자주 발생 → 14B 이상 권장

③ 같은 청크가 여러 번 반환됨

• 중복 제거 후 retrieval

④ “확인 필요“가 너무 자주

• top-k 를 2 → 4 정도로 늘림
• 청크 크기 조정

26.11 RAG 품질 끌어올리기 — 다음 단계

기본 RAG가 동작하기 시작하면 다음 단계로:

이 중 가장 효과 큰 건 Reranker. 다음 장에서 실제 도구와 함께 봅니다.

이 장에서 기억할 한 가지

RAG의 본질:

1. 문서를 청크로 쪼개고 임베딩으로 저장
2. 질문이 오면 비슷한 청크를 찾아서
3. LLM에 “이 근거만 보고 답해” 라고 함께 전달

이게 사내 챗봇·문서 챗봇의 거의 모든 모습입니다.

손으로 해볼 것

1. 임베딩 모델 받기

$ ollama pull bge-m3

2. 임베딩 직접 호출

$ curl http://localhost:11434/v1/embeddings -d '{
  "model": "bge-m3",
  "input": "휴가 정책 알려줘"
}' | jq '.data[0].embedding | length'

벡터의 차원이 출력됩니다. (보통 1024)

3. 26.9 절 코드 실행

가상환경에 numpy 와 openai 설치 후 26.9 의 60줄 코드를 그대로 실행.

같은 질문을 RAG 없이 LLM 단독으로 시키고 응답 차이를 비교하세요.

다음 장에서는 진짜 벡터 DB — Chroma, Qdrant 같은 도구를 봅니다.

수천~수만 문서로 가도 무너지지 않는 구조가 보입니다.

27장. 벡터 DB 입문

이 장의 목표 RAG 규모가 커졌을 때 어떤 벡터 DB를 어떻게 골라야 하는지 큰 그림이 잡힙니다.

Chroma·Qdrant·LanceDB 셋만 알면 대부분의 사내 RAG는 만들 수 있습니다.

27.1 왜 벡터 DB가 필요한가

26장 코드는 100개 문서까지는 잘 동작합니다. 하지만 1만 개·10만 개로 가면?

• 매번 모든 벡터를 다 비교 → 느려짐
• 메모리에 다 못 올림
• 새 문서 추가, 오래된 문서 삭제 어려움
• 메타데이터 검색 안 됨

벡터 DB는 이걸 다 해줍니다.

27.2 벡터 DB의 4가지 일

1. 저장 — 청크 + 벡터 + 메타데이터
2. 검색 — 가장 가까운 N개 빠르게 찾기 (ANN 알고리즘)
3. 필터 — “이 부서 문서만”, “최근 6개월” 등
4. 갱신 — 문서 추가·삭제·재인덱싱

27.3 ANN — Approximate Nearest Neighbor

벡터 검색의 핵심 알고리즘 가족.

정확한 검색: 모든 벡터와 거리 계산 (느림, 정확)
ANN 검색: 약간의 근사를 허용해 100~1000배 빠름

대표 알고리즘:

• HNSW (가장 흔함)
• IVF + PQ
• DiskANN

깊이 알 필요는 없습니다. 어떤 DB든 기본값으로 잘 동작합니다.

27.4 맥에서 쉽게 쓰는 벡터 DB 3가지

Chroma — 가장 입문 친화적

• 파이썬 한 줄로 시작
• SQLite 기반
• 작은 ~ 중간 규모 (수십만 청크까지)

$ pip install chromadb

import chromadb

client = chromadb.PersistentClient(path="./db")
col = client.get_or_create_collection("docs")

col.add(
    documents=["문서 1 내용", "문서 2 내용"],
    metadatas=[{"src": "wiki"}, {"src": "회의록"}],
    ids=["d1", "d2"],
)

result = col.query(query_texts=["관련 질문"], n_results=2)

임베딩 모델을 안 지정하면 Chroma 기본 모델을 씀. 한국어 잘하려면 별도로 bge-m3 같은 걸 직접 임베딩 후 전달.

Qdrant — 사내 서버용 표준

• Rust 기반, 매우 빠름
• REST·gRPC API
• 도커로 즉시 실행
• 메타데이터 필터링 강력
• 클라우드 서비스도 제공

$ docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance

q = QdrantClient(host="localhost", port=6333)
q.recreate_collection(
    collection_name="docs",
    vectors_config=VectorParams(size=1024, distance=Distance.COSINE),
)

LanceDB — 임베디드 + 빠름

• 파일 기반, 서버 필요 없음
• Apache Arrow 기반
• 빠른 쿼리·작은 디스크 풋프린트
• 인덱싱 자동

$ pip install lancedb

import lancedb

db = lancedb.connect("./lance_db")
tbl = db.create_table("docs", data=[
    {"vector": [0.1, 0.2, ...], "text": "...", "src": "wiki"},
])
results = tbl.search([0.1, 0.2, ...]).limit(5).to_list()

27.5 세 DB 비교

선택 가이드:

• 처음 / 한 사람 / 노트북 → Chroma or LanceDB
• 사내 서비스 / 다중 사용자 → Qdrant

27.6 청킹 전략 다시 보기 (실무 버전)

고정 길이 청킹

chunks = [text[i:i+500] for i in range(0, len(text), 400)]

500자 청크, 100자 겹침. 간단하지만 문장 중간에서 잘릴 수 있음.

문장·문단 기반

import re
sentences = re.split(r'(?<=[.!?])\s+', text)
chunks = []
buf = ""
for s in sentences:
    if len(buf) + len(s) < 500:
        buf += " " + s
    else:
        chunks.append(buf)
        buf = s

자연스러움 ↑

구조 기반 (Markdown / 코드)

• 헤더 단위로 자르기
• 코드는 함수 단위로

Recursive Splitter (LangChain 등)

여러 구분자(\n\n, \n, ., )를 순차로 시도하며 자릅니다. 가장 권장.

27.7 메타데이터 — RAG의 진짜 무기

벡터만 쓰지 말고 메타데이터 를 같이 저장하세요.

col.add(
    documents=["..."],
    metadatas=[{
        "source": "wiki",
        "title": "휴가 규정",
        "department": "HR",
        "last_updated": "2026-03-15",
        "language": "ko",
    }],
    ids=["d1"],
)

검색 때 필터:

result = col.query(
    query_texts=["휴가"],
    where={"department": "HR", "language": "ko"},
    n_results=3,
)

사내 검색이 잘 안 될 때 90%는 메타 필터 부재가 원인입니다.

27.8 Reranker — 한 단계 정밀화

벡터 검색은 빠르지만 종종 부정확. Reranker 모델이 1차 결과를 다시 정렬합니다.

[1차 벡터 검색] → 후보 20개
        ↓
[Reranker] → 상위 3~5개로 압축
        ↓
[LLM에 전달]

대표 모델:

• BAAI/bge-reranker-v2-m3 (다국어)
• jinaai/jina-reranker-v2-base-multilingual

# 예: sentence-transformers
from sentence_transformers import CrossEncoder
re = CrossEncoder("BAAI/bge-reranker-v2-m3")
pairs = [(query, c) for c in candidates]
scores = re.predict(pairs)

벡터 검색만 쓰는 RAG보다 체감 정확도가 크게 올라갑니다.

27.9 Hybrid Search — 벡터 + 키워드

벡터 검색이 약한 케이스:

• 사람·코드 이름 (고유명사)
• 짧은 키워드
• 숫자·코드

이때는 BM25 같은 키워드 검색과 병합.

방법:

1. 벡터 검색 → top 20
2. 키워드 검색 → top 20
3. 점수를 정규화해서 합치기 (RRF 등)
4. Reranker로 5개 압축
5. LLM에 전달

이 조합이 현업 RAG의 표준.

27.10 인덱싱 시점 vs 검색 시점

• 인덱싱: 문서를 청크화·임베딩해서 DB에 저장 → 느려도 OK (백그라운드)
• 검색: 사용자 질문을 임베딩·검색·LLM 호출 → 가능한 한 빠르게

분리해서 설계하면 운영이 쉬워집니다.

27.11 RAG 운영 체크리스트

사내 RAG 도입 시 확인할 것.

• ✅ 임베딩 모델은 한국어/다국어 강한 걸로 (bge-m3)
• ✅ 청크 300~800자
• ✅ 메타데이터 (source/department/date) 항상
• ✅ Reranker 적용
• ✅ “근거에 없으면 모른다” 시스템 프롬프트
• ✅ 출처 표시 (chunk_id 또는 title)
• ✅ 문서 갱신 파이프라인 (주기적 재인덱싱)
• ✅ 평가 셋 — 정답 알려진 질문 30~50개로 회귀 테스트

이 장에서 기억할 한 가지

RAG의 품질은 LLM이 아니라 검색에서 결정됩니다.

• 청킹 + 임베딩 + 메타 + Reranker 이 4박자가 RAG의 진짜 엔진입니다.

손으로 해볼 것

1. Chroma로 첫 RAG 만들기

$ pip install chromadb