로컬 LLM API로 활용하는 방법

귀하의 노트북은 프로덕션에 배포하는 것과 동일한 OpenAI 형태의 엔드포인트 뒤에서 70B 매개변수 모델을 제공할 수 있습니다. 기본 URL 하나만 바꾸면 코드가 계속 작동합니다. 이 단 한 번의 변경으로 오프라인 개발, 토큰당 비용 제로, 규제 데이터에 대한 비공개 경로가 가능해졌습니다. 이것이 바로 Hacker News가 하루 만에 "로컬 AI가 표준이 되어야 한다"는 주장을 633점 획득에서 1,760점 획득으로 끌어올린 이유입니다. 아래 글은 호스팅 모델로 어떤 변경 사항을 승격하기 전에 런타임을 선택하고, 엔드포인트를 노출하고, 클라이언트를 연결하고, Apidog로 전체 흐름을 테스트하는 방법을 보여줍니다.

TL;DR (요약)

Ollama, vLLM 또는 llama.cpp를 사용하여 노트북에서 로컬 LLM API를 실행할 수 있으며, 이들 모두 OpenAI 호환 REST 엔드포인트를 노출합니다. 기존 OpenAI 클라이언트에서 base_url을 http://localhost:11434/v1로 변경하면 Llama 3.3, DeepSeek V4 또는 Qwen 3.6에 대해 동일한 코드가 재작성 없이 실행됩니다. Apidog에서 전체 흐름을 구동하여 로컬 및 호스팅 환경에서 시나리오 테스트가 동일하게 유지되도록 하십시오.

소개

로컬 LLM API 스택은 18개월 만에 연구용 장난감에서 일상적인 도구로 발전했습니다. Apple은 M3 Max에 128GB 통합 메모리를 탑재했습니다. Ollama는 주간 다운로드 백만 건을 기록했습니다. vLLM은 GitHub 스타 30,000개를 돌파했습니다. 하지만 가장 큰 변화는 사회적인 것이었습니다. 이제 모든 주요 런타임은 OpenAI /v1/chat/completions 형식을 지원합니다. 더 이상 두 개의 클라이언트 경로를 유지할 필요가 없습니다. 동일한 SDK 호출이 하나의 환경 변수에 따라 localhost 또는 api.openai.com을 대상으로 합니다.

이는 API 개발자에게 중요합니다. 기존 도구가 계속 작동하기 때문입니다. Apidog의 요청 템플릿은 https://api.openai.com/v1/chat/completions를 가리킵니다. 기본 URL 변수를 전환하고 '보내기'를 누르면 자신의 GPU에서 실행되는 모델로부터 동일한 JSON을 받을 수 있습니다. 새로운 스키마도, 새로운 인증 흐름도 없습니다. 이미 기능별 API 지출을 추적하고 있다면, 로컬 모델과 호스팅 모델을 A/B 테스트하여 지연 시간이 증가하는 동안 비용이 감소하는 것을 확인할 수 있습니다.

이 가이드는 런타임 선택, 서버 설정, 클라이언트 연결, 시나리오 테스트, 양자화 절충점, 그리고 현재 네 가지 모델에 대한 비용-지연 시간 표를 설명합니다. 코드 샘플은 macOS 15.4 및 Ubuntu 24.04에서 Ollama 0.6 및 vLLM 0.7을 대상으로 테스트되었습니다. 더 넓은 옵션 범위에 대해서는 2026년 최고의 로컬 LLM을 참조하십시오. 모든 주장에 대한 외부 참조는 하단에 있습니다.

button

API 개발자에게 로컬 LLM이 합리적인 이유

귀하는 LLM을 호출하는 코드를 배포합니다. 또한 비행기 안에서, Wi-Fi가 좋지 않은 컨퍼런스에서, 그리고 *.openai.com으로의 외부 통신을 차단하는 고객 네트워크 내에서 해당 코드를 디버깅합니다. 로컬 LLM API는 네트워크 의존성 없이 프로덕션을 미러링하는 개발 환경을 제공합니다.

