Mesh LLM: distributed AI computing on iroh

TL;DR Highlight

사무실, 집, 클라우드에 흩어진 GPU들을 하나의 OpenAI 호환 API로 묶어주는 분산 LLM 실행 시스템으로, 비싼 API 비용 없이 큰 모델을 직접 운영할 수 있다.

Who Should Read

GPU가 여러 대 있는데 대형 모델을 혼자 돌리기엔 VRAM이 부족한 팀이나, OpenAI API 비용을 줄이고 데이터 프라이버시를 직접 통제하고 싶은 ML 인프라 담당 개발자.

Core Mechanics

Mesh LLM은 여러 머신의 GPU와 메모리를 묶어 하나의 OpenAI 호환 API(http://localhost:9337/v1)로 노출한다. 기존 OpenAI 클라이언트 코드를 그대로 써도 되고, 실제 추론이 어느 머신에서 일어나는지 신경 쓸 필요가 없다.
요청 처리 방식은 세 가지다. 로컬 GPU에서 직접 실행하거나, 이미 해당 모델을 올려둔 피어 노드로 라우팅하거나, 단일 머신에 올리기 너무 큰 모델은 여러 노드에 레이어 단위로 쪼개서 파이프라인으로 실행한다.
거대 모델 분산 실행 기능은 내부적으로 'Skippy'라고 부른다. 모델의 레이어를 범위별로 쪼개서 각 노드에 배분하고(예: 0~15레이어는 노드A, 16~31레이어는 노드B), 중간 활성화(activation) 값이 다음 스테이지로 흘러가는 파이프라인 구조다.
네트워킹 레이어는 iroh를 사용한다. iroh는 공개키 기반 신원, NAT 통과(hole-punching), QUIC 연결을 제공하는 P2P 네트워킹 라이브러리로, 중앙 서버 없이 어떤 두 노드 사이에서도 인증된 직접 연결을 만든다.
프로토콜은 QUIC의 ALPN 협상 위에서 세 채널을 사용한다. mesh-llm/1은 가십(peer 상태 공유), 라우팅, HTTP 터널 등 메인 메시용이고, mesh-llm-control/1은 설정 동기화 제어용, skippy-stage/2는 분산 모델의 레이어 간 활성화 전송용 저지연 채널이다.
하나의 QUIC 연결 안에서 스트림 첫 바이트 하나로 트래픽 종류를 구분한다. 0x01은 GOSSIP(피어 공지), 0x04는 TUNNEL_HTTP(추론 요청 프록시), 0x05는 ROUTE_REQUEST(모델 보유 쿼리) 등 8가지 스트림 타입이 한 연결을 공유한다.
기본 카탈로그에 40개 이상의 모델이 포함되어 있다. 노트북에서 돌릴 수 있는 5억 파라미터급 소형 모델부터 235B MoE(Mixture of Experts, 전체 파라미터 중 일부만 활성화하는 구조) 거대 모델까지 지원한다.
아키텍처는 플러그인 기반이다. 플러그인이 manifest로 제공 기능을 선언하면 런타임이 이를 시작하고 MCP, HTTP, 추론, 메시 이벤트로 노출한다. iroh 릴레이 서버를 두 리전에 운영해 직접 연결이 안 되는 노드도 폴백 경로를 확보했다.

Evidence

MacBook Pro 사용자가 공식 swarm 페이지의 'join' 버튼을 누르고 'mesh-llm --auto' 명령어 하나로 첫 시도에 바로 작동했다고 공유했다. 모델 선택, 피어에서 다운로드, GPU 작업 확인까지 자동으로 처리됐다며, 이렇게 매끄러운 온보딩 경험은 드물다고 언급했다.
분산 모델의 실제 속도에 대한 의문이 제기됐는데, 모델 목록에서 Qwen 235B A22B 모델이 '2개 노드에서 16 tok/s 검증됨'이라고 명시되어 있다는 게 확인됐다. 16 tok/s는 인터랙티브 대화용으로 약간 아쉬운 속도이지만 그나마 쓸 만한 수준이라는 평가가 나왔다.
네트워크 대역폭이 로컬 RAM보다 훨씬 느리기 때문에 분산 추론이 실용적이냐는 회의론도 있었다. 10Gbit 이더넷조차 로컬 메모리 대비 너무 느려서 인터랙티브 사용에는 비현실적이라는 의견이 있었고, 이는 실제로 유효한 우려로 받아들여졌다.
exo 프로젝트와의 차이점을 묻는 댓글이 있었다. exo도 Apple Silicon 기기 등 여러 머신에 모델을 분산해 실행하는 비슷한 도구인데, 두 프로젝트의 차별점에 대한 명확한 답변은 이어지지 않았다.
노드 간 페이로드 암호화 여부와 다른 사용자 요청을 읽을 수 있는지에 대한 보안 질문이 올라왔다. iroh가 공개키 기반 인증된 QUIC 연결을 쓰기 때문에 전송 구간은 암호화되지만, 해당 질문에 대한 공식 답변은 댓글에서 확인되지 않았다.
오래된 GPU를 가진 사용자는 내장 llama.cpp 빌드가 호환되지 않아 설치에 실패했다고 보고했다. 외부 llama.cpp 서비스를 프록시로 연결하는 방법도 시도했지만 성공하지 못했다며, 아직 거친 부분이 있다고 평가했다.
AI Horde라는 유사 프로젝트를 언급한 댓글이 있었다. AI Horde는 현존하는 분산 LLM 플랫폼 중 가장 크지만 KoboldCPP 텍스트 컴플리션 API만 지원하고 채팅 컴플리션이 없어 롤플레이 외 용도로 쓰기 어렵다는 한계가 공유됐다.

How to Apply

팀 내 여러 개발자 PC나 사무실 서버에 GPU가 흩어져 있는데 큰 모델을 쓰고 싶다면, 각 머신에 mesh-llm을 설치하고 'mesh-llm --auto'로 참여시킨 뒤 기존 OpenAI 클라이언트의 base_url만 http://localhost:9337/v1로 바꾸면 된다. 코드 변경 없이 분산 GPU 풀을 하나의 API로 쓸 수 있다.
단일 머신 VRAM으로는 올릴 수 없는 235B급 MoE 모델을 실험해보고 싶다면, Skippy 분산 모드를 활용해 2개 이상의 노드에 레이어를 나눠 올릴 수 있다. Qwen 235B 기준 2노드에서 16 tok/s가 측정된 바 있으니 배치 추론이나 비실시간 태스크에 적합하다.
데이터가 외부 API로 나가면 안 되는 규제 환경(의료, 금융 등)에서 LLM을 써야 하는 경우, Mesh LLM으로 사내 GPU를 묶어 완전히 온프레미스 추론 환경을 구성할 수 있다. iroh의 공개키 기반 인증 QUIC 연결로 노드 간 통신도 사내 네트워크 안에서 처리된다.
Raspberry Pi나 저사양 임베디드 디바이스처럼 단독으로는 추론이 힘든 엣지 디바이스 군집에 소형 SLM(Small Language Model)을 분산 배포하는 실험을 하려면, Mesh LLM의 플러그인 아키텍처와 iroh의 NAT 통과 기능을 활용해 중앙 서버 없이 P2P 추론 네트워크를 구성해볼 수 있다.

Code Example

snippet

# 설치 후 자동 모드로 메시 참여 (모델 자동 선택 및 다운로드)
mesh-llm --auto

# 기존 OpenAI 클라이언트에서 Mesh LLM 엔드포인트 사용
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:9337/v1",
    api_key="not-needed"  # 로컬이므로 불필요
)

