Crea experiencias híbridas con modelos alojados en la nube y en el dispositivo


Compila apps y funciones web potenciadas por IA con inferencia híbrida usando Firebase AI Logic. La inferencia híbrida permite ejecutar la inferencia con modelos integrados en el dispositivo cuando están disponibles y recurrir sin problemas a los modelos alojados en la nube en otros casos (y viceversa).

En esta página, se describe cómo comenzar a usar el SDK del cliente y se muestran opciones y capacidades de configuración adicionales, como el resultado estructurado.

Ten en cuenta que la inferencia en el dispositivo es compatible con las apps web que se ejecutan en Chrome en computadoras.

Ir a los ejemplos de código

Casos de uso recomendados y funciones compatibles

Casos de uso recomendados:

  • El uso de un modelo en el dispositivo para la inferencia ofrece las siguientes ventajas:

    • Privacidad mejorada
    • Contexto local
    • Inferencias sin costo
    • Funcionalidad sin conexión

  • El uso de la funcionalidad híbrida ofrece las siguientes ventajas:

    • Llega al 100% de tu público, independientemente de la disponibilidad del modelo en el dispositivo o la conectividad a Internet

Funciones y capacidades compatibles con la inferencia en el dispositivo:

Antes de comenzar

Observa lo siguiente:

Comienza a usar localhost

En estos pasos para comenzar, se describe la configuración general necesaria para cualquier solicitud de instrucciones admitida que desees enviar.

Paso 1: Configura Chrome y la API de Prompt para la inferencia en el dispositivo

  1. Asegúrate de usar una versión reciente de Chrome. Actualiza en chrome://settings/help.
    La inferencia en el dispositivo está disponible a partir de Chrome v139.

  2. Para habilitar el modelo multimodal integrado en el dispositivo, establece la siguiente marca en Habilitado:

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

  3. Reinicia Chrome.

  4. (Opcional) Descarga el modelo integrado en el dispositivo antes de la primera solicitud.

    La API de Prompt está integrada en Chrome; sin embargo, el modelo integrado en el dispositivo no está disponible de forma predeterminada. Si aún no descargaste el modelo antes de tu primera solicitud de inferencia en el dispositivo, la solicitud iniciará automáticamente la descarga del modelo en segundo plano.

Paso 2: Configura un proyecto de Firebase y conecta tu app a Firebase

  1. Accede a la consola de Firebase y, luego, selecciona tu proyecto de Firebase.

  2. En la consola de Firebase, ve a la página Firebase AI Logic.

  3. Haz clic en Comenzar para iniciar un flujo de trabajo guiado que te ayudará a configurar las APIs requeridas y los recursos para tu proyecto.

  4. Configura tu proyecto para usar un proveedor de "Gemini API".

    Te recomendamos que comiences con Gemini Developer API. En cualquier momento, puedes configurar el objeto Vertex AI Gemini API (y su requisito de facturación).

    En el caso de Gemini Developer API, la consola habilitará las APIs requeridas y creará una clave de API de Gemini en tu proyecto.
    No agregues esta clave de API de Gemini a la base de código de tu app. Obtén más información.

  5. Si se te solicita en el flujo de trabajo de la consola, sigue las instrucciones en pantalla para registrar tu app y conectarla a Firebase.

  6. Continúa con el siguiente paso de esta guía para agregar el SDK a tu app.

Paso 3: Agrega el SDK

La biblioteca de Firebase proporciona acceso a las APIs para interactuar con modelos generativos. La biblioteca se incluye como parte del SDK de Firebase JavaScript para la Web.

  1. Instala el SDK de Firebase JS para la Web con npm:

    npm install firebase

  2. Inicializa Firebase en tu app:

    import { initializeApp } from "firebase/app";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

Paso 4: Inicializa el servicio y crea una instancia del modelo

Haz clic en tu proveedor de Gemini API para ver el contenido y el código específicos del proveedor en esta página.

