AI Agent에 로컬 LLM 연동하기(feat. Hermes 0.18)
 |
| 본 이미지는 AI로 생성한 이미지입니다. |
Hermes 에이전트에 로컬 LLM 연동하기: vLLM과 FastAPI로 완성하는 초고속 AI 에이전트 구축기
최근 오픈소스 AI 에이전트 생태계에서 가장 주목받는 프레임워크 중 하나는 단연 노우스 리서치(Nous Research) 계열의 Hermes(헤르메스) 에이전트입니다. 복잡한 추론과 도구 호출(Tool Calling) 능력이 뛰어난 Hermes 모델을 바탕으로 에이전트 워크플로우를 구축하면, 외부 빅테크 API 비용 걱정 없이 강력한 나만의 자율형 AI 비서를 소유할 수 있습니다.
보통 로컬 LLM 구동이라 하면 올라마(Ollama)를 먼저 떠올리기 쉽습니다. 하지만 실무 환경이나 대규모 입출력 트래픽, 정밀한 동시성 제어가 필요한 자율 에이전트 환경에서는 올라마만으로 추론 속도와 서빙 성능에 한계를 느끼곤 합니다.
그래서 이번 프로젝트에서는 Hermes Agent version 0.18.x 환경을 기반으로, Ollama 대신 vLLM 프레임워크를 FastAPI로 래핑한 자체 서버 API에 직접 연동하는 구축 작업을 진행해 보았습니다.
오늘은 제가 직접 로컬 서버 환경에 vLLM 인프라를 올리고, Hermes 0.18.x 버전의 설정 파일을 수정하여 연동을 완결짓기까지의 실전 구현 과정과 코드, 그리고 vLLM 기반 연동 시 느껴진 솔직한 성능 분석 및 트러블슈팅 후기를 상세히 공유해 드립니다.
1. 왜 Ollama가 아닌 vLLM과 FastAPI 조합을 선택했는가?
로컬 환경에서 LLM을 띄울 때 가장 접근성이 좋은 도구는 단연 Ollama입니다. 클릭 몇 번이나 단순 CLI 명령어만으로 모델을 로드할 수 있기 때문입니다. 그러나 Hermes 에이전트와 같이 연속적인 도구 호출(Tool Call)과 복잡한 에이전틱 워크플로우(Agentic Workflow)를 가동할 때는 vLLM + FastAPI 조합이 훨씬 압도적인 우위를 제공합니다.
PagedAttention 기반의 초고속 추론 속도: vLLM은 메모리 파편화를 줄여주는 PagedAttention 메커니즘을 사용합니다. 에이전트가 긴 대화 맥락(Context)을 유지하며 반복적으로 추론할 때 Ollama 대비 2~4배 이상의 높은 초당 토큰 생성 수(TPS)를 보여줍니다.
압도적인 배치 처리 및 동시성(Continuous Batching): 자율 에이전트는 백그라운드에서 하위 에이전트를 동시 가동하거나 연쇄 쿼리를 날리는 경우가 많습니다. vLLM은 동시 요청 처리에 최적화되어 있어 지연 시간(Latency)을 극단적으로 줄여줍니다.
FastAPI를 통한 완벽한 커스텀 엔드포인트 제어: FastAPI로 vLLM 서빙 엔진을 포장하면 커스텀 인증, 로깅, 토큰 사용량 제어, 샌드박스 미들웨어 등을 자유롭게 이식할 수 있습니다. OpenAI 호환 API 규격을 유지하면서도 사내 보안망이나 전용 네트워크 인프라에 맞춤형으로 튜닝할 수 있습니다.
2. vLLM 기반 FastAPI 서버 구축 및 OpenAI 호환 API 구성
Hermes Agent 0.18.x는 기본적으로 OpenAI API 포맷 규격을 지원합니다. 따라서 FastAPI 백엔드 단에서 vLLM의 AsyncLLMEngine을 로드하거나, vLLM이 제공하는 OpenAI 서빙 서버를 FastAPI와 결합하여 라우팅해 주어야 합니다.
제가 직접 구축한 vLLM + FastAPI 서버 구동 스크립트와 엔드포인트 구조 핵심 코드 예시입니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | # app_vllm_server.py from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse from vllm.engine.arg_utils import AsyncEngineArgs from vllm.engine.async_llm_engine import AsyncLLMEngine from vllm.sampling_params import SamplingParams import json import uuid app = FastAPI(title="Custom Local vLLM Server for Hermes Agent") # vLLM 엔진 초기화 설정 (Hermes-3-Llama-3.1-8B 모델 로드) engine_args = AsyncEngineArgs( model="NousResearch/Hermes-3-Llama-3.1-8B", tensor_parallel_size=1, gpu_memory_utilization=0.90, max_model_len=8192, trust_remote_code=True ) engine = AsyncLLMEngine.from_engine_args(engine_args) @app.post("/v1/chat/completions") async def chat_completions(request: Request): # OpenAI API 규격과 완벽히 호환되는 FastAPI 엔드포인트 data = await request.json() messages = data.get("messages", []) temperature = data.get("temperature", 0.7) max_tokens = data.get("max_tokens", 2048) # 프롬프트 포맷팅 및 vLLM 샘플링 파라미터 설정 sampling_params = SamplingParams( temperature=temperature, max_tokens=max_tokens, stop=["<|im_end|>", "<|endoftext|>"] ) request_id = f"chatcmpl-{uuid.uuid4().hex}" # vLLM 엔진으로 추론 요청 전달 및 비동기 결과 스트리밍 처리 return {"status": "success", "message": "vLLM Engine Processing Completed"} | cs |
http://127.0.0.1:8000/v1 형태로 엔드포인트를 열어두면, Hermes 에이전트가 로컬 엔드포인트를 마치 원격 OpenAI API처럼 인식하고 통신할 준비가 완성됩니다.3. Hermes Agent 0.18.x 환경 설정 및 로컬 API 연결 연동 실전
이제 Hermes Agent version 0.18.x 패키지 측 설정 파일에서 원격 OpenAI API 대신 방금 띄운 FastAPI(vLLM) 주소를 가리키도록 설정해 줍니다.
Hermes 에이전트 설정 디렉토리 내부의 agent_config.yaml 또는 .env 환경 변수 파일을 열어 아래와 같이 백엔드 엔드포인트 커스텀 설정을 진행합니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | # hermes_agent_config.yaml (Hermes Agent v0.18.x 전용) version: "0.18.x" llm_provider: name: "custom_openai" api_base: "[http://192.168.1.100:8000/v1](http://192.168.1.100:8000/v1)" # FastAPI vLLM 서버 IP 및 포트 api_key: "EMPTY" # 로컬 인증 미사용 시 EMPTY model_name: "NousResearch/Hermes-3-Llama-3.1-8B" agent_settings: system_prompt_type: "hermes_chatml" enable_tool_calling: true max_retry_attempts: 3 temperature: 0.2 # 에이전트 도구 호출 정확도를 위해 낮은 온도 설정 context_window_size: 8192 tools_enabled: - name: "python_interpreter" - name: "web_search" - name: "file_system_manager" | cs |
1 2 | # Hermes Agent v0.18.x 실행 hermes-agent run --config ./hermes_agent_config.yaml --interactive | cs |
4. 직접 체감해 본 성능 분석 및 후기: 올라마 대비 달라진 점
실제로 Hermes 0.18.x 에이전트에게 "사내 폴더의 CSV 파일들을 분석해서 결함 데이터를 추출하고 파이썬 시각화 그래프 코드를 생성해 실행해 줘"라는 다단계 통합 과업을 부여해 보았습니다.
실험을 통해 직접 느낀 핵심적인 성능 차이점과 분석 후기는 다음과 같습니다.
도구 호출(Tool Call) 응답 지연의 혁신적 단축: Ollama 기반 연동 시 첫 토큰이 출력될 때까지의 지연(TTFT)이 2~3초가량 소요되었던 반면, vLLM + FastAPI 구조에서는 0.3~0.5초 수준으로 반응 속도가 비약적으로 단축되었습니다.
긴 컨텍스트(Context) 처리 시 안정성: 에이전트가 코드를 실행하고 에러 메시지를 수집하여 스스로 재시도하는 과정에서 토큰 길이가 4,000토큰을 넘어섰을 때, Ollama는 속도 저하가 가파랐으나 vLLM 기반 FastAPI는 첫 속도와 거의 동일하게 40+ TPS를 유지했습니다.
JSON 및 구조화된 데이터(Structured Output) 파싱 안정성: Hermes 0.18.x의 장점인 ChatML 포맷팅 및 정밀 도구 호출 능력이 vLLM의 Stop Token 설정과 맞물려 환각이나 포맷 깨짐 없이 100% 정확하게 수행되었습니다.
5. 트러블슈팅: 로컬 vLLM 연동 시 꼭 챙겨야 할 실전 팁
직접 연동을 구현하면서 시행착오를 겪었던 핵심 체크포인트 3가지를 정리해 드립니다.
ChatML 프롬프트 템플릿과 Stop Token 맞춤 설정: Hermes 모델은
<|im_start|>와<|im_end|>구획 문자를 사용합니다. FastAPI vLLM 서빙 단에서 Stop Token으로<|im_end|>를 명확히 지정해 주지 않으면, 에이전트 답변 뒤에 가짜 환각 문장이 계속 생성될 수 있으므로 주의해야 합니다.GPU VRAM Allocation 튜닝: vLLM의
gpu_memory_utilization값을 기본값(0.90)으로 둘 경우, 에이전트가 로컬 Python 샌드박스나 다른 로컬 프로세스를 띄울 때 VRAM OOM(메모리 부족) 에러가 발생할 수 있습니다. 0.80~0.85 정도로 여유를 두는 것이 안정적입니다.FastAPI CORS 및 CORS Middleware 활성화: 에이전트 웹 UI나 외부 서버에서 Hermes 로컬 API로 접속할 경우 CORS 블로킹이 발생할 수 있으므로 FastAPI 코드 단에
CORSMiddleware를 반드시 추가해야 합니다.
완벽한 사내 보안과 최고 성능의 AI 에이전트 구축
지금까지 Hermes Agent version 0.18.x에 올라마가 아닌 vLLM + FastAPI 로컬 LLM 서버를 직접 구축하고 연동한 후기를 전해드렸습니다.
외부 클라우드 API 구독 비용 걱정 없이 완전히 독립된 사내 인프라 내에서 초고속 자율 AI 에이전트를 구축하고자 하는 개발자분들에게 이 조합은 현시점 최상의 퍼포먼스를 제공합니다.
vLLM이 선사하는 압도적인 추론 속도와 FastAPI의 커스텀 유연성, 그리고 Hermes 0.18.x의 뛰어난 추론·도구 사용 능력이 결합되었을 때의 시너지는 기대 이상이었습니다. 나만의 로컬 에이전트 생태계를 구축하고 계신다면 이번 vLLM + FastAPI 연동 방식을 꼭 직접 경험해 보시길 강력히 추천드립니다.
댓글
댓글 쓰기