로컬 실행과 OpenAI 호환 API 구성
로컬 실행은 포맷 선택에서 시작한다
Unsloth로 학습한 모델을 실제 애플리케이션에 붙이려면 먼저 실행 포맷을 정해야 한다. Unsloth Studio는 GGUF, LoRA 어댑터, safetensors 모델을 로컬에서 불러와 실행할 수 있다.1
GGUF는 가볍게 배포하고 빠르게 실행하기 좋은 포맷이다. 양자화 모델을 쓰기 쉬워 개인 PC, Ollama, llama.cpp 계열, Studio Chat 테스트에 잘 맞는다. 반대로 safetensors는 학습 결과를 정밀하게 보존하고, 재학습이나 서버형 추론 환경으로 이어 가기에 좋다. LoRA 어댑터는 파일이 작고 실험 버전 관리가 쉽지만, 실행할 때 같은 base model이 필요하다.
간단히 말하면 개인 로컬 챗봇은 GGUF, 재학습과 품질 보존은 safetensors, 여러 실험 비교는 LoRA 어댑터가 편하다.
AI 생성 이미지
Studio에서 로컬 API 열기
최신 Unsloth Studio에서는 Chat 화면에서 모델을 불러온 뒤 로컬 API로 외부 프로그램에 연결할 수 있다. 흐름은 단순하다.
Studio를 실행한다.
Chat에서 New Chat을 누른다.
GGUF 모델을 선택하거나 검색해 로드한다.
왼쪽 아래 Unsloth 아바타에서 Settings → API로 이동한다.
API 키 이름을 입력하고 Create를 누른다.
sk-unsloth-...형식의 키를 복사한다.
API 키는 한 번만 표시되고 해시로 저장된다. 요청마다 Authorization: Bearer ... 헤더가 필요하다. OpenAI 호환 호출은 /v1/chat/completions를 사용하고, 최신 엔드포인트에서는 /v1/responses도 제공된다. Anthropic 호환 클라이언트는 /v1/messages를 사용할 수 있다.2
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8888/v1",
api_key="sk-unsloth-...",
)
response = client.chat.completions.create(
model="local-model",
messages=[
{"role": "system", "content": "간결하게 답하세요."},
{"role": "user", "content": "우리 제품 환불 규정을 요약해줘."},
],
)
print(response.choices[0].message.content)기존 애플리케이션에 붙이는 방법
OpenAI 호환 API의 장점은 기존 코드를 크게 바꾸지 않아도 된다는 점이다. 클라우드 OpenAI API를 쓰던 챗봇, 사내 자동화 스크립트, IDE 코딩 에이전트, Open WebUI 같은 도구는 보통 base_url, API 키, 모델명만 바꾸면 로컬 모델을 호출할 수 있다.
다만 모델이 바뀌면 응답 습관도 달라진다. 운영에 붙이기 전에는 같은 평가 프롬프트로 다시 확인해야 한다. 특히 JSON 출력, 표 형식, 도구 호출 인자처럼 후처리에 쓰이는 응답은 반드시 파싱 테스트를 거친다.
도구 호출은 계층을 나눠 설계한다
에이전트형 애플리케이션에서는 모델이 모든 일을 직접 하면 위험하다. 안전한 구조는 네 단계로 나누는 것이다.
로컬 모델 서버: 질문을 이해하고 다음 행동을 제안한다.
도구 실행 계층: 검색, 파일 읽기, DB 조회, Python 실행을 실제로 수행한다.
권한·로그 계층: 누가 어떤 파일과 도구를 호출했는지 기록한다.
응답 후처리: JSON 검증, 금지어 검사, 출처 표시, 실패 재시도를 처리한다.
Unsloth API는 tool calling, streaming, vision 입력을 지원하며, Studio의 서버 측 도구로 Python 실행, 웹 검색, Bash 실행을 사용할 수 있다.2 하지만 외부 접속을 여는 순간 위험도도 커진다. 로컬호스트에서는 도구가 기본 활성화될 수 있지만, 0.0.0.0 같은 외부 바인딩에서는 도구 노출 여부를 명시적으로 관리해야 한다.
100% 로컬의 장점과 책임
Unsloth Studio는 Windows, Linux, WSL, macOS에서 로컬 실행을 지원하고, Docker 환경도 활용할 수 있다. Studio는 로컬·오프라인 실행을 강조하므로 내부 문서, 고객 정보, 소스코드를 외부 API로 보내지 않고 모델을 사용할 수 있다.3
그러나 로컬이라는 말이 자동으로 안전하다는 뜻은 아니다. API 포트를 열면 내부 네트워크의 다른 사용자가 접근할 수 있다. 모델 파일, 로그, 업로드 문서, API 키도 보호 대상이다. 운영 전에는 방화벽, 인증, 접근 권한, 로그 보관 기간, 백업 위치를 정해야 한다.
실전 배포의 기준은 단순하다. 모델이 잘 답하는가, 같은 설정으로 반복 호출해도 안정적인가, 외부로 나가면 안 되는 데이터가 실제로 나가지 않는가. 이 세 가지를 통과해야 로컬 LLM은 실험 도구가 아니라 업무 시스템의 일부가 된다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.