임베딩과 벡터 데이터베이스를 로컬에서 실행하기

이 페이지를 사용하여 추출한 과정 챗봇을 컴퓨터에서 실행합니다. 이 페이지에서 누락된 패키지 두 개를 설치하고, 챗봇의 OpenAI와 Supabase 설정을 Vite에 맞게 조정한 후, 과정 중에 구축한 데이터베이스를 사용해 브라우저 프로젝트를 시작합니다.

먼저 필요한 것들

지원되는 LTS 버전의 Node.js를 설치합니다. Node 24를 추천하며 npm이 포함되어 있습니다. OpenAI API 키와 과정 데이터가 포함된 기존 Supabase 프로젝트도 필요합니다.

Supabase의 경우 공개 키(publishable key) 또는 레거시 anon 키를 사용합니다. 이 키들은 브라우저 코드에 나타나도록 설계되었습니다. 누군가 이 키를 복사하더라도 Supabase의 행 수준 보안 정책(Row Level Security, 행 단위 읽기 규칙)이 허용하는 작업만 수행할 수 있습니다. 이 브라우저 프로젝트에 비밀 키나 service_role 키를 절대 넣지 마세요. 현재 키 유형은 Supabase API 키를 참고하세요.

OpenAI 키는 이와 같은 범위 제한이 없습니다. 어떤 복사본이든 계정으로 청구되는 요청을 할 수 있으므로, 프로덕션에서는 절대 클라이언트 코드에 포함되면 안 됩니다. 이 학습 설정은 어쨌든 브라우저로 보냅니다. Vite 섹션의 경고에서 이를 수행하는 한계를 설명합니다. 이 설정의 서버 쪽 대응 프로젝트인 Vercel AI SDK 프로젝트는 동일한 Supabase 프로젝트를 사용하지만 비밀 키를 사용합니다. 그 프로젝트는 서버에서 실행되므로 키가 브라우저에 도달하지 않기 때문에 비밀 키를 사용해도 괜찮습니다.

Juno먼저 필요한 것들 Node.js LTS를 설치한 후 OpenAI 키와 과정 중에 구축한 Supabase 프로젝트를 준비합니다. Supabase의 경우 공개 키 또는 anon 키(브라우저용으로 설계된 키)를 사용하고, 절대 서버 비밀은 사용하지 마세요. 한 번 잘못된 키 유형을 사용했다가 그 차이를 배우는 데 저녁을 다 썼어요!

Juno먼저 필요한 것들 이 프로젝트에는 Node와 두 가지 라이브 서비스(OpenAI와 과정의 Supabase 데이터베이스)가 필요합니다. 구성하는 Supabase 키는 클라이언트 코드에서 읽을 수 있으므로 행 수준 보안이 접근을 제한하는 공개 키 또는 anon 키여야 합니다. 이 프로젝트에 서버 쪽 키를 넣지 마세요.

Juno먼저 필요한 것들 유출된 anon 키는 제한됩니다. 행 수준 보안 정책이 허용하는 작업만 수행할 수 있으며, 바로 이것이 그 키 유형이 브라우저 코드용으로 설계된 이유입니다. OpenAI 키는 이와 같은 범위 제한이 없으며, 어떤 복사본이든 피폐할 때까지 돈을 쓸 수 있습니다. 이 차이가 아키텍처를 결정합니다. 클라이언트 코드의 Supabase 키는 정책 문제이고, 프로덕션 클라이언트 코드의 OpenAI 키는 실수입니다.

프로젝트 폴더 열기

package.json이 있는 추출한 챗봇 폴더에서 터미널을 엽니다.

$ cd path-to-your-downloaded-project

올바른 다운로드임을 확인하려면 package.json을 엽니다. 챗봇 내보내기는 Vite를 선언하고, 그 옆의 소스에는 다음 섹션에서 편집할 config.js와 index.js 파일이 포함됩니다. 이 지침은 코드가 openai와 @supabase/supabase-js를 모두 가져오는 완성된 챗봇에 맞습니다. 폴더 이름만으로는 이전 수업의 내보내기와 구별할 수 없습니다.

Juno프로젝트 폴더 열기package.json이 있는 추출한 폴더에서 작업합니다. 이 페이지의 모든 설치와 모든 파일이 그곳에 있어야 합니다. 터미널이 다른 곳에 있으면 명령이 잘못된 폴더에서 실행되고 이 이후의 모든 것이 작동하지 않습니다. 뭔가 입력하기 전에 폴더 목록에서 package.json을 확인하는 습관을 들였어요. 그 실수를 여러 번 했거든요.

