오프라인/폐쇄망에서 쓰는 AI – 개요와 선택 가이드

이번에 회사에서 간단히 진행하는 토이프로젝트 주제에서 오프라인, 저사양 환경에서 구동하는 AI를 구상해보라 해서 해당글을 작성한다. 해당 프로젝트의 주요 요구사항은 다음과 같다.

회사 환경은 인터넷 차단, 노트북 단일 장비에서 끝내야 함
USB로 들고 다니며 즉시 실행 가능해야 함
모델과 데이터는 라이선스, 체크섬, 오프라인 업데이트 경로가 명확해야 함
각 프로젝트에 맞는 학습은 추가로 가능해야 한다.

이번 글에서는 LLM 러너, 모델선택, RAG 전략, 미세조정등 프로젝트 구성에 필요한 지식을 정리한다.

LLM 러너선택

같은 GGUF(또는 다른 포맷) 모델도 “러너”에 따라 설치 난이도, 포터블성, API 호환성, 속도/메모리 특성이 크게 달라진다.

목표는 USB 무설치·폐쇄망 환경에서도 바로 돌릴 수 있고, 필요하면 API 방식으로도 연동 가능한 구성을 갖추는 것이다.

아래 러너들은 혼용 가능하며, 본 프로젝트 기본축은 llama.cpp(포터블) + LocalAI(WSL, API)로 잡고, 나머지를 보조 선택지로 둘 예정이다.

llama.cpp (권장 기본)

포맷 : GGUF

특징 : 단일 실행파일(exe) + 모델 파일만으로 즉시 실행 가능한 초경량 C++ 러너

장점 : 진짜 포터블(무설치), CPU 친화, 세밀 튜닝(threads, n_gpu_layers, ctx 등), 서버 모드(--api) 지원

단점 : 다중 모델 전환/관리 자동화는 직접 스크립팅 필요

언제 : 에어갭·USB 즉시 실행 최우선, 윈도우 네이티브 선호

LocalAI (WSL 패키지형, API 친화)

포맷 : GGUF(llama 백엔드) 외 다양한 백엔드, OpenAI 호환 /v1 API 제공

특징 : 모델을 YAML로 선언해 “이름”으로 여러 개 동시에 노출, 함수 호출/임베딩 서버 등 확장 쉬움

장점 : 백엔드·프런트에서 API 방식으로 붙이기 편함, 멀티모델 운영에 유리

단점 : Windows 네이티브 exe가 없어 WSL 배포본을 오프라인 import 방식으로 패키징 필요

언제 : API 지향 설계, 모델 스위칭·함수 호출·임베딩 서버까지 한 번에 가져가고 싶을 때

Ollama (설치형 데몬, 모델 관리 편의)

포맷 : GGUF 기반(Modelfile로 로컬 GGUF import 가능)

특징 : 모델 다운로드/관리/전환이 매우 간단, 명령 한 줄로 실행

장점 : 운영 편의 최고, 로컬 캐시 기반 오프라인 운용 용이

단점 : 데몬 설치 필요(무설치 USB 우선 목표엔 제약), API는 자체 규격(어댑터로 OpenAI 스타일 변환 가능)

언제 : “여러 모델을 자주 바꿔 쓰는” 데스크톱 환경, 빠른 PoC

LM Studio (데스크톱 GUI, 초보자 친화)

포맷 : 주로 GGUF(내부적으로 llama.cpp 계열)

특징 : GUI에서 모델 검색/다운로드/채팅/간단 서버 제공

장점 : 손쉬운 실험과 데모, 노트북 개인 사용에 적합

단점 : 앱 설치 전제가 있어 에어갭·무설치 요구엔 부적합

언제 : 사전 실험·튜닝, 비개발자 데모

KoboldCpp (스토리/역할극 특화 GUI)

포맷 : GGUF

특징 : 창작·서사형 워크플로우에 특화된 GUI + llama.cpp 백엔드

장점 : 프롬프트 포맷·프리셋이 풍부, CPU에서도 비교적 가볍게 운용

단점 : 범용 API/멀티모델 관리에는 한계

언제 : 문장 생성형 데모, 로컬 스토리봇

Text Generation WebUI (브라우저 GUI 허브)

포맷 : transformers(원가중치), GPTQ/AWQ, GGUF 등 다수 백엔드 통합

특징 : 웹 UI 한 곳에서 다양한 포맷/백엔드를 전환하며 테스트

