개발 이야기2026년 11월 9일

KT 클라우드 H200 vLLM 사용기

최근 회사에서 AI Agent를 개발하는 일이 많아졌다.

회사에서 Agent를 개발하면서 KT 클라우드에서 제공받은 H200 서버를 쓰고 있다. 여기에 오픈 모델을 올려 두면 Agent가 API로 질문을 보낸다. 그동안 나는 주로 Agent가 어떤 도구를 쓰고, 가져온 자료를 어떻게 확인해 답변할지에 집중했다. 모델 서버 쪽은 주소를 받아 연결하면 됐기 때문에 실행 설정까지 자세히 볼 일이 많지 않았다.

그러다 조회 도구를 붙이면서 문제가 생겼다. 평범한 질문에는 답하던 서버가 도구 목록과 함께 도구 선택을 요청하면 HTTP 400을 돌려줬다. 처음에는 프롬프트나 모델부터 살펴봤는데, 확인해 보니 모델 앞에서 요청을 받는 vLLM의 실행 설정도 봐야 했다.

생각해 보면 속도가 아쉬웠던 때도 마찬가지다. 모델이 느리다고만 생각했지, GPU 메모리가 어떻게 나뉘어 있고 요청이 어디서 기다리는지는 제대로 보지 않았다. H200까지 쓰면서 그 위에서 모델이 어떻게 돌아가는지 이제야 공부하고 있다니... 조금 민망하지만 이번 기회에 정리해 보기로 했다.

아래 서버 화면은 11월 9일에 찍었다. 10월 23일에 해 둔 모델 비교 기록도 다시 꺼내 봤다. 도구 호출이 왜 막혔는지 보려다가, 그동안 이름만 알고 지나쳤던 설정까지 하나씩 보게 됐다.

KT 클라우드에서 받은 H200부터 확인해 봤다

먼저 서버에 접속해서 nvidia-smi를 실행했다. NVIDIA GPU의 메모리와 사용률, 드라이버 정보 등을 볼 때 쓰는 명령이다.

11월 9일 오후 2시 3분에 서버에서 nvidia-smi를 실행해 봤다.

서버에는 H200 한 장이 보인다. 전체 GPU 메모리는 143,771MiB인데, 캡처한 순간에는 129,205MiB를 쓰고 있었다. 그런데 오른쪽 GPU 연산 사용률은 0%다.

메모리는 거의 차 있는데 사용률은 0%라니. 아래 프로세스 목록을 보면 Ollama의 llama-server와 vLLM의 EngineCore가 각각 메모리를 차지하고 있다. 두 모델이 GPU에 올라가 있는 상태와, 바로 그 순간 GPU가 연산을 하고 있는지는 따로 봐야 한다. 요청이 잠깐 없더라도 모델을 다음 요청을 위해 메모리에 올려 둘 수 있기 때문이다.

같은 날 오후 1시 28분에는 사용률이 0%, 1시 59분에는 19%였다. 2시쯤 1초 간격으로 다섯 번 확인했을 때는 57%, 72%, 59%, 89%, 76%가 나왔고, 위 캡처에서는 다시 0%가 됐다. nvidia-smi 한 번 보고 서버가 한가하다거나 바쁘다고 판단하기 어려운 이유다.

캡처 위쪽에 표시된 CUDA Version: 13.0도 주의해서 봐야 한다. 저 숫자는 드라이버가 보고하는 CUDA 지원 버전이고, 서버에 설치된 CUDA Toolkit이나 각 프로그램이 쓰는 런타임이 반드시 13.0이라는 뜻은 아니다. 이 부분은 NVIDIA 문서를 보면서 다시 확인했다.

그런데 vLLM은 정확히 뭘 하는 걸까?

나는 그동안 모델 이름과 API 주소를 받아 연결하는 쪽에 익숙했다. 이번에는 그 주소 뒤에서 무슨 프로그램이 요청을 받는지부터 봤다.

H200은 계산을 담당하는 GPU다. Gemma는 질문을 받아 다음 내용을 생성하는 모델이고, 모델의 가중치도 GPU 메모리에 올라간다. vLLM은 그 모델을 실행하고 요청을 처리하는 추론 엔진이다. 웹 API 서버로 띄워서 다른 프로그램이 모델에 질문할 수 있게 만들 수도 있다.

여기서 추론은 이미 학습된 모델에 입력을 넣어 결과를 얻는 과정이다. 모델을 GPU에 올려 두고 요청이 올 때마다 계산하는 것이다. 이 서버에서 질문에 답할 때 가중치를 다시 학습시키는 과정은 없다.

이 서버는 Ubuntu 위에서 NVIDIA 드라이버와 CUDA 관련 실행 환경을 통해 GPU를 사용한다. vLLM은 그 위에서 모델을 실행하는 프로그램이다. CUDA는 GPU 계산을 위한 NVIDIA의 플랫폼과 실행 환경이고, vLLM은 모델 추론을 처리하는 쪽이라고 보면 된다.

우리 환경에서는 Agent 백엔드가 사용자 질문과 도구 목록을 vLLM에 보낸다. vLLM은 올라가 있는 Gemma를 실행하고, 나온 답변이나 도구 호출 요청을 API 응답으로 돌려준다. 그리고 실제 도구 실행과 권한 확인은 Agent 백엔드가 맡는다.

