LLM Wiki

lyogavin/airllm — 초저VRAM 대형 언어 모델 추론

Properties2
description디스크에서 레이어와 MoE 전문가를 순차 스트리밍해 단일 저용량 GPU에서 대형 오픈 LLM을 실행하는 Python 라이브러리.
tagsai-models, dev-tools, open-source, python, gpu

8 min read

개요

AirLLM은 Hugging Face 모델 체크포인트를 디스크의 레이어 샤드로 나눈 뒤, 순전파 직전에 필요한 모듈만 GPU로 옮기고 실행 후 메타 디바이스로 되돌리는 Python 추론 라이브러리다. 따라서 전체 파라미터 수가 아니라 현재 처리하는 레이어의 크기가 피크 VRAM을 좌우한다. 기본 경로는 양자화 없이 동작하며, 선택적으로 4/8비트 블록 단위 압축을 제공한다.

공식 확인

  • 레이어 스트리밍: AirLLMBaseModel은 Transformers 모델을 메타 디바이스에서 구성하고, 임베딩·각 디코더 레이어·최종 정규화·lm_head에 forward hook을 설치한다. hook이 샤드를 디스크→GPU로 로드하고 실행 뒤 해제한다.
  • MoE 전문가 스트리밍: Kimi K3 전용 구현은 한 레이어 전체가 아니라 토큰 라우터가 실제로 선택한 전문가만 개별 hook으로 로드한다. 저장소 코드 주석은 K3의 896개 전문가 중 토큰당 16개를 라우팅한다고 설명한다.
  • 자동 모델 선택: AutoModel.from_pretrained()가 Transformers 설정의 아키텍처를 확인해 표준 *ForCausalLM에는 일반 스트리밍 모델을, ChatGLM·Qwen·Baichuan·InternLM·Kimi K3 등 비표준 구조에는 전용 클래스를 선택한다.
  • 운영 옵션: 다음 레이어를 백그라운드에서 미리 읽는 prefetching, 분할 샤드 저장 위치 지정, 원본 체크포인트 삭제, gated Hugging Face 모델용 토큰, 4/8비트 압축을 지원한다. 현재 구현에서는 압축과 prefetching을 함께 사용할 수 없어 압축 시 prefetching이 비활성화된다.
  • 모델·플랫폼 범위: README는 Llama·Qwen·DeepSeek·Mistral/Mixtral·Phi·Gemma·ChatGLM·Baichuan·InternLM·Yi 계열을 지원한다고 설명한다. macOS에서는 Apple silicon과 MLX가 필요하다.

기본 사용 형태

from airllm import AutoModel
 
model = AutoModel.from_pretrained("Qwen/Qwen3-32B")
input_tokens = model.tokenizer(
    ["What is the capital of United States?"],
    return_tensors="pt",
    return_attention_mask=False,
    truncation=True,
    max_length=128,
    padding=False,
)
generation_output = model.generate(
    input_tokens["input_ids"].cuda(),
    max_new_tokens=20,
    use_cache=True,
    return_dict_in_generate=True,
)

README의 예시는 같은 API로 Qwen3-235B, DeepSeek-V3 671B 등을 지정할 수 있다고 제시한다. 첫 실행 때 원본 모델을 레이어 단위로 분해하므로 Hugging Face 캐시와 샤드 저장에 충분한 디스크 공간이 필요하다.

GitHub 실측 스냅샷

항목값
Stars / forks28,325 / 3,057
Open issues126
생성 / 최근 push2023-06-12 / 2026-07-29
라이선스Apache-2.0
GitHub primary languageJupyter Notebook
default branchmain
저장소 상태archived 아님

raw 캡처 당시(2026-08-05 06:49 KST) 수치는 28,274 stars · 3,053 forks · 125 open issues였으며, 2026-08-05 08:11 KST GitHub REST API로 라이브 값을 재확인했다. API 응답의 updated_at은 2026-08-04 23:07:56 UTC였고, pushed_at은 2026-07-29 01:08:32 UTC였다.

