실행 프로그램과 확장

Superfluid란? 로컬 LLM 하나로 여러 에이전트를 실행하는 방법

에이전트가 긴 문서를 읽는 동안에도 짧은 질문에 먼저 답하도록 설정할 수 있어요.

Superfluid는 내 컴퓨터의 LLM¹을 여러 앱과 에이전트가 함께 쓰도록 관리하는 서버예요. 앱이 API²로 질문을 보내면 llama.cpp나 MLX³ 같은 실행 엔진이 답변을 만들고, Superfluid가 요청 순서와 동시 처리 수를 조절해요. 문서 요약을 여러 개 돌리면서 직접 질문도 하고 싶을 때 유용해요.

실행 조건과 핵심 내용

GGUF는 llama.cpp, Apple Silicon의 MLX 모델은 MLX 엔진으로 실행해요.
채팅 요청에 `interactive` 우선순위를 주면 에이전트 작업 사이에 먼저 처리할 수 있어요.
처음에는 요청 2개·문맥 4,096토큰으로 시작하고, 메모리 여유를 확인하며 늘려요.

여러 앱이 모델 하나를 함께 쓰려면

문서 세 개를 각 에이전트에 맡겨 요약한다고 해볼게요. 그동안 채팅 창에서 짧은 질문을 보내면, 이미 들어온 긴 입력 뒤에서 기다릴 수 있어요. 이때 필요한 것은 답변을 만드는 모델과 함께 요청을 나눠 처리하는 서버예요.

Superfluid는 여러 요청을 묶어 처리하고, 급한 채팅을 먼저 처리할 우선순위를 제공해요. 에이전트들이 같은 지시문이나 문서 앞부분을 반복해서 보내면 계산해둔 프리픽스 캐시도 활용해요. 모델을 앱마다 따로 실행하는 대신 하나의 서버 주소를 함께 쓰는 방식이에요.

OpenAI·Anthropic·Ollama 형식의 API를 지원해 기존 연결 앱에서도 사용할 수 있어요. 여기서는 OpenAI 호환 API로 짧은 질문을 보내는 것부터 시작하고, 그다음 채팅과 에이전트의 우선순위를 나눠볼게요.

Superfluid 프로젝트

노트북 화면의 채팅·코드·폴더 창과 하나의 모델 블록 — 여러 앱의 질문을 하나의 로컬 서버로 모아 처리해요.

Mac은 MLX나 GGUF, Linux는 GGUF로 시작해요

Superfluid가 모델 형식에 맞는 실행 엔진을 선택해요. GGUF⁴ 파일은 llama.cpp로, Apple Silicon에서 MLX 형식의 모델을 고르면 MLX로 실행합니다. 이미 내려받은 모델 파일이나 폴더도 지정할 수 있어요.

Apple Silicon Mac은 Metal⁵과 MLX 경로를 사용할 수 있어요. Linux x86-64에서는 llama.cpp의 CUDA⁶·ROCm⁷·Vulkan·CPU⁸ 경로가 제공됩니다. Windows용 설치 절차는 아직 준비돼 있지 않아 이 글은 Mac과 Linux를 대상으로 설명해요.

프로그램을 설치한 뒤 모델 가중치와 대화 캐시를 담을 메모리를 남겨두세요. Qwen3.8-27B의 Q4 파일을 쓰려면 현재 장비에서 그 모델이 실행되는지 먼저 확인하는 편이 좋아요. 모델 적재부터 막힌다면 Qwen3.8-27B 실행 가이드에서 메모리와 파일 형식을 먼저 맞추세요.

모델 형식에 맞춰 고르는 실행 엔진
형식	엔진	시작할 때
GGUF	llama.cpp	Mac·Linux에서 GGUF 파일 지정
MLX	MLX	Apple Silicon에서 MLX 폴더 지정
.base	baseRT	별도 엔진과 해당 번들 준비

Qwen3.8-27B 서버를 열고 첫 답변을 받아요

설치 문서의 Mac·Linux 절차로 Superfluid를 설치한 뒤 터미널에서 아래 명령을 실행하세요. 먼저 버전을 출력하고, Qwen3.8-27B의 UD-Q4_K_M 파일을 요청 2개·문맥 4,096토큰⁹으로 실행해요. 첫 실행은 모델과 llama.cpp 엔진을 내려받으므로 인터넷 연결과 저장공간이 필요해요.

서버가 준비되면 다른 터미널에서 상태와 모델 목록을 조회해요. `/health`의 `status`가 `ok`이고 `/v1/models`에 모델이 있으면 질문을 보낼 준비가 된 거예요. 요청의 모델 이름에는 양자화¹⁰ 태그인 `:UD-Q4_K_M`을 붙이지 않아요.