MERMAID

웹 서버처럼 요청을 받아 응답하는 역할도 하지만, 모델을 GPU 메모리에 올리고 여러 요청의 추론을 처리하는 엔진까지 들어 있다고 생각하면 이해하기 편했다. vLLM은 OpenAI 호환 API를 제공해서 백엔드에서 익숙한 형식으로 요청을 보낼 수 있다. 다만 API 모양이 비슷하다고 모든 모델과 옵션이 똑같이 동작하는 건 아니다. 이번에 만난 400 오류가 그 사례였다.

같은 서버에서 쓰던 Ollama도 모델을 실행하고 API로 호출할 수 있게 해 준다. vLLM과 Ollama는 이런 점에서 역할이 겹치지만 지원하는 모델과 세부 설정, 운용 방식에 차이가 있다. 어느 쪽이 무조건 낫다고 정하기보다는 사용할 모델과 동시 요청, 배포 환경을 맞춰 비교해야 한다.

Agent의 질문 한 번에 모델은 몇 번 불릴까?

내가 만든 Agent에서도 질문 하나에 모델을 여러 번 부를 수 있다. 예를 들어 "최근 매출 변화를 알려 줘"라고 물었는데 필요한 자료가 아직 없다고 해 보자. 아래는 업무 데이터가 아닌 설명용 예시다.

MERMAID

모델이 한 번에 답하면 첫 호출에서 끝난다. 하지만 조회가 필요하면 도구를 실행한 다음 결과를 다시 보내야 한다. 추가 조회나 답변 형식 보정이 필요한 흐름이라면 모델 호출이 더 늘어날 수도 있다.

입력되는 내용도 생각보다 많다. 사용자가 쓴 한 줄 외에 시스템 지시문, 도구의 이름과 사용 방법, 이전 대화, 방금 조회한 결과가 들어간다. 내가 작업한 분석 Agent 쪽에도 도구 반복 횟수와 입력 예산을 따로 관리하는 설계가 있었다. 제한을 두지 않으면 도구 결과가 누적되면서 모델에 넘기는 문맥이 계속 커질 수 있기 때문이다.

서버 설정에 적힌 131072라는 문맥 길이도 이때 중요하다. 모델이 처리할 수 있는 입력과 출력의 총 토큰 한도이지, 사용자가 적은 질문만의 글자 수가 아니다. 토큰은 모델이 텍스트를 다루는 단위로, 단어와 꼭 일치하지 않는다. 언어와 내용에 따라 같은 글자 수라도 토큰 수가 달라질 수 있다.

도구 호출을 붙이던 Agent의 11월 2일 코드 기록을 보면, 한 질문에서 도구는 최대 3번, 도구 결과는 한 번에 약 1,500토큰, 전체 입력은 기본 16,000토큰으로 추정 예산을 잡아 두었다. 서버의 131,072토큰 한도를 다 채워 쓰는 구조는 아니었다. 이 값은 당시 앱 기본 설정이고 운영에서 덮어쓴 값까지 확인한 기록은 없다.

문맥이 길어지면 모델에 전달할 자료를 어디까지 남길지 고민해야 한다. 처음 본 자료를 전부 넣으면 충분할 것 같지만, 실제로는 필요한 근거를 찾기 어려워지고 처리할 입력도 늘어난다. 그렇다고 무작정 줄이면 답변에 필요한 정보가 빠진다. Agent 쪽에서 조회 범위와 도구 결과 크기를 관리해야겠다고 생각했던 이유다.

입력량을 바이트 수로 추정하는 코드도 있었다. 토크나이저로 직접 센 값이 아니니, 응답에 오는 usage와 비교해 실제로 얼마나 차이 나는지 봐야 한다.

그런데 서버는 이 긴 입력을 매번 어떻게 처리할까? 여기서부터 KV 캐시가 나온다.

KV 캐시는 뭘 저장하는 걸까?

모델은 답변을 완성된 문장으로 한 번에 꺼내지 않고, 보통 다음 토큰을 차례로 생성한다. 다음 토큰을 고를 때는 그 앞에 들어온 질문과 이미 생성한 내용을 참고해야 한다.

매번 앞의 내용을 처음부터 다시 계산하면 같은 작업이 반복된다. KV 캐시는 이전 토큰을 처리하면서 각 어텐션 층에서 계산한 Key와 Value를 보관하는 공간이다. 다음 토큰을 만들 때 이 결과를 다시 사용할 수 있다. 답변 문장 자체를 저장해 뒀다가 그대로 돌려주는 캐시는 아니다.

Key와 Value는 데이터베이스의 key: value처럼 원문 단어를 그대로 저장한 쌍이 아니다. 모델 안에서 토큰을 숫자 벡터로 바꾸고 계산해 얻은 값이다. 어텐션을 아주 단순하게 나누면 다음과 같다.

  • Query(Q): 현재 위치에서 어떤 정보를 참고할지 계산하는 값
  • Key(K): 앞의 각 위치를 참고할 때 비교에 쓰는 값
  • Value(V): 선택한 위치에서 가져와 섞을 정보에 쓰는 값

