Gemini Function Calling con Node.js: Guía Práctica para Operaciones (2026)
Automatice flujos de trabajo con Gemini AI en Node.js. Aprenda a usar la llamada a funciones con ejemplos de código y manejo de errores. ¡Impulse la eficiencia ahora!
Bienvenido a la guía definitiva sobre el tutorial de Gemini Function Calling en Node.js, un cambio de juego tanto para líderes de operaciones como para desarrolladores. En 2026, integrar sin problemas la IA avanzada en la infraestructura Node.js existente no es solo un lujo; es un imperativo estratégico. Esta guía va directo al grano. Le mostraré qué funciona realmente, le proporcionaré ejemplos concretos y le ofreceré ideas que empoderarán a sus equipos para construir sistemas eficientes y automatizados con Gemini.
Por qué Gemini Function Calling en Node.js es crucial para líderes de operaciones (2026)
Para los gerentes de operaciones, la IA a menudo se siente como un futuro distante o un proyecto complejo y que consume muchos recursos. Gemini Function Calling en Node.js cambia eso por completo. Imagine que su asistente de IA no solo genera texto, sino que interactúa activamente con sus sistemas internos. Podría reservar reuniones, actualizar registros de CRM, obtener datos de inventario en tiempo real o activar pipelines de implementación, todo basado en indicaciones en lenguaje natural. Ese es el poder del que estamos hablando.
Desde el punto de vista operativo, esto se traduce directamente en beneficios tangibles:
- Eficiencia sin precedentes: Automatice tareas repetitivas y basadas en reglas que actualmente consumen valiosas horas humanas. Piense en el tiempo que se ahorraría si su bot de soporte no solo pudiera responder preguntas frecuentes, sino también iniciar un restablecimiento de contraseña a través de su API interna.
- Reducción de cargas de trabajo manuales: Libere a su equipo de la entrada de datos monótona y la navegación del sistema. Esto les permite centrarse en iniciativas estratégicas de mayor valor, como mejorar la satisfacción del cliente en un 15% el próximo trimestre.
- Integración de IA sin problemas: Gemini actúa como un traductor universal. Permite que su IA "hable" con sus API y microservicios existentes creados con Node.js. No hay necesidad de renovaciones masivas; simplemente le está dando a su IA un nuevo conjunto de herramientas para usar dentro de su ecosistema actual.
- Ventaja competitiva: Las empresas que puedan integrar rápidamente la IA en sus flujos de trabajo operativos superarán a aquellas que dependen de procesos manuales. Esto no se trata solo de ser "inteligente"; se trata de ser ágil y receptivo en un mercado en rápida evolución.
- Ahorros significativos de costos: Al automatizar tareas y reducir la intervención humana, está buscando reducciones directas de costos en mano de obra y corrección de errores. Una llamada a función bien implementada puede prevenir un error manual costoso antes de que ocurra, lo que podría ahorrar miles de dólares en costos de recuperación.
Honestamente, Gemini Function Calling transforma su IA de un proveedor de información pasivo a un participante activo en sus procesos operativos. Es como darle a su asistente de IA un cinturón de herramientas lleno de las herramientas más poderosas de su empresa, impulsadas por Node.js, listas para ser implementadas en cualquier momento.
El concepto central: Gemini Function Calling explicado de forma sencilla
Piense en Gemini como una nueva empleada brillante, llamémosla Alex. Alex es increíblemente inteligente, puede comprender solicitudes complejas y es excelente conversando. Sin embargo, Alex también sabe cómo usar herramientas y aplicaciones internas específicas cuando usted le pide una tarea. Si le dice: "Alex, ¿puedes conseguirme el informe de ventas actual del tercer trimestre y enviarlo por correo electrónico al equipo?", Alex no solo responde: "Sí, puedo". En cambio, comprende que para cumplir su solicitud, necesita usar la herramienta "generarInforme" y la herramienta "enviarCorreoElectrónico".
Gemini Function Calling funciona de manera similar. Cuando le envía una indicación de usuario a Gemini, no solo genera una respuesta de texto. Analiza la indicación en busca de intención y determina si alguna de las "herramientas" (funciones) que usted ha definido podría ayudar a cumplir esa intención. Si identifica una herramienta adecuada, no ejecuta la herramienta en sí. En cambio, sugiere que usted, el desarrollador, ejecute una función específica con parámetros específicos.
Su aplicación Node.js luego toma esta sugerencia, realmente llama a la función correspondiente (que podría interactuar con su base de datos, una API externa u otro microservicio), obtiene el resultado y lo retroalimenta a Gemini. Gemini luego usa esta nueva información para generar una respuesta final en lenguaje natural al usuario. Es una conversación estructurada entre el usuario, la inteligencia de Gemini y sus sistemas backend.
El "por qué" aquí es crucial: no solo está obteniendo un chat más inteligente. Está obteniendo una IA que puede orquestar acciones dentro de su infraestructura digital existente, convirtiéndola en un agente activo en sus flujos de trabajo operativos. Esta distinción, que Gemini sugiera una llamada a función en lugar de ejecutarla, es fundamental para la seguridad, el control y la flexibilidad.
De cero a experto: Configurando su entorno Node.js para Gemini
Seamos prácticos. Aquí le mostramos cómo preparar su entorno Node.js para construir con Gemini Function Calling.
1. Requisitos previos
- Node.js: Asegúrese de tener Node.js instalado (se recomienda la versión 18 o superior). Puede descargarlo desde nodejs.org.
- npm o Yarn: Estos administradores de paquetes vienen con Node.js.
- Cuenta de Google Cloud: Necesitará una cuenta de Google Cloud para acceder a la API de Gemini. Si no tiene una, regístrese en cloud.google.com. Asegúrese de habilitar la API de Generative Language en su proyecto.
2. Inicialización del proyecto
Primero, cree un nuevo proyecto de Node.js:
mkdir gemini-functions-tutorial
cd gemini-functions-tutorial
npm init -y
npm install @google/generative-ai dotenv
Este comando inicializa un nuevo proyecto de Node.js, crea un archivo package.json e instala el SDK oficial de Google Generative AI, junto con dotenv para gestionar las variables de entorno.
3. Autenticación y claves de API
La seguridad es primordial, especialmente para las operaciones. Nunca codifique las claves de API directamente en el código de su aplicación. Usaremos variables de entorno para esto.
Cree un archivo llamado .env en la raíz de su proyecto:
# .env
API_KEY="SU_CLAVE_API_GEMINI_AQUI"
Reemplace "SU_CLAVE_API_GEMINI_AQUI" con su clave de API de Gemini real. Puede generar esta clave en Google AI Studio o en Google Cloud Console.
Nota crucial: Agregue .env a su archivo .gitignore para evitar que se envíe a sistemas de control de versiones como Git. Esta es una práctica de seguridad innegociable.
# .gitignore
.env
node_modules/
4. Configuración básica del cliente Gemini
Ahora, escribamos un código Node.js mínimo para inicializar el cliente Gemini y verificar nuestra configuración. Cree un archivo index.js:
// index.js
require('dotenv').config(); // Carga las variables de entorno del archivo .env
const { GoogleGenerativeAI } = require('@google/generative-ai');
const API_KEY = process.env.API_KEY;
if (!API_KEY) {
console.error('Error: API_KEY no está configurada en el archivo .env.');
process.exit(1);
}
const genAI = new GoogleGenerativeAI(API_KEY);
async function run() {
try {
const model = genAI.getGenerativeModel({ model: "gemini-pro" });
const prompt = "Hola, Gemini!";
const result = await model.generateContent(prompt);
const response = await result.response;
const text = response.text();
console.log("Gemini dice:", text);
} catch (error) {
console.error("Error al comunicarse con Gemini:", error);
}
}
run();
Ejecute esto con node index.js. Si todo está configurado correctamente, debería ver un saludo amistoso de Gemini. Esto confirma que su entorno está listo para los siguientes pasos.
Definiendo funciones: Enseñando a Gemini sobre sus herramientas Node.js
Aquí es donde le decimos a Gemini sobre las acciones específicas que puede sugerir. Definimos estas "herramientas" usando un objeto estructurado que describe su propósito y parámetros.
1. El objeto `tools`: Estructura explicada
Cada definición de función necesita una estructura clara:
- `name` (cadena): Un identificador único para la función (por ejemplo, `getCurrentWeather`).
- `description` (cadena): Una descripción legible por humanos de lo que hace la función. Esto es crucial para que Gemini entienda cuándo usarla. ¡Sea descriptivo!
- `parameters` (objeto): Define las entradas que espera la función. Esto utiliza una estructura similar a JSON Schema.
- `type` (cadena): Siempre `object` para los parámetros de nivel superior.
- `properties` (objeto): Cada clave aquí es un nombre de parámetro. Su valor es un objeto que describe el tipo, la descripción del parámetro y si es requerido.
- `required` (array de cadenas): Una lista de nombres de parámetros que deben proporcionarse para que se llame a la función.
2. Ejemplo práctico de Node.js: Definiendo herramientas
Definamos dos funciones simples: una para obtener el clima actual y otra para obtener el precio de una acción. Estas son "declaraciones" para Gemini; la implementación real de Node.js viene después.
// tools.js (o integrado en su archivo principal)
const tools = [
{
function_declarations: [
{
name: "getCurrentWeather",
description: "Obtiene el clima actual para una ciudad determinada.",
parameters: {
type: "OBJECT",
properties: {
location: {
type: "STRING",
description: "La ciudad y el estado, por ejemplo, 'San Francisco, CA' o 'Londres, UK'",
},
unit: {
type: "STRING",
description: "La unidad de temperatura a usar, por ejemplo, 'celsius' o 'fahrenheit'",
enum: ["celsius", "fahrenheit"],
},
},
required: ["location"],
},
},
{
name: "getStockPrice",
description: "Obtiene el precio actual de la acción para un símbolo de cotización determinado.",
parameters: {
type: "OBJECT",
properties: {
symbol: {
type: "STRING",
description: "El símbolo de cotización de la acción, por ejemplo, 'GOOGL' o 'MSFT'",
},
},
required: ["symbol"],
},
},
],
},
];
module.exports = tools; // Exportar si está en un archivo separado
Observe el array `function_declarations` dentro del objeto de nivel superior. Así es como Gemini espera recibir múltiples definiciones de herramientas. El `enum` para `unit` es una excelente manera de guiar a Gemini hacia opciones válidas.
3. Mapeo a APIs externas
Estas definiciones son los planos de Gemini. Su aplicación Node.js deberá tener funciones reales que coincidan con estos planos. Por ejemplo, su definición de `getCurrentWeather` corresponderá a una función de Node.js como `callWeatherAPI(location, unit)` que internamente realiza una solicitud HTTP a un servicio meteorológico (por ejemplo, OpenWeatherMap). De manera similar, `getStockPrice` se mapeará a `fetchStockData(symbol)` que consulta una API del mercado de valores (por ejemplo, Alpha Vantage).
Lo bueno es que Gemini no necesita conocer los detalles complejos de sus llamadas a API externas; solo necesita saber qué parámetros espera su "herramienta" y qué logra.
Invocando funciones: Haciendo que Gemini llame a su código Node.js
Este es el corazón de Gemini Function Calling: el flujo de interacción donde Gemini sugiere una herramienta, su código Node.js la ejecuta y el resultado se retroalimenta.
1. Enviando la indicación con herramientas
Cuando envía una indicación de usuario, ahora también incluye el objeto `tools` que definió anteriormente:
// index.js (continuación)
const { GoogleGenerativeAI } = require('@google/generative-ai');
require('dotenv').config();
const tools = require('./tools'); // Asumiendo que tools.js está en el mismo directorio
const API_KEY = process.env.API_KEY;
const genAI = new GoogleGenerativeAI(API_KEY);
async function chatWithGemini(userPrompt) {
const model = genAI.getGenerativeModel({ model: "gemini-pro" });
const chat = model.startChat({
tools: tools, // Crucial: proporcionar las definiciones de las herramientas
});
const result = await chat.sendMessage(userPrompt);
const response = result.response;
// ... el resto de la lógica
}
2. Respuesta de Gemini: Datos de `functionCall`
Si Gemini determina que se necesita una función, su respuesta no será texto directo. En cambio, contendrá un objeto `functionCall`. Esta es una señal para su aplicación:
// ... dentro de la función chatWithGemini
// Comprobar si Gemini quiere llamar a una función
const functionCall = response.functionCall;
if (functionCall) {
console.log("Gemini sugirió una llamada a función:", functionCall);
// {
// name: 'getCurrentWeather',
// args: { location: 'London, UK', unit: 'celsius' }
// }
// ... proceder a ejecutar la función
} else {
// Gemini generó una respuesta de texto
const text = response.text();
console.log("Gemini dice:", text);
}
3. Ejecutando la función en Node.js
Ahora, su aplicación Node.js necesita tomar la sugerencia `functionCall` de Gemini y ejecutar la función *real* de Node.js correspondiente. Esto requiere un mapeo entre el `name` de la función que Gemini sugiere y sus funciones implementadas.
// api-functions.js - Estas son sus funciones backend reales
async function callWeatherAPI(location, unit) {
console.log(`Llamando a la API externa del clima para ${location} en ${unit}...`);
// En una aplicación real, esto golpearía una API externa (por ejemplo, OpenWeatherMap)
// Para este tutorial, devolveremos una respuesta simulada.
if (location.toLowerCase().includes("london")) {
return { temperature: unit === "celsius" ? "15°C" : "59°F", conditions: "Parcialmente Nublado", location: location };
}
return { temperature: "22°C", conditions: "Soleado", location: location };
}
async function fetchStockData(symbol) {
console.log(`Obteniendo datos de acciones para ${symbol}...`);
// En una aplicación real, esto golpearía una API de acciones (por ejemplo, Alpha Vantage)
// Para este tutorial, devolveremos una respuesta simulada.
if (symbol.toUpperCase() === "GOOGL") {
return { symbol: "GOOGL", price: "$170.50", currency: "USD", timestamp: new Date().toISOString() };
}
return { symbol: symbol, price: "$Desconocido", currency: "USD", timestamp: new Date().toISOString() };
}
// Un despachador para llamar a la función correcta basándose en la sugerencia de Gemini
const availableFunctions = {
getCurrentWeather: callWeatherAPI,
getStockPrice: fetchStockData,
};
async function executeFunctionCall(functionCall) {
const { name, args } = functionCall;
if (availableFunctions[name]) {
return await availableFunctions[name](...Object.values(args)); // Pasa argumentos dinámicamente
} else {
throw new Error(`Función "${name}" no encontrada.`);
}
}
module.exports = { executeFunctionCall, availableFunctions };
4. Enviando resultados de vuelta a Gemini
Una vez que su función de Node.js se ejecuta y obtiene un resultado, debe enviar este resultado de vuelta a Gemini para que pueda incorporarlo en una respuesta de lenguaje natural al usuario. Esto se hace enviando otro mensaje al chat, pero esta vez, es una parte de `function_response`.
// index.js (continuación y refactorizado)
const { GoogleGenerativeAI } = require('@google/generative-ai');
require('dotenv').config();
const tools = require('./tools');
const { executeFunctionCall } = require('./api-functions'); // Importa la lógica de ejecución
const API_KEY = process.env.API_KEY;
const genAI = new GoogleGenerativeAI(API_KEY);
async function handleGeminiInteraction(userPrompt) {
const model = genAI.getGenerativeModel({ model: "gemini-pro" });
const chat = model.startChat({
tools: tools,
});
let result = await chat.sendMessage(userPrompt);
let response = result.response;
if (response.functionCall) {
console.log("Gemini quiere llamar a:", response.functionCall);
const functionResult = await executeFunctionCall(response.functionCall);
console.log("Resultado de la ejecución de la función:", functionResult);
// Envía el resultado de la función de vuelta a Gemini
result = await chat.sendMessage({
functionResponse: {
name: response.functionCall.name,
response: functionResult,
},
});
response = result.response; // Obtiene la respuesta final de Gemini
}
console.log("Respuesta final de Gemini:", response.text());
return response.text();
}
// Ejemplo de uso:
// handleGeminiInteraction("¿Cómo está el clima en Londres, UK, en Celsius?");
// handleGeminiInteraction("¿Cuál es el precio actual de la acción de GOOGL?");
// handleGeminiInteraction("Cuéntame un chiste."); // No hay llamada a función para esta
5. Flujo de código completo: El viaje de ida y vuelta
Unamos todo en un flujo único y coherente:
- El usuario envía una indicación: "¿Cómo está el clima en Londres?"
- Su aplicación Node.js envía esta indicación a Gemini, junto con las definiciones de todas las herramientas disponibles.
- Gemini analiza la indicación, se da cuenta de que necesita la herramienta `getCurrentWeather` y devuelve un objeto `functionCall` con `name: "getCurrentWeather"` y `args: { location: "London, UK" }`.
- Su aplicación Node.js recibe este `functionCall`.
- La función `executeFunctionCall` de su aplicación llama dinámicamente a su función `callWeatherAPI("London, UK")` real.
- `callWeatherAPI` realiza una solicitud HTTP a un servicio meteorológico real y obtiene los datos.
- Su aplicación envía los datos meteorológicos de vuelta a Gemini como una `function_response`.
- Gemini recibe los datos, los procesa y genera una respuesta en lenguaje natural: "El clima en Londres, UK es de 15°C y parcialmente nublado."
- Su aplicación Node.js recibe y muestra esta respuesta final al usuario.
Esta interacción de ida y vuelta es el patrón central para Gemini Function Calling en Node.js. Dominar este flujo es clave para construir potentes aplicaciones impulsadas por IA.
Estrategias de manejo de errores y depuración para llamadas de Gemini en Node.js
Un manejo de errores robusto es innegociable para los gerentes de operaciones. Al integrar la IA con sus sistemas, los fallos pueden propagarse en cascada. Aquí le mostramos cómo construir una llamada a función Gemini resiliente en Node.js.
1. Errores de llamadas a la API (Gemini y externas)
Envuelva todas las llamadas a API externas (tanto a Gemini como a sus propios servicios) en bloques `try-catch`. Esta es una práctica fundamental de Node.js.
async function handleGeminiInteraction(userPrompt) {
try {
// ... código de interacción con Gemini ...
} catch (error) {
console.error("Ocurrió un error durante la interacción con Gemini:", error);
// Proporcione una alternativa amigable para el usuario
return "Lo siento, encontré un problema. Por favor, inténtelo de nuevo más tarde.";
}
}
async function callWeatherAPI(location, unit) {
try {
// ... solicitud HTTP real ...
const response = await fetch(`https://api.weatherapi.com/v1/current.json?key=SU_CLAVE&q=${location}`);
if (!response.ok) {
throw new Error(`La API del clima devolvió el estado ${response.status}`);
}
const data = await response.json();
return { temperature: data.current.temp_c, conditions: data.current.condition.text, location: location };
} catch (error) {
console.error(`Error al obtener el clima para ${location}:`, error.message);
// Devuelva un error estructurado o una alternativa
return { error: `No se pudo recuperar el clima para ${location}.`, details: error.message };
}
}
- Problemas de red: `fetch` o `axios` lanzarán errores por problemas de conexión.
- Claves de API inválidas: Gemini o sus API externas podrían devolver errores 401/403. Verifique los códigos de estado.
- Límites de tasa: Las API a menudo tienen límites de uso. Implemente mecanismos de reintento con retroceso exponencial (por ejemplo, usando una biblioteca como `axios-retry`).
2. Desajustes en la definición de funciones
Si Gemini no sugiere sus funciones, o si las sugiere con parámetros incorrectos:
- Claridad de la descripción: ¿Es su `description` en el objeto `tools` clara y concisa? Gemini se basa en gran medida en esto.
- Tipos de parámetros: Vuelva a verificar las definiciones de `type` (por ejemplo, `STRING`, `NUMBER`, `OBJECT`, `ARRAY`). Un error común es definir un número como una cadena.
- Campos requeridos: Asegúrese de que su array `required` enumere correctamente los parámetros que son esenciales.
- Errores tipográficos: Simples errores tipográficos en `name` o `properties` pueden romper la conexión.
He descubierto que iterar sobre la `description` suele ser la forma más impactante de mejorar la precisión de la llamada a funciones de Gemini. Sea explícito sobre lo que hace la función y lo que significan sus parámetros.
3. Errores de API externas
¿Qué pasa si su función `callWeatherAPI` llama con éxito al servicio meteorológico, pero el servicio devuelve un 404 porque la ciudad no existe? Su `executeFunctionCall` debe estar preparada para manejar estos resultados. Devuelva objetos de error estructurados de sus envoltorios de API y retroalímentelos a Gemini.
async function executeFunctionCall(functionCall) {
const { name, args } = functionCall;
if (availableFunctions[name]) {
const result = await availableFunctions[name](...Object.values(args));
// Importante: si la función real devuelve un error, páselo de vuelta a Gemini
if (result && result.error) {
console.warn(`La función ${name} falló: ${result.error}`);
// Es posible que desee formatear esto para que Gemini lo entienda con gracia
return { status: "error", message: result.error, details: result.details };
}
return result;
} else {
throw new Error(`Función "${name}" no encontrada en la implementación local.`);
}
}
4. Errores de análisis de `functionCall` de Gemini
Aunque raro con el SDK oficial, asegúrese de que su análisis de `response.functionCall` sea robusto. Si la estructura alguna vez se desvía, su código no debería fallar. Use encadenamiento opcional (`response?.functionCall?.name`) o verificaciones explícitas.
5. Mejores prácticas de registro (logging)
El registro eficaz es fundamental para la depuración y el monitoreo en producción. Para Node.js:
- `console.log` / `console.error`: Bueno para el desarrollo y scripts simples.
- Winston o Pino: Para aplicaciones de grado de producción, use una biblioteca de registro dedicada. Ofrecen registro estructurado, niveles de registro y mecanismos de transporte (por ejemplo, a archivos, servicios externos).
Registre:
- Las indicaciones de usuario entrantes.
- Las sugerencias de `functionCall` de Gemini (incluyendo nombre y argumentos).
- Los resultados de sus funciones de Node.js ejecutadas.
- Cualquier error encontrado en cada etapa.
- La respuesta final enviada de vuelta al usuario.
Integración con frameworks de Node.js: Express y NestJS
Construir un script independiente es una cosa; integrarlo en una aplicación completa es otra. Veamos cómo usar la llamada a funciones de Gemini dentro de los frameworks populares de Node.js.
1. Ejemplo de Express.js
Express.js es un framework web minimalista. Aquí le mostramos cómo podría crear un punto final de API simple que use la llamada a funciones de Gemini.
// app.js
const express = require('express');
const bodyParser = require('body-parser');
require('dotenv').config();
const { GoogleGenerativeAI } = require('@google/generative-ai');
const tools = require('./tools');
const { executeFunctionCall } = require('./api-functions');
const app = express();
const port = 3000;
app.use(bodyParser.json());
const API_KEY = process.env.API_KEY;
if (!API_KEY) {
console.error('API_KEY no está configurada. Por favor, revise su archivo .env.');
process.exit(1);
}
const genAI = new GoogleGenerativeAI(API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-pro" });
// Middleware para la validación de la clave de API (opcional, pero buena práctica para producción)
app.use((req, res, next) => {
const providedApiKey = req.headers['x-api-key']; // Encabezado personalizado
if (!providedApiKey || providedApiKey !== 'SU_CLAVE_API_SECRETA_INTERNA') { // Reemplace con un secreto real
return res.status(401).send('No autorizado: Clave de API inválida');
}
next();
});
app.post('/gemini-chat', async (req, res) => {
const { prompt } = req.body;
if (!prompt) {
return res.status(400).send('Se requiere una indicación (prompt).');
}
try {
const chat = model.startChat({ tools: tools });
let result = await chat.sendMessage(prompt);
let response = result.response;
let finalOutput = '';
if (response.functionCall) {
console.log("Gemini sugirió la función:", response.functionCall);
const functionResult = await executeFunctionCall(response.functionCall);
console.log("Salida de la ejecución de la función:", functionResult);
result = await chat.sendMessage({
functionResponse: {
name: response.functionCall.name,
response: functionResult,
},
});
finalOutput = result.response.text();
} else {
finalOutput = response.text();
}
res.json({ response: finalOutput });
} catch (error) {
console.error('Error en /gemini-chat:', error);
res.status(500).json({ error: 'Error interno del servidor', details: error.message });
}
});
app.listen(port, () => {
console.log(`Aplicación Express escuchando en http://localhost:${port}`);
});
Este ejemplo de Express configura un único punto final POST. Muestra cómo manejar las indicaciones entrantes, interactuar con Gemini, ejecutar funciones y enviar una respuesta JSON estructurada. Para producción, agregaría una autenticación y validación más robustas, y potencialmente rutas separadas para diferentes interacciones de IA.
2. Ejemplo de NestJS
NestJS, construido sobre Express, proporciona un enfoque más estructurado y opinado, aprovechando TypeScript y los principios de la programación orientada a objetos. Esto es ideal para aplicaciones más grandes y fáciles de mantener.
Primero, configure un nuevo proyecto de NestJS:
npm i -g @nestjs/cli
nest new gemini-nestjs-app
cd gemini-nestjs-app
npm install @google/generative-ai dotenv
Luego, defina su lógica de Gemini dentro de un servicio:
// src/gemini/gemini.service.ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { GoogleGenerativeAI, GenerativeModel, ChatSession } from '@google/generative-ai';
import * as process from 'process'; // Módulo de proceso de Node.js
import * as tools from '../../tools'; // Ajuste la ruta según sea necesario
import { executeFunctionCall } from '../../api-functions'; // Ajuste la ruta según sea necesario
@Injectable()
export class GeminiService implements OnModuleInit {
private genAI: GoogleGenerativeAI;
private model: GenerativeModel;
onModuleInit() {
const API_KEY = process.env.API_KEY;
if (!API_KEY) {
throw new Error('API_KEY no está configurada en las variables de entorno.');
}
this.genAI = new GoogleGenerativeAI(API_KEY);
this.model = this.genAI.getGenerativeModel({ model: 'gemini-pro' });
}
async processPrompt(prompt: string): Promise {
const chat: ChatSession = this.model.startChat({ tools: tools });
let result = await chat.sendMessage(prompt);
let response = result.response;
let finalOutput = '';
if (response.functionCall) {
console.log('NestJS: Gemini sugirió la función:', response.functionCall);
const functionResult = await executeFunctionCall(response.functionCall);
console.log('NestJS: Salida de la ejecución de la función:', functionResult);
result = await chat.sendMessage({
functionResponse: {
name: response.functionCall.name,
response: functionResult,
},
});
finalOutput = result.response.text();
} else {
finalOutput = response.text();
}
return finalOutput;
}
}
Y un controlador para exponerlo a través de un punto final de API:
// src/gemini/gemini.controller.ts
import { Controller, Post, Body, Res, HttpStatus } from '@nestjs/common';
import { GeminiService } from './gemini.service';
import { Response } from 'express';
interface ChatPromptDto {
prompt: string;
}
@Controller('gemini')
export class GeminiController {
constructor(private readonly geminiService: GeminiService) {}
@Post('chat')
async chat(@Body() chatPromptDto: ChatPromptDto, @Res() res: Response) {
if (!chatPromptDto.prompt) {
return res.status(HttpStatus.BAD_REQUEST).json({ message: 'Se requiere una indicación (prompt).' });
}
try {
const responseText = await this.geminiService.processPrompt(chatPromptDto.prompt);
return res.status(HttpStatus.OK).json({ response: responseText });
} catch (error) {
console.error('Error en GeminiController:', error);
return res.status(HttpStatus.INTERNAL_SERVER_ERROR).json({ message: 'Error interno del servidor', details: error.message });
}
}
}
Finalmente, registre el servicio y el controlador en su módulo (src/gemini/gemini.module.ts) e importe el módulo en su `AppModule`.
NestJS enfatiza la inyección de dependencias y la modularidad, lo que facilita la gestión de integraciones complejas de IA. Su `GeminiService` encapsula toda la lógica relacionada con Gemini, que luego se puede inyectar en cualquier controlador u otro servicio que lo necesite.
3. Recomendaciones de estructura de proyectos
Para la mantenibilidad y la escalabilidad, especialmente cuando se trata de múltiples funciones y API externas, recomiendo encarecidamente:
- `src/tools/` o `src/gemini/functions/`: Directorio para sus definiciones de herramientas de Gemini.
- `src/api-wrappers/`: Directorio para sus funciones reales de Node.js que interactúan con API externas (por ejemplo, `weather.api.ts`, `stock.api.ts`).
- `src/gemini/`: Módulo/carpeta dedicada para todos los servicios, controladores y tipos relacionados con Gemini.
- Variables de entorno: Centralice la configuración (como las claves de API) en `.env` y use un servicio de configuración para cargarlas.
Patrones avanzados de Gemini Function Calling en Node.js
Una vez que haya dominado lo básico, exploremos patrones más sofisticados que desbloquean un potencial de automatización aún mayor.
1. Llamadas a funciones encadenadas
A veces, para cumplir una solicitud se requieren varios pasos, donde la salida de una función se convierte en la entrada de otra. Gemini puede orquestar esto. Por ejemplo: "Encuentre el último pedido del cliente, luego verifique su estado de envío".
Su lógica de Node.js debe estar preparada para que Gemini sugiera una función, reciba su resultado y *luego* potencialmente sugiera otra función basándose en ese resultado. Esto significa que su bucle de interacción podría ejecutarse varias veces.
// Ejemplo simplificado de cómo manejar llamadas encadenadas
async function handleChainedInteraction(userPrompt) {
const chat = model.startChat({ tools: tools });
let history = []; // Mantener un registro del historial de conversación
let currentPrompt = userPrompt;
for (let i = 0; i < 5; i++) { // Limitar la longitud de la cadena para evitar bucles infinitos
const result = await chat.sendMessage(currentPrompt);
const response = result.response;
if (response.functionCall) {
console.log(`Paso de la cadena ${i+1}: Gemini sugirió la función:`, response.functionCall);
const functionResult = await executeFunctionCall(response.functionCall);
console.log(`Paso de la cadena ${i+1}: Resultado de la función:`, functionResult);
// Retroalimentar el resultado de la función a Gemini
currentPrompt = {
functionResponse: {
name: response.functionCall.name,
response: functionResult,
},
};
history.push({ role: 'user', parts: [currentPrompt] }); // Añadir al historial
history.push({ role: 'model', parts: [{ functionCall: response.functionCall }] }); // Añadir el pensamiento de Gemini
} else {
console.log(`Paso de la cadena ${i+1}: Respuesta final de Gemini:`, response.text());
return response.text(); // La cadena termina con una respuesta de texto
}
}
return "La operación excedió la longitud máxima de la cadena.";
}
La clave aquí es que el método `chat.sendMessage` puede aceptar una indicación de usuario o una `functionResponse`. Al retroalimentar continuamente los resultados, permite que Gemini impulse un proceso de varios pasos.
2. Llamadas a funciones condicionales
Gemini es lo suficientemente inteligente como para decidir *si* una función debe ser llamada en función del contexto. "¿Qué tiempo hace?" activará la función del tiempo. "Cuéntame una historia sobre un dragón" no lo hará. Esto se maneja de forma natural por cómo define sus herramientas y la claridad de sus descripciones. No necesita sentencias `if` explícitas para esto; el motor de razonamiento de Gemini se encarga de ello.
3. Conversaciones multiturno
El objeto `chat` en el SDK de Gemini mantiene automáticamente el historial de conversaciones. Esto significa que si un usuario pregunta "¿Qué tiempo hace en Londres?" y luego en un turno de seguimiento pregunta "¿Y en París?", Gemini entiende el contexto y puede llamar a la función del tiempo nuevamente para París. Su aplicación Node.js simplemente continúa usando la misma instancia de `chat`.
Para entornos sin estado (como funciones serverless), deberá pasar todo el array `history` con cada solicitud a `startChat` para mantener el contexto entre invocaciones.
// Ejemplo de cómo mantener el historial en un contexto sin estado
async function handleStatelessChat(userPrompt, previousHistory = []) {
const chat = model.startChat({
tools: tools,
history: previousHistory, // Pasar el historial de conversación anterior
});
// ... misma lógica que antes ...
// Después de obtener la respuesta, actualizar y devolver el nuevo historial
const newHistory = [...previousHistory, { role: 'user', parts: [{ text: userPrompt }] }];
if (response.functionCall) {
newHistory.push({ role: 'model', parts: [{ functionCall: response.functionCall }] });
// ... después de la ejecución, añadir functionResponse al historial ...
} else {
newHistory.push({ role: 'model', parts: [{ text: response.text() }] });
}
return { response: finalOutput, history: newHistory };
}
4. Selección y priorización de herramientas
Cuando tiene docenas de herramientas, ¿cómo elige Gemini la correcta? Se basa en la claridad y especificidad de sus campos `description`. Si varias herramientas podrían aplicarse potencialmente, Gemini intenta elegir la más relevante en función de los matices de la indicación. Para guiarlo:
- Sea preciso: "Obtener precio actual de la acción" es mejor que "Obtener datos financieros".
- Use ejemplos en las descripciones: "por ejemplo, 'San Francisco, CA'" ayuda a Gemini a entender los formatos de los parámetros.
- Evite la ambigüedad: Si dos funciones tienen responsabilidades superpuestas, refine sus descripciones para resaltar sus casos de uso distintos.
Rendimiento y despliegue para aplicaciones Node.js de alto volumen
Para los líderes de operaciones, el rendimiento, la escalabilidad y la eficiencia de costos son las principales preocupaciones. Aquí le mostramos cómo optimizar sus aplicaciones Node.js Gemini.
1. Patrones asíncronos
Node.js destaca en E/S no bloqueante, y usted debe aprovechar esto. Siempre use `async/await` para las llamadas a la API de Gemini y sus servicios externos. Esto asegura que su servidor pueda manejar muchas solicitudes concurrentes sin bloquear el bucle de eventos.
// Siempre use async/await
async function fetchDataAndProcess() {
const geminiResult = await chat.sendMessage(prompt); // No bloquee aquí
const externalApiResult = await fetchExternalData(); // No bloquee aquí
// ...
}
2. Limitación de tasa y reintentos
Las API externas (incluida Gemini) tienen límites de tasa. Implemente mecanismos de reintento robustos con retroceso exponencial. Esto significa que si una llamada a la API falla con un error de límite de tasa (por ejemplo, 429 Demasiadas solicitudes), espera un período corto, luego reintenta, aumentando el tiempo de espera con cada reintento posterior. Bibliotecas como `axios-retry` pueden simplificar esto.
const axios = require('axios');
const axiosRetry = require('axios-retry');
axiosRetry(axios, {
retries: 3, // Número de reintentos
retryDelay: axiosRetry.exponentialDelay, // Retroceso exponencial
retryCondition: (error) => {
return error.response && error.response.status === 429; // Reintento en 429
},
});
// Use la instancia de axios configurada para sus llamadas a la API
async function callWeatherAPIWithRetry(location, unit) {
try {
const response = await axios.get(`https://api.weatherapi.com/v1/current.json?key=SU_CLAVE&q=${location}`);
return response.data;
} catch (error) {
console.error("La llamada a la API del clima falló después de los reintentos:", error.message);
throw error;
}
}
3. Estrategias de caché
Para los datos que no cambian con frecuencia (por ejemplo, información estática de productos, precio de cierre de las acciones de ayer), implemente el almacenamiento en caché. Esto reduce la latencia, los costos de las llamadas a la API y la carga en sus servicios externos.
- Caché en memoria: Para casos simples, un `Map` o `LRU-cache` puede funcionar.
- Redis/Memcached: Para el almacenamiento en caché distribuido en múltiples instancias de su aplicación Node.js.
Ejemplo: Almacenar en caché los datos meteorológicos durante 5 minutos.
const NodeCache = require('node-cache'); // npm install node-cache
const myCache = new NodeCache({ stdTTL: 300, checkperiod: 120 }); // TTL de 300 segundos (5 minutos)
async function getCachedWeather(location, unit) {
const cacheKey = `weather-${location}-${unit}`;
let cachedData = myCache.get(cacheKey);
if (cachedData) {
console.log(`Sirviendo el clima para ${location} desde la caché.`);
return cachedData;
}
console.log(`Obteniendo el clima fresco para ${location}...`);
const freshData = await callWeatherAPI(location, unit); // Su llamada a la API real
myCache.set(cacheKey, freshData);
return freshData;
}
4. Opciones de despliegue
- Serverless (Google Cloud Functions, AWS Lambda, Azure Functions): Ideal para una escalabilidad rentable y basada en eventos. Solo paga por el tiempo de ejecución. Node.js es un ciudadano de primera clase en la mayoría de las plataformas serverless. Esta es a menudo mi opción preferida para los puntos finales de API que principalmente orquestan servicios externos como Gemini.
- Docker/Contenerización: Proporciona entornos consistentes desde el desarrollo hasta la producción. Es esencial para aplicaciones complejas o microservicios. Puede desplegar contenedores Docker en Google Cloud Run, AWS ECS, Azure Container Instances, etc.
- Kubernetes: Para orquestar aplicaciones contenerizadas a escala. Si está construyendo una arquitectura de microservicios compleja con muchos agentes de IA interconectados, Kubernetes ofrece capacidades robustas de gestión, escalado y auto-curación.
5. Monitoreo
Implemente un monitoreo integral para rastrear la salud, el rendimiento y el uso de la API de Gemini de su aplicación:
- Monitoreo del rendimiento de la aplicación (APM): Herramientas como New Relic, Datadog o Google Cloud Operations (anteriormente Stackdriver) para rastrear la latencia, los errores y el uso de recursos de su aplicación Node.js.
- Agregación de registros: Centralice los registros de todas las instancias (por ejemplo, con la pila ELK, Splunk, Google Cloud Logging) para una depuración y auditoría más fáciles.
- Uso de la API de Gemini: Monitoree su panel de control de la API de Gemini para conocer las cuotas de uso, los costos y las tasas de error. Configure alertas para picos o errores inesperados.
Gemini vs. OpenAI Function Calling: Una perspectiva de Node.js
Los líderes de operaciones a menudo necesitan evaluar tecnologías competitivas. Comparemos Gemini Function Calling con el enfoque de OpenAI desde una perspectiva de desarrollo de Node.js.
Artículos relacionados
- Las mejores plataformas de chatbot para comercio electrónico
- Automatización N8N para consultores de SAP
- N8N para automatizar procesos financieros de SAP
- Cómo N8N ayuda a los consultores de estrategia de IA de SAP
- Domine Gemini Advanced: IA para profesionales de negocios
- Casos de uso de Gemini Advanced
