Executando Intro to AI Engineering localmente
Use esta página para executar o projeto Gift Genie extraído no seu computador. O curso atual tem duas formas do projeto: um app Vite somente browser e, após a migração do backend, um app Express e Vite. Identifique a forma que você tem e então siga sua configuração abaixo.
O que você precisa primeiro
Instale uma versão LTS suportada do Node.js. A versão Node 24 é recomendada. Node 22.12 ou posterior também funciona com a versão do Vite usada pelos projetos posteriores do curso.
Verifique se Node e npm estão disponíveis:
$ node --version
v24.18.0
$ npm --version
11.18.0npm vem incluído no Node. Se algum comando disser "command not found", termine a instalação do Node antes de continuar.
Identifique o projeto que você extraiu
Mude para a pasta extraída que contém package.json:
$ cd path-to-your-downloaded-projectTodos os comandos nesta página rodam a partir dessa pasta.
Então verifique qual forma do projeto você tem. A versão somente browser tem index.html e vite.config.js, e seu script start não executa nenhum arquivo de servidor. A versão Express e Vite tem server.js e vite.config.js, e seu script start os executa juntos.
start executa um arquivo server.js, siga a seção de backend, e se não executa, você tem a versão somente browser. Uma vez passei uma tarde com as instruções erradas porque pulei essa verificação! Adicione seus valores de ambiente
Scrimba fornece três variáveis de ambiente das suas configurações de conta. Seu computador não tem acesso a essas configurações, então crie um arquivo nomeado .env ao lado de package.json:
AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-idCopie os valores que você usou no curso. A URL e o modelo devem pertencer ao mesmo provider que a chave.
Antes de usar Git, crie um arquivo .gitignore ao lado de package.json e adicione:
.env
node_modules/O manual Git explica por que essas duas linhas pertencem a cada projeto em ignoring files and good habits.
Nunca faça commit da sua chave de API
O arquivo .env contém uma credencial ativa. Não faça upload, cole em código-fonte, ou faça commit no Git. Se uma chave ficar exposta, revogue-a no provider e crie uma nova.
Reinicie o projeto após qualquer mudança em .env. O comando de execução correto depende de qual parte do curso o ZIP veio.
.env bem ao lado de package.json, e copie seus três valores Scrimba nele. Esses são os mesmos valores que Scrimba mantinha nas suas configurações de conta, agora armazenados no seu próprio computador. Mantenha esse arquivo fora do Git; vazar uma chave é um erro que cometi cedo para você não ter que cometer. Execute o Gift Genie somente browser
As lições Gift Genie antes da migração do backend têm index.html e vite.config.js, mas nenhum server.js ativo no script start. Instale e inicie o projeto:
$ npm install
$ npm startVite imprime um endereço local similar a este:
VITE ready
Local: http://localhost:5173/Abra a URL Local exata impressa no seu terminal. Se a porta 5173 estiver ocupada, Vite normalmente seleciona outra porta e imprime esse endereço. Pare Vite com Ctrl+C.
Esta versão expõe sua chave para o browser
Essas lições deliberadamente chamam o provider de IA a partir de JavaScript frontend. Vite copia AI_KEY no bundle do browser, então qualquer pessoa que abra a página pode ler a chave nas ferramentas do desenvolvedor do seu browser. Use uma chave temporária e restrita para aprendizado local. Não implante esta versão ou a compartilhe em uma rede. A migração do backend depois no curso é a arquitetura segura para construir.
npm install, depois npm start, e abra a URL Local exata que Vite imprime em vez de uma que você lembre. Ctrl+C para quando você terminar; esse hábito levou mais tempo para eu aprender do que gosto de admitir. Execute o Gift Genie com seu backend
A migração do backend e as lições posteriores têm server.js e vite.config.js. Seu script start inicia Express e Vite juntos. O download atual não carrega .env no processo Express automaticamente, então faça essa única mudança em package.json antes de iniciá-lo.
Encontre o script server:
"server": "node --watch server.js"Mude para:
"server": "node --env-file=.env --watch server.js"O projeto do curso Deployment precisa da mesma mudança --env-file para seu servidor.
Adicione a porta do backend ao .env:
AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id
PORT=3001Então instale e inicie ambos os processos:
$ npm install
$ npm startVocê deveria ver uma mensagem Express para a porta 3001 e uma URL Local do Vite, geralmente porta 5173. Abra a URL do Vite. Não abra a porta 3001 como a página da aplicação. O browser envia requisições /api para o Vite, e o Vite as proxia para Express. A chave de API fica no processo do servidor.
Pare ambos os processos com Ctrl+C.
Mantenha o backend na porta 3001
O servidor Express baixado lê PORT, mas seu proxy Vite aponta diretamente para http://localhost:3001. Deixe PORT=3001 a menos que outro processo precise daquela porta. Se você mudar, também mude o alvo do proxy em vite.config.js para a mesma porta e reinicie o projeto.
PORT=3001, execute npm install e npm start, depois abra a URL do Vite, não a porta 3001. Um Ctrl+C para ambas as partes do app, o que parecia mágica a primeira vez que vi. Solução de problemas
Missing AI_KEY, uma resposta 401, ou um erro de autenticação: Verifique a ortografia de todos os três nomes de variável, confirme que a chave está ativa, e reinicie o projeto. Uma chave, URL, e modelo de diferentes providers não funcionarão como um conjunto.
O modelo não pode ser encontrado ou o provider rejeita a requisição: Copie a ID do modelo exatamente. Alguns recursos do curso, incluindo API de Respostas tools, os helpers built-in que um modelo pode chamar durante uma requisição, não são suportados por cada provider compatível com OpenAI, e não são suportados por cada modelo que esses providers oferecem.
npm start diz que um pacote ou comando está faltando: Certifique-se de que o terminal está na pasta contendo package.json, depois execute npm install novamente. Se o download contém um lockfile para um gerenciador de pacotes diferente, siga esse lockfile em vez de gerar um segundo.
A página abre, mas uma requisição /api falha: Isso se aplica à versão de backend. Verifique que Express e Vite ainda estão rodando no mesmo terminal. Confirme que Express está na porta 3001 e o alvo do proxy em vite.config.js também diz 3001.
EADDRINUSE menciona porta 3001: Outro processo está usando a porta do backend. Pare esse processo, ou mude tanto PORT em .env quanto o alvo do proxy Vite para a mesma porta não utilizada.
Vite usa 5174 ou outra porta frontend: Isso é normal quando 5173 está ocupada. Abra a URL Local que Vite imprimiu. Você não precisa mudar a porta Express.
package.json, que .env contém todos os três valores de IA, e que você reiniciou depois de editá-lo. Para a versão de backend, mantenha ambos os processos rodando. Quase todo erro que vi cedo veio de uma dessas três coisas.