현재 위치의 Query와 이전 위치들의 Key를 비교해 참고할 정도를 정하고, 그에 따라 Value들을 활용한다. 실제 계산은 모델의 여러 층과 어텐션 헤드에서 일어난다. 여기서는 그중 한 흐름만 단순하게 적었다. (Hugging Face의 캐시 설명)

NVIDIA의 아래 그림도 같은 과정을 보여 준다. 위쪽 prefill에서는 입력의 K와 V를 계산하고, 아래쪽 decode에서는 캐시에 저장된 부분을 다시 사용하면서 새 값만 추가한다.

출처: NVIDIA Technical Blog, KV 캐시 설명과 원본 그림. 이미지의 파란색은 해당 단계에서 계산하는 값, 보라색은 캐시에서 가져오는 값이다.

가상의 입력 토큰을 t1, t2, t3이라고 놓고 보면 조금 쉽다. 실제 한국어 문장을 세 토큰으로 나눴다는 뜻은 아니다.

MERMAID

처음 입력을 처리하는 단계를 prefill이라고 한다. 여기서 기존 입력의 K와 V를 계산해 캐시에 담고 첫 답변 토큰을 고른다. 그다음 decode 단계에서는 방금 만든 토큰을 입력으로 사용하면서 새로운 K와 V를 추가하고, 앞에서 보관한 K와 V도 참고해 다음 토큰을 만든다.

이렇게 하면 이전 K와 V를 매번 다시 계산하지 않아도 된다. 그렇다고 과거 문맥을 읽는 어텐션 연산까지 전부 없어지는 건 아니다. 캐시를 쓰면 재계산은 줄지만 보관할 GPU 메모리는 필요하다.

그러면 캐시는 얼마나 커질까?

캐시 크기는 모델 구조, 문맥 길이, 데이터 형식과 동시에 처리하는 요청 수에 영향을 받는다. 어텐션 헤드는 연산을 나누어 수행하는 단위인데, 모델에 따라 Query 헤드보다 Key·Value 헤드가 적을 수도 있다. 캐시 용량을 따질 때는 KV 헤드 수를 봐야 한다. 숫자로 감을 잡기 위해 아주 단순한 가정을 하나 해 봤다.

32개 층이 모두 전체 문맥에 어텐션을 쓰고, 각 층에 KV 헤드 8개, 헤드 차원 128개가 있다고 하자. K와 V를 각각 2바이트 형식으로 저장한다면 토큰 하나에 필요한 캐시는 대략 이렇다.

TEXT

이 가상의 모델에서 문맥이 8,192토큰이면 한 시퀀스의 KV 캐시는 약 1GiB다. 같은 크기의 요청 4개가 캐시를 공유하지 않고 함께 처리되면 약 4GiB가 된다. 이 숫자는 설명용 계산이며 우리 H200이나 Gemma의 실측값이 아니다. 실제 모델은 층마다 구조가 다르거나 sliding window를 쓰기도 하고, 캐시 공유·양자화·병렬화·메모리 관리에 따라서도 달라진다.

이걸 보고 나니 모델 파일이 GPU에 올라갔다고 메모리 계산이 끝나는 게 아니었다. Agent가 긴 문맥을 보내고 요청이 겹치면 KV 캐시 공간도 필요하다. 내 서버에는 모델이 두 개나 올라가 있었으니 더 봐야 했고.

PagedAttention은 캐시를 어떻게 나눌까?

요청마다 입력 길이가 다르고 답변이 끝나는 시점도 다르다. 요청 하나에 필요한 캐시를 매번 커다란 연속 공간으로 잡으려고 하면 남는 공간을 활용하기 어려워질 수 있다.

vLLM의 PagedAttention은 KV 캐시를 같은 크기의 블록으로 나누고, 요청에 필요한 블록을 관리한다. 한 요청의 논리적인 순서와 GPU 메모리 안의 실제 블록 위치는 테이블로 연결한다. 아래 블록 번호는 원리를 보여 주기 위해 내가 임의로 만든 것이다.

MERMAID

요청 A의 블록 ①, ②, ③이 GPU 메모리에 꼭 연달아 놓여 있지 않아도, 어디에 있는지 알면 순서에 맞게 사용할 수 있다. 요청 B도 남은 블록을 쓸 수 있고, 요청이 끝나면 사용하던 블록을 다시 관리한다. 운영체제의 페이징에서 착안한 방식이지만, GPU 메모리의 캐시 블록을 관리하는 것이지 vLLM이 운영체제가 되는 건 아니다.

아래 vLLM 팀의 애니메이션으로 보면 더 쉽다. 왼쪽의 논리 블록이 가운데 테이블을 거쳐 오른쪽 GPU 메모리 블록으로 연결된다. 둘 다 원리를 설명하는 그림이다.

vLLM 팀의 PagedAttention 소개에 있는 캐시 블록 배치 그림이다.

요청이 추가되고 끝날 때 블록을 어떻게 관리하는지는 vLLM 추론 엔진 구조 글에서도 자세히 볼 수 있다.

같은 앞부분은 다시 쓸 수 있을까?

Agent가 모델을 여러 번 부를 때 시스템 지시문과 도구 목록은 같은 내용으로 시작할 수 있다. 앞부분의 토큰이 같으면 이미 계산한 KV 캐시를 다시 쓸 여지도 있다. vLLM에서는 이 기능을 prefix caching이라고 부른다.

