Ejecutar embeddings y bases de datos vectoriales en tu máquina

Usa esta página para ejecutar el chatbot del curso que extrajiste en tu computadora. Aquí instalas dos paquetes faltantes, adaptas la configuración de OpenAI y Supabase del chatbot para Vite, e inicias el proyecto del navegador con la base de datos que construiste durante el curso.

Lo que necesitas primero

Instala una versión LTS soportada de Node.js. Se recomienda Node 24 e incluye npm. También necesitas una clave de API de OpenAI y un proyecto de Supabase existente que contenga los datos del curso.

Para Supabase, usa una clave publicable o la clave anon heredada. Estas claves están diseñadas para aparecer en código del navegador: cualquiera que copie una solo puede hacer lo que tus políticas de Row Level Security (reglas de lectura por fila de Supabase) permitan. Nunca pongas una clave secreta o una clave service_role en este proyecto del navegador. Consulta Claves de API de Supabase para los tipos de clave actuales.

La clave de OpenAI no tiene un alcance equivalente: cualquier copia de ella puede hacer solicitudes facturadas a tu cuenta, así que en producción nunca pertenece en código cliente. Esta configuración de aprendizaje la envía al navegador de todas formas; la advertencia en la sección de Vite explica los límites de hacerlo. El equivalente del lado del servidor de esta configuración, el proyecto del SDK de Vercel AI, usa el mismo proyecto de Supabase pero con una clave secreta. Una clave secreta es aceptable allí porque ese proyecto se ejecuta en un servidor, así que sus claves nunca llegan a un navegador.

JunoLo que necesitas primero Instala Node.js LTS, luego ten tu clave de OpenAI y el proyecto de Supabase que construiste durante el curso listos. Para Supabase, usa una clave publicable o anon, el tipo diseñado para navegadores, nunca un secreto de servidor. Una vez usé el tipo de clave incorrecto y pasé una noche aprendiendo la diferencia entre ellas.

JunoLo que necesitas primero Este proyecto necesita Node más dos servicios en vivo: OpenAI y la base de datos de Supabase del curso. La clave de Supabase que configures se vuelve legible en código cliente, así que debe ser una clave publicable o anon cuyo acceso limite Row Level Security. No pongas ninguna clave del lado del servidor en este proyecto.

JunoLo que necesitas primero Una clave anon filtrada está limitada: solo puede hacer lo que tus políticas de Row Level Security permitan, que es exactamente por qué ese tipo de clave está diseñado para código de navegador. La clave de OpenAI no tiene un alcance equivalente, y cualquier copia de ella gasta tu dinero hasta que la revoques. Esa diferencia decide la arquitectura: una clave de Supabase en código cliente es una cuestión de política, una clave de OpenAI en código cliente de producción es un error.

Abre la carpeta del proyecto

Abre una terminal en la carpeta del chatbot extraído que contiene package.json:

$ cd ruta-a-tu-proyecto-descargado

Para confirmar que tienes la descarga correcta, abre package.json: la exportación del chatbot declara Vite, y la fuente junto a ella incluye los archivos config.js e index.js que las siguientes secciones editan. Estas instrucciones se ajustan al chatbot completado, cuyo código importa tanto openai como @supabase/supabase-js; el nombre de la carpeta por sí solo no lo distingue de la exportación de una lección anterior.

JunoAbre la carpeta del proyecto Trabaja en la carpeta extraída que contiene package.json; toda instalación y todo archivo en esta página pertenece allí. Si la terminal está en otro lugar, los comandos se ejecutan en la carpeta incorrecta y nada después de esto funciona. Verifico la lista de carpetas buscando package.json antes de escribir cualquier cosa, un hábito que construí después de cometer ese error varias veces.

JunoAbre la carpeta del proyecto Confirma la carpeta antes de editar algo: package.json en el nivel superior, Vite declarado dentro y config.js e index.js junto a él. Treinta segundos de verificación aquí cuestan menos que reparar los archivos de un proyecto diferente. Todo comando en esta página asume que estás en esta carpeta.

JunoAbre la carpeta del proyecto Verifica el hito antes de repararlo: estas instrucciones se ajustan a la exportación cuya fuente importa tanto OpenAI como Supabase y ejecuta el flujo del chatbot completado. La exportación de una lección anterior se ve casi idéntica si solo lees el nombre de la carpeta. Dos minutos gastados leyendo los imports cuestan menos que una tarde gastada depurando una reparación que el proyecto nunca necesitó.

Prepara el proyecto para Vite

Instala la dependencia Vite declarada, luego los dos paquetes que la fuente importa pero el package.json descargado no declara:

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

Abre config.js y reemplaza toda lectura de ambiente de Scrimba. Mantén los imports, exports y validación existentes, pero reemplaza tres nombres de ambiente en cuatro ocurrencias; OPENAI_API_KEY aparece dos veces:

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

Las dos lecturas de OPENAI_API_KEY están en la validación y el cliente de OpenAI, así que cambia ambas.

Abre index.js y cambia el modelo de chat de gpt-4 a gpt-4o-mini. Deja el modelo de embedding text-embedding-ada-002 suministrado sin cambios mientras sigues el curso. Los vectores existentes en la base de datos del curso deben tener las mismas dimensiones que los embeddings de consulta; cambiar ese modelo es una migración de base de datos separada, no parte de la configuración local.

