Implementa automáticamente una aplicación web de Genkit de IA generativa de Node.js desde el control de versión a Cloud Run

1. Descripción general

Implementar una aplicación web por primera vez puede ser intimidante. Incluso después de la primera implementación, si el proceso es demasiado laborioso, es posible que evites implementar versiones nuevas de tu aplicación. Con la implementación continua, puedes implementar automáticamente los cambios de tu aplicación con facilidad.

En este lab, escribirás una aplicación web y configurarás Cloud Run para que implemente automáticamente tu aplicación cuando se realice un cambio en el código fuente de la aplicación. Luego, modifica tu aplicación y vuelve a implementarla.

Qué aprenderás

• Escribe una aplicación web con el editor de Cloud Shell
• Almacena el código de tu aplicación en GitHub
• Implementa automáticamente tu aplicación en Cloud Run

• Agrega IA generativa a tu aplicación con Genkit
• Administra instrucciones de LLM con la biblioteca dotprompt

2. Requisitos previos

1. Si aún no tienes una Cuenta de Google, debes crear una.
   • Usa una cuenta personal en lugar de una cuenta de trabajo o institución educativa. Es posible que las cuentas de trabajo y de instituciones educativas tengan restricciones que te impidan habilitar las APIs necesarias para este lab.
2. Si aún no tienes una cuenta de GitHub, debes crear una.
   • Usa una cuenta de GitHub existente si la tienes. Es más probable que GitHub bloquee una cuenta nueva como spam.
   • Configura la autenticación de dos factores en tu cuenta de GitHub para reducir las probabilidades de que se marque como spam.

3. Configura el proyecto

1. Accede a la consola de Google Cloud.
2. Habilita la facturación en la consola de Cloud.
   • Completar este lab debería costar menos de USD 1 en recursos de Cloud.
   • Puedes seguir los pasos al final de este lab para borrar recursos y evitar cargos adicionales.
   • Los usuarios nuevos pueden acceder a la prueba gratuita de USD 300.
   • ¿Asistirás a un evento sobre IA generativa para desarrolladores? Es posible que haya disponible un crédito de USD 1.
3. Crea un proyecto nuevo o elige reutilizar uno existente.
4. Confirma que la facturación esté habilitada en Mis proyectos en la Facturación de Cloud.
   • Si tu proyecto nuevo dice Billing is disabled en la columna Billing account, haz lo siguiente:
     1. Haz clic en los tres puntos de la columna Actions.
     2. Haz clic en Cambiar la facturación.
     3. Selecciona la cuenta de facturación que deseas usar.
   • Si asistes a un evento de IA generativa para desarrolladores, es probable que la cuenta se llame Cuenta de facturación de prueba de Google Cloud Platform.

4. Abre el editor de Cloud Shell

1. Navega al Editor de Cloud Shell.
2. Si la terminal no aparece en la parte inferior de la pantalla, ábrela:
   • Haz clic en el menú de hamburguesa .
   • Haz clic en Terminal.
   • Haz clic en Terminal nueva.
3. En la terminal, configura tu proyecto con este comando:
   • Formato:

     gcloud config set project [PROJECT_ID]
     

   • Ejemplo:

     gcloud config set project lab-project-id-example
     

   • Si no recuerdas el ID de tu proyecto, haz lo siguiente:
     • Puedes enumerar todos los IDs de tus proyectos con el siguiente comando:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. Si se te solicita autorización, haz clic en Autorizar para continuar.
5. Deberías ver el siguiente mensaje:

   Updated property [core/project].
   

   Si ves un WARNING y se te pregunta Do you want to continue (Y/N)?, es probable que hayas ingresado el ID del proyecto de forma incorrecta. Presiona N, presiona Enter y vuelve a intentar ejecutar el comando gcloud config set project.

5. Habilita las APIs

En la terminal, habilita las APIs:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

Este comando puede tardar unos minutos en completarse, pero, finalmente, debería producir un mensaje de éxito similar a este:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Configurar Git

1. Configura tu correo electrónico de usuario global de Git:

   git config --global user.email "[e-mail]"
   

2. Configura tu nombre de usuario global de Git:

   git config --global user.name "Your Name"
   

3. Configura tu rama predeterminada global de Git en main:

   git config --global init.defaultBranch main
   

7. Escribe el código

Para escribir una aplicación en Node.js, sigue estos pasos:

1. Navega al directorio principal:

   cd ~
   