요청앞부분달라지는 부분
첫 요청공통 지시문 + 도구 설명질문 A
다음 요청같은 공통 지시문 + 도구 설명질문 B

조건이 맞아 캐시가 남아 있다면 다음 요청은 일치하는 앞부분의 캐시 블록을 재사용하고 달라진 부분을 처리한다. vLLM은 완성된 블록 단위로 캐시를 관리하므로, 공통 부분이 있다고 해서 그 길이 전체가 항상 적중하는 것은 아니다. 대화 템플릿이나 도구 순서가 달라져 토큰이 달라지거나, 캐시가 메모리에서 교체돼도 적중하지 않을 수 있다.

이 설정으로 줄일 수 있는 건 앞부분의 prefill 계산이다. 다른 질문 B에 질문 A의 최종 답변을 그대로 돌려주는 게 아니고, decode 단계의 답변 생성 자체를 없애 주는 것도 아니다. 적용 전후에는 실제 공통 프롬프트와 캐시 적중률, 첫 토큰 시간을 같이 봐야 한다. (vLLM 자동 prefix caching 문서)

요청이 여럿 들어오면

vLLM은 여러 요청을 처리할 때도 앞선 요청이 전부 끝나기만 기다리지 않는다. 진행 중인 요청과 새 요청을 작업 단계마다 조정해 함께 처리할 수 있는데, 이를 continuous batching이라고 한다.

다만 요청을 무한히 동시에 돌리는 건 아니다. 입력과 출력 길이가 길어지면 각 요청이 쓸 캐시가 늘어난다. 남은 블록이 부족하거나 스케줄러의 한도에 닿으면 대기나 재계산이 생길 수 있다. 앞에서 본 것처럼 Agent 한 번의 질문에도 모델 호출이 여러 번 섞일 수 있으니, 사용자 수만 보고 모델 서버의 실제 요청 수를 짐작하기도 어렵다.

실제로 실행된 옵션을 보니

이제 아까 메모리를 차지하고 있던 vLLM이 어떤 설정으로 떠 있는지 봤다.

실행 중인 vLLM의 인자를 확인해 봤다. 모델 경로 일부와 바인드 주소는 가렸다.

옵션이 꽤 많다. 그동안 나는 이 중에서 모델 이름이랑 API 주소 정도만 알고 썼던 셈이다. 눈에 들어온 것부터 하나씩 살펴봤다.

--gpu-memory-utilization 0.40은 이 vLLM 인스턴스가 모델 실행에 사용할 GPU 메모리 비율을 정하는 설정이다. 전체 143,771MiB의 40%는 약 57,508MiB이고, 앞의 프로세스 목록에서 vLLM이 사용한 메모리는 57,784MiB로 비슷한 크기다. 다만 이 옵션은 인스턴스별 설정이지 다른 프로세스의 메모리를 통제하는 장치는 아니다. 실제 점유량도 실행 시점과 환경에 따라 달라질 수 있다. 이 서버에서는 Ollama도 같은 GPU를 쓰므로 남은 공간까지 같이 봐야 한다.

--max-model-len 131072는 한 요청의 문맥 길이 한도다. 질문에 포함된 내용과 생성할 답변을 합쳐 토큰 단위로 계산한다. 글자 수 131,072자라는 뜻은 아니다. 입력이 길면 모델이 먼저 처리해야 할 내용도 많아지고 KV 캐시도 더 필요하다.

--max-num-seqs 32는 스케줄러가 한 번의 처리 단계에서 다룰 시퀀스 수의 상한이다. "사용자가 32명만 접속할 수 있다"는 뜻은 아니다. 요청이 더 들어오면 대기할 수도 있고, 실제 동작은 다른 스케줄링 설정과 메모리 상황에도 영향을 받는다. 각 옵션의 설명은 실행 중인 버전의 vLLM 문서에서 확인할 수 있다.

--enable-prefix-caching은 앞에서 살펴본 공통 접두부의 KV 재사용 기능을 켜는 설정이다. Agent의 시스템 지시문과 도구 설명이 반복되는 환경이라면 실제로 같은 앞부분이 얼마나 유지되는지 확인해 볼 만하다.

--kv-cache-dtype fp8은 KV 캐시를 FP8 형식으로 저장하는 설정이다. 이 서버에서 모델 이름에도 FP8이 붙어 있는데, 그건 모델의 가중치·활성값에 적용된 양자화 이야기다. 이름은 같아도 어느 데이터를 줄이는지 다르다.

Red Hat AI의 Gemma 4 FP8 모델 카드도 열어 봤다. 가중치와 활성값에 FP8을 적용했다고 적혀 있다.

실제로 예전 비교 기록에서 같은 Gemma에 KV 캐시 FP8을 적용하니 서버가 기록한 캐시 수용량이 약 66만 토큰에서 약 132만 토큰으로 늘었다. 반면 분석 계획 시간은 6.4초와 6.1초로 큰 차이가 없었다. 캐시 공간을 더 확보하는 것과 단일 요청이 바로 빨라지는 것은 별도로 봐야 한다. 저 132만도 캐시의 총 수용량이지, 한 요청에 그만큼을 넣을 수 있다는 뜻은 아니다.