장점 : 광범위한 호환성, 플러그인 다수

단점 : 파이썬 환경·의존성 준비 필요, USB 완전 포터블성은 낮음

언제 : 다양한 포맷/백엔드 비교 실험, GPU 환경 병행

vLLM (GPU 최적화, 고성능 서버)

포맷 : transformers(원가중치), fp16/bf16 중심

특징 : 대규모 배치·서빙에 최적화, OpenAI 호환 API 제공

장점 : GPU가 충분하면 매우 빠른 토큰 처리율, 함수 호출 등 신기능 대응 활발

단점 : 노트북 CPU-only 환경과는 거리가 멈

언제 : 외장 GPU가 충분하거나, 추후 서버형으로 확장할 계획이 있을 때

ExLlamaV2 / GPTQ / AWQ 계열(전문 GPU 양자화 러너)

포맷 : GPTQ/AWQ 양자화

특징 : NVIDIA GPU에서 대규모 모델을 효율적으로 추론

장점 : 동일 VRAM으로 더 큰 모델 가동 가능

단점 : 포맷/세팅 복잡, CPU-only 노트북에는 부적합

언제 : VRAM이 넉넉한 GPU 노트북·워크스테이션에서 더 큰 모델을 돌릴 때

선택 기준 요약

무설치·USB 즉시 실행 최우선: llama.cpp
API 지향·다중 모델 이름 운영·함수 호출/임베딩 서버: LocalAI(WSL)
모델 관리 편의·간단 전환: Ollama
초보자 친화 GUI/빠른 데모: LM Studio
다양한 포맷/백엔드 통합 실험: Text Generation WebUI
고성능 GPU 서버 지향: vLLM
GPU 양자화 전문(GPTQ/AWQ): ExLlamaV2 등

Hugging Face 모델 검색 가이드

AI 모델은 기계 학습 모델을 구축, 배포 및 교육하기 위한 도구와 리소스를 개발하는 프랑스계 미국 회사이자 오픈 소스 커뮤니티인 huggingfac에서 선택할 예정이다

Hugging Face 모델 목록 페이지에는 여러 “필터(좌측)”가 있다.

오프라인/노트북 환경 뿐만 아니라 데스크탑 환경에서도 유연하게 대응할 수 있게 사용자에게 모델을 선택할 수 있게 할 것이다.

아래는 주요 필터의 의미와, 언제 어떻게 쓰면 좋은지에 대한 실전 설명이다.

Tasks (무엇을 하는 모델인가)

의미 : 모델이 수행하도록 설계된 작업 유형.

예시 : text-generation(텍스트 생성), text-embedding(임베딩), summarization(요약), translation(번역), question-answering(QA), image-classification(이미지 분류), object-detection(객체 탐지), automatic-speech-recognition(ASR, 음성 인식) 등.

언제 쓰나: 목적이 명확할 때 1순위로 고른다.

로컬 챗봇 → text-generation
RAG용 문서 벡터화 → text-embedding
음성 → 텍스트 → automatic-speech-recognition

팁 : text-generation 중에서도 “Instruct(대화 지시 튜닝)” 모델은 챗봇 목적에 더 적합하다.

Parameters (파라미터 수, 모델 크기)

의미 : 모델의 규모(파라미터 수) 범위를 지정한다. 7B의 B는 Billions(십억), 즉 7B ≈ 70억 매개변수.

일반 상식 :

파라미터가 클수록 추론력·지식량이 증가하는 경향이 있으나, 메모리·지연도 커진다.
노트북 CPU 위주면 3B~8B, RAM 16GB 기준 출발점은 7B가 현실적이다.
언제 쓰나: 하드웨어 제약에 맞춰 상한선을 먼저 정한다.

사양별 추천 모델크기 :

RAM 16GB → 3B~8B
RAM 32GB 이상 → 7B~13B

팁 : 파라미터는 “원본 FP 정밀도 모델” 기준이라, GGUF(양자화)로 용량이 줄더라도 “기초 난이도”는 원래 파라미터 수를 따른다. 즉 24B Q4는 돌아가도 7B Q4보다 느리고 무겁다.

Libraries (런타임/포맷)

의미 : 모델이 어떤 라이브러리/포맷로 제공되는지.

예시 :

gguf: llama.cpp/LocalAI/Ollama에서 바로 쓰기 좋은 양자화 가중치.
transformers: PyTorch 기반 표준(원가중치, LoRA 등과 호환).
diffusers, timm, peft 등 다른 생태계용 포맷.