response = client.chat.completions.create(
    model="qwen-235b",  # 카탈로그에 있는 모델명
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Terminology

irohP2P 네트워킹 라이브러리로, 공개키로 기기를 식별하고 NAT(공유기) 뒤에 있는 기기들끼리도 직접 연결을 뚫어주는 역할을 한다. 중앙 서버 없이 어디서든 두 기기를 이어준다.

QUICUDP 기반의 차세대 전송 프로토콜로, TCP보다 연결 수립이 빠르고 멀티스트림을 지원해 레이턴시에 민감한 P2P 통신에 적합하다. HTTP/3의 기반이기도 하다.

ALPNTLS/QUIC 연결 시 '어떤 애플리케이션 프로토콜을 쓸 건지' 협상하는 메커니즘. 같은 포트로 여러 프로토콜을 구분해 처리할 수 있게 해준다.

NAT traversal공유기(NAT) 뒤에 있는 두 기기가 외부 서버 없이 직접 통신할 수 있도록 연결을 뚫는 기술. 일반 가정용 인터넷 환경에서 P2P 연결을 가능하게 하는 핵심 기술이다.

MoE (Mixture of Experts)거대 모델을 구성하는 방식 중 하나로, 전체 파라미터를 항상 다 쓰지 않고 입력에 따라 일부 '전문가' 서브네트워크만 활성화한다. 235B 파라미터지만 실제 추론 시 22B만 쓰는 Qwen 235B A22B가 대표 예다.

activation (활성화)신경망의 한 레이어를 통과한 중간 계산 결과값. 분산 추론에서는 이 값을 네트워크를 통해 다음 노드로 전달해 파이프라인을 이어간다.