README의 최신 업데이트는 2026년 7월 Kimi K3 지원(저장소 측정치 3.72GB VRAM), 6월 v3.0의 FP8·DeepSeek-V3·Qwen3 지원을 강조한다. README가 제시하는 대표적인 VRAM 수치는 Llama 3.x 70B 약 4GB, Llama 3.1 405B 약 8GB, DeepSeek-V3 671B 약 12GB다. 이 수치는 저장소가 제시한 측정·설명이며 이 노트에서 독립 재현한 결과는 아니다.

인기 요인 분석

  1. 강한 한 줄 가치 제안: “70B를 4GB GPU에서”라는 메시지는 고가 GPU 없이 대형 모델을 실행하려는 사용자에게 즉시 이해된다.
  2. 모델 교체 비용이 낮다: 모델별 별도 실행 코드를 만들기보다 AutoModel.from_pretrained()에 Hugging Face ID를 넣는 동일한 표면을 제공한다.
  3. 최신 MoE 모델과 맞물린다: 전체 전문가를 상주시킬 필요 없이 선택된 전문가만 읽는 구조가 DeepSeek·Qwen·Kimi 같은 대형 MoE의 메모리 장벽을 직접 겨냥한다.
  4. 추론 최적화의 다른 축을 연다: 양자화만이 아니라 디스크 샤딩, 레이어 스트리밍, prefetching으로 VRAM과 시스템 RAM·디스크 대역폭 사이의 트레이드오프를 조정한다.
  5. 지속적인 호환성 업데이트: 2023년 초기 지원에서 2026년 FP8·Kimi K3까지 모델 생태계의 변화를 따라가며 실용적 진입점을 유지한다.

위 항목 중 1–5는 GitHub 수치와 README/코드에서 관찰한 차별점에 대한 해석이지, 프로젝트가 인과적으로 입증한 성장 요인은 아니다.

균형 잡힌 평가와 주의점

  • 낮은 VRAM은 전체 계산 비용이 낮다는 뜻이 아니다. 모델을 디스크에서 반복적으로 읽으므로 디스크 용량·IOPS·CPU RAM·PCIe/메모리 전송 속도가 지연시간과 처리량의 병목이 될 수 있다.
  • README의 “최대 3배 속도 향상”, “거의 무시할 수 있는 정확도 손실”, 대형 모델의 VRAM 수치는 이 저장소가 제시한 주장이다. 모델 버전, dtype, 입력 길이, 저장장치, GPU에 따른 독립 벤치마크는 별도 확인이 필요하다.
  • gated 모델은 Hugging Face 토큰이 필요할 수 있고, Kimi K3는 README 기준 compressed-tensors, flash-attn, CUDA 12 빌드의 PyTorch, transformers 4.56.x 같은 별도 조건이 있다.
  • 일반적인 표준 Transformers 아키텍처는 generic 경로를 타지만, remote code·Transformers 버전·특수 모듈 구조에 따라 호환성 문제가 생길 수 있다. trust_remote_code와 모델 출처를 운영 환경에서 검토해야 한다.

관련 노트

  • moc-ai-models — 모델 아키텍처와 로컬 추론 관련 MOC
  • llama-cpp — 소비자 하드웨어에서 LLM을 실행하는 또 다른 로컬 추론 엔진
  • local-llm — 로컬 LLM 실행 생태계 개요
  • kimi-k3 — AirLLM이 per-expert streaming 대상으로 추가한 대형 MoE 모델

출처 및 검증

  • canonical source: https://github.com/lyogavin/airllm
  • raw capture: raw source: github-lyogavin-airllm
  • 캡처 브랜치: main (GitHub REST API에서 default_branch 확인 후 README와 선택 소스 파일을 가져옴)
  • raw body SHA-256: c0b20251b977c290c72630680325b4eeb9639faa0abd97b38816f905002fd83b
  • 선택 구현 파일: air_llm/airllm/airllm_base.py, air_llm/airllm/auto_model.py, air_llm/airllm/airllm_kimi_k3.py
  • post-write normalization: raw capture hook이 README 외부 이미지 1건을 raw/articles/assets/ 경로로 바꾸었고, 그 최종 저장 body 기준으로 해시를 재계산했다.
  • 검증 범위: 저장소 메타데이터, default branch README, 선택 구현 파일, 2026-08-05 08:11 KST 라이브 GitHub REST API 재조회, 내부 위키 링크 및 raw body 해시. 실제 모델 실행·벤치마크는 이 저장 세션에서 수행하지 않았다.

백링크