Juno프로젝트 폴더 열기 뭔가 편집하기 전에 폴더를 확인합니다. 최상위에 package.json이 있고, 내부에 Vite가 선언되어 있으며, config.js와 index.js가 그 옆에 있어야 합니다. 여기서 30초를 들여 확인하는 것이 다른 프로젝트의 파일을 수정하는 것보다 비용이 적게 듭니다. 이 페이지의 모든 명령은 이 폴더에서 실행된다고 가정합니다.

Juno프로젝트 폴더 열기 수정하기 전에 마일스톤을 확인합니다. 이 지침은 OpenAI와 Supabase를 모두 가져오는 소스이고 완성된 챗봇 흐름을 실행하는 내보내기에 맞습니다. 이전 수업의 내보내기는 폴더 이름만 읽으면 거의 동일해 보입니다. 가져오기를 읽는 데 2분을 쓰는 것이 프로젝트가 필요하지 않은 수정을 디버깅하는 데 오후를 다 쓰는 것보다 낫습니다.

Vite용 프로젝트 준비하기

선언된 Vite 종속성을 설치한 후 소스는 가져오지만 다운로드한 package.json에는 선언되지 않은 두 패키지를 설치합니다.

$ npm install
$ npm install openai @supabase/supabase-js

config.js를 열고 모든 Scrimba 환경 읽기를 바꿉니다. 기존 가져오기, 내보내기 및 유효성 검사는 유지하되 4개 위치에서 3가지 환경 이름을 바꿉니다. OPENAI_API_KEY는 두 번 나타납니다.

process.env.OPENAI_API_KEY
import.meta.env.VITE_OPENAI_API_KEY

process.env.SUPABASE_API_KEY
import.meta.env.VITE_SUPABASE_API_KEY

process.env.SUPABASE_URL
import.meta.env.VITE_SUPABASE_URL

두 OPENAI_API_KEY 읽기는 유효성 검사 확인과 OpenAI 클라이언트에 있으므로 둘 다 변경합니다.

index.js를 열고 채팅 모델을 gpt-4에서 gpt-4o-mini로 변경합니다. 과정을 따르는 동안 제공된 text-embedding-ada-002 임베딩 모델은 변경하지 않고 유지합니다. 과정 데이터베이스의 기존 벡터는 쿼리 임베딩과 같은 차원을 가져야 합니다. 그 모델을 변경하는 것은 로컬 설정의 일부가 아닌 별도의 데이터베이스 마이그레이션입니다.

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

VITE_OPENAI_API_KEY=your-openai-api-key
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_API_KEY=your-publishable-or-anon-key

또한 .gitignore를 만듭니다.

.env
node_modules/

.env를 Git 저장소로 보내는 것이 키가 유출되는 가장 일반적인 방법입니다. 파일 무시 및 좋은 습관에서 이 습관을 자세히 다룹니다.

이 자격 증명은 브라우저에서 표시됩니다

Vite는 VITE_ 값을 프론트엔드 번들에 복사합니다. 제한된 학습 자격 증명을 사용하고, Supabase에서 행 수준 보안을 활성화하며, 이 버전을 절대 게시하지 마세요. 프로덕션 앱은 OpenAI 요청을 백엔드로 이동해야 합니다.

JunoVite용 프로젝트 준비하기 누락된 패키지를 설치하고, 모든 이전 환경 읽기를 해당하는 Vite 등가물로 바꾸며, 브라우저에 안전한 Supabase 키를 사용하여 .env에 키를 넣습니다. 그런 다음 .env를 Git에서 제외합니다. 첫 프로젝트에서 키를 게시했다가 저녁을 다 들여 바꿨었기 때문에 이 순서는 경험에서 나온 것입니다.

JunoVite용 프로젝트 준비하기 소스는 다운로드가 절대 선언하지 않은 두 SDK를 가져오고 Scrimba의 환경 이름을 읽으므로 두 패키지를 모두 설치하고 Vite를 시작하기 전에 4개 환경 읽기를 모두 변경합니다. 이 읽기 중 하나를 변경하지 않으면 빌드 타임보다는 런타임에서 앱이 실패합니다. .env와 .gitignore 쌍이 수정을 마무리합니다.

