로컬 AI 가이드

사기 전에 속도와 비용부터

실행 프로그램과 확장

최종 업데이트

SGLang HiCache: 반복 문서의 KV를 GPU·CPU·저장장치에 나누기

SGLang으로 로컬 LLM 서버를 열고 반복 입력을 빠르게 처리하기

SGLang은 모델을 실행해 API1로 받은 질문에 답변을 생성하는 LLM2 서버 프로그램이에요. 같은 지침이나 문서를 다시 입력하면 앞서 계산한 상태를 캐시에서 재사용해 첫 답변까지의 대기를 줄일 수 있어요. 서버 연결부터 확인한 뒤 HiCache로 GPU3 메모리(L1)·호스트 메모리(L2)·지원 저장장치(L3)에 캐시를 나눠 보관하는 방법을 살펴봐요.

같은 저장소를 반복해서 설명하는 코드 도우미에서는 시스템 지침과 앞선 코드가 매번 같을 수 있어요. HiCache를 쓰면 그 공통 입력을 처리한 KV 상태를 GPU 바깥에도 보관해 다시 활용할 수 있어요. 새 코드나 문서가 들어오는 첫 요청과 반복 질문은 나눠 비교해야 해요.

목차
실행 조건과 핵심 내용
  • L1은 GPU, L2는 호스트 메모리, L3는 연결된 storage backend예요.
  • SGLang 0.5.13 이후 UnifiedTree 경로는 SWA·Mamba hybrid cache도 다루지만 조합별 지원을 확인해요.
  • 같은 prefix, 새 문서, eviction 뒤 복원을 나눠 TTFT와 IO를 기록해요.

Spark·PC·Mac은 서로 다른 설치 경로예요

일반 NVIDIA 서버의 SGLang은 Linux·CUDA4·PyTorch5와 호환 GPU 커널6이 함께 맞아야 해요. 기존 Python 환경에 덮어 설치하지 말고 별도 환경을 마련해 버전을 기록해요. DGX Spark는 ARM64 CPU7와 Blackwell GPU를 지원하는 빌드가 필요하므로 x86 설치 이미지를 그대로 가져오지 않아요.

Mac에서는 SGLANG_USE_MLX=1을 사용하는 MLX8 실행 경로를 따로 준비해요. MLX 형식의 모델과 지원 기능을 확인하고 시작해요. 이미지·영상용 Diffusion은 MPS를 사용하는 별도 경로예요. 설치 안내를 고를 때 텍스트 LLM용인지 Diffusion용인지 먼저 구분해요.

작은 모델로 서버와 API 연결을 먼저 확인해요

추가 가속을 켜기 전에 Qwen2.5-0.5B-Instruct로 질문에 응답하는지 확인해요. 문맥 상한 4096과 동시 요청 하나는 연결 점검 조건이지 최고 속도 설정이 아니에요. 모델 파일을 처음 받는 시간은 서버 준비와 추론 응답에서 따로 기록해요.

서버에서 모델 준비가 끝난 뒤 curl로 짧은 질문을 보내요. 127.0.0.1은 이 컴퓨터 안에서 쓰는 주소이고 앱에는 OpenAI 호환 endpoint http://127.0.0.1:30000/v1을 지정할 수 있어요. 답이 오면 통신 기준선이 생긴 것이며 대형 모델의 품질이나 속도는 별도로 확인해요.

NVIDIA CUDA 서버 시작
python3 -m sglang.launch_server \
  --model-path Qwen/Qwen2.5-0.5B-Instruct \
  --host 127.0.0.1 --port 30000 \
  --context-length 4096 --max-running-requests 1
NVIDIA 장비에 맞는 SGLang 설치 후 연결을 확인하는 예제예요.
로컬 서버에 짧은 질문 보내기
curl --fail-with-body http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen2.5-0.5B-Instruct","messages":[{"role":"user","content":"Explain what a local AI server does in two sentences."}],"max_tokens":64,"temperature":0}'
서버와 요청의 모델 이름을 맞춰요. 공개 예문이라 개인 문서는 필요하지 않아요.
가속 설정 없이 작은 모델의 서버 응답을 확인하는 개념 장면
서버가 응답하는 최소 구성부터 확인해요.