11월 9일에는 한 GPU에 모델이 두 개 올라가 있었다

다른 명령으로 현재 올라간 모델도 확인해 봤다.

같은 서버에서 Ollama에 올라간 모델과 vLLM 버전도 확인했다.

Ollama에는 gpt-oss:120b가 올라가 있고, UNTIL은 Forever로 표시된다. vLLM의 버전은 0.31.0이었다. 앞에서 본 것처럼 같은 GPU에 Ollama와 vLLM이 각각 자리를 쓰고 있다.

이렇게 된 데에는 이전 시험이 있다. 사내 분석 Agent는 원래 GPT-OSS 120B를 Ollama로 사용하고 있었는데, 10월 23일에 Red Hat의 Gemma 4 26B A4B FP8 모델을 vLLM에 별도로 올려 비교했다. 기존 Agent의 모델을 그 자리에서 교체한 시험은 아니었다.

분석 계획 2종과 블록 옵션 3종의 요청을 한 번에 하나씩 보냈다. 당시 기록의 중앙값은 아래와 같다. GPT-OSS 계획 시간은 원본에 17.4~21.9초 범위로 남아 있었다.

시험 구성분석 계획블록 옵션
GPT-OSS 120B + Ollama, 추론 수준 medium17.4~21.9초6.3초
Gemma 4 26B FP8 + vLLM, thinking 끔6.4초1.4초
같은 Gemma 구성, thinking 켬59.1초24.7초

두 모델 이름의 숫자도 따로 볼 필요가 있다. GPT-OSS 120B는 전체 약 117B 파라미터 중 한 토큰을 처리할 때 약 5.1B가 활성화되는 MoE 모델이다. 시험한 Gemma 4 26B A4B도 전체 약 26B 중 약 4B가 활성화되는 MoE다. 전체 파라미터 수는 모델을 저장하고 올리는 데 필요한 공간과 관련이 있고, 매 토큰에서 활성화되는 부분은 계산량을 이해할 때 참고할 수 있다. 다만 숫자만으로 속도나 답변 품질을 정할 수는 없다. (OpenAI 모델 카드, Google의 Gemma 모델 설명)

thinking을 끈 Gemma는 빨랐다. 켜니까 계획 요청이 59.1초까지 늘었다. 다만 모델과 서빙 엔진, 추론 설정을 같이 바꾼 작은 시험이라, 이 표만 보고 vLLM 자체가 몇 배 빠르다고 할 수는 없다.

계획 내용도 달랐다. 한 생존 예측 시험에서 GPT-OSS와 thinking을 켠 Gemma는 당시 분석 블록 기준으로 불필요하다고 본 원핫 인코딩을 넣지 않았는데, thinking을 끈 Gemma는 넣었다. 그래서 당시에는 복잡한 계획에 GPT-OSS를 유지하면서 Gemma를 짧은 작업에 나눠 쓸 수 있을지 더 보기로 했다. 이때 본 건 해당 분석 블록에 맞는 계획을 만드는지였다.

응답 형식도 확인할 게 있었다. thinking을 끈 Gemma의 응답 25건 중 JSON 내용이 깨진 것으로 기록된 건 없었지만, 12건은 마크다운 코드 블록으로 감싸서 왔다. 사람 눈에는 보기 편한데 프로그램이 원문을 그대로 JSON으로 파싱하면 코드 블록 표시부터 걸린다. 겉의 표시를 벗긴 다음에도 원하는 스키마와 내용이 맞는지는 따로 검사해야 한다.

별도의 초기 통합 시험에서는 질문 40개 중 6개가 계획 완성으로 판정됐다. 이때는 도구 인자 형식과 애플리케이션의 검증·재시도도 결과에 영향을 줬으므로 모델 하나의 성공률로 보면 안 된다. 계획이 완성된 것과 실제 화면에서 실행까지 성공한 것도 별개다.

도구만 넘기면 400이 났던 이유

이제 처음에 만난 오류로 돌아가 보자. 다른 Agent에 조회 도구를 붙일 때, 일반 질문에는 답하던 서버가 도구 목록과 tool_choice를 auto나 required로 보내면 HTTP 400을 돌려줬다.

도구 호출은 모델이 DB에 직접 접속하는 기능이 아니다. 예를 들어 문서 검색이 필요하면 모델이 "어떤 도구를 어떤 인자로 호출할지" 요청을 만들고, 백엔드가 도구와 인자, 사용자 권한을 확인한 뒤 실제로 검색한다. 검색 결과를 다시 모델에 보내면 모델이 그 내용을 바탕으로 답변을 이어 간다.

예를 들어 search_documents라는 도구를 제공했다면 백엔드가 받는 도구 호출은 아래처럼 생길 수 있다. 실제 업무 자료는 넣지 않은 설명용 예시다.

JSON

이건 검색 결과가 아니라 검색해 달라는 요청이다. 백엔드가 허용된 도구인지 확인하고 실행해 결과를 모델에 돌려줘야 비로소 답변에 사용할 수 있다.

문제는 모델마다 이 도구 요청을 만들어 내는 형식이 다르다는 점이다. vLLM은 모델에 맞는 파서로 생성 결과를 읽어 API의 tool_calls 형식으로 전달한다. 당시 서버에서는 자동 도구 선택과 Gemma 4에 맞는 파서 설정이 빠져 있었고, 확인 후 실행 인자에 다음 두 옵션을 추가했다.