언제 쓰나 : 오프라인 노트북에서 챗봇 → gguf 필수 체크. 파이썬 환경에서 직접 로딩 → transformers.

팁 : gguf를 고르면 파일 탭(“Files and versions”)에서 Q4_K_M 등 양자화 스킴을 즉시 확인할 수 있다.

Apps (데모 앱/스페이스 연계)

의미 : 이 모델과 연결된 데모 앱(Spaces) 여부를 필터링한다.

언제 쓰나 : 모델 품질 감을 빠르게 보려 할 때. 다만 폐쇄망에선 온라인 데모 실행이 불가하므로, 카드의 프롬프트 예시와 사용 주의만 참고하고 파일만 오프라인 반입하면 된다.

팁 : 데모가 없어도 모델 자체가 나쁜 것은 아니다. gguf, 라이선스, 파일 무결성이 더 중요하다.

language (지원/학습 언어)

의미 : 모델이 학습·지원하는 언어 태그로 필터링한다.

언제 쓰나 : 한국어 비중이 높다면 Korean을 포함하는 모델부터 본다. 다국어가 필요하면 multilingual 라벨 또는 영어+한국어를 함께 가진 후보를 체크한다.

팁 : “한국어 특화(Instruct)”와 “다국어 범용(Instruct)”을 각각 1~2개씩 받아 A/B 테스트하면 실제 품질 편차를 금방 체감할 수 있다.

licenses (라이선스)

의미 : 모델 가중치의 사용 조건을 제한한다.

흔한 타입 :

apache-2.0, mit: 비교적 관대한 오픈 라이선스(상업적 사용 가능).
llama3(메타 라이선스), qwen 등 공급자별 라이선스: 상업적 이용 가능 범위·제약을 꼭 확인.

언제 쓰나 : 사내 PoC라도 지재권·상용 정책을 준수해야 한다. 배포·내부 서비스화가 목적이라면 반드시 상업적 사용 허용 여부를 확인하고, 카드의 LICENSE 섹션과 리포지토리 문서를 로컬로 보관한다.

팁 : 동일 모델의 변형 중 라이선스가 다를 수 있다. “같은 이름”이라도 카드별 LICENSE를 항상 따로 체크한다.

Inference Providers (호스팅/추론 제공자)

의미 : 모델을 외부 서비스에서 바로 돌릴 수 있는지(지원 인퍼런스 제공자)

오프라인 관점 :

폐쇄망 노트북에서는 직접적 의미가 작다. 다만 “생태계에서 널리 쓰이는 모델인지”를 가늠하는 보조 지표로 활용할 수 있다.
오프라인 배포가 목표라면 이 섹션 대신 gguf 유무, 파일 크기, 양자화 종류, 템플릿 주의(--jinja 등) 같은 로컬 실행 관점의 신호를 우선 본다.

실전 조합 예시 (오프라인/노트북 챗봇)

목표 : 한국어 대화형, 노트북 CPU 위주, 오프라인 gguf

Tasks: text-generation
Parameters: 3B~8B
Libraries: gguf
language: Korean(또는 multilingual)
licenses: apache-2.0 또는 상업 이용 가능 항목 위주

후보를 몇 개 고른 뒤, Files에서 Q4_K_M, Q5_K_M 등 양자화 파일이 있는지 확인하고 다운로드 목록을 확정한다.

다운로드 전 최종 체크

Files and versions : gguf 파일 존재, 양자화 스킴(Q4_K_M 등), 컨텍스트 창, 채팅 템플릿 주의(--jinja 등)
LICENSE : 상업적 사용 가능 여부와 조건
카드 설명 : 한국어 성능, 툴콜/함수 호출, 권장 하이퍼파라미터(temperature, top_p)
무결성 : 체크섬(SHA256)으로 파일 검증을 병행

RAG 전략(LLM 교체와 독립)

폐쇄망 프로젝트에서는 인터넷을 통한 지속적 업데이트가 불가능하기 때문에, 내부 데이터를 정제·임베딩하여 AI가 “참조할 수 있는 지식”을 만들어두는 전략이 필수다.

이 과정을 RAG(Retrieval-Augmented Generation) 이라고 하며, 생성 LLM의 품질을 높이기 위한 핵심 구성 요소다.

