Ejecutar el curso de Vercel AI SDK localmente

Usa esta página para ejecutar el agente de soporte al cliente extraído en tu computadora. Conectas su servidor Express a OpenAI y los datos de Supabase creados durante el curso, luego haces un cambio en el script de inicio para que Node cargue esos valores desde .env. La guía de Embeddings y Bases de Datos Vectoriales ejecuta un proyecto relacionado contra el mismo tipo de configuración de vectores de Supabase.

Lo que necesitas primero

Instala una versión LTS compatible de Node.js. Se recomienda Node 24. También necesitas:

• una clave de API de OpenAI con acceso a facturación y modelos;
• el proyecto de Supabase y los datos creados durante el curso;
• una clave secreta de Supabase, o la clave heredada service_role.

Las claves secretas y service_role evitan Row Level Security. Pertenecen solo a este .env del lado del servidor, nunca en código del navegador. Ver claves de API de Supabase.

JunoLo que necesitas primero Instala Node.js LTS, luego reúne tu clave de OpenAI más el proyecto de Supabase y la clave del servidor del curso. Esa clave de Supabase es como la llave maestra de toda la base de datos, así que nunca se acerca al código del navegador.

JunoLo que necesitas primero El servidor lee Supabase con una clave elevada, y la búsqueda no retorna nada útil sin las filas creadas durante el curso. Ambos servicios y esos datos tienen que existir antes de tu primer ejecución. Mantén el secreto de Supabase solo en el entorno Express; nunca pertenece al navegador.

JunoLo que necesitas primero La clave service-role evita Row Level Security, así que quien la tenga actúa con los permisos de base de datos completos del servidor. Mantenla solo en Express; enviarla al navegador le da ese acceso a cada visitante con devtools abierto. He visto ese error llegar a producción exactamente una vez, y una vez fue suficiente.

Abre e instala el proyecto

Abre una terminal en la carpeta extraída que contiene package.json, luego instala los paquetes fijados:

$ cd path-to-your-downloaded-project
$ npm ci

JunoAbre e instala el proyecto Ejecuta npm ci en la carpeta extraída, la que contiene package.json. Instala exactamente las versiones de paquetes con las que se construyó el curso, así que no hay nada que configurar o adivinar aquí.

JunoAbre e instala el proyectonpm ci instala desde el lockfile incluido, así que tus versiones coinciden exactamente con el proyecto de soporte al cliente extraído. Esa coincidencia importa porque el SDK y el código del modelo fueron probados juntos; una dependencia desalineada es una sesión de depuración que no pediste.

JunoAbre e instala el proyecto Instala desde el lockfile descargado antes de tocar cualquier otra cosa. Luego cambia solo el script de inicio, así que una actualización de dependencia no relacionada no puede confundirse con la corrección del archivo de entorno; separar esos dos me ha ahorrado más noches de las que puedo contar.

Haz que Node cargue .env

Abre package.json y cambia el script de inicio de:

"start": "node server.js"

a:

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

El código usa el nombre de variable heredado SUPABASE_SERVICE_ROLE_KEY. Puedes poner una clave secreta actual de Supabase en esa variable sin renombrar el código.

Crea .env junto a package.json:

OPENAI_API_KEY=your-openai-api-key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-server-side-secret-key
PORT=3000

Crea .gitignore:

.env
node_modules/

El manual de Git cubre este hábito en ignorar archivos y buenas prácticas.

Mantén la clave de Supabase en el servidor

Nunca renombres la clave de servicio con un prefijo VITE_ ni la muevas a client.js. Tiene acceso elevado a la base de datos. No hagas commit de .env ni lo compartas en un ZIP.

JunoHaz que Node cargue .env Añade --env-file=.env al script de inicio, crea el archivo con los cuatro valores y mantenlo fuera de Git. La clave de Supabase se queda en el servidor, siempre. Un .gitignore con .env en él es el primer archivo que creo en cualquier proyecto, habiendo aprendido ese por la manera difícil.

JunoHaz que Node cargue .env Node no lee .env por sí solo, así que el proyecto extraído comienza sin configuración. La bandera --env-file lo arregla con una función integrada: ningún paquete adicional, y los valores se quedan del lado del servidor donde Express los lee.

JunoHaz que Node cargue .env La bandera integrada carga los cuatro nombres de variable existentes antes de que server.js se ejecute. Porque solo Express los lee, los secretos de OpenAI y Supabase nunca aparecen en código enviado al navegador. Sin renombrar, sin dependencia dotenv, sin nueva superficie de ataque.

Mantén los modelos suministrados