답변이 오면 연결 앱의 API 주소를 `http://127.0.0.1:8453/v1`로 바꿔 같은 모델을 선택하세요. 이 예제는 같은 컴퓨터 안에서만 접속할 수 있는 주소를 사용해요. 앱이 API 키 입력을 요구하면 키 없는 로컬 서버에는 임의의 자리표시자를 입력할 수 있어요.

터미널 1 — 서버 시작

superfluid --version
superfluid serve unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_M --http 127.0.0.1:8453 --max-batch 2 --max-context 4096

서버를 실행한 터미널은 그대로 두고, 다음 요청은 새 터미널에서 보내세요.

터미널 2 — 상태 확인과 질문

curl -sS http://127.0.0.1:8453/health
curl -sS http://127.0.0.1:8453/v1/models
curl -sS http://127.0.0.1:8453/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"unsloth/Qwen3.8-27B-GGUF","messages":[{"role":"user","content":"Explain prefix caching in two sentences."}],"max_tokens":128}'

응답의 `choices`에서 생성한 답변을 읽을 수 있어요.

빠른 실행·API 연결

터미널이 열린 노트북과 작은 컴퓨터 옆의 메모리 블록 — 모델 가중치에 더해 동시에 처리할 대화의 캐시 공간도 남겨두세요.

직접 하는 질문을 에이전트 작업보다 먼저 처리해요

연결이 됐다면 채팅과 자동 작업의 우선순위를 나눠보세요. Superfluid는 기본 HTTP 요청을 `agent`로 처리해요. 직접 보낸 질문에는 `x-superfluid-qos: interactive` 헤더를 붙이고, 급하지 않은 일괄 요약에는 `background`를 붙일 수 있어요.

모든 처리 자리가 에이전트로 차 있어도, 더 높은 우선순위의 질문이 들어오면 낮은 우선순위 작업을 잠시 멈추고 채팅부터 처리할 수 있어요. 채팅 답변 뒤에는 대기하던 작업이 이어집니다. 일반 채팅 앱이 사용자 지정 헤더를 지원하지 않는다면 앱의 연결 설정을 확인하거나 API 요청으로 먼저 시험하세요.

공통 지시문은 매번 같은 순서로 앞에 배치하면 프리픽스 캐시를 활용하기 좋아요. 문서와 질문을 무작위로 섞기보다 공통 안내·공통 문서·개별 질문 순서를 유지하세요. 반복 질문이 빨라지는지 확인할 때는 같은 문서를 다시 보내고 첫 글자가 나타날 때까지 걸린 시간을 비교하면 돼요.

채팅 요청에 우선순위 지정

curl -sS http://127.0.0.1:8453/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'x-superfluid-qos: interactive' \
  -d '{"model":"unsloth/Qwen3.8-27B-GGUF","messages":[{"role":"user","content":"Reply with one short sentence."}],"max_tokens":64,"stream":true}'

급하지 않은 작업은 같은 헤더 값을 `background`로 바꿔 보낼 수 있어요.

스케줄링·우선순위

노트북의 채팅 창과 우선순위별로 나뉜 작업 카드 쟁반 — 직접 묻는 질문은 먼저 처리하고, 뒤에서 도는 작업은 잠시 기다리게 할 수 있어요.

동시에 처리한 전체 속도와 답변 하나의 속도를 나눠 읽어요

요청을 더 많이 묶으면 일정 시간에 완료하는 전체 토큰은 늘 수 있어요. 여러 답변을 동시에 만들기 때문에 각 답변이 이어지는 속도도 함께 비교해야 하죠. 문서 요약 묶음을 빨리 끝내고 싶은지, 내가 읽는 답변을 빠르게 받고 싶은지에 따라 설정이 달라져요.

Superfluid의 llama.cpp 경로 · 동시 요청별 처리량
동시 요청	전체 tok/s	요청별 평균 tok/s
1	76.7	76.7
2	87.6	43.8
4	126.5	31.6
8	150.8	18.9

공개 측정 · 2026-10-06 · M1 Max 64GB · Qwen3-4B Q4_K_M · llama.cpp b11284 · 요청별 256토큰 출력 · temperature 0 · 서로 다른 입력 · 3회 중앙값. 표의 요청별 값은 전체 처리량¹¹을 동시 요청 수로 나눈 평균이에요. 측정 조건과 전체 결과

