llmock: OpenAI, Gemini, Anthropic API를 대체하는 결정론적 LLM 모킹 도구

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

LLM 기반 애플리케이션 개발 시 실제 API 호출은 비용 발생, 타임아웃, 비결정론적 응답으로 인해 테스트 자동화의 걸림돌이 된다. llmock은 이러한 문제를 해결하기 위해 OpenAI, Claude, Gemini API를 완벽하게 흉내 내는 로컬 HTTP 서버를 제공한다. 이 도구는 실제 포트에서 실행되어 모든 프로세스가 접근 가능하며, SSE 스트리밍과 WebSocket 통신을 지원하여 실제 운영 환경과 유사한 테스트를 가능하게 한다. 특히 매일 실제 API와의 정렬 상태를 확인하는 드리프트 감지 기능을 통해 모킹 데이터의 신뢰성을 보장한다.

배경

Node.js 및 npm/pnpm 패키지 관리자, OpenAI, Anthropic, Gemini 등 LLM API 사용 경험, 기본적인 E2E 테스트 프레임워크(Playwright 등) 지식

대상 독자

LLM 기반 에이전트나 복잡한 RAG 시스템을 개발하고 자동화된 E2E 테스트를 구축하려는 개발자

의미 / 영향

llmock은 LLM 애플리케이션 개발 주기에서 테스트 비용을 획기적으로 낮추고 CI/CD 파이프라인의 속도를 개선한다. 특히 실제 API와의 정렬을 보장하는 드리프트 감지 기능은 모킹 도구의 고질적인 문제인 '현실과의 괴리'를 해결하여 개발자가 안심하고 모킹 데이터를 신뢰할 수 있게 한다.

섹션별 상세

llmock은 실제 포트에서 구동되는 HTTP 서버를 생성하여 Next.js, Mastra, LangGraph 등 모든 외부 프로세스가 접근할 수 있는 통합 테스트 환경을 제공한다. 이는 단순히 프로세스 내부의 호출을 가로채는 MSW와 달리, 여러 마이크로서비스나 워커가 동일한 모킹 엔드포인트를 공유할 수 있게 한다.

OpenAI, Claude, Gemini 등 주요 제공자의 고유한 SSE(Server-Sent Events) 형식을 완벽하게 지원하여 스트리밍 및 비스트리밍 모드 모두에서 실제 API와 동일한 데이터 흐름을 재현한다. 이를 통해 프론트엔드 UI의 스트리밍 렌더링이나 복잡한 에이전트 워크플로를 실제 비용 지출 없이 테스트할 수 있다.

JSON 피스처 파일을 통해 응답을 정의하며, 단순 텍스트 매칭뿐만 아니라 정규표현식이나 사용자 정의 조건(Predicate)을 활용한 라우팅이 가능하다. 시스템 프롬프트의 특정 플래그나 메시지 이력을 검사하여 에이전트의 상태에 따른 동적 응답을 설정할 수 있어 복잡한 멀티턴 대화 시나리오를 구성하기 용이하다.

json

{
  "fixtures": [
    {
      "match": {
        "userMessage": "stock price of AAPL"
      },
      "response": {
        "content": "The current stock price of Apple Inc. (AAPL) is $150.25."
      }
    }
  ]
}

특정 사용자 메시지에 대해 텍스트 응답을 반환하도록 설정하는 JSON 피스처 예시

실제 API와의 규격 불일치를 방지하기 위해 SDK 타입, 실제 API 응답, 모킹 출력을 삼각 비교하는 드리프트 감지(Drift Detection) 시스템을 운영한다. 매일 자동 실행되는 CI 테스트를 통해 제공자의 API 변경 사항을 즉각 감지하며, 규격이 어긋날 경우 테스트를 실패 처리하여 개발자가 잘못된 모킹 데이터로 인해 프로덕션 장애를 겪지 않도록 보호한다.

typescript

import { LLMock } from "@copilotkit/llmock";
const mock = new LLMock({ port: 5555 });

mock.loadFixtureDir("./fixtures/openai");
const url = await mock.start();

process.env.OPENAI_BASE_URL = `${url}/v1`;
process.env.OPENAI_API_KEY = "mock-key";

llmock 서버를 시작하고 환경 변수를 설정하여 API 호출을 가로채는 TypeScript 코드

OpenAI Realtime 및 Gemini Live와 같은 최신 WebSocket 기반 API를 지원하며, 오디오/비디오를 제외한 텍스트 및 도구 호출 경로에 대해 RFC 6455 프레임워크를 준수하는 통신을 제공한다. 또한 429(Rate Limit), 503(Service Unavailable) 등 일회성 에러 주입 기능을 통해 애플리케이션의 예외 처리 로직을 손쉽게 검증할 수 있다.

실무 Takeaway

비용과 지연 시간이 발생하는 실제 LLM API 대신 llmock을 사용하면 로컬 환경에서 1ms 미만의 응답 속도로 결정론적인 E2E 테스트를 수행할 수 있다.
JSON 피스처에 Predicate 로직을 결합하여 시스템 프롬프트 상태나 대화 맥락에 따른 정교한 에이전트 응답 시나리오를 구축할 수 있다.
Playwright와 같은 테스트 러너의 글로벌 셋업 단계에서 llmock을 실행하고 OPENAI_BASE_URL 환경 변수를 수정하는 것만으로 기존 코드 수정 없이 모킹을 적용할 수 있다.

언급된 리소스

GitHubllmock GitHub Repository

DemoCopilotKit Test Suite Examples