Bash

첫 번째는 모델이 도구를 선택하는 기능을 켜고, 두 번째는 Gemma 4의 도구 호출 형식을 해석할 파서를 지정한다. 위 실행 인자 캡처의 마지막 두 줄이 이 설정이다. 다른 모델에도 무조건 gemma4를 넣는 게 아니라 모델과 vLLM 버전에 맞춰 확인해야 한다. (vLLM 도구 호출 문서)

이 옵션은 서버를 띄울 때 읽는 값이라 vLLM 프로세스를 다시 시작해야 했다. 정상 응답이 돌아오기까지 기록상 약 6분이 걸렸다. H200 서버 전체를 재부팅하거나 모델을 다시 학습시킨 건 아니다. 그래도 다른 작업도 GPU를 함께 쓰는 환경이니 재시작 전에는 영향을 확인하고 시간을 공유해야 한다. 매번 똑같이 6분 걸린다는 의미도 아니다.

캡처에 보이는 --reasoning-parser gemma4는 또 다른 설정이다. 도구 파서가 도구 호출을 해석한다면, reasoning 파서는 추론 영역을 답변과 구분한다. 이름은 비슷하지만 처리하는 출력이 다르고, thinking을 켤지 여부도 따로 확인해야 한다.

재시작 뒤 가짜 자료로 시험했을 때는 auto와 required 모두 도구 호출이 나왔다. auto는 모델이 도구를 쓸지 고르고, required는 하나 이상의 도구 호출을 요구한다.

여기서 당시의 400 기록과 일반적인 동작을 구분해야 한다. vLLM 0.31.0 문서는 required를 구조화 출력으로 처리하는 기본 지원 기능으로 설명한다. 따라서 required도 언제나 자동 도구 선택 옵션이 없어서 실패한다고 볼 수는 없다. 당시에는 두 옵션을 함께 추가해 복구했고, 각각의 영향을 따로 시험한 기록은 없다.

실제 자료로 보낸 대화 시험에서는 4건 중 2건에서 도구를 호출했고, 둘 다 질문에서 사용할 도구를 직접 짚어 준 경우였다. 그중에는 조회는 했지만 원하는 대상을 찾지 못한 사례도 있었다. 당시에는 화면 입력이 막혀 API로 시험했기 때문에 사용자 화면에서 끝까지 동작하는지도 확인하지 못했다. 표본이 적어 성공률이라고 부르기보다는, 도구 설명과 질문을 바꿔 가며 다시 확인해야 할 기록으로 남겨 뒀다.

도구를 쓰면서 JSON으로도 답해야 했다

이번 Agent는 최종 답변을 정해진 JSON 형식으로 받아야 했다. 그래서 처음에는 도구 목록을 주면서 JSON 형식도 함께 강제했다. 그런데 당시 모델과 서버 조합에서는 도구를 부르지 않거나 빈 JSON을 돌려주는 경우가 있었다. 도구를 주는 단계에서 JSON 강제를 빼고 시험하니 도구 호출이 나왔다.

11월 9일에는 도구를 쓰는 호출에서 JSON 강제를 빼고, 도구를 뺀 마지막 호출과 형식 재작성에만 다시 적용하는 코드를 작업 중이었다. 코드 블록으로 감싼 응답은 표시를 벗긴 다음 JSON과 스키마를 검증한다. 이 변경은 당시 작업 중이었고, 운영 배포 여부는 확인하지 못했다.

이 조합에서는 이렇게 나눠야 도구가 호출됐다. 다른 모델에도 같은 처리가 필요한지는 각각 시험해 봐야 한다.

빠른 GPU가 있는데 왜 기다릴까?

도구 호출 오류와 응답 시간이 긴 문제도 나눠서 봐야 한다. 옵션을 넣어 400이 사라졌다고 모델의 답변 속도까지 빨라진 건 아니기 때문이다. 이번에는 vLLM이 내보내는 메트릭을 살펴봤다.

vLLM /metrics에서 필요한 줄을 골라 봤다. 모델 이름 등이 담긴 라벨은 가렸다.

메트릭의 count는 관측된 건수, sum은 시간의 합계다. 둘을 나눠 평균을 구해 볼 수 있다. 위 캡처에 나온 값으로 계산하면 이렇다.

지표캡처에 기록된 평균무엇을 보는지
첫 토큰까지 시간, TTFT약 29msvLLM 내부 요청 처리 시작부터 첫 출력까지
출력 간 시간, ITL약 4.9ms답변을 생성하는 동안 출력 이벤트 사이에 걸린 시간
요청 전체 시간약 0.38초vLLM 내부 요청 처리 시작부터 마지막 출력까지
요청 대기 시간약 0.04msvLLM이 요청을 처리하기 전 대기한 시간

TTFT는 5,178건, 요청 전체 시간은 5,177건으로 캡처에 찍힌 각 지표의 count를 사용했다. ITL은 요청 건수가 아니라 출력 이벤트 간격의 합을 그 관측 건수로 나눈 값이다. 한 이벤트에 여러 토큰이 담길 수도 있으므로 이 값을 그대로 토큰당 처리 속도라고 단정하지는 않았다. (vLLM 메트릭 설명)