Radix cache와 HiCache는 공통 prefix를 재사용해요

첫 코드 요청은 시스템 지침과 코드를 읽어 KV cache9를 만들어요. 같은 대화에서 테스트 결과만 추가하고 앞 내용이 일치하면 Radix cache가 공통 prefix 상태를 재사용할 수 있어요. 코드나 지침이 달라지는 만큼 일치하는 prefix가 짧아지고, 완전히 새 문서는 새 prefill10이 필요해요.

HiCache는 이 계산 상태를 GPU 메모리 밖의 호스트 메모리와 저장장치에도 보관해요. GPU에 여유가 줄어도 재사용할 상태를 다른 계층에 남길 수 있어요. 모델 가중치는 모델을 실행하는 자리에서 사용하고, 캐시에는 이미 읽은 입력의 계산 결과를 저장해요.

같은 코드 질문의 반복 입력과 새 문서 입력을 비교하는 개념 장면
새 입력과 반복 입력은 cache 효과가 달라 따로 비교해요.

GPU·호스트 메모리·저장장치 계층을 구분해요

HiCache의 L1은 GPU 메모리, L2는 host memory, L3는 파일 또는 외부 storage backend예요. GPU에 남은 상태는 빠르게 재사용되지만 자리가 부족하면 host tier로 밀려날 수 있어요. L3에 파일이 보존돼도 다음 요청에서 prefix key와 모델 조건이 맞아야 재사용돼요.

CPU tier는 저장 자리를 늘리지만 host 대역폭과 전송이 추가되고, 파일 backend는 NVMe11 read와 페이지 캐시, 인덱스 관리가 요청 경로에 들어와요. 전원 종료 뒤 파일이 남는 것과 즉시 cache hit가 되는 것은 달라요.

SGLang 0.5.20은 UnifiedTree의 SWA·Mamba hybrid HiCache 지원을 소개하고, 해당 hybrid 경로의 기본 연결 변경은 0.5.13에 기록돼 있어요. 이는 모든 모델·하드웨어·저장 backend 조합이 호환된다는 뜻은 아니므로 실제 architecture 지원을 확인해요.

host cache 기준으로 시작하고 상태를 확인해요

아래 구성은 NVIDIA CUDA의 SGLang 0.5.20과 openai/gpt-oss-20b를 사용하는 연결 기준이에요. GPU 메모리가 모델을 감당하는지 공식 모델 카드와 지원 문서에서 먼저 확인해요. 문맥 8192와 동시 요청 하나는 연결 점검값이에요. --enable-hierarchical-cache와 --hicache-ratio 2를 설정해도 비율이 데이터 크기 두 배를 보장하지 않으므로 시작 로그에서 실제 pool을 봐요.

서버가 뜨면 /health와 같은 모델 ID의 chat completion을 확인해요. 첫 답변과 cold 상태는 별도 기록하고, 모델 로드·cache pool·CUDA 초기화 로그를 확인해요. 이 요청은 속도 측정이 아니므로 파일 tier나 동시 요청을 한꺼번에 추가하지 않아요.

host cache 서버를 시작하기 전, 앞의 기본 서버를 실행한 터미널에서 Ctrl+C로 종료하세요. 두 예제는 같은 30000 포트를 사용해요. 새 서버의 모델과 캐시 풀이 준비되면 다른 터미널에서 아래 상태 조회와 질문을 보내요.

