Executando Embeddings e Bancos de Dados Vetoriais localmente

Use esta página para executar o chatbot do curso extraído no seu computador. Aqui você instala dois pacotes faltantes, adapta as configurações de OpenAI e Supabase do chatbot para Vite e inicia o projeto no navegador com o banco de dados que você construiu durante o curso.

O que você precisa primeiro

Instale uma versão LTS suportada do Node.js. Node 24 é recomendado e inclui npm. Você também precisa de uma chave de API do OpenAI e de um projeto Supabase existente contendo os dados do curso.

Para o Supabase, use uma chave publicável ou a chave anon legada. Essas chaves são projetadas para aparecer em código do navegador: quem copiar uma delas só consegue fazer o que suas políticas de Row Level Security (regras de leitura por linha do Supabase) permitem. Nunca coloque uma chave secreta ou chave service_role neste projeto do navegador. Veja chaves de API do Supabase para os tipos de chave atuais.

A chave do OpenAI não tem equivalente em escopo: qualquer cópia dela pode fazer requisições cobradas na sua conta, então em produção nunca fica em código de cliente. Este setup de aprendizado a envia para o navegador mesmo assim; o aviso na seção de Vite explica os limites de fazer isso. O equivalente do lado do servidor deste setup, o projeto do Vercel AI SDK, usa o mesmo projeto Supabase mas com uma chave secreta. Uma chave secreta é aceitável lá porque aquele projeto roda em um servidor, então suas chaves nunca chegam a um navegador.

JunoO que você precisa primeiro Instale Node.js LTS e tenha sua chave do OpenAI e o projeto Supabase que você construiu durante o curso prontos. Para o Supabase, use uma chave publicável ou anon, do tipo projetado para navegadores, nunca um segredo de servidor. Já usei o tipo de chave errado uma vez e passei uma noite aprendendo a diferença entre eles!

JunoO que você precisa primeiro Este projeto precisa de Node mais dois serviços ao vivo: OpenAI e o banco de dados Supabase do curso. A chave Supabase que você configurar fica legível em código de cliente, então deve ser uma chave publicável ou anon cujo acesso o Row Level Security limita. Não coloque nenhuma chave do lado do servidor neste projeto.

JunoO que você precisa primeiro Uma chave anon vazada é limitada: só consegue fazer o que suas políticas de Row Level Security permitem, que é exatamente por que esse tipo de chave é projetado para código de navegador. A chave do OpenAI não tem limitação equivalente e qualquer cópia dela gasta seu dinheiro até você revogá-la. Essa diferença decide a arquitetura: uma chave Supabase em código de cliente é uma questão de política, uma chave OpenAI em código de cliente em produção é um erro.

Abra a pasta do projeto

Abra um terminal na pasta do chatbot extraída que contém package.json:

$ cd path-to-your-downloaded-project

Para confirmar que tem o download certo, abra package.json: a exportação do chatbot declara Vite e a fonte ao lado dela inclui os arquivos config.js e index.js que as próximas seções editam. Estas instruções se encaixam no chatbot completo, cujo código importa tanto openai quanto @supabase/supabase-js; o nome da pasta sozinho não o distingue da exportação de uma lição anterior.

JunoAbra a pasta do projeto Trabalhe na pasta extraída que contém package.json; toda instalação e cada arquivo nesta página pertence lá. Se o terminal está em qualquer outro lugar, os comandos rodão na pasta errada e nada depois disso funciona. Eu verifico a listagem da pasta por package.json antes de digitar qualquer coisa, um hábito que construí depois de cometer esse erro várias vezes.

JunoAbra a pasta do projeto Confirme a pasta antes de editar qualquer coisa: package.json no topo, Vite declarado dentro dele e config.js e index.js ao lado. Trinta segundos de verificação aqui custam menos que consertar os arquivos de um projeto diferente. Todo comando nesta página assume que você está nesta pasta.

JunoAbra a pasta do projeto Verifique o marco antes de corrigi-lo: estas instruções se encaixam na exportação cuja fonte importa OpenAI e Supabase e executa o fluxo completo do chatbot. A exportação de uma lição anterior parece quase idêntica se você só ler o nome da pasta. Dois minutos lendo os imports custam menos que uma tarde debugando um conserto que o projeto nunca precisava.

Prepare o projeto para Vite

Instale a dependência Vite declarada, então os dois pacotes que a fonte importa mas o package.json baixado não declara:

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

Abra config.js e substitua cada leitura de ambiente de Scrimba. Mantenha os imports, exports e validação existentes, mas substitua três nomes de ambiente em quatro ocorrências; OPENAI_API_KEY aparece duas vezes:

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

As duas leituras de OPENAI_API_KEY ficam na verificação de validação e no cliente OpenAI, então mude ambas.

Abra index.js e mude o modelo de chat de gpt-4 para gpt-4o-mini. Deixe o modelo de embedding text-embedding-ada-002 fornecido inalterado enquanto segue o curso. Os vetores existentes no banco de dados do curso devem ter as mesmas dimensões que os embeddings de query; mudar esse modelo é uma migração de banco de dados separada, não parte da configuração local.