프라이버시 문제가 가장 중요합니다. HIPAA, GDPR 및 EU AI 법은 환자 기록, 계약 또는 생체 인식 식별자를 포함하는 순간 프롬프트를 사용자 데이터로 간주합니다. 해당 페이로드를 호스팅된 엔드포인트로 전송하면 문서화, 감사 및 갱신해야 하는 데이터 처리자 관계가 생성됩니다. 하드웨어를 벗어나지 않는 모델은 이러한 서류 작업을 완전히 건너뛸 수 있습니다. 유럽 데이터 보호 이사회(European Data Protection Board)의 2024년 AI 처리 지침은 온디바이스 추론이 제44조에 따른 대부분의 국경 간 전송 의무를 제거한다고 언급합니다.

비용은 다른 방향으로 복합됩니다. GPT-5.5 Instant를 통해 하루에 5천만 프롬프트 토큰을 실행하는 팀은 백만 토큰당 5달러로 하루에 약 250달러를 지불합니다. 4,500달러짜리 M3 Max 스튜디오에서 동일한 볼륨은 전기를 무시하고 18일간의 완전 활용 후에는 비용이 0으로 상각됩니다. 이러한 수치에 대한 분석은 GPT-5.5 Instant 사용 방법에서 읽을 수 있으며, 동일한 산술을 자신의 워크로드에 적용할 수 있습니다.

세 번째 이유는 결정론입니다. 호스팅 모델은 사용자 모르게 가중치를 변경합니다. OpenAI의 모델 사용 중단 페이지에는 지난 12개월 동안 11개의 스냅샷 중단이 나열되어 있습니다. 로컬 모델은 디스크에 있는 파일입니다. 오늘과 3년 후에도 동일한 로짓을 생성합니다. 이러한 안정성은 회귀 테스트 스위트가 LLM 출력에 의존할 때 중요합니다. OpenAI 호환 엔드포인트는 이러한 안정성에 대한 통합 비용을 더 이상 지불하지 않기 때문에 판도를 바꾸었습니다. 이미 사용 중인 SDK가 작동합니다.

OpenAI 호환 엔드포인트를 제공하는 세 가지 런타임

2026년에는 네 가지 런타임이 로컬 LLM API 공간을 지배합니다. 세 가지는 OpenAI 호환 REST 서버를 즉시 제공합니다. 네 번째인 llama.cpp는 llama-server 바이너리의 일부로 이를 제공합니다. 인기도가 아닌 워크로드에 따라 선택하십시오.

Ollama

Ollama는 가장 쉬운 진입점입니다. 하나의 바이너리, 하나의 CLI, 포트 11434의 하나의 HTTP 서버. 단일 머신에서 단일 모델을 실행하는 개발자를 대상으로 하며, 모델 다운로드, GGUF 양자화 및 프롬프트 템플릿 생성을 처리합니다.

## install on macOS
brew install ollama
ollama serve &
ollama pull llama3.3:70b-instruct-q4_K_M
ollama run llama3.3:70b-instruct-q4_K_M

ollama serve가 실행되면 OpenAI 호환 엔드포인트는 http://localhost:11434/v1에 위치합니다. 이 엔드포인트는 채팅, 임베딩 및 스트리밍을 지원합니다. M3 Max에서 70B Q4_K_M 모델의 처리량 한계는 초당 약 12토큰입니다. 더 작은 모델은 초당 80~120토큰을 처리합니다. Ollama는 단일 사용자 개발, 데모 및 CI 러너에 적합한 선택입니다.

vLLM

