본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
Vercel 엔터프라이즈 AI 플랫폼

플랫폼 기초

플랫폼 아키텍처AI SDK 런타임AI Gateway 제어면

실행 런타임

Workflow 장기 실행Sandbox 실행 격리MCP 데이터 계층Queues & 비동기 작업 관리

프롬프트 & 품질

프롬프트 엔지니어링 & 가드레일RAG & 검색 증강 생성관측성·평가

운영 체계

보안·거버넌스비용·안정성배포 전략 & AI CI/CD

실전 시나리오

고객지원 에이전트 아키텍처내부 리서치 에이전트 아키텍처승인형 백오피스 자동화코딩 오케스트레이션

오케스트레이션 패턴

그래프 중심 오케스트레이션실무 오케스트레이션 플레이북멀티 에이전트 아키텍처

부록

마이그레이션 가이드레퍼런스검증 리포트업데이트 내역
핸드북›Vercel 엔터프라이즈 AI›배포 전략 & AI CI/CD
한국어English

배포 전략 & AI CI/CD

Vercel 환경에서 AI 기능의 배포, 롤아웃, 테스트, 롤백 전략을 정리합니다.

핵심 요약

  • AI 기능 배포는 eval -> preview -> canary -> full rollout 파이프라인을 따르고 빠른 롤백을 기본으로 둡니다.
  • 배포 전 golden set offline eval로 통과율 85%·relevance 0.8·faithfulness 0.9·비용 +20% 이내 같은 게이트를 통과시킵니다.
  • 카나리는 510% 비율로 2448시간 관찰하고, p95 latency 2배 초과 시 자동 롤백합니다.
  • Feature flag로 모델 전환·점진 롤아웃·프롬프트 A/B를 배포 없이 제어하고, AI kill-switch를 반드시 준비합니다.
  • Vercel CLI v50.37.1은 vercel deploy 시 에이전트 플러그인 자동 설치와 AGENTS.md/CLAUDE.md 컨텍스트 주입을 지원합니다.

AI 기능 배포는 일반 코드 배포보다 불확실성이 큽니다. 프롬프트 한 줄만 바꿔도 전체 품질이 흔들리고, 모델을 갈아끼우면 비용과 지연시간이 함께 움직입니다. 그래서 AI 배포는 preview → canary → production 단계와 빠른 롤백을 기본으로 둡니다.

Vercel CLI v50.37.1 — AI 에이전트 통합

Vercel CLI v50.37.1에 AI 에이전트 워크플로를 강화하는 기능이 들어왔습니다.

기능설명CI/CD 영향
AI 에이전트 플러그인 자동 설치vercel deploy 시 에이전트 플러그인을 감지하고 자동 설치수동 설정 단계 제거
AGENTS.md 추가 프롬프트프로젝트 내 AGENTS.md를 AI 에이전트 컨텍스트로 자동 주입에이전트가 프로젝트 규칙을 준수
CLAUDE.md 추가 프롬프트CLAUDE.md도 동일하게 프롬프트로 활용Claude 기반 에이전트에 프로젝트 맞춤 지침 전달

운영 권장

AGENTS.md에 배포 금지 규칙, 테스트 필수 게이트, 승인 절차를 적어두면 AI 에이전트가 CI/CD 파이프라인에서 그 규칙을 알아서 따릅니다.

AI 배포가 다른 점

일반 코드 배포AI 기능 배포
동작이 결정적동일 입력에도 출력이 달라질 수 있음
테스트로 정확성 보장평가(eval)로 품질 범위 확인
롤백 기준이 명확품질 저하 감지가 느릴 수 있음
비용 영향 예측 가능모델/프롬프트 변경이 비용을 크게 바꿀 수 있음

배포 파이프라인

단계별 설계

1. Preview Deployment

Vercel의 PR별 Preview Deployment를 AI 기능 검증에 씁니다.

활용 방법목적
프롬프트 변경 미리보기응답 품질 사전 확인
모델 변경 테스트지연시간/비용 비교
tool schema 변경 검증호환성 확인
팀 리뷰어에게 테스트 URL 공유human evaluation
# AI 기능 PR 체크리스트
- [ ] Preview에서 주요 시나리오 테스트 완료
- [ ] 프롬프트 변경 시 golden set eval 통과
- [ ] 모델 변경 시 비용 추정치 확인
- [ ] tool schema 변경 시 하위 호환성 확인

2. Offline Evaluation

배포 전에 golden set으로 품질을 측정합니다.

interface EvalCase {
  input: string
  expectedOutput?: string
  criteria: ('relevance' | 'faithfulness' | 'format')[]
}

async function runEval(cases: EvalCase[], config: ModelConfig) {
  const results = await Promise.all(
    cases.map(async (c) => {
      const output = await generateText({ model: config.model, prompt: c.input })
      const scores = await evaluateOutput(output.text, c)
      return { input: c.input, output: output.text, scores }
    })
  )

  const summary = {
    avgRelevance: avg(results.map((r) => r.scores.relevance)),
    avgFaithfulness: avg(results.map((r) => r.scores.faithfulness)),
    passRate: results.filter((r) => allPass(r.scores)).length / results.length,
  }

  return summary
}
기준통과 조건 예시실패 시 액션
전체 통과율85% 이상배포 차단
relevance 평균0.8 이상프롬프트 검토
faithfulness 평균0.9 이상RAG/context 검토
비용 증가율기존 대비 +20% 이내모델/프롬프트 재검토