NVIDIA CUDA host cache 서버 시작
python -m sglang.launch_server --model-path openai/gpt-oss-20b --host 127.0.0.1 --port 30000 --context-length 8192 --max-running-requests 1 --enable-hierarchical-cache --hicache-ratio 2 --hicache-io-backend kernel --hicache-mem-layout page_first
SGLang 0.5.20 NVIDIA CUDA 예제예요. 설치 빌드의 옵션과 모델 지원을 확인해요.
준비 상태와 같은 모델의 짧은 질문 확인
curl -sS http://127.0.0.1:30000/health
curl -sS http://127.0.0.1:30000/v1/chat/completions -H 'Content-Type: application/json' -d '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"Review this Python function for empty-list input and suggest a minimal fix: def first_item(items): return items[0]"}],"temperature":0,"max_tokens":96,"stream":false}'
서버가 준비되면 loopback으로 연결해요. 이 요청은 기능 확인이지 속도 측정이 아니에요.
동작한 버전과 실행 조건을 기록해 다음 변경 전 기준으로 보관하는 작업대
정상 동작한 버전과 조건은 복구 기준으로 남겨요.

같은 prefix·새 문서·eviction 복원을 나눠 기록해요

첫 함수 요청 뒤 같은 대화에 테스트 로그 한 줄만 더해 질문해요. cache 통계에서 hit token12이나 재사용 prefix를 확인하고, 완전히 다른 함수·로그를 보내는 새 입력 조건과 비교해요. 입력 길이가 달라지면 계산량도 달라지므로 서로 다른 요청의 완료 시간만 비교하지 않아요.

파일 tier를 시험할 때는 별도 NVMe 경로를 쓰고 SGLang file backend가 실제로 연결됐는지 확인해요. SGLANG_HICACHE_FILE_BACKEND_STORAGE_DIR은 캐시 파일 위치를 지정하며 모델 다운로드 폴더나 OS swap 경로가 아니에요.

cold와 warm 요청을 나눠 시험하고, GPU에서 밀려난 상태를 복원한 뒤와 eviction 후 다시 요청한 경우도 기록해요.

NVMe read, 페이지 캐시, cache key 일치 여부를 확인해요. hit 통계가 확인돼야 storage tier에서 상태를 재사용했다고 판단할 수 있어요.

파일 tier는 host cache 서버의 설정을 바꾸어 재시작하는 시험이에요. 기존 서버를 Ctrl+C로 종료한 뒤 캐시 디렉터리를 지정하고 아래 명령을 실행하세요. 재시작 후 첫 요청과 같은 입력을 다시 보낸 요청을 각각 기록하면 캐시가 재사용되는 구간을 비교할 수 있어요.

NVMe file tier 추가
mkdir -p /mnt/nvme/sglang-hicache
export SGLANG_HICACHE_FILE_BACKEND_STORAGE_DIR=/mnt/nvme/sglang-hicache
python -m sglang.launch_server --model-path openai/gpt-oss-20b --host 127.0.0.1 --port 30000 --context-length 8192 --max-running-requests 1 --enable-hierarchical-cache --hicache-ratio 2 --hicache-io-backend kernel --hicache-mem-layout page_first --hicache-storage-backend file
쓰기 가능한 NVMe 디렉터리로 바꿔요. OS swap과 별도인 SGLang backend 경로예요.

hybrid attention의 SWA·Mamba 상태도 확인해요

GPT-OSS처럼 sliding-window attention13을 포함한 모델은 전체 토큰의 상태를 한 방식으로 재사용하지 않아요. FULL attention prefix가 남아도 window에 필요한 상태가 부족하면 같은 prefix를 그대로 hit로 쓸 수 없어요. SGLang의 UnifiedTree는 hybrid 요소를 관리하고 0.5.20에서 SWA·Mamba hybrid HiCache를 설명하지만, 모든 모델·backend에서 보장되는 조합은 아니에요.

새 prefix·같은 prefix·eviction 뒤 재질문을 나눠 문맥 길이·cache hit·TTFT14·완료 시간·host RAM15·NVMe IO를 기록해요. GPU에 이미 남은 warm cache와 L3에서 다시 읽은 요청도 분리해요.

HiCache와 MTP·NGRAM은 다른 기능이에요