Configura lo siguiente antes de enviar una solicitud de instrucción al modelo.

  1. Inicializa el servicio para el proveedor de la API que elegiste.

  2. Crear una instancia de GenerativeModel. Asegúrate de hacer lo siguiente:

    1. Llama a getGenerativeModel después de una interacción del usuario final o en el momento de esta (como un clic en un botón). Este es un requisito previo para inferenceMode.

    2. Establece mode en uno de los siguientes valores:

      • PREFER_ON_DEVICE: Usa el modelo integrado en el dispositivo si está disponible; de lo contrario, recurre al modelo alojado en la nube.

      • ONLY_ON_DEVICE: Usa el modelo integrado en el dispositivo si está disponible; de lo contrario, arroja una excepción.

      • PREFER_IN_CLOUD: Usa el modelo alojado en la nube si está disponible; de lo contrario, usa el modelo integrado.

      • ONLY_IN_CLOUD: Usa el modelo alojado en la nube si está disponible; de lo contrario, lanza una excepción.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Paso 5: Envía una solicitud de instrucción a un modelo

En esta sección, se muestra cómo enviar varios tipos de entrada para generar diferentes tipos de salida, incluidos los siguientes:

Si deseas generar resultados estructurados (como JSON o enumeraciones), usa uno de los siguientes ejemplos de "generar texto" y, además, configura el modelo para que responda según un esquema proporcionado.

Genera texto a partir de una entrada de solo texto

Antes de probar este ejemplo, asegúrate de haber completado la sección Comienza ahora de esta guía.

Puedes usar generateContent() para generar texto a partir de una instrucción que contenga texto:

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Ten en cuenta que Firebase AI Logic también admite la transmisión de respuestas de texto con generateContentStream (en lugar de generateContent).

Genera texto a partir de entradas de texto e imágenes (multimodales)

Antes de probar este ejemplo, asegúrate de haber completado la sección Comienza ahora de esta guía.

Puedes usar generateContent() para generar texto a partir de una instrucción que contenga archivos de texto y de imagen. Para ello, proporciona el mimeType de cada archivo de entrada y el archivo en sí.

Los tipos de imágenes de entrada admitidos para la inferencia en el dispositivo son PNG y JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Ten en cuenta que Firebase AI Logic también admite la transmisión de respuestas de texto con generateContentStream (en lugar de generateContent).

Permite que los usuarios finales prueben tu función

Para que los usuarios finales prueben tu función en la app, debes inscribirte en las pruebas de origen de Chrome. Ten en cuenta que estas pruebas tienen una duración y un uso limitados.

  1. Regístrate en la prueba de origen de Chrome de la API de Prompt. Recibirás un token.

  2. Proporciona el token en cada página web en la que desees habilitar la función de prueba. Usa una de las siguientes opciones:

    • Proporciona el token como una metaetiqueta en la etiqueta <head>: <meta http-equiv="origin-trial" content="TOKEN">

    • Proporciona el token como un encabezado HTTP: Origin-Trial: TOKEN

    • Proporciona el token de forma programática.

¿Qué más puedes hacer?

En esta sección, aprenderás a establecer un modo de inferencia, anular el modelo de resguardo predeterminado alojado en la nube y usar la configuración del modelo para controlar las respuestas (como generar resultados estructurados).

Cómo establecer un modo de inferencia

En los ejemplos de la configuración general, se usa el modo PREFER_ON_DEVICE, pero este es solo uno de los cuatro modos de inferencia disponibles.

  • PREFER_ON_DEVICE: Usa el modelo integrado en el dispositivo si está disponible; de lo contrario, recurre al modelo alojado en la nube.

    const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

  • ONLY_ON_DEVICE: Usa el modelo integrado en el dispositivo si está disponible; de lo contrario, arroja una excepción.

    const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });

  • PREFER_IN_CLOUD: Usa el modelo alojado en la nube si está disponible; de lo contrario, usa el modelo integrado.

    const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });

  • ONLY_IN_CLOUD: Usa el modelo alojado en la nube si está disponible; de lo contrario, lanza una excepción.

    const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });

Determina si se usó la inferencia en el dispositivo o en la nube

Si usas los modos de inferencia PREFER_ON_DEVICE o PREFER_IN_CLOUD, puede ser útil saber qué modo se usó para solicitudes determinadas. Esta información la proporciona la propiedad inferenceSource de cada respuesta (disponible a partir de la versión 12.5.0 del SDK de JS).

Cuando accedas a esta propiedad, el valor que se mostrará será ON_DEVICE o IN_CLOUD.

// ...

console.log('You used: ' + result.response.inferenceSource);

console.log(result.response.text());

Anula el modelo de resguardo predeterminado

El modelo predeterminado alojado en la nube es gemini-2.5-flash-lite (a partir de la versión 12.8.0 del SDK de JS).