El constants.js descargado usa gpt-4o para generación de respuestas y clasificación, y text-embedding-3-small para embeddings. La configuración local no requiere cambiar ninguno de los dos modelos. Mantenlos sin cambios a menos que OpenAI rechace uno para tu proyecto. Si luego reemplazas un modelo, prueba el flujo completo del agente y confirma que los nuevos embeddings de consulta siguen siendo compatibles con los vectores almacenados de Supabase. Un cambio de embedding puede fallar silenciosamente: un modelo con la misma cantidad de dimensiones pero un espacio vectorial diferente retorna coincidencias pobres sin error, así que regenera los vectores almacenados después de cambiar el modelo de embedding.

JunoMantén los modelos suministrados Deja ambos nombres de modelo suministrados sin cambios para la configuración local; no son la razón por la que algo falla en esta página. Si tu proyecto de OpenAI rechaza uno, verifica la lista de modelos actual antes de editar el código, y reprueba todo el agente después.

JunoMantén los modelos suministrados Los roles de respuesta, clasificación y embedding tienen diferentes necesidades de compatibilidad, así que un cambio de modelo nunca es una edición de una sola línea. Un reemplazo tiene que funcionar con este SDK y mantenerse compatible con los vectores ya almacenados en Supabase.

JunoMantén los modelos suministrados Un modelo de embedding con la misma cantidad de dimensiones pero un espacio vectorial diferente rompe la búsqueda silenciosamente: las consultas retornan coincidencias pobres y ningún error en absoluto. Por eso un cambio de embedding significa regenerar los vectores almacenados, no solo editar constants.js. La degradación silenciosa es el modo de fallo que más respeto, porque nada te alerta.

Ejecuta el agente

$ npm start

Abre http://localhost:3000, o usa el puerto que configuraste en .env. Detén el servidor con Ctrl+C.

La carga de la página muestra que el servidor local se ejecuta. Haz una pregunta cubierta por los datos del curso: una respuesta útil muestra que la búsqueda de Supabase y la generación de OpenAI también funcionan. Si una respuesta falla, la terminal del servidor imprime la primera llamada que falla en la cadena: embedding, búsqueda o generación. El capítulo de RAG explica por qué el agente fundamenta sus respuestas en datos del curso recuperados en primer lugar.

JunoEjecuta el agente Ejecuta npm start y abre la dirección local en tu navegador. La carga de la página prueba que el servidor se ejecuta; una respuesta completa también necesita OpenAI y los datos de Supabase del curso, así que trata esos como dos ganancias separadas.

JunoEjecuta el agente Trata el inicio del servidor y la generación de respuestas como verificaciones separadas: un servidor en ejecución con respuestas que fallan es un problema de servicio, no un problema de código. Detén con Ctrl+C y configura PORT en .env si la dirección predeterminada está ocupada.

JunoEjecuta el agente Cuando una respuesta falla, la terminal del servidor imprime la primera llamada que falla en la cadena: embedding, búsqueda o generación. Lee ese error y atribuye el fallo antes de tocar ninguna configuración. Adivinar configuración con tres llamadas externas en juego es cómo desaparece una noche; hablo por experiencia.

Solución de problemas

Missing OPENAI_API_KEY: Confirma que el script de inicio incluye --env-file=.env, que .env está junto a package.json, y que el nombre de variable coincide exactamente.

Error de autenticación de Supabase o relación: Confirma que la URL y la clave del servidor pertenecen al mismo proyecto, luego completa los pasos de esquema y datos del curso. No sustituyas una clave publicable para esta operación del servidor.

El puerto 3000 ya está en uso: Cambia PORT en .env, reinicia el servidor y abre el nuevo puerto.

La página carga pero las respuestas fallan: Verifica la terminal del servidor para el primer error del proveedor o base de datos. El inicio local por sí solo no valida ningún servicio externo.

JunoSolución de problemas Una clave faltante apunta al script de inicio o .env, un error de Supabase apunta al proyecto o sus datos, y una página cargada con respuestas que fallan apunta a un servicio externo. Haz coincidir el síntoma con la capa primero, y la solución generalmente se nombra a sí misma.

JunoSolución de problemas Lee el primer error de terminal del servidor, no el último; los fracasos posteriores son generalmente consecuencia del primero. Ese primer error separa la carga de entorno, la autorización de base de datos, el enlace de puerto y el acceso a OpenAI en cuatro soluciones distintas.

JunoSolución de problemas Recorre los errores del servidor en orden: ¿cargó Node .env, devolvió Supabase los datos del curso, generó OpenAI una respuesta? Y nunca sustituyas una clave de Supabase segura para el navegador para acallar un error; eso oculta un problema de tabla o política faltante en lugar de solucionarlo.