MTP16는 모델이 다음 토큰 후보를 제안하는 생성 가속이고, NGRAM17 speculative decoding18은 앞선 토큰에서 후보를 찾는 생성 경로예요. PLE19 offload20는 큰 임베딩 테이블을 RAM·SSD21에 두는 저장·적재 방식이에요. HiCache는 공통 prefix 계산 상태를 보관해 재사용하므로 세 기능의 설정을 한꺼번에 묶지 않아요.

SGLang에서 MTP speculative 설정을 쓴다면 모델에 맞는 algorithm·depth·width가 필요해요. NEXTN은 EAGLE의 별칭으로 문서에 쓰이지만 모든 Qwen·Gemma·GLM 파일이 같은 명령을 지원한다는 뜻은 아니에요. 버전과 모델별 지원을 확인하고 기능을 하나씩 켜요.

Radix cache의 입력 재사용과 MTP·NGRAM의 후보 검증은 서로 다른 단계예요. 두 번째 요청이 빨랐다는 사실만으로 어느 기능이 작동했는지 알 수 없으니, 통계와 응답 구간을 기능별로 나눠 비교하세요.

사용 중인 버전의 공식 지원 자료를 기록해요

SGLang 0.5.13·0.5.20 릴리스와 HiCache 설계 문서에서 설치 및 지원 조건을 확인해요. 재현할 때 모델 ID와 SGLang 버전, GPU·backend도 함께 적어요.

용어 각주

  1. API — 프로그램의 기능을 다른 코드에서 호출하기 위한 약속된 인터페이스입니다.

    본문으로 돌아가기

  2. 대규모 언어 모델 — 대규모 텍스트 데이터에서 언어 패턴을 학습해 문맥에 맞는 텍스트를 처리하고 생성하는 모델입니다.

    본문으로 돌아가기

  3. GPU — 많은 계산을 병렬로 처리하는 프로세서입니다. AI 모델 실행에서는 모델 계산을 맡습니다.

    본문으로 돌아가기

  4. CUDA — NVIDIA GPU에서 범용 계산을 실행하기 위한 소프트웨어 플랫폼입니다.

    본문으로 돌아가기

  5. PyTorch — AI 모델을 만들고 실행하는 소프트웨어 프레임워크입니다. 모델과 함께 호환되는 PyTorch 버전 및 하드웨어 지원도 확인해야 합니다.

    본문으로 돌아가기

  6. GPU 커널 — GPU에서 병렬 실행되는 연산 코드로, 행렬 곱셈이나 정규화 같은 작업을 수행합니다.

    본문으로 돌아가기

  7. CPU — 운영체제와 일반 프로그램 명령을 실행하고, AI에서는 전처리·데이터 이동 등 범용 연산을 맡는 중앙 처리 장치입니다.

    본문으로 돌아가기

  8. MLX — Apple이 개발하는 머신러닝 프레임워크로, Apple Silicon의 CPU와 GPU가 공유하는 메모리를 활용해 모델을 실행합니다.

    본문으로 돌아가기

  9. KV 캐시 — 어텐션에서 이전 토큰의 키·값을 저장해 다음 토큰 생성 때 재사용하는 메모리입니다. 문맥 길이와 배치 크기에 따라 용량이 달라집니다.

    본문으로 돌아가기

  10. 프리필 — LLM이 입력 프롬프트를 읽고 각 토큰의 내부 표현을 계산하는 단계입니다. 입력이 길수록 처리할 토큰이 많아집니다.

    본문으로 돌아가기

  11. NVMe — SSD가 PCI Express를 통해 통신할 때 사용하는 저장 장치용 프로토콜입니다.

    본문으로 돌아가기

  12. 토큰 — 모델이 입력이나 출력을 나누어 처리하는 단위입니다.

    본문으로 돌아가기

  13. 어텐션 — 입력 토큰 사이의 관련도를 계산해 각 위치의 정보를 현재 표현에 반영하는 신경망 연산입니다.

    본문으로 돌아가기

  14. 첫 토큰 지연 — 요청을 보낸 뒤 첫 출력 토큰이 도착하기까지 걸린 시간입니다.

    본문으로 돌아가기

  15. 시스템 RAM — 프로그램이 실행되는 동안 데이터를 임시로 보관하는 시스템 메모리입니다.

    본문으로 돌아가기

  16. MTP — 한 번에 여러 미래 토큰을 예측하도록 학습하는 목표 또는 이를 수행하는 모델 구성입니다. 추측 디코딩에서는 이 예측을 후보 토큰으로 제안할 수 있습니다.

    본문으로 돌아가기

  17. n-그램 — 연속된 n개의 토큰 또는 항목으로 이루어진 구간입니다. 문맥 조회·추측 생성에 쓰일 수도 있고, 일부 모델에서는 임베딩 테이블의 구성 단위로도 쓰입니다.

    본문으로 돌아가기

  18. 추측 디코딩 — 초안 모델·MTP 헤드·반복 문맥 조회가 출력 후보를 먼저 만들고, 본 모델이 후보를 검증해 확정하는 생성 기법입니다.

    본문으로 돌아가기

  19. PLE 임베딩 테이블 — Per-Layer Embedding의 약자로, 모델의 특정 층에 임베딩 정보를 더하는 구조입니다. Qwen Flash-Next 계열은 n-그램 테이블을 사용하며, 지원되는 실행 경로에서는 이 테이블을 RAM이나 SSD로 오프로딩할 수 있습니다.

    본문으로 돌아가기

  20. 오프로딩 — 메모리가 부족할 때 모델 데이터 일부를 GPU 메모리에서 시스템 RAM이나 저장장치로 옮겨 처리하는 방식입니다. 데이터 이동이 추가됩니다.

    본문으로 돌아가기

  21. SSD — 플래시 메모리를 사용하는 데이터 저장 장치입니다. 전원이 꺼져도 데이터가 보존됩니다.

    본문으로 돌아가기