3. Canary Release

항목권장 기본값이유
카나리 비율5~10%위험 최소화
관찰 기간24~48시간다양한 패턴 노출
비교 지표latency, spend, quality동시에 세 가지 확인
자동 롤백 기준p95 latency 2배 초과사용자 경험 보호

4. Production Monitoring

배포 후 모니터링해야 할 AI 전용 지표:

지표알림 기준대응
TTFT 증가기준선 대비 50% 이상모델/Gateway 확인
Spend 급증일일 예산 80% 도달rate limit 또는 롤백
Schema failure 증가5% 초과프롬프트/모델 검토
Escalation 급증정상 대비 2배즉시 롤백 검토
Tool failure 증가1% 초과tool/sandbox 확인

환경 분리

환경AI 모델 정책데이터 정책비용 통제
Development저비용 모델 기본합성 데이터낮은 한도
Previewproduction 동일 모델 허용합성 + 샘플 데이터중간 한도
Stagingproduction 동일마스킹된 실데이터production 동일
ProductionGateway 정책에 따름실데이터예산 관리

Feature Flag로 AI 기능 제어

용도플래그 예시효과
모델 전환ai.model.primary = gpt-5-mini배포 없이 모델 교체
기능 점진 도입ai.feature.rag = 10%점진적 롤아웃
프롬프트 A/B 테스트ai.prompt.version = v2효과 비교
비상 차단ai.kill-switch = true즉시 AI 기능 비활성화

실무 해석

AI kill-switch는 과잉 방어가 아닙니다. 모델 장애나 비용 폭발, 품질 급락이 닥쳤을 때 AI 기능만 빠르게 끄는 스위치는 프로덕션에 반드시 둬야 합니다.

롤백 전략

시나리오롤백 방법소요 시간
코드/프롬프트 롤백Vercel instant rollback수초
모델 롤백Gateway provider order 변경수초
feature flag 롤백flag 값 변경수초
RAG 인덱스 롤백이전 인덱스 snapshot 복원수분
전체 AI 기능 비활성화kill-switch수초

CI/CD 파이프라인 예시

# .github/workflows/ai-deploy.yml 개념
steps:
  - name: Lint & Type Check
    run: yarn lint && yarn typecheck

  - name: Offline Eval
    run: yarn eval:run --golden-set=golden.json
    # 통과율 85% 미만이면 실패

  - name: Deploy to Preview
    run: vercel deploy --prebuilt

  - name: Smoke Test on Preview
    run: yarn test:smoke --url=$PREVIEW_URL

  - name: Deploy to Production (canary)
    run: vercel promote --canary=10%
    # 24시간 모니터링 후 전체 롤아웃

ADR 스타일 결론

Decision

AI 기능 배포는 eval → preview → canary → full rollout 파이프라인을 따릅니다. 프롬프트와 모델 변경은 코드 변경과 동일한 리뷰/테스트 수준을 적용하고, kill-switch와 instant rollback을 기본으로 준비합니다.

실무 체크리스트

  • golden set eval이 CI에 포함돼 있는가
  • Preview에서 AI 기능을 팀이 테스트할 수 있는가
  • 카나리 배포와 관찰 기간이 설정돼 있는가
  • AI kill-switch가 준비돼 있는가
  • 모델/프롬프트 변경의 비용 영향을 사전에 추정하는가

관련 문서

  • Vercel Deployments
  • Vercel Preview Deployments
  • Vercel Instant Rollback
  • AI Gateway Overview
  • Observability

관련 문서

Ch7. 롤백 전략

Prisma Production Guardrails · 코드 롤백 우선, 데이터는 롤포워드, PITR은 최후 수단이라는 우선순위와 호환성 창 운영, 롤백 결정 트리, 비즈니스 승인 체계를 다룹니다.

Ch6. Vercel 배포 전략

엔터프라이즈 프로젝트 설계 · 모노레포 배포 구조, Preview 환경, Rolling Releases, 환경 변수 관리, turbo prune

관측성·평가

AI Gateway, Workflow, Vercel Observability, AI SDK telemetry를 연결해 품질과 운영 신호를 하나의 루프로 관리하는 방법을 정리합니다.

마이그레이션 가이드

LangChain, LangGraph, 커스텀 오케스트레이션에서 Vercel AI 스택으로 전환할 때의 개념 매핑과 전환 전략을 정리합니다.

Ch13. 레퍼런스와 아키텍처 결정 기록

엔터프라이즈 프로젝트 설계 · ADR 템플릿, 기술 선택 근거, 전체 참고 문헌

비용·안정성

비용, 지연시간, 에러 버짓을 함께 관리해 엔터프라이즈 AI 제품의 운영 연속성을 확보하는 방법을 정리합니다.

고객지원 에이전트 아키텍처

고객-facing 챗/지원 에이전트를 AI SDK, AI Gateway, MCP, escalation 구조로 설계하는 방법을 정리합니다.

On this page

Vercel CLI v50.37.1 — AI 에이전트 통합AI 배포가 다른 점배포 파이프라인단계별 설계1. Preview Deployment2. Offline Evaluation3. Canary Release4. Production Monitoring환경 분리Feature Flag로 AI 기능 제어롤백 전략CI/CD 파이프라인 예시ADR 스타일 결론실무 체크리스트관련 문서