Vercel 배포 가이드

Vercel 배포 가이드 (Vercel Deployment Guide)

Next.js(App Router)로 만든 AI 애플리케이션을 Vercel에 배포하는 방법을 설명하는 문서예요.

출처: 문서

본문

이 가이드에서는 Next.js(App Router)를 사용해 만든 AI 애플리케이션을 Vercel에 배포해요.

Vercel은 개발자를 위한 플랫폼으로, 추가 설정 없이 웹 앱을 더 빨리 구축하고 배포하는 데 필요한 도구, 워크플로, 인프라를 제공해요.

Vercel은 GitHub, GitLab, Bitbucket 프로젝트의 모든 브랜치 푸시와 프로덕션 브랜치로의 병합 시 자동 배포를 지원해요. AI 애플리케이션을 배포하기에 좋은 선택이에요.

시작하기 전에 (Before You Begin)

이 가이드를 따라 하려면 다음이 필요해요:

Vercel 계정
Git 프로바이더 계정 (이 튜토리얼은 Github을 사용해요)
OpenAI API 키

이 가이드는 Next.js(App Router) 퀵스타트 튜토리얼에서 만든 애플리케이션을 Vercel에 배포하는 방법을 알려줘요. 퀵스타트 가이드를 아직 완료하지 않았다면 이 저장소에서 시작할 수 있어요.

변경 사항 커밋 (Commit Changes)

Vercel은 강력한 git 중심 워크플로를 제공하며, 저장소의 main 브랜치에 푸시할 때마다 애플리케이션을 프로덕션에 자동 배포해요.

로컬 변경 사항을 커밋하기 전에 .gitignore가 있는지 확인하세요. .gitignore 안에서 환경 변수(.env)와 node modules(node_modules)를 제외하고 있는지 확인하세요.

로컬 변경 사항이 있다면 다음 명령으로 커밋할 수 있어요:

git add .
git commit -m "init"

Git 저장소 만들기 (Create Git Repo)

터미널에서 또는 github.com에서 GitHub 저장소를 만들 수 있어요. 이 튜토리얼에서는 GitHub CLI(자세한 정보)를 사용해요.

GitHub 저장소를 만들려면:

github.com으로 이동하기
오른쪽 상단에서 "plus" 아이콘을 클릭하고 "New repository" 선택하기
저장소 이름 정하기 (아무거나 가능)
"Create repository" 클릭하기

저장소를 만들면 GitHub가 새 저장소로 리다이렉트해요.

페이지를 아래로 스크롤해 "...or push an existing repository from the command line" 제목 아래의 명령 복사하기
터미널로 돌아가 명령을 붙여 넣고 실행하기

참고: "error: remote origin already exists." 오류가 발생한다면, 로컬 저장소가 여전히 클론한 저장소에 연결되어 있기 때문이에요. "연결 해제"하려면 다음 명령을 실행하면 돼요:

rm -rf .git
git init
git add .
git commit -m "init"

이전 단계의 코드 스니펫을 다시 실행하세요.

Vercel에 프로젝트 가져오기 (Import Project in Vercel)

New Project 페이지의 Import Git Repository 섹션에서 프로젝트를 가져올 Git 프로바이더를 선택하세요. GitHub 계정에 로그인하라는 프롬프트를 따라 진행하세요.

로그인하면 이전 단계에서 만든 새 저장소가 "Import Git Repository" 섹션에 보일 거예요. 해당 프로젝트 옆의 "Import" 버튼을 클릭하세요.

환경 변수 추가 (Add Environment Variables)

애플리케이션은 환경 시크릿을 사용해 OpenAI API 키를 로컬 개발에서 .env.local 파일로 저장해요. 이 API 키를 프로덕션 배포에 추가하려면 "Environment Variables" 섹션을 펼치고 .env.local 파일을 붙여 넣으세요. Vercel이 변수를 자동으로 파싱해 적절한 key:value 형식으로 입력해요.

배포 (Deploy)

Deploy 버튼을 누르세요. Vercel이 선택한 구성에 따라 Project를 만들고 배포할 거예요.

축하합니다! (Enjoy the confetti!)

배포를 보려면 대시보드에서 Project를 선택한 다음 Domain을 선택하세요. 이제 이 페이지는 URL을 가진 누구에게나 보여요.

고려사항 (Considerations)

AI 애플리케이션을 배포할 때 알아야 할 인프라 관련 고려사항이 있어요.

함수 지속시간 (Function Duration)

대부분의 경우 서버에서 대규모 언어 모델(LLM)을 호출할 거예요. 기본적으로 Vercel serverless 함수는 Hobby Tier에서 최대 10초의 지속시간을 가져요. 프롬프트에 따라 LLM이 응답을 완료하는 데 이 제한을 초과할 수 있어요. 이 제한 내에서 응답이 완료되지 않으면 서버가 오류를 던져요.

route segment config를 사용해 Vercel 함수의 최대 지속시간을 지정할 수 있어요. 최대 지속시간을 업데이트하려면 라우트 핸들러나 서버 액션을 호출하는 페이지의 최상단에 다음 route segment config를 추가하세요.

export const maxDuration = 30;

Hobby Tier에서는 최대 지속시간을 60초까지 늘릴 수 있어요. 다른 티어의 제한은 문서를 참고하세요.

요청 취소 (Request Cancellation)

useChat, useCompletion 같은 AI SDK UI 헬퍼는 stop()을 호출하면 클라이언트 요청을 중단해요. 그 취소를 Vercel Function과 그 모델 요청에 전파하려면 다음을 수행해야 해요:

Next.js 라우트 핸들러의 기본값인 Node.js 런타임을 사용하세요.
vercel.json에서 해당 라우트에 대해 supportsCancellation을 활성화하세요.
라우트의 req.signal을 streamText 또는 generateText에 abortSignal로 전달하세요.

예를 들어 채팅 라우트에 취소를 활성화하려면:

{
  "functions": {
    "app/api/chat/route.ts": {
      "supportsCancellation": true
    }
  }
}

그런 다음 요청 신호를 AI SDK에 전달하세요:

import { convertToModelMessages, streamText, type UIMessage } from 'ai';
__PROVIDER_IMPORT__;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: __MODEL__,
    messages: convertToModelMessages(messages),
    abortSignal: req.signal,
  });

  return result.toUIMessageStreamResponse();
}

supportsCancellation 없이 stop()을 호출하면 클라이언트 측 스트림은 닫히지만 Vercel Function이나 모델 요청은 취소되지 않아요. 완전한 클라이언트와 서버 설정은 Streams 중지를 참고하세요.

보안 고려사항 (Security Considerations)

LLM 호출 비용이 높기 때문에 애플리케이션을 남용으로부터 보호하는 조치를 마련하는 것이 중요해요.

속도 제한 (Rate Limit)

속도 제한(rate limiting)은 주어진 시간 프레임 내에서 클라이언트가 서버에 보낼 수 있는 최대 요청 수를 정의해 네트워크 트래픽을 규제하는 방법이에요.

애플리케이션에 속도 제한을 추가하려면 이 가이드를 따라 하세요.

방화벽 (Firewall)

방화벽은 애플리케이션과 웹사이트를 DDoS 공격과 무단 접근으로부터 보호하는 데 도움을 줘요.

Vercel Firewall은 보안을 염두에 두고 특별히 만들어진 도구와 인프라 집합이에요. DDoS 공격을 자동으로 완화하며, Enterprise 팀은 IP 차단을 위한 전용 지원과 커스텀 규칙을 포함한 사이트별 추가 커스터마이즈를 받을 수 있어요.

Vercel 배포 가이드