올바른 구조를 잡아두면 모델을 바꾸거나 업그레이드하더라도, 임베딩 데이터는 그대로 재사용할 수 있어 유지보수가 크게 단순해진다.

핵심 전략 – LLM과 RAG를 분리하여 독립 운영

1) 생성 LLM(텍스트 생성 담당) 은 바꿔도 임베딩 모델(문서 벡터화 담당) 이 같다면 인덱스는 그대로 재사용 가능하다.

→ “답변 엔진을 교체해도, 지식 데이터베이스는 그대로 유지”가 핵심.

2) 임베딩 모델을 바꾸는 경우 : 벡터 공간 자체가 달라지므로 모든 문서를 다시 임베딩하고 인덱스를 새로 구축해야 한다.

→ 예: bge-m3 → e5-large로 바꾸면 전량 재처리 필요.

3) 인덱스 버전 관리 : 각 임베딩 모델별로 독립된 인덱스 폴더를 유지한다.

폴더 구조 예시 :

index/bge-m3/
index/e5-large/

메타데이터에 embedding_model_id를 함께 저장해 어떤 모델로 생성된 인덱스인지 추적할 수 있도록 한다.

4) 재랭커(Re-ranker) 옵션

검색된 상위 k개 결과를 cross-encoder(bge-reranker 등) 로 재정렬해 정확도를 높인다.
특히 유사한 문장이 많거나 기술 문서 기반 검색 시, 정밀도 향상 효과가 크다.

데이터 파이프라인 설계 (추출 → 청크 → 임베딩 → 인덱스)

이 파이프라인은 새로운 문서를 추가하거나 전체 데이터를 업데이트할 때 동일하게 사용된다.

① 입력 단계

지원 포맷: pdf, docx, pptx, txt, md, csv 등.
폐쇄망 환경에서는 변환 라이브러리(예: PyMuPDF, python-docx, python-pptx)를 오프라인 설치 후 사용.

② 전처리 단계

텍스트 추출 후 불필요한 요소 제거:
헤더/푸터, 목차, 페이지 번호 등 비의미 텍스트 제거.
언어 감지(ko/en) 및 문단 단위 정리.
인코딩 에러, 특수문자, 공백 정제.

③ 청크(Chunking) 단계

모델이 처리 가능한 단위로 문서를 쪼갠다.
기준: 600~1200자 범위, 문장 경계를 고려.
중복 정보 유실 방지를 위해 10~20% overlap 적용.
예: [문단1~문단3] → [문단3~문단5] 식으로 중첩.

④ 메타데이터 관리 : 각 청크에 다음 정보를 함께 저장한다

file_path: 원본 파일 경로
page: 페이지 번호
start_offset / end_offset: 텍스트 위치
lang: 언어 코드(ko/en)
pack: 문서 그룹 식별자
version: 데이터 버전
sha256: 원문 해시(무결성 검증용)
-이 정보는 RAG 응답 시 “출처 정보”를 함께 표시하는 데 사용된다.

⑤ 임베딩(Embedding) 단계

선택된 임베딩 모델(bge-m3, e5-base 등)로 각 청크를 벡터화.
동일 임베딩 모델을 사용하면 LLM이 바뀌어도 인덱스 유지 가능.
초기 구축 시 bge-m3를 기본값으로 고정해 시작하는 것을 권장한다.

⑥ 인덱스 구축(Indexing) 단계

FAISS 또는 Chroma 중 하나를 사용해 벡터를 저장.
FAISS: 빠른 검색 속도, 파일형 저장에 적합.
Chroma: SQLite 기반, 메타데이터 관리가 편리.
index/ 폴더 내에 모델별 벡터 인덱스를 생성하고, 변경 시마다 버전업.

RAG 검색 흐름 요약

사용자가 질문 → FastAPI 백엔드 수신
질문 텍스트를 동일 임베딩 모델로 벡터화
FAISS/Chroma에서 유사도 기반 top-k 검색
상위 k 청크를 재랭킹(선택적)
결과를 LLM 프롬프트에 삽입 → 답변 생성
사용자에게 답변 + 근거 출처(file_path/page) 함께 반환

RAG는 “지식 저장소”이자 “LLM 교체 후에도 유지되는 데이터 자산”.

임베딩 모델 고정으로 인덱스 재사용이 가능하고, 프로젝트별 독립 버전 관리가 핵심.