Este modelo es el modelo alojado en la nube de respaldo cuando usas el modo PREFER_ON_DEVICE. También es el modelo predeterminado cuando usas el modo ONLY_IN_CLOUD o el modo PREFER_IN_CLOUD.

Puedes usar la opción de configuración inCloudParams para especificar un modelo alternativo predeterminado alojado en la nube.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
  }
});

Encuentra los nombres de los modelos para todos los modelos de Gemini compatibles.

Usa la configuración del modelo para controlar las respuestas

En cada solicitud a un modelo, puedes enviar una configuración del modelo para controlar cómo este genera una respuesta. Los modelos alojados en la nube y los modelos integrados en el dispositivo ofrecen diferentes opciones de configuración.

La configuración se mantiene durante el ciclo de vida de la instancia. Si quieres usar una configuración diferente, crea una instancia de GenerativeModel nueva con esa configuración.

Establece la configuración de un modelo alojado en la nube

Usa la opción inCloudParams para configurar un modelo Gemini alojado en la nube. Obtén información sobre los parámetros disponibles.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
    temperature: 0.8,
    topK: 10
  }
});

Cómo establecer la configuración de un modelo en el dispositivo

Ten en cuenta que la inferencia con un modelo integrado en el dispositivo usa la API de Prompt de Chrome.

Usa la opción onDeviceParams para configurar un modelo en el dispositivo. Obtén información sobre los parámetros disponibles.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

Establece la configuración para el resultado estructurado (como JSON)

Se admite la generación de resultados estructurados (como JSON y enumeraciones) para la inferencia con modelos alojados en la nube y en el dispositivo.

Para la inferencia híbrida, usa inCloudParams y onDeviceParams para configurar el modelo de modo que responda con un resultado estructurado. Para los demás modos, usa solo la configuración aplicable.

  • Para inCloudParams: Especifica el responseMimeType adecuado (en este ejemplo, application/json), así como el responseSchema que deseas que use el modelo.

  • Para onDeviceParams: Especifica el responseConstraint que quieres que use el modelo.

Salida de JSON

En el siguiente ejemplo, se adapta el ejemplo general de salida en formato JSON para la inferencia híbrida:

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});
Salida de enumeración

Como se indicó anteriormente, pero adaptando la documentación sobre la salida de enumeración para la inferencia híbrida:

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...
});

// ...

Funciones aún no disponibles para la inferencia en el dispositivo

Como se trata de un lanzamiento experimental, no todas las capacidades del SDK web están disponibles para la inferencia en el dispositivo. Las siguientes funciones aún no son compatibles con la inferencia en el dispositivo (pero suelen estar disponibles para la inferencia basada en la nube).

  • Generar texto a partir de tipos de entrada de archivos de imagen que no sean JPEG ni PNG

    • Puede recurrir al modelo alojado en la nube. Sin embargo, el modo ONLY_ON_DEVICE arrojará un error.

  • Generar texto a partir de entradas de audio, video y documentos (como PDFs)

    • Puede recurrir al modelo alojado en la nube. Sin embargo, el modo ONLY_ON_DEVICE arrojará un error.

  • Genera imágenes con los modelos de Gemini o Imagen

    • Puede recurrir al modelo alojado en la nube. Sin embargo, el modo ONLY_ON_DEVICE arrojará un error.

  • Proporcionar archivos con URLs en solicitudes multimodales Debes proporcionar archivos como datos intercalados a los modelos integrados en el dispositivo.

  • Chat de varios turnos

    • Puede recurrir al modelo alojado en la nube. Sin embargo, el modo ONLY_ON_DEVICE arrojará un error.

  • Transmisión bidireccional con el Gemini Live API

  • Proporcionar herramientas al modelo para ayudarlo a generar su respuesta (como llamadas a funciones, ejecución de código, contexto de URL y fundamentación con la Búsqueda de Google)

  • Cuenta tokens

    • Siempre arroja un error. El recuento diferirá entre los modelos alojados en la nube y los modelos integrados en el dispositivo, por lo que no hay una alternativa intuitiva.

  • Supervisión de la IA en la consola de Firebase para la inferencia en el dispositivo

    • Ten en cuenta que cualquier inferencia que use los modelos alojados en la nube se puede supervisar al igual que otras inferencias que usen el SDK del cliente de Firebase AI Logic para la Web.


Enviar comentarios sobre tu experiencia con Firebase AI Logic