198B 모델로 1T급 효율을 내는 로컬 LLM과 도커 기반 개발 환경 구축 방법

궁금하면 500원·2026년 6월 25일

Backend LLM Stepfun codex docker localLLM

AI 미생지능

목록 보기

116/117

대형 언어 모델을 로컬 환경에 올릴 때 가장 먼저 마주하는 벽은 바로 '비용과 자원의 한계'입니다.

상용 API를 쓰자니 비용과 보안이 걱정되고, 그렇다고 1T급 모델을 로컬에서 직접 돌리는 것은 불가능에 가깝습니다.

결국 엔지니어는 한정된 인프라 안에서 가장 효율적인 대안을 찾아내야 합니다.

이 글에서는 중국의 Stepfun에서 공개한 Step 3.7 Flash(198B) 모델을 로컬 LM 스튜디오에 올리고, 도커 기반으로 코덱스와 연동하여 실무에 쓸 만한 로컬 환경을 구축한 과정을 공유해 드리고자 합니다.

배경과 제약 조건

엔지니어링 환경에서 인프라 자원은 언제나 유한합니다.

400B나 1T가 넘는 초거대 모델들이 벤치마크 점수가 좋다는 것은 누구나 알지만, 일반적인 워크스테이션 환경에서 이를 구동하는 것은 현실적으로 어렵습니다.

언슬로스에서 양자화된 Q6 버전만 하더라도 163GB가 넘어가는 용량이기 때문에, 싱글 PC나 일반적인 테스트 서버 환경에서는 메모리 오버플로우를 직면할 수밖에 없습니다.

또한, 이러한 오픈소스 툴체인을 로컬 호스트 PC에 직접 설치하는 방식은 지양해야 합니다.
권한 설정이 꼬이거나 Node.js 의존성이 로컬 시스템을 오염시키면 나중에 환경을 원상복구하기가 매우 까다롭기 때문입니다.

레거시 환경을 다룰 때와 마찬가지로, 기존 시스템을 건드리지 않고 철저히 격리된 컨테이너 환경 안에서 로컬 인프라와 통신할 수 있는 구조를 만드는 것이 이번 작업의 핵심 제약 조건이었습니다.

주요 기술 선택과 이유

1. Step 3.7 Flash (198B) 선택

유사한 성능을 내는 대안으로 미니맥스 M2.7 모델이 있었습니다.
SW벤치프로 점수도 56.2점으로 비슷했습니다. 하지만 저는 최종적으로 Step 3.7 Flash를 선택했습니다.

선택한 이유: 미니맥스는 200K 컨텍스트를 지원하는 텍스트 전용 모델인 반면, Step 3.7 Flash는 262K 컨텍스트를 지원하는 멀티모달 모델이기 때문입니다.
프론트엔드 작업이나 UI 구현 시 스크린샷을 던지며 핑퐁을 주고받아야 하는 바이브 코딩 환경에서는 비전 기능의 유무가 생산성을 갈랐습니다.
이 선택으로 얻은 가장 큰 이득: 1T급에 근접한 추론 능력을 유지하면서도, 비전 기능과 더 긴 컨텍스트를 동시에 확보할 수 있었다는 점입니다.
대신 감수한 비용: 198B 크기 특성상 최초 프롬프트 프로세싱 단계에서 약간의 지연 시간이 발생합니다.
다만 운영 환경에서는 프리픽스 캐시가 유지되는 한, 이후 6~8 tokens/sec 수준의 출력을 보장하므로 실무적으로 타협할 만한 비용이었습니다.

2. Q5 KM 양자화 모델 채택

선택한 이유: 가용한 하드웨어 자원의 한계로 인해 Q6는 구동이 불가능했습니다.
모델의 성능 손실을 최소화하면서 로컬 메모리에 안정적으로 올릴 수 있는 최적의 타협점이 바로 Q5 KM이었습니다.

구현 핵심 포인트

환경 오염을 막기 위해 코덱스는 도커 컨테이너로 격리하여 실행했습니다.
핵심은 컴포즈 파일에서 볼륨을 매핑할 때, 작업 공간과 설정 폴더를 완전히 분리하여 설계하는 것입니다.

# Dockerfile: Node 기반 이미지로 환경 격리
FROM node:20-alpine

WORKDIR /app
RUN npm install -g @go-codex/codex

CMD ["codex", "serve"]

아래는 컨테이너 내부의 설정 파일들이 휘발되지 않도록 외부 호스트와 연결해 준 핵심 설정입니다.
특히 config.toml 구조를 로컬 호스트와 안전하게 매핑해 주는 부분이 중요합니다.

