Ejecutar Intro to AI Engineering en tu máquina

Usa esta página para ejecutar el proyecto Gift Genie extraído de Intro to AI Engineering en tu computadora con tu propio proveedor de IA. El proyecto viene en dos formas: una app Vite solo para navegador en las lecciones antes de la migración del backend, y una app Express y Vite desde la migración del backend en adelante. Una línea en package.json te dice cuál tienes; la instalación y el archivo .env son iguales para ambas, y el inicio es diferente.

Lo que necesitas primero

Instala una versión LTS compatible de Node.js. Se recomienda Node 24 e incluye npm.

Verifica que ambos comandos funcionen. Tus números de versión pueden ser diferentes:

$ node --version
v24.18.0
$ npm --version
11.18.0

También necesitas los tres valores que configuraste en las variables de entorno de Scrimba durante el curso: la URL de tu proveedor, tu clave API y el ID del modelo. Si ya no tienes la clave, crea una nueva en el mismo proveedor.

JunoLo que necesitas primero Instala la versión LTS de Node.js, que incluye npm, y verifica que node --version y npm --version muestren una versión.

Luego ten lista la URL de tu proveedor, tu clave API y tu ID de modelo. Pegarás los tres en un archivo en unos minutos.

JunoLo que necesitas primero Los tres valores funcionan como un conjunto: la URL elige el proveedor, la clave prueba quién eres ante ese proveedor, y el ID del modelo nombra uno de sus modelos. Una clave de un proveedor enviada a la URL de otro proveedor es rechazada.

JunoLo que necesitas primero Ambas formas del proyecto usan Vite 7.3, que necesita Node 20.19 o 22.12 y versiones más recientes. Node 20 ha llegado al final de su vida útil, así que en la práctica eso significa Node 22.12 o un LTS más reciente.

Averigua qué proyecto tienes

Abre package.json en la carpeta extraída y encuentra la línea start. Si solo dice vite, tienes el proyecto solo para navegador:

"start": "vite"

Si dice concurrently, con un script server debajo, tienes el proyecto con backend. Su carpeta también contiene server.js:

"start": "concurrently \"npm run client\" \"npm run server\" ",
"server": "node --watch server.js",

JunoAverigua qué proyecto tienes Abre package.json y lee la línea start. Si dice vite y nada más, tienes el proyecto solo para navegador. Si dice concurrently, tienes el proyecto con backend.

Recuerda cuál es: las últimas dos secciones cubren una de ellas.

JunoAverigua qué proyecto tienes El script start es lo que se ejecuta cuando escribes npm start. El proyecto solo para navegador ejecuta Vite solo; el proyecto con backend ejecuta Vite y un servidor Express lado a lado desde un solo comando.

JunoAverigua qué proyecto tienesconcurrently inicia npm run client y npm run server como dos procesos secundarios y prefija su salida con [0] y [1], por lo que las líneas de Vite y Express comparten una terminal.

Instala los paquetes

Abre una terminal en la carpeta extraída, la que contiene package.json. Todos los comandos en esta página se ejecutan desde ahí:

$ cd path-to-your-extracted-project

Instala los paquetes que el proyecto lista. Esto es igual para ambas formas:

$ npm install

npm termina reportando cuántos paquetes agregó. También puede reportar vulnerabilidades, o advertencias de allow-scripts sobre esbuild y fsevents. Ninguna de ellas impide que el proyecto se ejecute.

JunoInstala los paquetes Ejecuta npm install en la carpeta con package.json. Termina diciendo cuántos paquetes agregó.

Si npm dice que no puede encontrar package.json, estás en la carpeta incorrecta.

JunoInstala los paquetes La descarga incluye package-lock.json, así que npm instala las mismas versiones de paquetes que el curso usó. El recuento de vulnerabilidades describe esas versiones; no es una señal de que la instalación falló.

JunoInstala los paquetes Las versiones más recientes de npm listan paquetes cuyos scripts de instalación no han sido aprobados. Vite aún se inicia sin aprobarlos aquí, porque el binario de esbuild llega como un paquete de plataforma en lugar de a través de ese script.

Agrega tus valores a .env

En Scrimba, el editor completa tus tres variables de entorno por ti. En tu computadora, vienen de un archivo. Crea .env junto a package.json e introduce tus valores bajo exactamente estos nombres:

AI_URL=https://api.openai.com/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id

Este ejemplo usa la URL de OpenAI. Si usaste otro proveedor en el curso, como Groq u OpenRouter, usa su URL en su lugar. El ID del modelo debe ser uno que ese proveedor ofrezca.