vLLM은 프로덕션 등급 옵션입니다. PagedAttention과 연속 배칭을 사용하여 처리량을 일반적인 런타임보다 2배에서 4배까지 높입니다. 기본적으로 포트 8000에서 서비스를 제공하며 /v1에서 OpenAI 호환 API를 노출합니다. 아래 권(Kwon) 등의 SOSP 2023 참조에서 vLLM 논문의 아키텍처 세부 정보를 읽을 수 있습니다.

pip install vllm
vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192

단일 H100에서 vLLM은 동시 요청에 걸쳐 초당 약 2,400토큰으로 Llama 3.3 70B를 제공합니다. CUDA GPU 또는 최신 AMD ROCm 카드가 필요하며 Apple Silicon에서는 실행되지 않습니다. 따라서 노트북에는 적합하지 않고 공유 개발 클러스터에는 적합합니다.

llama.cpp

llama.cpp는 GGUF 생태계를 시작한 C++ 런타임입니다. Raspberry Pi 5부터 듀얼 RTX-5090 리그까지 모든 곳에서 실행됩니다. llama-server 바이너리는 /v1/chat/completions에서 OpenAI 형식을 지원합니다.

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make -j LLAMA_METAL=1
./llama-server -m models/llama-3.3-70b-q4_k_m.gguf \
  --port 8080 --host 0.0.0.0 -c 8192 -ngl 99

-ngl 99 플래그는 모든 레이어를 GPU로 오프로드합니다. llama.cpp는 양자화, 배칭 및 메모리 매핑에 대한 가장 많은 제어권을 제공합니다. 16GB VRAM에 모델을 압축해야 하거나 이국적인 하드웨어를 테스트해야 할 때 올바른 선택입니다.

LM Studio와 Jan은 llama.cpp를 GUI로 감싸고 구성 가능한 포트에서 OpenAI 엔드포인트를 노출합니다. 이들은 터미널을 건드리지 않고 프롬프트를 테스트해야 하는 팀의 비기술 사용자에게 유용합니다.

엔드포인트가 작동하는지 확인하는 간단한 Python 검사:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.3:70b-instruct-q4_K_M",
    messages=[{"role": "user", "content": "Reply with the word OK only."}],
)
print(resp.choices[0].message.content)

OK가 보이면 런타임, 포트 및 SDK 계약이 모두 일치하는 것입니다. 이제 엔드포인트를 도구에 연결할 준비가 된 것입니다.

Apidog로 로컬 LLM 테스트하기

로컬 LLM API는 테스트 스위트가 프로덕션에 접근하는 것과 동일한 방식으로 접근할 수 있을 때만 유용합니다. Apidog는 요청 템플릿의 환경 변수를 사용하여 이를 처리하며, 이는 하나의 프로젝트가 두 대상 모두를 커버할 수 있음을 의미합니다.

흐름은 다섯 단계로 이루어집니다.

Apidog 프로젝트를 열고 Local이라는 새 환경을 생성합니다. BASE_URL 변수에 http://localhost:11434/v1 값을 추가합니다. API_KEY에 ollama 값을 추가합니다. 저장합니다.
기존 OpenAI 환경을 복제하고 Production으로 이름을 변경한 다음, BASE_URL은 https://api.openai.com/v1로, API_KEY는 호스팅 키로 유지합니다.
채팅 엔드포인트를 호출하는 모든 요청에서 하드코딩된 호스트를 {{BASE_URL}}로, 인증 헤더를 Bearer {{API_KEY}}로 바꿉니다. 요청 URL은 {{BASE_URL}}/chat/completions가 됩니다.
요청을 실행하고, choices[0].message.role == "assistant"를 단언하고, choices[0].message.content가 비어 있지 않음을 단언하고, usage.total_tokens > 0임을 단언하는 시나리오 테스트를 구축합니다. 시나리오를 저장합니다.
Local 환경에 대해 시나리오를 실행합니다. 환경 드롭다운을 Production으로 전환합니다. 다시 실행합니다. 두 환경 모두에서 단언이 통과해야 합니다.

