로컬 LLM을 사용하여 ASP.NET Core MimimalAPI에서 API를 자동으로 시뮬레이션 | Kevin Logan

프로그래밍 C# / .NET
, ,
1

llm-api #ASP.NET-Core #Mock-API ollama #테스트-데이터

개요: LLM 기반 자동 Mock API 생성 시스템

mostlylucid.mockllmapi는 로컬 LLM(Ollama)을 활용하여 ASP.NET Core 애플리케이션에서 실시간으로 현실적인 Mock API 응답을 자동 생성하는 경량 미들웨어입니다. 단 2줄의 코드만으로 지능형 Mock 엔드포인트를 추가할 수 있으며, 복잡한 테스트 데이터 관리 없이 변동성 높은 샘플 데이터를 동적으로 생성합니다.

핵심 개념 및 활용 시나리오

핵심 문제 해결

개발 초기 단계에서는 실제 데이터 없이도 기능을 테스트해야 하는 Catch-22 상황이 발생합니다. 본 패키지는 이 문제를 LLM의 고급 데이터 생성 능력을 활용하여 해결합니다.

주요 사용 사례

  • 프론트엔드 개발: 백엔드 완성 대기 없이 현실적 데이터 흐름 테스트
  • API 설계 검증: 응답 구조 결정 전에 동작 방식 실험
  • 데모 및 프로토타입: 하드코딩된 픽스처 없이 다양한 데이터 시나리오 시연
  • 단위/통합 테스트: 엣지 케이스 테스트용 변동성 높은 데이터 자동 생성
  • 학습 자료: .NET에서의 LLM 통합 구현 사례 학습

주요 기능 및 특징

1. 초간단 구현

  • 서비스 등록: builder.Services.Addmostlylucid.mockllmapi()
  • 엔드포인트 매핑: app.Mapmostlylucid.mockllmapi("/api/mock")
  • 단 2줄로 Mock API 시스템 완성

2. 고도의 설정 가능성

  • appsettings.json을 통한 중앙 집중식 설정
  • 인라인 코드 설정으로 프로그래밍적 제어
  • 여러 Mock API 인스턴스 동시 운영 가능 (개발/테스트 환경별 구분)

3. 정교한 응답 형태 제어 (Shape Control)

JSON 스키마를 통해 정확한 응답 구조 지정:

  • HTTP 헤더: X-Response-Shape 헤더로 전달 (권장)
  • 쿼리 매개변수: URL 인코딩된 JSON 형태
  • 요청 본문: 요청 body 내 shape 필드로 지정