이 비교에서는 동시 요청을 1개에서 8개로 늘리자 전체 처리량은 76.7에서 150.8 tok/s로 늘었어요. 요청 하나가 받는 평균은 76.7에서 18.9 tok/s로 줄었죠. 혼자 쓰는 채팅은 동시 요청 수를 낮게 시작하고, 자동 요약을 여러 개 처리할 때는 완료 시간을 비교하며 늘리는 편이 좋아요.

메모리가 부족하거나 연결이 안 되면

모델을 불러오지 못한다면 먼저 `superfluid runtimes`로 엔진의 상태와 장치 경로를 확인하세요. 내려받은 GGUF 파일로 시작할 때는 파일 경로를 모델 이름 대신 지정할 수 있어요. 다운로드는 끝났는데 메모리 부족으로 멈추면 동시 요청 수를 1개로 낮추고 문맥 4,096토큰에서 다시 실행하세요.

API 접속이 안 된다면 `/health`부터 조회하세요. 상태 조회는 되지만 채팅 앱에서 실패하면 주소 끝의 `/v1`과 모델 목록의 ID를 다시 맞춰요. 이미 8453 포트를 쓰는 프로그램이 있다면 `--port 8455`로 바꾸고 연결 앱의 주소도 같은 포트로 변경하세요.

내 컴퓨터 안에서만 쓸 때는 `127.0.0.1`을 유지하세요. 다른 기기와 공유하려면 API 키와 HTTPS 연결을 먼저 준비해야 해요. 입력과 답변은 기본적으로 `~/.superfluid/sessions`에 저장되므로 민감한 문서를 처리할 때는 해당 폴더의 접근 권한과 백업 대상을 함께 관리하세요.

Superfluid는 현재 1.0 이전 단계예요. 중요한 자동 작업은 기존 서버 구성을 남겨둔 채 별도 포트에서 시험하고, 앱 연결·긴 문서·동시 요청 순서로 늘려보세요. 에이전트 자체를 처음 설치한다면 로컬 AI 에이전트¹² 시작 가이드를 먼저 읽고, 맥용 관리 화면이 필요하면 oMLX 가이드도 비교해보세요.

용어 각주

대규모 언어 모델 — 대규모 텍스트 데이터에서 언어 패턴을 학습해 문맥에 맞는 텍스트를 처리하고 생성하는 모델입니다.
본문으로 돌아가기
API — 프로그램의 기능을 다른 코드에서 호출하기 위한 약속된 인터페이스입니다.
본문으로 돌아가기
MLX — Apple이 개발하는 머신러닝 프레임워크입니다. Apple silicon에서는 통합 메모리와 Metal을 활용하며, 별도로 Linux 실행 경로도 제공합니다. 지원 모델과 기능은 MLX 기반 도구마다 다릅니다.
본문으로 돌아가기
GGUF — 모델 정보를 담는 파일 형식으로 llama.cpp 계열 도구에서 널리 사용됩니다.
본문으로 돌아가기
Metal — Apple 기기에서 그래픽과 GPU 병렬 계산을 실행하는 저수준 기술입니다.
본문으로 돌아가기
CUDA — NVIDIA GPU에서 범용 계산을 실행하기 위한 소프트웨어 플랫폼입니다.
본문으로 돌아가기
ROCm — AMD GPU에서 AI와 고성능 계산을 실행하는 소프트웨어 플랫폼입니다. 지원 여부는 GPU 모델뿐 아니라 운영체제·드라이버·프레임워크 버전의 조합으로 확인합니다.
본문으로 돌아가기
CPU — 운영체제와 일반 프로그램 명령을 실행하고, AI에서는 전처리·데이터 이동 등 범용 연산을 맡는 중앙 처리 장치입니다.
본문으로 돌아가기
토큰 — 모델이 입력이나 출력을 나누어 처리하는 단위입니다.
본문으로 돌아가기
양자화 — 모델의 가중치나 계산값을 더 적은 비트로 표현해 저장 공간과 메모리 사용량을 줄이는 방법입니다. 표현 단계가 거칠어져 정확도에도 영향을 줄 수 있습니다.
본문으로 돌아가기
처리량 — 일정 시간 동안 처리하거나 생성한 작업량입니다. 토큰/초, 요청/초처럼 단위를 함께 확인해야 비교할 수 있습니다.
본문으로 돌아가기
AI 에이전트 — 목표를 받아 사용할 도구를 선택하고, 실행 결과를 확인해 다음 작업을 이어 가는 프로그램 구성입니다. 수행 범위는 연결된 도구와 부여된 권한으로 정해집니다.
본문으로 돌아가기