자주 묻는 질문

이 글에서 가장 먼저 확인할 것은 무엇인가요?
SGLang은 모델을 실행해 API로 받은 질문에 답변을 생성하는 LLM 서버 프로그램이에요. 같은 지침이나 문서를 다시 입력하면 앞서 계산한 상태를 캐시에서 재사용해 첫 답변까지의 대기를 줄일 수 있어요. 서버 연결부터 확인한 뒤 HiCache로 GPU 메모리(L1)·호스트 메모리(L2)·지원 저장장치(L3)에 캐시를 나눠 보관하는 방법을 살펴봐요.
필요한 메모리는 어느 정도인가요?
HiCache는 이 계산 상태를 GPU 메모리 밖의 호스트 메모리와 저장장치에도 보관해요. GPU에 여유가 줄어도 재사용할 상태를 다른 계층에 남길 수 있어요. 모델 가중치는 모델을 실행하는 자리에서 사용하고, 캐시에는 이미 읽은 입력의 계산 결과를 저장해요.
조건과 출처는 어디서 확인하나요?
아래 구성은 NVIDIA CUDA의 SGLang 0.5.20과 openai/gpt-oss-20b를 사용하는 연결 기준이에요. GPU 메모리가 모델을 감당하는지 공식 모델 카드와 지원 문서에서 먼저 확인해요. 문맥 8192와 동시 요청 하나는 연결 점검값이에요. --enable-hierarchical-cache와 --hicache-ratio 2를 설정해도 비율이 데이터 크기 두 배를 보장하지 않으므로 시작 로그에서 실제 pool을 봐요.
수정 내역

사이트의 안내가 바뀐 기록입니다. 설치된 엔진·모델 버전을 자동으로 확인한 결과는 아닙니다.

  1. SGLang 캐시·모델별 옵션 안내 추가

    로컬 서버 연결 예제와 프리필·디코드 단계별 메모리 조정 순서를 추가했습니다. 반복 입력의 캐시 효과를 분리하고, NGRAM 후보 검색과 PLE 테이블의 RAM·SSD 배치를 다른 기능으로 설명했습니다.