동일한 시나리오는 런타임 업그레이드를 위한 스모크 테스트 역할도 합니다. 새 태그에서 ollama pull을 실행한 후 Local 시나리오를 다시 실행하십시오. 응답 형태가 달라지면 애플리케이션 코드가 새 가중치에 영향을 주기 전에 이를 파악할 수 있습니다. 이 패턴은 다단계 API를 호출하는 AI 에이전트 테스트로 확장됩니다.

프로그래밍 방식 사용을 위해 OpenAI Python SDK는 하나의 키워드 인수로 대상을 전환합니다:

import os
from openai import OpenAI

def get_client():
    if os.getenv("ENV") == "local":
        return OpenAI(
            base_url="http://localhost:11434/v1",
            api_key="ollama",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

client = get_client()
response = client.chat.completions.create(
    model=os.getenv("MODEL", "llama3.3:70b-instruct-q4_K_M"),
    messages=[
        {"role": "system", "content": "You are a JSON-only assistant."},
        {"role": "user", "content": "Return {\"status\": \"ok\"}."},
    ],
    response_format={"type": "json_object"},
)
print(response.choices[0].message.content)

JavaScript 형태는 다음과 같습니다:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.ENV === "local"
    ? "http://localhost:11434/v1"
    : "https://api.openai.com/v1",
  apiKey: process.env.ENV === "local" ? "ollama" : process.env.OPENAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: process.env.MODEL || "llama3.3:70b-instruct-q4_K_M",
  messages: [{ role: "user", content: "Say hi." }],
});
console.log(resp.choices[0].message.content);

프로젝트를 apidog-cli 컬렉션으로 내보내고 GitHub Actions에서 apidog run을 호출하여 Apidog의 시나리오 러너를 CI에 연결하십시오. 러너는 단언 실패 시 0이 아닌 종료 코드를 반환하며, 이는 로컬 또는 호스팅 계약이 어긋나는 순간 빌드를 실패하게 합니다. QA 엔지니어는 동일한 흐름을 기존 API 테스트 파이프라인에 연결할 수 있습니다.

고급 기술 및 전문가 팁

양자화는 70B 모델이 노트북에 맞을지 여부를 결정하는 핵심 요소입니다. GGUF 형식은 매개변수당 8, 6, 5, 4, 3 또는 2비트로 가중치를 저장합니다. Q4_K_M이 기본값인 데는 이유가 있습니다. FP16 대비 MMLU 벤치마크에서 0.6%포인트 손실을 보이지만 70B 모델을 140GB에서 40GB로 줄입니다. Q8은 FP16에 비해 0.1포인트 이내를 유지하지만 디스크 및 RAM 공간을 두 배로 늘립니다. Q2_K는 공간을 절약하지만 긴 컨텍스트를 가진 모든 작업에서 혼란도 저하가 눈에 띄게 나타납니다. 채팅에는 Q4_K_M을, 코드 생성에는 Q8을, RAM이 충분하고 안전 여유를 원할 때는 Q5_K_M을 선택하십시오.

llama.cpp의 -ngl 플래그 또는 Ollama의 num_gpu 옵션을 통한 GPU 오프로드는 GPU에 상주하는 트랜스포머 레이어 수를 제어합니다. VRAM이 허용하는 한 최대한 높게 설정하십시오. CPU로 대체되는 각 레이어는 처리량을 약 30% 감소시킵니다. 24GB 카드에서는 70B Q4 모델이 80개 레이어 중 40개를 수용할 수 있습니다. 48GB에서는 전체 스택을 수용할 수 있습니다.

메모리 매핑(mmap)은 llama.cpp 및 Ollama에서 기본적으로 켜져 있습니다. 이를 통해 운영 체제는 시작 시 전체 모델을 할당하는 대신 필요할 때 가중치를 페이지 인합니다. 엄격한 메모리 제한이 있는 컨테이너에서 실행하는 경우가 아니면 켜 두십시오. mmap를 끄면 첫 토큰 지연 시간이 약 200ms 단축되지만 RAM 사용량이 두 배로 증가합니다.