처음 토큰까지 오래 걸린다면 입력 처리나 대기 시간을 확인해 볼 수 있고, 답변이 시작된 뒤 천천히 이어진다면 생성 구간을 살펴볼 수 있다. 여기에 Agent의 도구 조회와 재호출 시간이 더해지면 사용자가 화면에서 기다리는 시간은 달라진다.

캡처 시점의 num_requests_running은 1, num_requests_waiting은 0이었다. kv_cache_usage_perc는 약 0.00048, 즉 캐시 블록의 약 0.048%가 사용 중이라는 값이다. 이 숫자는 vLLM이 관리하는 KV 캐시의 사용 비율이라 GPU 전체 메모리 사용률과 바로 비교할 수 없다. 앞의 nvidia-smi와 메트릭 캡처는 조회 시점도 다르다.

찍힌 순간에는 대기 요청이 없었고 누적 평균도 짧았다. 내가 느리다고 느꼈던 요청의 기록을 골라낸 건 아니어서, 이것만 보고 병목이 없다고 할 수는 없다.

입력·출력 토큰의 누적 합계를 완료 요청 수로 대략 나누면 각각 약 69개와 73개다. 진행 중인 요청도 있어 정확히 짝지은 평균은 아니지만, 앞에서 시험한 긴 분석 계획과 서버 전체 누적치를 바로 비교하기는 어렵다. 다음에는 느렸던 요청의 입력 길이, 첫 토큰 시간, 생성 시간과 도구 조회 시간을 따로 남겨야겠다.

다음에는 느린 요청을 따로 재봐야겠다

이번에 기록을 다시 보면서 아쉬웠던 건 모델과 서빙 엔진을 함께 바꾼 비교가 많았다는 점이다. 속도가 달라져도 모델의 차이인지, 엔진인지, thinking 설정인지 하나씩 떼어 말하기 어렵다.

다음에는 가능한 범위에서 같은 모델을 두 서빙 환경에 올리고 입력·출력 길이와 동시 요청 수를 맞춰 보려고 한다. 그다음에는 같은 환경에서 모델을 바꾸고, 응답 시간뿐 아니라 도구 선택과 인자, 최종 작업 완료 여부도 같이 확인해 볼 생각이다. 실제 운영과 시험이 GPU를 공유한다면 다른 작업에 영향이 가지 않는 시간부터 잡아야 한다.

prefix caching도 기록에는 흥미로운 수치가 있다. 당시 이를 끈 쪽의 첫 토큰 시간이 0.08초에서 0.40초로 늘었다. 다만 끈 상태의 표본이 6건뿐이었고, 내 Agent의 실제 프롬프트와 동시 요청에서도 같은 효과가 날지는 다시 재봐야 한다.

이번에 찾아본 Gemma 4 vLLM 설정 글도 파서와 이미지 버전을 살펴보는 데 도움이 됐다. 다만 2026년 4월의 환경을 기준으로 작성된 글이니 당시 Docker 태그나 패키지 버전을 그대로 현재 권장 설정으로 가져오기보다는, 실제 쓸 버전의 문서를 함께 확인하는 편이 좋겠다.

그동안 Agent 응답이 느리면 프롬프트부터 줄이거나 모델을 바꿀 생각을 했다. 이번에는 GPU에 뭐가 올라가 있는지, 입력을 처리하는 데 얼마나 걸리는지부터 봐야 한다는 걸 알았다. H200이 있으니 빠르겠지 하고 넘어간 부분이 생각보다 많았다.

도구 호출의 400은 해결했지만, 느리다고 느낀 요청의 원인을 전부 찾은 건 아니다. 다음에는 오래 걸린 질문 하나를 잡고 끝까지 시간을 재볼 생각이다. 장비는 이미 좋은 걸 받고 있었으니, 쓰는 쪽에서도 좀 알아야겠다...

11월 16일, 메모리를 더 주면 되는 줄 알았는데

여러 서비스에서 H200을 같이 쓰다 보니 문맥 길이도 더 늘려 놓으면 좋지 않을까 싶었다. 지금 131k로 되어 있으니 262k로 올리면 더 많이 받아 줄 수 있지 않을까? 나는 이 숫자와 KV 캐시 크기, 동시 처리 수를 조금씩 섞어서 생각하고 있었다.

막상 설정을 다시 보니 서로 바꾸는 게 달랐다. 그래서 RAM부터 다시 정리해 봤다.

서버 RAM과 GPU RAM은 따로 있었다

보통 서버 메모리라고 부르는 RAM은 CPU가 쓰는 메모리다. 프로그램을 실행하고, 요청 데이터를 준비하고, 모델 파일을 읽어 오는 데 쓴다. GPU에도 메모리가 따로 있는데, 이쪽을 VRAM이라고 부른다. H200의 HBM도 이 GPU 메모리에 해당한다.

지금 구성에서는 GPU 메모리에 Gemma의 모델 가중치가 올라가고, 계산 중에 필요한 데이터와 KV 캐시도 들어간다. KV 캐시는 메모리 장치의 이름이 아니라, 메모리에 저장해 두는 계산 결과다. 서버 RAM을 늘린다고 GPU의 KV 캐시가 저절로 커지는 건 아니었다.