4. 실시간 스트리밍 지원

  • Server-Sent Events (SSE) 기반 점진적 JSON 생성
  • /api/mock/stream/** 엔드포인트로 실시간 데이터 전송
  • 클라이언트가 생성 중 데이터를 즉시 처리 가능

5. 매우 높은 데이터 변동성

  • 각 요청마다 완전히 다른 현실적 데이터 생성
  • Temperature 설정으로 변동성 조절 (1.2-1.5: 높은 변동, 0.3: 안정적 데이터)
  • 랜덤 시드와 타임스탬프로 고유성 보장

6. 모든 HTTP 메서드 지원

GET, POST, PUT, DELETE, PATCH 모두 지원하는 와일드카드 라우팅

7. 선택적 스키마 반환

생성된 데이터의 구조 정보를 응답 헤더나 SSE 이벤트로 반환:

  • 클라이언트 측 TypeScript 타입 생성에 활용
  • API 문서화 및 스키마 검증 자동화
  • 런타임 유효성 검사 지원

8. 응답 캐싱 메커니즘

  • Shape 객체 내 "$cache": N 필드로 N개 응답 사전 생성 및 캐싱
  • 캐시 키: HTTP 메서드 + 경로 + 정규화된 Shape (XXHash64 사용)
  • 캐시된 응답 소진 시 자동으로 새 배치 생성
  • 스트리밍 엔드포인트는 캐싱 대상 제외

빠른 시작 가이드

설치 및 환경 구성

1단계: 필수 도구 설치

# .NET 8.0 SDK 이상 설치 (이미 설치된 경우 건너뛰기)
https://dotnet.microsoft.com/download/dotnet/8.0

# Ollama 설치 및 모델 다운로드
https://ollama.ai/
ollama pull llama3

2단계: NuGet 패키지 추가

dotnet add package mostlylucid.mockllmapi

기본 사용법

Program.cs 설정

using mostlylucid.mockllmapi;

var builder = WebApplication.CreateBuilder(args);

// LLMock API 서비스 추가
builder.Services.Addmostlylucid.mockllmapi(builder.Configuration);

var app = builder.Build();

// Mock 엔드포인트를 /api/mock에 매핑
app.Mapmostlylucid.mockllmapi("/api/mock");

app.Run();

appsettings.json 설정 (권장)

{
  "mostlylucid.mockllmapi": {
    "BaseUrl": "http://localhost:11434/v1/",
    "ModelName": "llama3",
    "Temperature": 1.2
  }
}

이 설정만으로 /api/mock/**로 들어오는 모든 요청에 지능형 Mock 데이터 반환!

설정 옵션 상세 가이드

JSON 기반 설정 (권장)

{
  "mostlylucid.mockllmapi": {
    "BaseUrl": "http://localhost:11434/v1/",
    "ModelName": "llama3",
    "Temperature": 1.2,
    "TimeoutSeconds": 30,
    "EnableVerboseLogging": false,
    "CustomPromptTemplate": null,
    "IncludeShapeInResponse": false,
    "MaxCachePerKey": 5
  }
}

코드 기반 설정

builder.Services.Addmostlylucid.mockllmapi(options =>
{
    options.BaseUrl = "http://localhost:11434/v1/";
    options.ModelName = "mixtral";
    options.Temperature = 1.5;
    options.TimeoutSeconds = 60;
});

엔드포인트 패턴 커스터마이징

// 기본값: /api/mock/** 및 /api/mock/stream/**
app.Mapmostlylucid.mockllmapi("/api/mock");

// 커스텀 패턴
app.Mapmostlylucid.mockllmapi("/demo");
// 생성: /demo/** 및 /demo/stream/**

// 스트리밍 없이
app.Mapmostlylucid.mockllmapi("/api/mock", includeStreaming: false);

실제 사용 예제

예제 1: 기본 요청

curl http://localhost:5000/api/mock/users?limit=5

결과: LLM이 생성한 현실적인 사용자 데이터 반환

예제 2: 정확한 구조 제어 (Shape 사용)

curl -X POST http://localhost:5000/api/mock/orders \
  -H "X-Response-Shape: {\"orderId\":\"string\",\"total\":0.0,\"items\":[{\"sku\":\"string\",\"qty\":0}]}" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"cus_123"}'

결과: 지정된 JSON 구조에 정확히 맞는 데이터 생성

예제 3: 실시간 스트리밍

curl -N http://localhost:5000/api/mock/stream/products?category=electronics \
  -H "Accept: text/event-stream"

반환 형식 (Server-Sent Events):

data: {"chunk":"{","done":false}
data: {"chunk":"\"id\"","done":false}
...
data: {"content":"{완전한 JSON}","done":true}

예제 4: 스키마 포함 응답

curl "http://localhost:5000/api/mock/users?shape=%7B%22id%22%3A0%2C%22name%22%3A%22string%22%7D&includeSchema=true"

응답 헤더:

X-Response-Schema: {"id":0,"name":"string"}

고급 기능

1. 응답 스키마 내보내기

생성된 응답의 JSON 구조를 헤더나 SSE 이벤트로 반환하여 클라이언트 타입 생성 자동화:

전역 활성화:

{
  "mostlylucid.mockllmapi": {
    "IncludeShapeInResponse": true
  }
}

요청별 오버라이드:

curl "http://localhost:5000/api/mock/users?includeSchema=true"

스트리밍 응답에 포함:

data: {"content":"{full json}","done":true,"schema":{"id":0,"name":"string"}}

주요 제약사항:

  • Shape가 제공되지 않으면 헤더 미포함
  • 매우 큰 Shape (> 4000자)는 전송 문제 회피를 위해 헤더 제외 (응답은 정상 생성)

2. 커스텀 프롬프트 템플릿

LLM에 전달되는 프롬프트를 완전히 제어:

{
  "mostlylucid.mockllmapi": {
    "CustomPromptTemplate": "Generate mock data for {method} {path}. Body: {body}. Use seed: {randomSeed}"
  }
}

사용 가능한 플레이스홀더:

  • {method}: HTTP 메서드 (GET, POST 등)
  • {path}: 전체 요청 경로 (쿼리 문자열 포함)
  • {body}: 요청 본문
  • {randomSeed}: 생성된 GUID 랜덤 시드
  • {timestamp}: Unix 타임스탬프
  • {shape}: Shape 스펙 (제공된 경우)

3. 여러 Mock API 인스턴스 구성

개발/테스트 환경별로 다른 성격의 데이터 생성:

// 높은 변동성의 개발용 데이터
builder.Services.Addmostlylucid.mockllmapi("Dev", options =>
{
    options.Temperature = 1.5;
    options.ModelName = "llama3";
});

// 안정적인 테스트 데이터
builder.Services.Addmostlylucid.mockllmapi("Test", options =>
{
    options.Temperature = 0.3;
    options.ModelName = "llama3";
});

app.Mapmostlylucid.mockllmapi("/api/dev");
app.Mapmostlylucid.mockllmapi("/api/test");

Shape 스펙 상세

Shape 제공 방식 (우선순위 순서)

  1. 쿼리 매개변수 (최우선): ?shape=%7B%22field%22%3A%22type%22%7D
  2. HTTP 헤더: X-Response-Shape: {"field":"type"}
  3. 요청 본문 필드: {"shape": {...}, "actualData": ...}

응답 캐싱 메커니즘 상세

Shape 객체 내에 특수 필드 "$cache": N을 포함하여 N개의 응답을 사전 생성 및 캐싱:

헤더 기반 Shape:

X-Response-Shape: {"$cache":3,"orderId":"string","status":"string","items":[{"sku":"string","qty":0}]}

본문 기반 Shape:

{
  "shape": {
    "$cache": 5,
    "invoiceId": "string",
    "customer": {
      "id": "string",
      "name": "string"
    },
    "items": [
      {
        "sku": "string",
        "qty": 0,
        "price": 0.0
      }
    ],
    "total": 0.0
  }
}

쿼리 매개변수 (URL 인코딩):

?shape=%7B%22%24cache%22%3A2%2C%22users%22%3A%5B%7B%22id%22%3A0%2C%22name%22%3A%22string%22%7D%5D%7D

캐싱 메커니즘 동작 원리:

  • 캐시 키: HTTP 메서드 + 경로 + 정규화된 Shape (XXHash64 알고리즘 사용)
  • 초기 요청 시 N개 응답을 LLM에서 생성하여 메모리 캐시에 저장
  • 후속 비스트리밍 요청은 캐시 큐에서 응답 소진하며 제공
  • 캐시 소진 시 자동으로 새 배치 N개 생성
  • 스트리밍 엔드포인트는 캐싱 미적용
  • 앱 재시작 시 캐시 초기화

설정:

  • MaxCachePerKey (기본값: 5): “$cache” 요청값의 상한선

중요 사항:

  • "$cache" 필드는 LLM 프롬프트 전달 전에 제거됨
  • "$cache" 미포함 또는 0이면 캐싱 없이 즉시 생성 (이전과 동일)

테스트 방법 및 커버리지

HTTP 클라이언트를 이용한 테스트

포함된 LLMApi.http 파일 활용:

  • Visual Studio / Rider HTTP 클라이언트
  • VS Code REST Client 확장 프로그램
  • 기타 HTTP 클라이언트

자동화된 단위 테스트 실행

# 모든 테스트 실행
dotnet test

# 상세 출력 포함
dotnet test --verbosity detailed

테스트 커버리지

✓ 요청 본문 읽기 (빈 본문, JSON 콘텐츠)
✓ Shape 추출 (쿼리 매개변수, 헤더, 본문 필드, 우선순위)
✓ 프롬프트 생성 (변동성, Shape 포함, 스트리밍 모드)
✓ 요청 빌드 (Temperature, 모델, 메시지)
✓ 엣지 케이스 (유효하지 않은 JSON, 누락된 데이터)

시스템 아키텍처

요청 처리 흐름

  1. 클라이언트 → Mock API로 GET/POST/PUT/DELETE 요청 전송
  2. LLMApi 미들웨어 → 컨텍스트 추출 (메서드, 경로, 본문, Shape)
  3. AutoApiHelper → 랜덤 시드 + 타임스탐프 생성
  4. 프롬프트 생성 → 변동성이 높은 프롬프트 구성
  5. Ollama 호출 → POST /v1/chat/completions 요청
  6. LLM 추론 → llama3 (또는 선택한 모델)에서 JSON 생성
  7. 응답 반환 → 생성된 JSON을 클라이언트에 전달

Shape 제어 흐름

요청 도착
  ↓
쿼리 매개변수에 Shape 있음? → YES → 쿼리 Shape 사용
  ↓ NO
헤더에 Shape 있음? → YES → 헤더 Shape 사용
  ↓ NO
본문 필드에 Shape 있음? → YES → 본문 Shape 사용
  ↓ NO
제약 없이 자유 생성
  ↓
프롬프트 빌드
  ↓
랜덤 시드 + 타임스탬프 추가
  ↓
LLM으로 전송

프로젝트 구조

  • mostlylucid.mockllmapi: 핵심 NuGet 패키지 라이브러리
  • LLMApi: 데모 애플리케이션
  • LLMApi.Tests: xUnit 기반 13개 테스트 스위트

실제 적용 효과

1. 신속한 프로토타이핑 (Rapid Prototyping)

백엔드 구현 완료 대기 없이 프론트엔드 개발 병렬 진행 가능

2. 데모 및 시연

하드코딩된 픽스처 없이 현실적인 데이터 흐름 구현

3. 테스트 (Testing)

엣지 케이스 검증용 변동성 높은 테스트 데이터 자동 생성

4. API 설계 검증 (API Design)

구현 전 응답 구조 실험 및 검증

5. .NET에서의 LLM 통합 학습

ASP.NET Core Minimal API에서 LLM을 활용한 구현 사례 제시

6. 0 유지보수 (Zero Maintenance)

별도의 데이터베이스, 상태 관리, Mock 데이터 파일 불필요

NuGet 패키지 빌드 방법

cd mostlylucid.mockllmapi
dotnet pack -c Release

패키지 출력 경로: bin/Release/mostlylucid.mockllmapi.{version}.nupkg

배포 및 기여

라이선스

Public Domain - 제약 없이 자유롭게 사용 가능
Unlicense 참고

커스터마이징

본 프로젝트를 자유롭게 포크하여 필요에 맞게 커스터마이징 가능

NuGet 페이지

주요 특징 요약

특징 설명
초간단 구현 2줄 코드로 Mock API 시스템 완성
지능형 데이터 LLM 기반 현실적 Mock 데이터 자동 생성
정교한 제어 Shape 스펙을 통한 정확한 응답 구조 제어
실시간 스트리밍 SSE 기반 점진적 데이터 전송
높은 변동성 각 요청마다 완전히 다른 데이터 생성
캐싱 지원 선택적 응답 사전 생성 및 캐싱
다중 인스턴스 환경별 다른 특성의 데이터 생성 가능
스키마 내보내기 생성된 구조 정보 자동 반환
포괄적 테스트 13개의 xUnit 테스트로 검증 완료

참고 링크 및 자료

추가 학습 리소스

관련 개념

  • ASP.NET Core Minimal APIs: 경량 API 구축 패턴
  • Server-Sent Events (SSE): 실시간 스트리밍 통신
  • LLM 통합: .NET 환경에서의 로컬/원격 LLM 활용
  • Mock 데이터 생성: 테스트 및 개발 프로세스 최적화

확장 가능성

  • 캐싱 확장: Redis 등 분산 캐시 통합
  • 성능 최적화: 모델 선택 및 Temperature 튜닝
  • 다중 모델 지원: 모델별 특성에 따른 동적 선택
  • 로깅 강화: 추적 및 디버깅용 상세 로깅 시스템