Vercel AI SDK 코스를 로컬에서 실행하기

이 페이지를 사용하여 추출한 고객 지원 에이전트를 컴퓨터에서 실행합니다. Express 서버를 OpenAI 및 코스에서 생성한 Supabase 데이터에 연결한 후, Node가 .env에서 이 값들을 로드하도록 시작 스크립트를 한 줄 수정합니다. 임베딩 및 벡터 데이터베이스 가이드는 동일한 종류의 Supabase 벡터 설정에 대해 관련 프로젝트를 실행합니다.

먼저 필요한 것

Node.js의 지원되는 LTS 버전을 설치합니다. Node 24 이상을 권장합니다. 다음도 필요합니다.

청구 및 모델 접근 권한이 있는 OpenAI API 키;
코스 중에 생성한 Supabase 프로젝트 및 데이터;
Supabase 시크릿 키 또는 레거시 service_role 키.

시크릿 및 service_role 키는 Row Level Security를 우회합니다. 이러한 키는 이 서버 측 .env에만 속하며 브라우저 코드에는 절대 포함되지 않습니다. Supabase API 키를 참조합니다.

Juno먼저 필요한 것 Node.js LTS를 설치한 후 코스의 OpenAI 키와 Supabase 프로젝트, 서버 측 키를 준비합니다. 그 Supabase 키는 전체 데이터베이스의 마스터 키 같은 것이므로 절대 브라우저 코드에 들어가면 안 됩니다.

프로젝트 열기 및 설치

package.json이 있는 추출한 폴더에서 터미널을 열고 잠금된 패키지를 설치합니다.

bash

$ cd path-to-your-downloaded-project
$ npm ci

Juno프로젝트 열기 및 설치package.json이 있는 추출한 폴더에서 npm ci를 실행합니다. 코스가 빌드된 정확한 패키지 버전을 설치하므로 구성하거나 추측할 것이 없습니다.

Node가 `.env`를 로드하도록 설정

package.json을 열고 시작 스크립트를:

json

"start": "node server.js"

에서 다음으로 변경합니다.

json

"start": "node --env-file=.env server.js"

코드는 레거시 변수명 SUPABASE_SERVICE_ROLE_KEY를 사용합니다. 코드를 이름을 바꾸지 않고 현재 Supabase 시크릿 키를 그 변수에 넣을 수 있습니다.

package.json 옆에 .env를 만듭니다.

dotenv

OPENAI_API_KEY=your-openai-api-key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-server-side-secret-key
PORT=3000

.gitignore을 만듭니다.

txt

.env
node_modules/

Git 핸드북은 이 방식을 파일 무시 및 좋은 관행에서 다룹니다.

Supabase 키를 서버에만 유지

시크릿 키에 VITE_ 접두사를 붙이거나 client.js로 옮기지 않습니다. 이것은 상승된 데이터베이스 접근 권한을 가집니다. .env을 커밋하거나 ZIP으로 공유하지 않습니다.

JunoNode가 .env를 로드하도록 설정 시작 스크립트에 --env-file=.env를 추가하고, 네 값 모두를 가진 파일을 만들고, Git에서 제외합니다. Supabase 키는 항상 서버에만 있습니다. .gitignore에 .env를 포함하는 것이 모든 프로젝트에서 제가 만드는 첫 파일이며, 어려운 방식으로 배운 것입니다.

제공된 모델 유지

다운로드한 constants.js는 답변 생성 및 분류에 gpt-4o를, 임베딩에 text-embedding-3-small을 사용합니다. 로컬 설정은 어느 모델도 변경할 필요가 없습니다. OpenAI가 프로젝트의 한 모델을 거부하지 않는 한 변경 없이 유지합니다. 나중에 모델을 교체하는 경우, 전체 에이전트 흐름을 테스트하고 새 쿼리 임베딩이 저장된 Supabase 벡터와 호환되는지 확인합니다. 임베딩 교체는 조용히 실패할 수 있습니다. 같은 차원 수이지만 다른 벡터 공간의 모델은 오류 없이 형편없는 일치를 반환하므로, 임베딩 모델을 변경한 후 저장된 벡터를 다시 생성합니다.

Juno제공된 모델 유지 로컬 설정에서는 제공된 모델명 둘 다 변경 없이 유지합니다. 이것이 이 페이지에서 뭔가가 실패하는 이유는 아닙니다. OpenAI 프로젝트가 한 모델을 거부하면 코드를 편집하기 전에 현재 모델 목록을 확인하고 그 후 전체 에이전트를 다시 테스트합니다.

에이전트 실행

bash

$ npm start

http://localhost:3000을 열거나 .env에 설정한 포트를 사용합니다. Ctrl+C로 서버를 중지합니다.

페이지가 로드되면 로컬 서버가 실행 중임을 보여줍니다. 코스 데이터로 다룬 질문을 합니다. 유용한 답변은 Supabase 검색과 OpenAI 생성이 작동함을 보여줍니다. 답변이 실패하면 서버 터미널이 체인의 첫 실패 호출(임베딩, 검색 또는 생성)을 인쇄합니다. RAG 장은 에이전트가 처음부터 검색된 코스 데이터에 답변을 기반으로 하는 이유를 설명합니다.

Juno에이전트 실행npm start를 실행하고 브라우저에서 로컬 주소를 엽니다. 페이지 로드는 서버가 실행 중임을 증명합니다. 완전한 답변도 OpenAI와 코스의 Supabase 데이터를 필요로 하므로 그것들을 두 가지의 별개 승리로 취급합니다.

문제 해결

Missing OPENAI_API_KEY: 시작 스크립트가 --env-file=.env를 포함하고, .env가 package.json 옆에 있고, 변수명이 정확히 일치하는지 확인합니다.

Supabase 인증 또는 relation 오류: URL과 서버 측 키가 같은 프로젝트에 속하는지 확인한 후 코스의 스키마 및 데이터 단계를 완료합니다. 서버 작동을 위해 게시 가능한 키로 대체하지 않습니다.

포트 3000이 이미 사용 중입니다: .env에서 PORT를 변경하고, 서버를 다시 시작하고, 새 포트를 엽니다.

페이지는 로드되지만 답변이 실패합니다: 서버 터미널에서 첫 제공자 또는 데이터베이스 오류를 확인합니다. 로컬 시작만으로는 외부 서비스 중 하나도 검증하지 않습니다.

Juno문제 해결 누락된 키는 시작 스크립트나 .env를 가리키고, Supabase 오류는 프로젝트나 데이터를 가리키고, 로드된 페이지가 답변에 실패하면 외부 서비스를 가리킵니다. 증상을 먼저 레이어에 일치시키면 수정이 보통 자신의 이름을 표시합니다.

Vercel AI SDK 코스를 로컬에서 실행하기 ​

먼저 필요한 것 ​

프로젝트 열기 및 설치 ​

Node가 .env를 로드하도록 설정 ​

제공된 모델 유지 ​

에이전트 실행 ​

문제 해결 ​