Crea .env junto a package.json:

VITE_OPENAI_API_KEY=tu-clave-api-openai
VITE_SUPABASE_URL=https://tu-proyecto.supabase.co
VITE_SUPABASE_API_KEY=tu-clave-publicable-o-anon

También crea .gitignore:

.env
node_modules/

Enviar .env a un repositorio de Git es la forma más común en que se filtra una clave; ignorar archivos y buenos hábitos cubre el hábito en detalle.

Estas credenciales son visibles en el navegador

Vite copia valores VITE_ en el bundle del frontend. Usa credenciales de aprendizaje restringidas, habilita Row Level Security en Supabase, y nunca publiques esta versión. Una aplicación de producción debe mover la solicitud de OpenAI a un backend.

JunoPrepara el proyecto para Vite Instala los paquetes faltantes, reemplaza toda lectura de ambiente antigua con su equivalente de Vite, y pon tus claves en .env con una clave de Supabase segura para navegador. Luego mantén .env fuera de Git. Una vez publiqué una clave con mi primer proyecto y pasé la noche reemplazándola, así que este orden está escrito por experiencia.

JunoPrepara el proyecto para Vite La fuente importa dos SDKs que la descarga nunca declaró y lee los nombres de ambiente de Scrimba, así que instala ambos paquetes y cambia las cuatro lecturas de ambiente antes de iniciar Vite. Si dejas una de esas lecturas sin cambios, la aplicación falla en tiempo de ejecución en lugar de en tiempo de compilación. El par .env y .gitignore termina la reparación.

JunoPrepara el proyecto para Vite Instalar los SDKs corrige los imports; los nombres VITE_ son lo que coloca los valores en el bundle, que también entrega la clave de OpenAI al código del navegador. Eso es aceptable para una lección y descalificador para producción, así que mueve la llamada de OpenAI detrás de un backend antes de que usuarios reales lleguen a este chatbot. He visto un proyecto saltar ese paso y terminó con una clave revocada y una factura inesperada.

Ejecuta el proyecto

$ npm start

Abre la URL Local impresa por Vite y hazle al chatbot una pregunta cubierta por los datos del curso. Una respuesta útil muestra que la página, la recuperación de Supabase y la solicitud de OpenAI están funcionando. Reinicia el comando después de cambiar .env, y detente con Ctrl+C.

JunoEjecuta el proyecto Ejecuta npm start, abre la URL Local, y hazle al chatbot algo que los datos del curso cubran. Si cambias .env, reinicia el comando para que Vite lea los nuevos valores, y presiona Ctrl+C cuando termines. Una vez olvidé ese reinicio y me confundió toda una tarde, así que espero que esta nota te ahorré una.

JunoEjecuta el proyecto Vite iniciando limpiamente prueba que el proyecto reparado se agrupa; una respuesta útil prueba el resto. Una buena pregunta prueba el acceso a OpenAI junto con las filas y políticas de Supabase al mismo tiempo, así que trátala como tu prueba de integración. Reinicia después de cualquier cambio en .env.

JunoEjecuta el proyecto Una página que se carga no es una prueba aprobada. Verifica servicio local, recuperación de Supabase, búsqueda de embedding y generación de respuesta como puntos de control separados, porque cada uno puede fallar silenciosamente detrás de una página perfectamente renderizada. Una vez declaré un proyecto terminado después de ver solo la pantalla de inicio, y el bug apareció durante la demostración.

Solución de problemas

Failed to resolve import "openai" o "@supabase/supabase-js": Ejecuta ambos comandos de instalación mostrados anteriormente en esta página, y ejecútalos en la carpeta que contiene package.json.

process is not defined: Una referencia process.env permanece en config.js. Reemplázala con el valor import.meta.env.VITE_... correspondiente.

Supabase no devuelve filas o devuelve un error de permisos: Confirma la URL del proyecto, usa una clave publicable o anon, y verifica que la tabla del curso y las políticas de Row Level Security existan en ese mismo proyecto.

OpenAI rechaza el modelo o la clave: Confirma la facturación y el acceso de la clave en la cuenta de OpenAI. Usa un modelo actual disponible para ese proyecto.

JunoSolución de problemas Lee el error como una pista: un import faltante significa que los paquetes extras no están instalados, un error de ambiente significa que un nombre de Vite sigue siendo incorrecto, y respuestas vacías generalmente indican un problema con los datos de Supabase o permisos. Tómalos uno a la vez. Todo problema en esta lista es reversible, así que puedes arreglar cada uno y seguir adelante.

JunoSolución de problemas Verifica en orden de dependencia: resolución de paquetes, luego las cuatro sustituciones de ambiente, luego la URL de Supabase y políticas RLS, luego la clave de OpenAI y modelo. Cada capa depende de la anterior, así que una corrección fuera de orden puede verse como una falla completamente nueva. Detente en la primera capa rota y repárala allí.

JunoSolución de problemas Un chatbot sin respuesta útil falla en una de tres capas: el bundle del navegador, permisos y filas de Supabase, o la solicitud de OpenAI, y cada una puede fallar mientras la página se renderiza hermosamente. Verifica en ese orden. Una página que se abre solo prueba que Vite está ejecutándose.