# docker-compose.yml
version: '3.8'

services:
  codex:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./workspace:/app/workspace
      - ./config:/root/.config/codex # 설정 폴더를 별도로 분리하여 매핑합니다.

코덱스는 기본적으로 자체 연동 모델 외의 메타 정보가 없기 때문에, 사용자가 config.toml에 컨텍스트 길이나 로컬 LM 스튜디오의 엔드포인트를 명확히 명시해 주어야 합니다.

# config.toml
[llm]
api_type = "openai"
api_base = "http://host.docker.internal:1234/v1" # 로컬 LM 스튜디오 연동
model = "step-3.7-flash-198b-q5"
context_window = 262144

사이드프로젝트에서 마주친 문제와 해결

1. 도커 컨테이너 내 파일 접근 권한 문제

어떤 문제가 있었는가: 도커로 코덱스를 실행하자 호스트 파일 시스템의 워크스페이스에 접근할 때 권한 오류가 발생하거나, 호스트에서 생성한 파일이 컨테이너 내부에서 정상적으로 수정되지 않는 현상이 있었습니다.
왜 단순 해결이 어려웠는가: 호스트OS와 도커 내부 컨테이너의 권한 체계가 다르다 보니, 단순히 파일 권한을 777로 푸는 방식은 보안상 위험할 뿐 아니라 근본적인 해결책이 되지 못했습니다.
어떤 방식으로 해결했는가: 컨테이너 실행 시 호스트의 권한 환경을 맞추어 실행하거나, 도커 볼륨 내 샌드박스 실행 권한을 유연하게 조정하여 격리 상태를 유지하면서도 호스트-컨테이너 간의 파일 동기화 문제를 해결했습니다.
남은 한계: 완전히 정제된 프로덕션 환경이 아닌 로컬 테스트 목적의 샌드박스 완화이기 때문에, 추후 다중 사용자 환경으로 확장할 때는 파일 소유권 문제를 추가로 검토해야 합니다.

2. 메타 정보 부재로 인한 모델의 컨텍스트 인지 오작동

어떤 문제가 있었는가: 로컬 LLM을 연동했을 때 코덱스가 모델의 최대 컨텍스트나 성능 한계를 인지하지 못해, 프롬프트가 도중에 잘리거나 답변이 멈추는 현상이 발생했습니다.

왜 단순 해결이 어려웠는가: 코덱스 자체에 외부 로컬 모델에 대한 정보가 내장되어 있지 않다 보니, 수동 정렬 없이는 대형 모델의 컨텍스트를 제대로 활용할 수 없었습니다.
어떤 방식으로 해결했는가: 앞서 언급한 config.toml에 하드코딩 방식으로 context_window 값과 토큰 가이드를 메타 정보로 명확히 주입했습니다.
모델이 스스로의 스코프를 인지하도록 정렬해 줌으로써 컨텍스트가 긴 작업도 안정적으로 처리할 수 있게 되었습니다.
남은 한계: 모델을 바꿀 때마다 토큰 제한과 메타 정보를 매번 수동으로 갱신해 주어야 하는 관리 비용이 존재합니다.

의도적으로 포기한 것과 교훈

이번 환경 구축에서 상용 인프라 수준의 즉각적인 추론 속도는 의도적으로 포기했습니다. 198B 모델을 로컬에서 돌릴 때 최초 프롬프트 처리 시간약 35초 내외 이 걸리는 것은 현재 하드웨어 제약상 당연한 현상입니다.

중요한 것은 "얼마나 즉각적으로 응답하는가"가 아니라, "한 번 구동된 환경에서 프리픽스 캐시를 깨뜨리지 않고 지속적인 수정 피드백을 올바르게 반영하는가"였습니다.

실제로 마우스 포인터를 추적하는 그래픽 파티클 효과를 구현할 때, 지속적인 피드백을 주며 코드를 수정해 나가는 과정에서 단발성 생성보다 훨씬 안정적인 문맥 유지를 보여주었습니다.

사이드프로젝트에서 여러 번 부딪혀 본 결과, 처음부터 실시간 응답을 기대하며 너무 가벼운 8B, 70B 모델을 쓰는 것보다, 속도를 조금 양보하더라도 추론 깊이가 깊은 198B 모델을 올바른 아키텍처로 운영하는 것이 최종 생산성 측면에서 훨씬 이득이었습니다.
기술 선택은 정답 찾기가 아니라 비용 배분에 가깝기 때문입니다.