AI 엔지니어링 입문 과정을 로컬에서 실행하기
이 페이지를 사용하여 추출한 Gift Genie 프로젝트를 컴퓨터에서 실행합니다. 현재 과정에는 두 가지 형태의 프로젝트가 있습니다. 브라우저 전용 Vite 앱과 백엔드 마이그레이션 이후의 Express와 Vite 앱입니다. 보유한 형태를 파악한 후 아래의 설정을 따릅니다.
먼저 필요한 것
지원되는 Node.js LTS 버전을 설치합니다. Node 24를 권장합니다. Node 22.12 이상은 과정의 후반부 프로젝트에서 사용하는 Vite 버전도 지원합니다.
Node와 npm이 사용 가능한지 확인합니다:
$ node --version
v24.18.0
$ npm --version
11.18.0npm은 Node에 포함되어 있습니다. 어느 명령이든 "command not found"라고 표시되면 계속하기 전에 Node 설치를 완료합니다.
추출한 프로젝트 파악하기
package.json이 포함된 추출한 폴더로 이동합니다:
$ cd path-to-your-downloaded-project이 페이지의 모든 명령은 해당 폴더에서 실행됩니다.
그런 다음 보유한 프로젝트의 형태를 확인합니다. 브라우저 전용 버전은 index.html과 vite.config.js를 가지고 있으며, start 스크립트는 서버 파일을 실행하지 않습니다. Express와 Vite 버전은 server.js와 vite.config.js를 모두 가지고 있으며, start 스크립트는 이들을 함께 실행합니다.
start 스크립트가 server.js 파일을 실행하면 백엔드 섹션을 따릅니다. 실행하지 않으면 브라우저 전용 버전입니다. 이 확인을 건너뛰었기 때문에 한 번은 잘못된 설명에 오후를 낭비했습니다! 환경 변수 추가하기
Scrimba는 계정 설정에서 세 개의 환경 변수를 제공합니다. 컴퓨터는 해당 설정에 액세스할 수 없으므로 package.json 옆에 .env 파일을 만듭니다:
AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id과정에서 사용한 값을 복사합니다. URL과 모델은 키와 동일한 제공자에 속해야 합니다.
Git을 사용하기 전에 package.json 옆에 .gitignore 파일을 만들고 다음을 추가합니다:
.env
node_modules/Git 핸드북은 왜 이 두 줄이 모든 프로젝트에 속해야 하는지 파일 무시하기 및 좋은 습관에서 설명합니다.
API 키를 절대 커밋하지 마세요
.env 파일에는 유효한 자격증명이 포함되어 있습니다. 업로드하거나 소스 코드에 붙여넣거나 Git에 커밋하지 마세요. 키가 노출된 경우 제공자에서 폐기하고 새 키를 만듭니다.
.env를 변경한 후 프로젝트를 다시 시작합니다. 올바른 실행 명령은 ZIP이 온 과정 부분에 따라 다릅니다.
.env를 package.json 바로 옆에 만들고 세 개의 Scrimba 값을 복사합니다. 이것은 Scrimba가 계정 설정에 보관했던 것과 같은 값이며, 이제 자신의 컴퓨터에 저장된 것입니다. 해당 파일을 Git 외부에 보관합니다. 키 노출은 제가 초기에 저질렀던 실수이므로 여러분은 하지 않아도 됩니다. 브라우저 전용 Gift Genie 실행하기
백엔드 마이그레이션 이전의 Gift Genie 강의는 index.html과 vite.config.js를 가지고 있지만 start 스크립트에서 활성화된 server.js는 없습니다. 프로젝트를 설치하고 시작합니다:
$ npm install
$ npm startVite는 다음과 같은 로컬 주소를 출력합니다:
VITE ready
Local: http://localhost:5173/터미널에 출력된 정확한 Local URL을 엽니다. 포트 5173이 사용 중이면 Vite는 일반적으로 다른 포트를 선택하고 해당 주소를 출력합니다. Vite를 Ctrl+C로 중지합니다.
이 버전은 키를 브라우저에 노출합니다
이 강의는 의도적으로 프론트엔드 JavaScript에서 AI 제공자를 호출합니다. Vite는 AI_KEY를 브라우저 번들에 복사하므로 페이지를 여는 사람은 누구나 브라우저의 개발자 도구에서 키를 읽을 수 있습니다. 로컬 학습을 위해 임시의 제한된 키를 사용합니다. 이 버전을 배포하거나 네트워크에서 공유하지 마세요. 과정 후반의 백엔드 마이그레이션이 빌드해야 할 보안 아키텍처입니다.
npm install을 실행한 후 npm start를 실행하고 기억하는 것이 아니라 Vite가 출력한 정확한 Local URL을 엽니다. Ctrl+C로 중지합니다. 이 습관을 배우는 데 생각보다 오래 걸렸습니다. 백엔드와 함께 Gift Genie 실행하기
백엔드 마이그레이션 이후 강의는 server.js와 vite.config.js를 모두 가지고 있습니다. start 스크립트는 Express와 Vite를 함께 실행합니다. 현재 다운로드는 자동으로 .env를 Express 프로세스에 로드하지 않으므로 시작하기 전에 package.json에서 이 한 가지를 변경합니다.
server 스크립트를 찾습니다:
"server": "node --watch server.js"다음과 같이 변경합니다:
"server": "node --env-file=.env --watch server.js"배포 과정 프로젝트도 서버를 위해 같은 --env-file 변경이 필요합니다.
백엔드 포트를 .env에 추가합니다:
AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id
PORT=3001그런 다음 두 프로세스를 설치하고 시작합니다:
$ npm install
$ npm start포트 3001에 대한 Express 메시지와 Vite Local URL(일반적으로 포트 5173)이 표시됩니다. Vite URL을 엽니다. 포트 3001을 애플리케이션 페이지로 열지 마세요. 브라우저는 /api 요청을 Vite로 보내고 Vite는 이를 Express로 프록시합니다. API 키는 서버 프로세스에 유지됩니다.
Ctrl+C로 두 프로세스를 모두 중지합니다.
백엔드를 포트 3001에 유지하세요
다운로드한 Express 서버는 PORT를 읽지만 Vite 프록시는 http://localhost:3001을 직접 가리킵니다. 다른 프로세스에 해당 포트가 필요하지 않으면 PORT=3001을 유지합니다. 변경하면 vite.config.js의 프록시 대상도 같은 포트로 변경하고 프로젝트를 다시 시작합니다.
PORT=3001을 유지하고 npm install과 npm start를 실행한 후 포트 3001이 아니라 Vite URL을 엽니다. 한 번의 Ctrl+C로 앱의 두 부분을 모두 중지합니다. 처음 봤을 때는 마법 같았습니다. 문제 해결
Missing AI_KEY, 401 응답 또는 인증 오류: 세 변수 이름의 철자를 모두 확인하고, 키가 활성화되어 있는지 확인하고, 프로젝트를 다시 시작합니다. 다른 제공자의 키, URL, 모델은 한 세트로 작동하지 않습니다.
모델을 찾을 수 없거나 제공자가 요청을 거부합니다: 모델 ID를 정확하게 복사합니다. Responses API 도구, 모델이 요청 중에 호출할 수 있는 기본 제공 헬퍼를 포함한 일부 과정 기능은 모든 OpenAI 호환 제공자에서 지원되지 않으며, 이들 제공자가 제공하는 모든 모델에서도 지원되지 않습니다.
npm start가 패키지 또는 명령이 누락되었다고 합니다: 터미널이 package.json이 포함된 폴더에 있는지 확인한 후 npm install을 다시 실행합니다. 다운로드에 다른 패키지 관리자용 lockfile이 포함되어 있으면 두 번째 lockfile을 생성하는 대신 그 lockfile을 따릅니다.
페이지가 열리지만 /api 요청이 실패합니다: 이것은 백엔드 버전에 적용됩니다. Express와 Vite가 모두 여전히 같은 터미널에서 실행 중인지 확인합니다. Express가 포트 3001에 있고 vite.config.js의 프록시 대상도 3001을 말하는지 확인합니다.
EADDRINUSE가 포트 3001을 언급합니다: 다른 프로세스가 백엔드 포트를 사용 중입니다. 해당 프로세스를 중지하거나 .env의 PORT와 Vite 프록시 대상을 모두 사용 가능한 같은 포트로 변경합니다.
Vite가 5174 또는 다른 프론트엔드 포트를 사용합니다: 5173이 사용 중일 때 정상입니다. Vite가 인쇄한 Local URL을 엽니다. Express 포트를 변경할 필요가 없습니다.
package.json이 있는 폴더에 있는지, .env가 세 개의 AI 값을 모두 보유하는지, 그리고 편집 후 다시 시작했는지 확인합니다. 백엔드 버전의 경우 두 프로세스를 모두 실행 중으로 유지합니다. 초기에 본 거의 모든 오류는 이 세 가지 중 하나에서 비롯되었습니다.