파이프라인(추출 → 청크 → 임베딩 → 인덱스)을 자동화하면 오프라인에서도 재학습 없이 데이터 업데이트가 가능하다.

라고 GPT가 정리해주긴했는데 해당부분은 프로젝트를 만들어보면서 조정하는 작업을 해야할 거 같다.

미세조정(선택 사항)

기본 LLM이 충분히 강력하더라도, 사내 도메인 용어나 답변 스타일을 맞추기 위해 “미세조정(Fine-tuning)”을 선택적으로 적용할 수 있다.

완전한 재학습이 아닌 LoRA(경량 어댑터) 기반 튜닝을 사용하면 오프라인 노트북에서도 수행 가능하다.

해당 미세조정은 다음과 같은 목적을 이룰 수 있다.

답변 스타일 통일: 예를 들어 “정중한 어투”, “간결한 요약체” 등.
도메인 보정: 내부 문서, 기술 용어, 정책 문장 등에 맞는 반응 생성.
포맷 고정: JSON, 표 형식, 보고서 양식 등 특정 출력 형식 강제.

QLoRA(4bit) 방식 권장: 메모리 효율적이며, 원본 모델(예: 7B)을 그대로 두고 어댑터만 추가 학습.

데이터 규모: 수천~수만 샘플(대화형 또는 지시문-응답 형태).

오프라인 환경에서는 CSV/JSONL 형태로 정제된 학습 데이터만 준비해 진행.

학습이 끝나면 어댑터 파일이 다음 형태로 생성된다:

  adapters/<base-llm>/<experiment-name>.safetensors

- 추론 시 LLM 로드 후 이 어댑터를 추가 로딩하면 미세조정된 동작이 반영된다.

미세조정은 선택 사항이며, 기본 모델로 충분하면 생략 가능하다 한다 제한된 환경에서 이러한 조정작업을 하기에는 사용자가 어느정도 지식과 정제된 데이터가 많이 필요할 것으로 생각되어 이부분은 실제 데모를 만드는 과정에서 추가적으로 고려해야할 사항같다.

USB 오프라인 패키징(최종 계획)

최종적으로 앞으로 만들게 될 프로젝트는 환경 설정 및 실행을 하나의 배치 파일로 가능하게 만들어볼까 한다.

운영 환경은 FE는 next BE는 fest.api
러너 : 기본은 llama.cpp(무설치), 필요시 LocalAI(WSL) 병행
모델 : 7B Q4_K_M부터 시작, 환경에 맞춰 변화 가능하게 개발
RAG : 임베딩 모델 고정, 인덱스는 embedding_model_id 기준으로 버전 관리
미세조정 : 선택 기능, 해당 LLM용 LoRA만 별도 보관 및 적용
목표 : USB에서 즉시 실행, 1분 내 답변, 출처 가능한 RAG, 오프라인 업데이트 체계 확보

UX 메뉴와 동작 흐름

메인페이지 : 상태 표시, 러너 포트, 인덱스 선택 요약, 최근 로그
모델선택 : gguf 파일 선택, 러너 선택(기본 llama.cpp, 선택 LocalAI), 스레드, n_gpu_layers, ctx, max_tokens, temperature
학습데이터 등록 및 선택 : 파일 업로드, 추출 로그, 청크 파라미터, 임베딩 모델 선택, 인덱스 빌드/증분
미세조정 : 기반 LLM 고르기, 데이터셋 선택, QLoRA 하이퍼파라미터, 어댑터 저장/적용
AI 사용: 대화, 스트리밍 표시, RAG on/off, 출처(파일명, 페이지/오프셋) 표시

성능/품질 검증(오프라인 리그)

속도 : TTFT, tokens/sec, 전체 지연
정확도 : EM/F1, 근거 포함율(출처가 붙은 답변 비율)
환각 : 근거 불일치율
회귀 테스트 : 대표 프롬프트 세트로 버전업마다 측정
운영 정책 : 주간 리그 상위 모델을 기본값, 나머지는 백업

보안/거버넌스 체크리스트

모델/데이터 라이선스 확인 및 문서 보관
모든 외부 전송 기본 차단, 로컬 포트는 127.0.0.1 바인딩
오프라인 업데이트 경로 수립(USB, 내부 미러), 해시 검증(SHA256)
패키지 버전 잠금(requirements/lockfile)과 SBOM 유지
프롬프트/결과 로그 기본 비활성, 필요한 최소만 암호화 저장