Crea .gitignore junto a package.json y agrega:

.env
node_modules/

Una clave que llega a un repositorio Git permanece en su historial incluso después de que elimines el archivo. El manual de Git cubre el hábito en ignorar archivos y buenas prácticas.

Nunca hagas commit de tu clave API

.env contiene una clave funcionando. No la subas, pegues la clave en tu código, ni hagas commit del archivo. Si una clave alguna vez se expone, elimínala en tu proveedor y crea una nueva.

JunoAgrega tus valores a .env Crea un archivo llamado .env junto a package.json con tus tres valores, uno por línea, luego lista .env en .gitignore para que Git nunca lo guarde.

JunoAgrega tus valores a .env Ambos proyectos observan .env mientras se ejecutan. Guárdalo y Vite imprime .env changed, restarting server...; en el proyecto con backend el servidor también imprime Restarting 'server.js'. Recarga la página y los nuevos valores están en uso.

JunoAgrega tus valores a .env Las dos formas leen el mismo archivo en diferentes lugares. La config vite.config.js del proyecto solo para navegador la carga con loadEnv; el proyecto con backend la carga en Node con una bandera de inicio que agregás en su propia sección. El Vite config del backend aún lee .env, pero nunca pone la clave en la página.

Ejecuta el proyecto solo para navegador

Esta versión pone tu clave en el navegador

Estas lecciones llaman al proveedor de IA directamente desde la página, así que Vite escribe AI_KEY en el código que envía al navegador, y cualquiera que abra la página puede leerlo. Usa una clave que eliminarás cuando termines, mantén esta versión en tu propia computadora, y nunca la implementes ni la compartas. La migración del backend más adelante en el curso mueve la clave a un servidor.

Inicia el proyecto:

$ npm start

Vite imprime la dirección para abrir:

  VITE v7.3.0  ready in 176 ms

  ➜  Local:   http://localhost:5173/

Abre la dirección exacta de Local. Si el puerto 5173 está ocupado, Vite elige el siguiente e imprime eso en su lugar.

En las primeras lecciones, como Setting Up Your AI Client, la página está en blanco a propósito: el trabajo ocurre en la consola del navegador. Abre las herramientas de desarrollo de tu navegador (F12, o Cmd+Opción+J en Chrome en una Mac) y lee la pestaña Console. Debería mostrar tus valores:

AI provider URL: https://api.openai.com/v1
AI model: your-model-id

Las lecciones que construyen la página Gift Genie muestran esa página en su lugar. Detén el proyecto con Ctrl+C.

JunoEjecuta el proyecto solo para navegador Ejecuta npm start y abre la dirección Local. Si la página está en blanco, abre la Consola: las dos líneas con tu URL de proveedor y modelo significan que .env fue leído.

Un Missing AI_URL rojo ahí significa que no fue así.

JunoEjecuta el proyecto solo para navegadorutils.js verifica los tres valores tan pronto como la página carga y lanza una excepción en el primero que falta. Las líneas de la consola son esa verificación pasando; aún no dicen nada sobre si el proveedor acepta la clave.

JunoEjecuta el proyecto solo para navegadorvite.config.js usa define para reemplazar cada process.env.AI_KEY, AI_URL y AI_MODEL en tu código con el valor de .env mientras sirve la página. Ese reemplazo es cómo la clave termina en cada navegador que la carga.

Ejecuta el proyecto con backend

En Scrimba, el servidor obtuvo tus variables de entorno automáticamente. En tu computadora, Node lee .env solo cuando le dices que lo haga, y el script del servidor en la descarga no lo hace. Así que haz un cambio en package.json antes de que inicies. Cambia el script server de:

"server": "node --watch server.js",

a:

"server": "node --env-file=.env --watch server.js",

Luego inicia ambas partes de la app:

$ npm start

Las líneas [1] vienen del servidor Express y las líneas [0] de Vite:

[1] Server running at http://localhost:3001
[0]
[0]   VITE v7.3.1  ready in 1526 ms
[0]
[0]   ➜  Local:   http://localhost:5173/

Abre la dirección Local de Vite, no el puerto 3001: el servidor solo responde las peticiones /api de la app, así que el puerto 3001 por sí solo muestra Cannot GET /. Escribe para quién es el regalo y haz clic en Rub the Lamp. El botón cambia a Summoning Gift Ideas..., y unos segundos después aparecen ideas de regalos debajo. Eso significa que tu clave, URL y modelo funcionan.