구분지금 구성에서 맡는 일
서버 RAM프로그램 실행, 입력 데이터 준비, 모델 파일 로딩 등
GPU 메모리(VRAM)GPU가 쓸 모델 가중치와 계산 데이터, KV 캐시 보관
KV 캐시앞선 토큰에서 계산한 Key·Value를 보관해 다음 토큰을 만들 때 재사용

아래처럼 나눠 보니 조금 이해가 됐다. GPU 메모리 안에 KV 캐시만 들어가는 게 아니라 모델과 계산에 필요한 공간도 함께 들어간다.

MERMAID

동접자가 많으면 캐시도 많이 필요한 거 아닌가?

이 부분은 맞게 생각하고 있었다. 다만 사이트에 접속한 사람 수와 모델이 동시에 처리하는 요청 수는 다르다. 채팅 화면만 열어 둔 사람마다 KV 캐시를 하나씩 배정하는 방식은 아니다.

여러 사람이 동시에 답변을 요청하면 각 요청을 처리할 캐시가 필요하다. 같은 수의 요청이라도 짧은 질문만 보낼 때와 긴 문서에 대화 기록까지 붙일 때는 필요한 공간이 달라진다. Agent가 도구 조회 결과를 붙여 다시 질문하면 그 내용도 문맥에 들어간다.

캐시가 부족하면 요청이 기다리거나, 진행하던 요청의 일부 계산을 다시 해야 할 수 있다. 그렇다고 캐시를 두 배로 잡으면 처리할 사람 수도 정확히 두 배가 되는 건 아니다. GPU가 실제로 계산하는 시간도 있으니, 같은 질문 묶음으로 같이 요청해 봐야 알 수 있다.

131k를 262k로 올리는 건 공간을 늘리는 설정이 아니었다

--max-model-len은 한 요청에 들어갈 입력과 출력의 길이 한도다. 131,072를 262,144로 바꾸면 더 긴 요청을 허용하는 것이지, GPU 메모리가 늘어나지는 않는다. 오히려 실제로 긴 요청이 들어오면 그 요청이 캐시와 계산 시간을 더 사용할 수 있다.

내가 생각했던 “GPU 메모리를 더 주자”에 가까운 설정은 --gpu-memory-utilization이었다. 현재는 0.40으로, vLLM이 GPU 메모리의 40%를 예산으로 잡도록 되어 있다. 이 안에서 모델과 실행에 필요한 공간을 확보하고 KV 캐시를 잡는다. 40% 전체가 KV 캐시라는 뜻도 아니었다. 두 옵션의 설명은 vLLM 실행 옵션 문서에서도 확인했다.

설정으로 물리적인 VRAM 용량 자체를 늘릴 수는 없다. 이번에 검토한 건 이미 있는 H200 메모리 중 vLLM에 배정하는 몫을 늘리는 방법이다.

다시 확인하니 GPU 사용 상태도 달라져 있었다

앞에서 쓴 11월 9일 캡처와 16일에 확인한 상태는 달랐다. Ollama API에는 GPT-OSS가 올라와 있다고 나왔지만, 실제 GPU 프로세스 목록에는 없었다. API 응답만 보면 GPT-OSS가 여전히 GPU 메모리를 크게 쓰고 있다고 잘못 판단할 뻔했다.

16일 확인에서는 Gemma가 약 56.6GiB, 위변조·음성인식 모델들이 약 6.8GiB를 사용하고 있었다. GPU 여유는 약 76.5GiB였다. Gemma만 쓰는 전용 GPU는 아니어서 다른 모델이 사용할 공간도 남겨 둬야 한다.

11월 16일 확인 항목값
한 요청의 문맥 길이 한도131,072토큰
vLLM GPU 메모리 할당 설정40%
기동 로그에 나온 KV 캐시 확보량27.88GiB
확인 당시 GPU 여유 메모리약 76.5GiB
동시 처리 시퀀스 설정 상한32개

여기서 32도 가입자나 접속자 제한이 아니다. vLLM이 한 번에 처리하도록 설정한 시퀀스 수의 상한이다. 실제 처리량은 요청 길이와 생성할 답변 길이에 따라 달라진다.

확인한 순간에는 대기 요청과 KV 캐시 사용률이 모두 0이었다. 그때 여유가 있었다는 건 알 수 있지만, 여러 서비스가 몰려 쓰는 시간에도 괜찮은지는 따로 봐야 한다. 기동 때 캐시용으로 확보한 공간과 그 순간 실제로 사용 중인 캐시도 구분해서 읽어야 했다.

그래서 우선 문맥은 131k로 두고, GPU 메모리 할당을 40%에서 60%로 늘려 비교해 보는 쪽을 검토하고 있다. 아직 설정을 바꾸지는 않았다. 같은 요청을 동시에 보내면서 첫 답변이 나오는 시간과 대기 요청, 다른 모델의 메모리 사용량을 함께 볼 생각이다.

처음에는 “남는 메모리도 많은데 그냥 올리면 되지 않나?” 했는데, 정작 내가 올리려던 숫자는 문맥 길이였다. 여러 서비스에서 편하게 쓰려면 어떤 메모리를 얼마나 쓰고 있는지부터 구분할 줄 알아야겠다.

참고한 자료