Ejecutar Intro to AI Engineering en tu máquina

Usa esta página para ejecutar el proyecto Gift Genie extraído en tu computadora. El curso actual tiene dos formas del proyecto: una app Vite solo navegador y, después de la migración del backend, una app Express y Vite. Identifica cuál tienes y sigue su configuración abajo.

Qué necesitas primero

Instala una versión LTS compatible de Node.js. Se recomienda Node 24. Node 22.12 o superior también soporta la versión de Vite que usan los proyectos posteriores del curso.

Verifica que Node y npm estén disponibles:

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

npm viene incluido con Node. Si alguno de los comandos dice "command not found", termina de instalar Node antes de continuar.

JunoQué necesitas primero Instala la versión LTS de Node.js, que incluye npm, así con una descarga obtienes ambas herramientas. Si ambos comandos de versión imprimen números, tu máquina está lista.

JunoQué necesitas primero Consigue Node 24, o Node 22.12 en adelante. Eso cubre el runtime que los proyectos Vite 7 hacia el final del curso esperan, así lo configuras una vez y dejas de pensar en ello.

JunoQué necesitas primero Los proyectos posteriores usan Vite 7.3, que requiere Node 20.19 o Node 22.12 en adelante. Instala un LTS actualmente soportado en lugar de la versión más antigua que aún cumpla el mínimo; he perseguido demasiados bugs de runtime que comenzaron con una versión elegida de esa forma.

Identifica el proyecto que extrajiste

Entra a la carpeta extraída que contiene package.json:

$ cd path-to-your-downloaded-project

Todos los comandos en esta página se ejecutan desde esa carpeta.

Luego verifica cuál forma del proyecto tienes. La versión solo navegador tiene index.html y vite.config.js, y su script start no ejecuta ningún archivo de servidor. La versión Express y Vite tiene tanto server.js como vite.config.js, y su script start los ejecuta juntos.

JunoIdentifica el proyecto que extrajiste Verifica una cosa antes de elegir una sección: si el script start ejecuta un archivo server.js, sigue la sección del backend, y si no, tienes la versión solo navegador. ¡Una vez pasé una tarde en las instrucciones equivocadas porque omití esta verificación!

JunoIdentifica el proyecto que extrajiste Abre package.json y lee el script start; te dice qué se ejecuta realmente. Una lección solo Vite y la app Express-más-Vite posterior usan instrucciones diferentes abajo, así que decide qué forma tienes antes de empezar, o seguirás la sección equivocada y tendrás que empezar de nuevo.

JunoIdentifica el proyecto que extrajiste Cuando los scripts extraídos o el lockfile difieran de un ejemplo aquí, sigue los archivos. Ellos determinan qué procesos se inician y qué comando de instalación aplica, y he aprendido a confiar en un lockfile más que en mi recuerdo de cualquier lección.

Agrega tus valores de entorno

Scrimba proporciona tres variables de entorno desde la configuración de tu cuenta. Tu computadora no tiene acceso a esa configuración, así que crea un archivo llamado .env junto a package.json:

AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id

Copia los valores que usaste en el curso. La URL y el modelo deben pertenecer al mismo proveedor que la clave.

Antes de usar Git, crea un archivo .gitignore junto a package.json y agrega:

.env
node_modules/

El manual de Git explica por qué estas dos líneas pertenecen en cada proyecto en ignoring files and good habits.

Nunca hagas commit de tu clave API

El archivo .env contiene una credencial que funciona. No la subas, la pegues en código fuente, ni la hagas commit en Git. Si una clave se expone, revócala en el proveedor y crea una nueva.

Reinicia el proyecto después de cualquier cambio en .env. El comando de ejecución correcto depende de qué parte del curso vino el ZIP.

JunoAgrega tus valores de entorno Crea .env justo junto a package.json, y copia tus tres valores de Scrimba en él. Esos son los mismos valores que Scrimba guardaba en la configuración de tu cuenta, ahora almacenados en tu propia computadora en su lugar. Mantén ese archivo fuera de Git; filtrar una clave es un error que cometí al principio para que no tengas que hacerlo.

JunoAgrega tus valores de entorno El curso lee AI_URL, AI_KEY y AI_MODEL como un conjunto para que un cliente pueda apuntar a diferentes proveedores compatibles con OpenAI. Cambia cualquiera de ellos y reinicia; el proceso en ejecución mantiene los valores antiguos de otra forma.

JunoAgrega tus valores de entorno Los proyectos solo navegador cargan .env en la configuración de Vite y escriben los valores en el bundle del cliente en tiempo de compilación. La descarga del backend actual necesita un cambio en el script del paquete antes de que Node cargue el mismo archivo, cubierto abajo; nada lo carga por ti, un hecho que redescubro en cada máquina nueva.

Ejecuta Gift Genie solo navegador

Las lecciones de Gift Genie antes de la migración del backend tienen index.html y vite.config.js, pero ningún server.js activo en el script start. Instala e inicia el proyecto:

$ npm install
$ npm start

Vite imprime una dirección local similar a esta:

  VITE ready

  Local: http://localhost:5173/

Abre la URL exacta de Local impresa en tu terminal. Si el puerto 5173 está ocupado, Vite normalmente selecciona otro puerto e imprime esa dirección en su lugar. Detén Vite con Ctrl+C.

Esta versión expone tu clave al navegador

Estas lecciones deliberadamente llaman al proveedor de IA desde JavaScript de frontend. Vite copia AI_KEY en el bundle del navegador, así que cualquiera que abra la página puede leer la clave en las herramientas de desarrollo de su navegador. Usa una clave temporal y restringida para aprender localmente. No despliegues esta versión ni la compartas en una red. La migración del backend más adelante en el curso es la arquitectura segura sobre la que construir.