JunoVite용 프로젝트 준비하기 SDK 설치는 가져오기를 고치고, VITE_ 이름은 번들에 값을 넣으며, 이것이 또한 OpenAI 키를 브라우저 코드로 전달합니다. 이것은 수업에는 괜찮지만 프로덕션에는 불가능합니다. 실제 사용자가 이 챗봇에 도달하기 전에 OpenAI 호출을 백엔드 뒤로 옮기세요. 이 단계를 건너뛴 프로젝트를 봤는데 해지된 키와 예상치 못한 청구서로 끝났습니다.

프로젝트 실행하기

$ npm start

Vite가 인쇄한 Local URL을 열고 과정 데이터로 다룬 질문을 챗봇에 합니다. 유용한 답변은 페이지, Supabase 검색 및 OpenAI 요청이 모두 작동함을 보여줍니다. .env를 변경한 후 명령을 다시 시작하고 Ctrl+C로 중지합니다.

Juno프로젝트 실행하기npm start를 실행하고 Local URL을 열어 과정 데이터가 다루는 것을 챗봇에 물어봅니다. .env를 변경하면 명령을 다시 시작하여 Vite가 새 값을 읽도록 하고, 완료하면 Ctrl+C를 누릅니다. 이 재시작을 한 번 잊어서 하루 종일 헷갈린 적이 있으니 이 참고사항이 시간을 절약해주길 바랍니다.

Juno프로젝트 실행하기 Vite가 깨끗이 시작되는 것은 수정된 프로젝트가 번들되었음을 증명합니다. 유용한 답변은 나머지를 증명합니다. 한 가지 좋은 질문은 동시에 OpenAI 접근과 Supabase 행 및 정책을 테스트하므로 통합 테스트로 취급하세요. .env 변경 후 다시 시작합니다.

Juno프로젝트 실행하기 페이지 로드는 통과 테스트가 아닙니다. 로컬 서빙, Supabase 검색, 임베딩 조회 및 답변 생성을 별개의 체크포인트로 확인합니다. 각각이 완벽하게 렌더링된 페이지 뒤에서 무음으로 실패할 수 있기 때문입니다. 한 번 방문 화면만 보고 프로젝트를 완료라고 선언했다가 데모 중에 버그가 나타났어요.

문제 해결

Failed to resolve import "openai" 또는 "@supabase/supabase-js": 이 페이지의 앞부분에 표시된 두 설치 명령을 모두 실행하고, package.json이 있는 폴더에서 실행합니다.

process is not defined: config.js에 process.env 참조가 남아 있습니다. 일치하는 import.meta.env.VITE_... 값으로 바꾸세요.

Supabase가 행을 반환하지 않거나 권한 오류 반환: 프로젝트 URL을 확인하고, 공개 키 또는 anon 키를 사용하며, 해당 프로젝트에 과정 테이블과 행 수준 보안 정책이 있는지 확인합니다.

OpenAI가 모델 또는 키를 거부: OpenAI 계정에서 청구 및 키 접근을 확인합니다. 해당 프로젝트에서 사용 가능한 현재 모델을 사용하세요.

Juno문제 해결 오류를 단서로 읽으세요. 누락된 가져오기는 추가 패키지가 설치되지 않았음을 의미하고, 환경 오류는 Vite 이름이 여전히 잘못되었음을 의미하며, 빈 답변은 보통 Supabase 데이터 또는 권한 문제를 나타냅니다. 한 번에 하나씩 다루세요. 이 목록의 모든 문제는 되돌릴 수 있으므로 각각을 고치고 계속 진행할 수 있습니다.

Juno문제 해결 종속성 순서로 확인합니다. 패키지 해석, 그 다음 4개 환경 치환, 그 다음 Supabase URL과 RLS 정책, 그 다음 OpenAI 키와 모델. 각 계층은 그 전 계층에 달려 있으므로 잘못된 순서의 수정은 완전히 새로운 실패처럼 보일 수 있습니다. 첫 번째 깨진 계층에서 멈추고 거기서 수정하세요.

Juno문제 해결 유용한 답변이 없는 챗봇은 3개 계층 중 하나에서 실패합니다. 브라우저 번들, Supabase 권한 및 행, 또는 OpenAI 요청이고, 각각이 페이지를 아름답게 렌더링하면서 실패할 수 있습니다. 그 순서로 확인하세요. 페이지 열림은 Vite 실행만 증명합니다.