2. Crea el directorio codelab-genai.

   mkdir codelab-genai
   

3. Navega al directorio codelab-genai:

   cd codelab-genai
   

4. Crea un archivo index.js:

   touch index.js
   

5. Crea el archivo package.json:

   npm init es6 -y
   

6. Agrega express como una dependencia

   npm install express
   

7. Agrega el archivo .gitignore para evitar la confirmación de node_modules

   echo node_modules/ >> .gitignore
   

8. Abre el archivo index.js en el editor de Cloud Shell:

   cloudshell edit index.js
   

   Ahora debería aparecer un archivo vacío en la parte superior de la pantalla. Aquí puedes editar este archivo index.js.
9. Copia el siguiente código y pégalo en el archivo index.js abierto:

   import express from 'express';
   
   const app = express();
   app.get('/', async (req, res) => {
       res.send('Hello world!');
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

   Después de unos segundos, el editor de Cloud Shell guardará tu código automáticamente. Este código responde a las solicitudes HTTP con nuestro saludo “Hello world!”.

El código inicial de tu aplicación está terminado y listo para almacenarse en el control de versión.

8. Crea un repositorio

1. Regresa a la terminal de Cloud Shell en la parte inferior de la pantalla.
2. Asegúrate de seguir en el directorio correcto:

   cd ~/codelab-genai
   

3. Inicializa tu repositorio de Git

   git init -b main
   

4. Accede a la CLI de GitHub.

   gh auth login
   

   Presiona Enter para aceptar las opciones predeterminadas y sigue las instrucciones de la herramienta de la CLI de GitHub, incluidas las siguientes:
   1. ¿A qué cuenta quieres acceder? GitHub.com
   2. ¿Cuál es tu protocolo preferido para las operaciones de Git en este host? HTTPS
   3. ¿Quieres autenticar Git con tus credenciales de GitHub? Y (omite este paso si no aparece).
   4. ¿Cómo deseas autenticar la CLI de GitHub? Login with a web browser
   5. Copia tu código de un solo uso
   6. Abre https://github.com/login/device.
   7. Pega tu código de uso único
   8. Haz clic en Authorize github.
   9. Completa tu acceso
5. Confirma que accediste a tu cuenta:

   gh api user -q ".login"
   

   Si accediste correctamente, se mostrará tu nombre de usuario de GitHub.
6. Crea una variable de GITHUB_USERNAME

   GITHUB_USERNAME=$(gh api user -q ".login")
   

7. Confirma que creaste la variable de entorno:

   echo ${GITHUB_USERNAME}
   

   Si creaste la variable correctamente, debería mostrarse tu nombre de usuario de GitHub.
8. Crea un repositorio de GitHub vacío llamado codelab-genai:

   gh repo create codelab-genai --private
   

   Si recibes el siguiente error:

   GraphQL: Name already exists on this account (createRepository)
   

   Entonces, ya tienes un repositorio llamado codelab-genai. Tienes dos opciones para seguir este instructivo:
   • Borra el repositorio de GitHub existente
   • Crea un repositorio con un nombre diferente y recuerda cambiarlo en los siguientes comandos.
9. Agrega el repositorio codelab-genai como el origin remoto:

   git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai
   

9. Comparte tu código

1. Confirma que estás en el directorio correcto:

   cd ~/codelab-genai
   

2. Agrega todos los archivos del directorio actual a esta confirmación:

   git add .
   

3. Crea la primera confirmación:

   git commit -m "add http server"
   

4. Envía tu confirmación a la rama main del repositorio origin:

   git push -u origin main
   

Puedes ejecutar este comando y visitar la URL resultante para ver el código de tu aplicación en GitHub:

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/index.js \n\n"

10. Configura implementaciones automáticas

1. Deja abierta la pestaña del editor de Cloud Shell. Volveremos a esta pestaña más adelante.
2. En una pestaña nueva, visita la página de Cloud Run.
3. Selecciona el proyecto de Google Cloud correcto en la consola .
4. Haz clic en CONNECT REPO.
5. Haz clic en CONFIGURAR CON CLOUD BUILD.
   1. Selecciona GitHub como Proveedor de repositorio.
      • Si no accediste a tu cuenta de GitHub en el navegador, hazlo con tus credenciales.
   2. Haz clic en Autenticar y, luego, en Continuar.
   3. Después de acceder, verás un mensaje en la página de Cloud Run que indica La app de GitHub no está instalada en ninguno de tus repositorios.
   4. Haz clic en el botón INSTALL GOOGLE CLOUD BUILD.
      • En la página de configuración de la instalación, selecciona Only select repositories y elige el repositorio codelab-genai que creaste a través de la CLI.
      • Haz clic en Instalar.
      • Nota: Si tienes muchos repositorios de GitHub, la carga puede tardar unos minutos.
   5. Selecciona your-user-name/codelab-genai como el repositorio
      .
      • Si el repositorio no está presente, haz clic en el vínculo Administrar repositorios conectados.
   6. Deja Rama como ^main$.
   7. Haz clic en Go, Node.js, Python, Java, .NET Core, Ruby o PHP a través de los buildpacks de Google Cloud.
      • Deja los otros campos (Build context directory, Entrypoint y Function target) como están.
   8. Haga clic en Guardar.
6. Desplázate hacia abajo hasta Authentication.
7. Haz clic en Permitir invocaciones sin autenticar.
8. Haz clic en CREAR.

Una vez que finalice la compilación (lo que tardará varios minutos), ejecuta este comando y visita la URL resultante para ver tu aplicación en ejecución:

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. Cómo cambiar tu código

Regresa al editor de Cloud Shell

Si aún tienes abierto el editor de Cloud Shell, puedes omitir estos pasos.

1. Navega al Editor de Cloud Shell.
2. Si la terminal no aparece en la parte inferior de la pantalla, ábrela:
   • Haz clic en el menú de hamburguesa .
   • Haz clic en Terminal.
   • Haz clic en Terminal nueva.
3. En la terminal, configura tu proyecto con este comando:
   • Formato:

     gcloud config set project [PROJECT_ID]
     

   • Ejemplo:

     gcloud config set project lab-project-id-example
     

   • Si no recuerdas el ID de tu proyecto, haz lo siguiente:
     • Puedes enumerar todos los IDs de tus proyectos con el siguiente comando:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. Si se te solicita autorización, haz clic en Autorizar para continuar.
5. Deberías ver el siguiente mensaje:

   Updated property [core/project].
   

   Si ves un WARNING y se te pregunta Do you want to continue (Y/N)?, es probable que hayas ingresado el ID del proyecto de forma incorrecta. Presiona N, presiona Enter y vuelve a intentar ejecutar el comando gcloud config set project.

Agrega Genkit y Vertex AI a tu aplicación

1. Regresa a la terminal de Cloud Shell en la parte inferior de la pantalla.
2. Asegúrate de seguir en el directorio correcto:

   cd ~/codelab-genai
   

3. Instala el SDK de Genkit para Node.js:

   npm install @genkit-ai/ai
   

4. Instala el SDK de Genkit para Node.js de Vertex AI:

   npm install @genkit-ai/vertexai
   

5. Vuelve a abrir index.js en el editor de Cloud Shell

   cloudshell edit ~/codelab-genai/index.js
   

6. Reemplaza el código de tu archivo index.js por lo siguiente:

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
       const llmResponse = await ai.generate({
           model: gemini15Flash,
           prompt: prompt,
       });
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

1. Asegúrate de que aún te encuentres en el directorio correcto en Cloud Shell:

   cd ~/codelab-genai
   

2. Ejecuta estos comandos para confirmar una nueva versión de tu aplicación en tu repositorio local de Git:

   git add .
   git commit -m "add latest changes"
   

3. Envía los cambios a GitHub:

   git push
   

4. Cuando finalice la compilación, ejecuta este comando y visita la aplicación implementada:

   echo -e "\n\nOnce the build finishes, visit your live application:\n \
       "$( \
           gcloud run services list | \
           grep codelab-genai | \
           awk '/URL/{print $2}' | \
           head -1 \
       )" \n\n"
   

Es posible que la compilación tarde varios minutos en finalizar antes de que puedas ver los cambios.

Puedes ver el historial de todas las revisiones aquí: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

12. (Opcional) Usa archivos .prompt con Genkit

1. Regresa a la terminal de Cloud Shell en la parte inferior de la pantalla.
2. Asegúrate de seguir en el directorio correcto:

   cd ~/codelab-genai
   

3. Crea una carpeta prompts para almacenar tus instrucciones:

   mkdir prompts
   

4. Crea un archivo animal-facts.prompt para crear tu primera instrucción:

   touch prompts/animal-facts.prompt
   

5. Abre el archivo animal-facts.prompt en el editor de Cloud Shell:

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

6. Edita animal-facts.prompt y pega el siguiente código:

   ---
   model: vertexai/gemini-1.5-flash
   input:
       schema:
           animal: string
   ---
   
   Give me 10 fun facts about {{animal}}. Return the results as HTML without markdown backticks.
   

7. Abre el archivo index.js en el editor de Cloud Shell:

   cloudshell edit ~/codelab-genai/index.js
   

8. Reemplaza el código de tu archivo index.js por lo siguiente:

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const animalPrompt = ai.prompt('animal-facts');
       const llmResponse = await animalPrompt({animal});
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

1. Asegúrate de que aún te encuentres en el directorio correcto en Cloud Shell:

   cd ~/codelab-genai
   

2. Ejecuta estos comandos para confirmar una nueva versión de tu aplicación en tu repositorio local de Git:

   git add .
   git commit -m "add latest changes"
   

3. Envía los cambios a GitHub:

   git push
   

4. Cuando finalice la compilación, ejecuta este comando y visita la aplicación implementada:

   echo -e "\n\nOnce the build finishes, visit your live application:\n \
       "$( \
           gcloud run services list | \
           grep codelab-genai | \
           awk '/URL/{print $2}' | \
           head -1 \
       )" \n\n"
   

Es posible que la compilación tarde varios minutos en finalizar antes de que puedas ver los cambios.

Puedes ver el historial de todas las revisiones aquí: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (Opcional) Usa instrucciones del sistema

En este paso, se supone que ya agregaste archivos .prompt en el paso anterior.

1. Regresa a la terminal de Cloud Shell en la parte inferior de la pantalla.
2. Asegúrate de seguir en el directorio correcto:

   cd ~/codelab-genai
   

3. Abre el archivo animal-facts.prompt en el editor de Cloud Shell:

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

4. Edita animal-facts.prompt y pega el siguiente código:

   ---
   model: vertexai/gemini-1.5-flash
   config:
       temperature: 0.9
   input:
       schema:
           animal: string
   ---
   
   role "system"
   The user should have submitted an animal.
   If the user requests anything besides animal fun facts, respond in a kind and firm manner that you only provide information about fun facts.
   Give the user 10 fun facts about the animal the user provided.
   All responses should be valid HTML without markdown backticks.
   
   role "user"
   {{animal}}
   

1. Asegúrate de que aún te encuentres en el directorio correcto en Cloud Shell:

   cd ~/codelab-genai
   

2. Ejecuta estos comandos para confirmar una nueva versión de tu aplicación en tu repositorio local de Git:

   git add .
   git commit -m "add latest changes"
   

3. Envía los cambios a GitHub:

   git push
   

4. Cuando finalice la compilación, ejecuta este comando y visita la aplicación implementada:

   echo -e "\n\nOnce the build finishes, visit your live application:\n \
       "$( \
           gcloud run services list | \
           grep codelab-genai | \
           awk '/URL/{print $2}' | \
           head -1 \
       )" \n\n"
   

Es posible que la compilación tarde varios minutos en finalizar antes de que puedas ver los cambios.

Puedes ver el historial de todas las revisiones aquí: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

14. Felicitaciones

En este lab, escribiste una aplicación web y configuraste Cloud Run para implementar automáticamente tu aplicación cuando se realizaba un cambio en el código fuente de la aplicación. Luego, modificaste tu aplicación y la volviste a implementar.

Si disfrutaste este lab, puedes volver a intentarlo en otro lenguaje de programación o framework:

• Python
• Node.js
• Go
• Java
• Angular
• Next.js

Estas son algunas opciones para continuar tu aprendizaje:

• Documentos de Genkit: Comienza a usar Genkit
• Codelab para agregar observabilidad a tu aplicación de Node.js: Técnicas prácticas de observabilidad para aplicaciones de IA generativa en JavaScript
• Codelab para agregar un frontend a tu aplicación con Next.js: Implementa automáticamente una aplicación web de IA generativa de Next.js desde el control de versiones en Cloud Run
• Codelab para mostrar cómo usar las llamadas a funciones: Cómo usar las llamadas a funciones de Gemini con Cloud Run
• Codelab para usar la IA y procesar contenido de video: Cómo usar la API de Video Intelligence de Cloud Run Jobs para procesar un video escena por escena