배칭은 vLLM의 초능력입니다. 32개의 동시 요청을 보내면 vLLM은 이를 단일 GPU 패스로 그룹화합니다. 처리량은 GPU의 컴퓨팅 한계까지 거의 선형적으로 확장됩니다. 공유 CPU 메모리를 사용하는 노트북에는 --max-num-seqs 64를 설정하고 H100급 하드웨어에는 --max-num-seqs 256을 설정하십시오.

스트리밍 응답은 인지되는 지연 시간을 절반으로 줄입니다. OpenAI SDK에서 stream=True를 설정하면 서버는 토큰이 생성되는 즉시 플러시합니다. 전체 완료를 기다리는 대신 첫 번째 바이트가 200~500ms 이내에 도착합니다. 이 가이드의 모든 런타임이 이를 지원합니다.

Ollama의 Modelfile을 사용하면 시스템 프롬프트, 온도 및 중지 시퀀스를 명명된 모델에 통합하여 애플리케이션 코드를 깔끔하게 유지할 수 있습니다. ollama create my-assistant -f Modelfile을 한 번 실행하면 클라이언트가 매 요청마다 시스템 프롬프트를 반복하는 대신 my-assistant를 가리키게 됩니다.

흔한 실수

프로덕션 코드에 http://localhost:11434를 하드코딩하는 것. 환경 변수를 사용하세요.
로컬 모델이 max_tokens를 강제하지 않는다는 것을 잊는 것. 그들은 기꺼이 4,096개의 토큰을 생성할 것입니다. 중지 시퀀스를 설정하세요.
Ollama와 다른 런타임을 동일한 포트에서 실행하는 것. 둘 다 기본적으로 깨끗한 포트를 사용하지만, 사용자 지정 포트는 조용히 충돌합니다.
Authorization 헤더를 건너뛰는 것. Ollama는 이를 무시하지만, --api-key가 있는 vLLM은 인증되지 않은 요청을 401로 거부합니다.
Q4 모델을 로드하고 수학에서 GPT-5.5 품질을 기대하는 것. 양자화는 추론 능력을 가장 빠르게 저하시킵니다.

로컬 vs 호스팅: 비용 및 지연 시간 계산

아래 수치는 로컬의 경우 128GB 통합 메모리를 갖춘 M3 Max를 가정하며, 호스팅된 엔드포인트의 경우 현재 공개 가격을 기준으로 합니다. 첫 토큰까지의 시간(TTFT)은 1,024 토큰 프롬프트에서 배치 처리 없이 콜드 상태로 측정됩니다.

모델	로컬 TTFT	로컬 처리량	호스팅 동등 모델	호스팅 가격	호스팅 TTFT
Llama 3.3 70B Q4_K_M	1.2 초	12 토큰/초	GPT-5.5 Instant	1백만 토큰당 $5 / $30	200 ms
DeepSeek V4 67B Q4_K_M	1.4 초	10 토큰/초	DeepSeek-Chat (호스팅)	1백만 토큰당 $0.55 / $2.20	280 ms
Qwen 3.6 32B Q5_K_M	0.7 초	28 토큰/초	Qwen-Max (호스팅)	1백만 토큰당 $1.60 / $6.40	240 ms
Gemma 4 27B Q4_K_M	0.5 초	35 토큰/초	Gemini 3 Flash	1백만 토큰당 $0.35 / $1.05	180 ms

지연 시간 면에서는 항상 호스팅된 옵션이 우세합니다. 로컬 옵션은 하루에 약 1천만 토큰을 초과하는 순간 비용 면에서 유리하며, 첫 요청부터 프라이버시 면에서 우세합니다. 개발에는 거의 항상 로컬을 원할 것입니다. 사용자 대면 프로덕션에는 데이터 분류가 금지하지 않는 한 거의 항상 호스팅을 원할 것입니다.