Si la página dice Sorry, I can't access what I need right now, la razón está en la terminal, en una línea [1] del servidor. La solución de problemas abajo coincide con cada mensaje.

Detén ambas partes con un Ctrl+C. Cuando guardas .env mientras la app se ejecuta, ambas partes se reinician por sí solas y usan los nuevos valores.

El proyecto de implementación necesita el mismo cambio --env-file para su servidor.

JunoEjecuta el proyecto con backend Agrega --env-file=.env al script server, ejecuta npm start, y abre la dirección Local de Vite. Haz clic en Rub the Lamp y espera las ideas de regalos.

Si la página se disculpa en su lugar, lee las líneas [1] más recientes en la terminal.

JunoEjecuta el proyecto con backend La página envía su petición a /api/gift en la dirección de Vite. Vite reenvía todas las peticiones /api a Express en el puerto 3001, y Express llama al proveedor con la clave que leyó de .env. El navegador nunca ve la clave.

JunoEjecuta el proyecto con backend El destino del proxy en vite.config.js es fijo en http://localhost:3001, mientras que server.js escucha en PORT o 3001. Deja PORT fuera de .env y los dos concuerdan, a menos que tu terminal ya configure PORT, que gana sobre .env. Siempre que el servidor aterrice en otro puerto, el destino del proxy debe cambiar para coincidir.

Solución de problemas

Solo para navegador: una página en blanco, y la consola dice Missing AI_URL, Missing AI_MODEL o Missing AI_KEY: Vite no encontró ese valor. Verifica que .env esté junto a package.json y que los nombres estén deletreados exactamente como arriba, luego guárdalo. Vite se reinicia por sí solo (.env changed, restarting server...); recarga la página.

Con backend: la terminal dice Missing credentials, luego Failed running 'server.js': El servidor se inició sin tu .env. Verifica que el script server contenga --env-file=.env y que .env deletree AI_KEY exactamente, luego detén el proyecto con Ctrl+C y ejecuta npm start de nuevo.

Con backend: la terminal dice node: .env: not found: La bandera está en su lugar, pero no hay .env junto a package.json. Créalo ahí, o verifica que tu editor no lo guardó como .env.txt. El servidor ya se ha detenido, así que detén el proyecto con Ctrl+C y ejecuta npm start de nuevo.

Con backend: la página dice Sorry, I can't access what I need right now, y la terminal muestra 401 con Incorrect API key provided: La petición llegó a tu proveedor, que no aceptó la clave. Copia la clave de nuevo, y verifica que la URL en AI_URL pertenezca al mismo proveedor.

Tu proveedor dice que el modelo no existe o no está disponible: El mensaje se muestra en una línea [1] en la terminal para el proyecto con backend, o en la consola del navegador para una lección solo para navegador que envía una petición. Copia el ID del modelo de nuevo exactamente como tu proveedor lo lista, y verifica que pertenezca al proveedor en AI_URL.

Con backend: la terminal muestra http proxy error: /api/gift con ECONNREFUSED: Vite no puede alcanzar Express en el puerto 3001. Desplázate hacia arriba a las primeras líneas [1]. Si muestran un error, el servidor se detuvo ahí, usualmente por una de las razones arriba. Si dicen Server running at un puerto que no es 3001, tu terminal ya configura PORT, que gana sobre .env: cambia el destino del proxy en vite.config.js a ese puerto.

Con backend: EADDRINUSE menciona el puerto 3001: Otro programa está usando el puerto del servidor. Detenlo, o configura PORT en .env y cambia el destino del proxy en vite.config.js al mismo puerto.

npm start dice concurrently: command not found o vite: command not found: Los paquetes no están instalados en esta carpeta. Ejecuta npm install en la carpeta que contiene package.json.

JunoSolución de problemas Encuentra el primer error y coincídelo con un encabezado en negrita arriba. En el proyecto solo para navegador, busca en la Consola del navegador; en el proyecto con backend, busca en la terminal.

JunoSolución de problemas Mantén tres problemas separados: .env no siendo leído, un proceso no ejecutándose, y el proveedor rechazando la clave o modelo. Fallan en ese orden, y los primeros dos nunca alcanzan al proveedor en absoluto.

JunoSolución de problemas Un 401 significa que toda la cadena funcionó hasta el proveedor: la página, el proxy, Express y --env-file. Un error de credenciales faltantes viene del constructor del cliente de OpenAI, así que el servidor se detiene antes de que escuche en cualquier puerto.