배포 전략 & AI CI/CD
Vercel 환경에서 AI 기능의 배포, 롤아웃, 테스트, 롤백 전략을 정리합니다.
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 | 저비용 모델 기본 | 합성 데이터 | 낮은 한도 |
| Preview | production 동일 모델 허용 | 합성 + 샘플 데이터 | 중간 한도 |
| Staging | production 동일 | 마스킹된 실데이터 | production 동일 |
| Production | Gateway 정책에 따름 | 실데이터 | 예산 관리 |
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가 준비돼 있는가
- 모델/프롬프트 변경의 비용 영향을 사전에 추정하는가