실용적인 패턴: 내부 개발 루프 동안 로컬에서 실행하고, 스테이징에서는 호스팅으로 전환하며, CI에서 두 대상 모두 성공 상태를 유지합니다. 위 섹션의 Apidog 시나리오 테스트는 단일 환경 토글로 이 패턴을 지원합니다. 개별 모델에 대한 더 깊은 벤치마크는 DeepSeek V4 로컬에서 실행하는 방법 및 원래 DeepSeek V4 사용 가이드를 참조하십시오.

실제 사용 사례

싱가포르의 한 핀테크 컴플라이언스 팀은 엔지니어 노트북에서 Ollama를 사용하여 의심스러운 활동 보고서를 작성합니다. 프롬프트에는 MAS 규정상 국가를 벗어날 수 없는 계좌 번호와 거래 패턴이 포함되어 있습니다. 프로덕션에서 사용하는 호스팅된 엔드포인트는 동일한 프롬프트의 수정된 버전을 받습니다. Apidog 시나리오는 요청이 localhost를 벗어나기 전에 수정자가 모든 요청에서 실행됨을 단언합니다.

스톡홀름의 한 게임 스튜디오는 로컬 Qwen 3.6 인스턴스로 디자인 인턴들에게 프롬프트 엔지니어링을 교육합니다. 무료이며 오프라인에서 작동하고, 다음 게임의 세계관을 제3자에게 유출할 위험이 없습니다. 동일한 프로젝트가 단일 환경 변수 변경으로 프로덕션에서 Gemini 3 Flash를 대상으로 배포됩니다. 그들은 프로덕션 연결을 위해 Gemini 3 Flash API 가이드를 재사용합니다.

한 헬스케어 스타트업은 고객 병원 네트워크 내에서 임대한 A100에 vLLM을 실행합니다. 이 엔드포인트는 공개 DNS에 노출되지 않습니다. 그들의 통합 테스트는 동일한 VLAN 내의 Jenkins 에이전트에서 로컬에서 사용하는 것과 동일한 OpenAI SDK를 대상으로 실행됩니다. 동일한 코드, 세 가지 배포 대상, 하나의 시나리오 스위트.

결론

로컬 LLM API 스택은 빠르게 성숙했습니다. 클라이언트, 테스트 또는 CI를 재작성할 필요 없이 호스팅된 엔드포인트에서 프롬프트를 이동할 수 있습니다. 이를 실현하는 다섯 가지 단계는 다음과 같습니다:

노트북에는 Ollama를, 공유 개발 클러스터에는 vLLM을, 빠듯한 메모리 예산에는 llama.cpp를 선택하세요.
OpenAI 호환 엔드포인트를 노출하고 한 줄 curl로 확인하세요.
base_url과 api_key를 환경 변수로 이동하여 동일한 코드가 로컬 및 호스팅 환경에 모두 적용되도록 하세요.
Apidog에서 두 환경 모두에서 동일하게 실행되는 시나리오 테스트를 구축하세요.
비용-지연 시간 표를 확인하고 워크로드에 따라 적절한 대상을 선택하세요.

“로컬 AI가 표준이 되어야 한다”는 주장을 1,700점 이상으로 끌어올린 HN 신호는 이러한 성숙도의 결과입니다. API 표면이 안정화되자 모든 개발 도구가 이에 맞춰졌습니다. Apidog를 다운로드하고 http://localhost:11434/v1에 하나의 환경을 지정하여 루프가 얼마나 빨리 닫히는지 확인하십시오. 아직 모델을 선택하지 않았다면 2026년 최고의 로컬 LLM으로 시작하고, 이러한 엔드포인트 위에 에이전트 흐름을 테스트하는 방법에 대해 더 깊이 알고 싶다면 AI 에이전트 API 테스트 방법을 읽어보십시오.

button