Crie .env ao lado de package.json:

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

Também crie .gitignore:

.env
node_modules/

Enviar .env para um repositório Git é a forma mais comum de uma chave vazar; ignorando arquivos e bons hábitos cobre o hábito em detalhes.

Essas credenciais são visíveis no navegador

Vite copia valores VITE_ para o bundle do frontend. Use credenciais de aprendizado restritas, ative Row Level Security no Supabase e nunca publique esta versão. Um app em produção deve mover a requisição do OpenAI para um backend.

JunoPrepare o projeto para Vite Instale os pacotes faltantes, substitua cada leitura de ambiente antiga por seu equivalente Vite e coloque suas chaves em .env com uma chave Supabase segura para navegador. Depois mantenha .env fora do Git. Já publiquei uma chave com meu primeiro projeto e passei a noite a substituí-la, então essa ordem é escrita a partir de experiência.

JunoPrepare o projeto para Vite A fonte importa dois SDKs que o download nunca declarou e lê nomes de ambiente de Scrimba, então instale ambos os pacotes e mude todas as quatro leituras de ambiente antes de iniciar Vite. Se deixar uma dessas leituras inalterada, o app falha em tempo de execução em vez de em tempo de build. O par .env e .gitignore finaliza o conserto.

JunoPrepare o projeto para Vite Instalar os SDKs conserta os imports; os nomes VITE_ são o que coloca os valores no bundle, que também entrega a chave do OpenAI para código de navegador. Isso é aceitável para uma lição e desqualificador para produção, então mova a chamada do OpenAI atrás de um backend antes de usuários reais chegarem a este chatbot. Já vi um projeto pular esse passo e terminou com uma chave revogada e uma fatura inesperada.

Execute o projeto

$ npm start

Abra a URL Local impressa por Vite e faça ao chatbot uma pergunta coberta pelos dados do curso. Uma resposta útil mostra que a página, a recuperação do Supabase e a requisição do OpenAI estão todos funcionando. Reinicie o comando depois de mudar .env e pare-o com Ctrl+C.

JunoExecute o projeto Execute npm start, abra a URL Local e faça ao chatbot uma pergunta que os dados do curso cobrem. Se mudar .env, reinicie o comando para que Vite leia os novos valores, e pressione Ctrl+C quando terminar. Esquecer esse reinício uma vez me confundiu por uma tarde inteira, então espero que esta nota economize uma para você.

JunoExecute o projeto Vite iniciando limpamente prova que o projeto consertado é agrupado; uma resposta útil prova o resto. Uma boa pergunta testa acesso do OpenAI junto com as linhas e políticas do Supabase ao mesmo tempo, então trate como seu teste de integração. Reinicie após qualquer mudança de .env.

JunoExecute o projeto Uma página que carrega não é um teste aprovado. Verifique servimento local, recuperação do Supabase, busca de embedding e geração de resposta como checkpoints separados, porque cada um pode falhar silenciosamente atrás de uma página perfeitamente renderizada. Uma vez declarei um projeto terminado depois de ver só a tela de abertura e o bug apareceu durante a demo.

Solução de problemas

Failed to resolve import "openai" ou "@supabase/supabase-js": Execute ambos os comandos de instalação mostrados anteriormente nesta página e execute-os na pasta que contém package.json.

process is not defined: Uma referência process.env permanece em config.js. Substitua-a pelo valor import.meta.env.VITE_... correspondente.

Supabase não retorna linhas ou um erro de permissões: Confirme a URL do projeto, use uma chave publicável ou anon e verifique se a tabela do curso e as políticas de Row Level Security existem no mesmo projeto.

OpenAI rejeita o modelo ou chave: Confirme cobrança e acesso de chave na conta OpenAI. Use um modelo atual disponível para esse projeto.

JunoSolução de problemas Leia o erro como uma pista: um import faltante significa que os pacotes extras não estão instalados, um erro de ambiente significa que um nome Vite ainda está errado e respostas vazias geralmente indicam um problema com dados ou permissões do Supabase. Pegue um de cada vez. Cada problema nesta lista é reversível, então você consegue corrigir cada um e continuar.

JunoSolução de problemas Verifique em ordem de dependência: resolução de pacotes, depois todas as quatro substituições de ambiente, depois a URL do Supabase e políticas RLS, depois a chave e modelo do OpenAI. Cada camada depende da anterior, então um conserto fora de ordem pode parecer uma falha completamente nova. Pare na primeira camada quebrada e conserte lá.

JunoSolução de problemas Um chatbot sem resposta útil falha em uma de três camadas: o bundle do navegador, permissões e linhas do Supabase ou a requisição do OpenAI, e cada uma pode falhar enquanto a página renderiza lindamente. Verifique-as nessa ordem. Uma página que abre prova só que Vite está rodando.