Ejecutar el curso del SDK de Vercel AI 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 a los datos de Supabase creados en 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 en 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 facturación y acceso a modelos;
• el proyecto de Supabase y los datos creados durante el curso;
• una clave con acceso a la base de datos del lado del servidor: ya sea una clave secreta de Supabase (comienza con sb_secret_) o la clave heredada service_role.

Una clave secreta de Supabase y la clave heredada service_role ambas omiten la Row Level Security. Una clave de cualquiera de los dos tipos pertenece solo a este .env del lado del servidor, nunca en código del navegador. Supabase está descontinuando las claves heredadas hacia finales de 2026; aún funcionan, pero una clave secreta es la que durará. Ver claves de API de Supabase.

JunoLo que necesitas primero Instala Node.js LTS, luego reúne tu clave de OpenAI, el proyecto de Supabase del curso y su clave secreta.

Esa clave de Supabase funciona como una clave maestra de toda la base de datos, así que solo va en el archivo .env del servidor.

JunoLo que necesitas primero El servidor lee Supabase con una clave que tiene permisos elevados, y la recuperación no devuelve nada útil sin las filas creadas durante el curso. Ambos servicios y esos datos tienen que existir antes de tu primera ejecución.

JunoLo que necesitas primero Una clave secreta y la clave heredada service_role ambas omiten Row Level Security, así que quien las tenga actúa con los permisos completos de la base de datos del servidor. En código del navegador, cada visitante que abra devtools la tendría también. Mantenla solo en Express.

Abre e instala el proyecto

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

$ 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 elegir aquí.

JunoAbre e instala el proyectonpm ci instala desde el archivo de bloqueo incluido, así que tus versiones coinciden exactamente con el proyecto de soporte al cliente extraído. Eso importa porque el SDK de AI y el código del modelo fueron escritos contra esas versiones.

JunoAbre e instala el proyecto Instala desde el archivo de bloqueo descargado antes de tocar cualquier otra cosa. Luego cambia solo el script de inicio, así una actualización de dependencia no relacionada no puede confundirse con la corrección del archivo de entorno.

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 almacenar una clave secreta de Supabase actual en esa variable sin renombrar nada en el código. El valor tiene que ser una clave secreta o la clave heredada service_role, no una clave publicable.

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 secreta de Supabase con un prefijo VITE_ ni la muevas a client.js. Esa clave tiene acceso elevado a la base de datos. No hagas commit de .env ni la compartas en un ZIP.

JunoHaz que Node cargue .env Añade --env-file=.env al script de inicio, crea .env con los cuatro valores, y mantenlo fuera de Git.

Crea el .gitignore antes de tu primer commit, así la clave nunca tiene la oportunidad de llegar al repositorio.

JunoHaz que Node cargue .env Node no lee .env por su cuenta, así que el proyecto extraído comienza sin configuración. La bandera --env-file está integrada en Node: sin paquetes extra, y los valores se quedan en el servidor donde Express los lee.

JunoHaz que Node cargue .env La bandera carga los cuatro nombres de variables existentes en process.env antes de que server.js se ejecute. Solo Express los lee, así que los secretos de OpenAI y Supabase nunca aparecen en código enviado al navegador, y no se necesita ninguna dependencia dotenv.

Mantén los modelos suministrados

El constants.js descargado usa gpt-4o para la generación y clasificación de respuestas y text-embedding-3-small para embeddings. La configuración local no requiere cambiar ninguno de los modelos. Mantenlos sin cambios a menos que OpenAI rechace uno para tu proyecto.

Si luego reemplazas un modelo, prueba el flujo completo del agente. Reemplazar el modelo de embedding requiere cuidado extra: un modelo con la misma cantidad de dimensiones pero un espacio vectorial diferente devuelve coincidencias pobres y no reporta error, así que regenera los vectores almacenados de Supabase después de cambiarlo.

JunoMantén los modelos suministrados Deja ambos nombres de modelo en constants.js como están. Si tu proyecto de OpenAI rechaza uno, verifica la lista de modelos actual antes de editar el código, y prueba el agente completo después.

JunoMantén los modelos suministrados Los roles de respuesta, clasificación y embedding tienen necesidades de compatibilidad diferentes, así que reemplazar un modelo nunca es un cambio de una 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 Los embeddings de consulta se comparan contra los vectores almacenados, así que ambos tienen que venir del mismo modelo. Un modelo de embedding diferente con la misma cantidad de dimensiones rompe la recuperación silenciosamente: las respuestas empeoran y nada genera error. Cambiarlo significa regenerar los vectores almacenados, no solo editar constants.js.

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 página que se carga muestra que el servidor local está ejecutándose. Haz una pregunta cubierta por los datos del curso: una respuesta útil muestra que la recuperación de Supabase y la generación de OpenAI también funcionan. El capítulo RAG explica por qué el agente basa sus respuestas en datos del curso recuperados.

JunoEjecuta el agente Ejecuta npm start y abre la dirección local en tu navegador. La página que se carga 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 una segunda verificación separada.

JunoEjecuta el agente Trata el inicio del servidor y la generación de respuestas como verificaciones separadas: un servidor en ejecución con respuestas fallidas apunta a OpenAI, Supabase, o las claves que les diste, no al código. Detén con Ctrl+C y configura PORT en .env si otro proceso ya usa el puerto 3000.

JunoEjecuta el agente Un proceso Express sirve la página y la API, así que una página cargada solo prueba el servicio HTTP. Las respuestas aún dependen de llamadas a OpenAI y recuperación de Supabase, y cualquiera puede fallar mucho después de que el inicio tuvo éxito.

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 la variable coincide exactamente.

Error de autenticación de Supabase o de relación: Confirma que la URL y la clave secreta de Supabase pertenecen al mismo proyecto, luego completa los pasos de esquema y datos del curso. Esta operación del lado del servidor necesita una clave secreta o la clave heredada service_role; una clave publicable, que está pensada para código del navegador, no tiene el acceso que requiere.

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

La página se carga pero las respuestas fallan: Verifica el terminal del servidor para el primer error de proveedor o base de datos. El hecho de que la página se cargue no prueba que OpenAI o Supabase respondan.

JunoSolución de problemas Una clave faltante apunta al script de inicio o a .env, un error de Supabase apunta al proyecto o sus datos, y una página cargada con respuestas fallidas apunta a un servicio externo. Haz coincidir el síntoma con uno de esos primero.

JunoSolución de problemas Lee el primer error del terminal del servidor, no el último; las fallas posteriores suelen ser consecuencias del primero. Ese primer error distingue la carga de entorno, el acceso a la base de datos, el enlace de puerto y el acceso a OpenAI.

JunoSolución de problemas Verifica en orden: ¿Node cargó .env, Supabase devolvió los datos del curso, OpenAI generó una respuesta? Nunca intercambies una clave publicable para hacer desaparecer un error; eso oculta una tabla o política faltante en lugar de arreglarlo.