JunoEjecuta Gift Genie solo navegador Ejecuta npm install, luego npm start, y abre la URL Local exacta que Vite imprime en lugar de una que recuerdes. Ctrl+C lo detiene cuando terminas; ese hábito me tomó más tiempo en aprender de lo que me gustaría admitir.

JunoEjecuta Gift Genie solo navegador Este proyecto es solo Vite aunque un archivo de servidor no utilizado esté presente en la carpeta. El script start decide qué se ejecuta realmente, así que léelo antes de confiar en el listado de archivos.

JunoEjecuta Gift Genie solo navegador La configuración de Vite descargada usa define para sustituir process.env.AI_KEY, AI_URL y AI_MODEL en tiempo de compilación, así la clave se envía a cada navegador que carga la página. Usa una clave de un solo uso restringida y trátala como ya pública, porque en la práctica lo es.

Ejecuta Gift Genie con su backend

La migración del backend y las lecciones posteriores tienen tanto server.js como vite.config.js. Su script start lanza Express y Vite juntos. La descarga actual no carga .env en el proceso de Express automáticamente, así que haz este único cambio en package.json antes de iniciarlo.

Encuentra el script server:

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

Cambialo a:

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

El proyecto del curso de Deployment necesita el mismo cambio --env-file para su servidor.

Agrega el puerto del backend a .env:

AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id
PORT=3001

Luego instala e inicia ambos procesos:

$ npm install
$ npm start

Deberías ver un mensaje de Express para el puerto 3001 y una URL Local de Vite, usualmente puerto 5173. Abre la URL de Vite. No abras el puerto 3001 como la página de la aplicación. El navegador envía solicitudes /api a Vite, y Vite las envía por proxy a Express. La clave API permanece en el proceso del servidor.

Detén ambos procesos con Ctrl+C.

Mantén el backend en el puerto 3001

El servidor Express descargado lee PORT, pero su proxy de Vite apunta directamente a http://localhost:3001. Deja PORT=3001 a menos que otro proceso necesite ese puerto. Si lo cambias, también cambia el objetivo del proxy en vite.config.js al mismo puerto y reinicia el proyecto.

JunoEjecuta Gift Genie con su backend Mantén PORT=3001, ejecuta npm install y npm start, luego abre la URL de Vite, no el puerto 3001. Un Ctrl+C detiene ambas partes de la app, lo que pareció magia la primera vez que lo vi.

JunoEjecuta Gift Genie con su backend Un comando inicia Express en el puerto 3001 y Vite en su puerto de frontend impreso. Abre la URL de Vite; reenvía las solicitudes relativas /api a Express, que es cómo la clave permanece en el lado del servidor.

JunoEjecuta Gift Genie con su backend El script start usa el paquete concurrently para ejecutar Node y Vite como un comando. La bandera --env-file=.env agregada carga credenciales solo en el proceso de Express, mientras que la configuración de Vite posee el objetivo de proxy de desarrollo fijo. Eso es más ordenado que iniciar dos terminales a mano, que aún me atrapo haciéndolo por hábito antiguo.

Solución de problemas

Missing AI_KEY, una respuesta 401, o un error de autenticación: Verifica la ortografía de los tres nombres de variables, confirma que la clave está activa, y reinicia el proyecto. Una clave, URL y modelo de diferentes proveedores no funcionarán como un conjunto.

El modelo no se puede encontrar o el proveedor rechaza la solicitud: Copia el ID del modelo exactamente. Algunas características del curso, incluidas las herramientas de la API de Responses, los ayudantes integrados que un modelo puede llamar durante una solicitud, no son soportadas por cada proveedor compatible con OpenAI, y no son soportadas por cada modelo que esos proveedores ofrecen.

npm start dice que falta un paquete o comando: Asegúrate de que la terminal esté en la carpeta que contiene package.json, luego ejecuta npm install de nuevo. Si la descarga contiene un lockfile para un gestor de paquetes diferente, sigue ese lockfile en lugar de generar uno segundo.

La página se abre, pero una solicitud /api falla: Esto aplica a la versión del backend. Verifica que tanto Express como Vite sigan ejecutándose en la misma terminal. Confirma que Express esté en el puerto 3001 y que el objetivo del proxy en vite.config.js también diga 3001.

EADDRINUSE menciona el puerto 3001: Otro proceso está usando el puerto del backend. Detén ese proceso, o cambia tanto PORT en .env como el objetivo del proxy de Vite al mismo puerto no utilizado.

Vite usa 5174 u otro puerto de frontend: Eso es normal cuando 5173 está ocupado. Abre la URL Local que Vite imprimió. No necesitas cambiar el puerto de Express.

JunoSolución de problemas Verifica que tu terminal esté en la carpeta con package.json, que .env contenga los tres valores de IA, y que hayas reiniciado después de editarlo. Para la versión del backend, mantén ambos procesos ejecutándose. Casi todos los errores que vi al principio vinieron de una de esas tres cosas.

JunoSolución de problemas Separa fallos de entorno de fallos de proceso. Un 401 apunta a configuración del proveedor; una solicitud /api fallida usualmente significa que Express se detuvo o el puerto del proxy no coincide. Identifica la categoría primero, y el error específico se aclara.

JunoSolución de problemas Lee el package.json descargado antes de cambiar cualquier comando. El script start dice si Vite se ejecuta solo o junto a Express, y el lockfile dice que esta descarga espera npm. Leerlo toma cinco segundos y previene la sesión de depuración que de otra forma pasaría una hora en.