Comienza a usar la API de Gemini en apps de Dart o Flutter

En este instructivo, se muestra cómo acceder a la API de Gemini para tu aplicación de Dart o Flutter con el SDK de Dart de la IA de Google. Puedes usar este SDK si no quieres trabajar directamente con las APIs de REST para acceder a los modelos de Gemini en tu app.

En este instructivo, aprenderás a hacer lo siguiente:

Además, este instructivo contiene secciones sobre casos de uso avanzados (como incorporaciones y recuentos de tokens) y opciones para controlar la generación de contenido.

Requisitos previos

En este instructivo, se supone que estás familiarizado con la compilación de aplicaciones con Dart.

Para completar este instructivo, asegúrate de que tu entorno de desarrollo cumpla con los siguientes requisitos:

  • Dart 3.2.0 o versiones posteriores

Configura tu proyecto

Antes de llamar a la API de Gemini, debes configurar tu proyecto, lo que incluye configurar tu clave de API, agregar el SDK a tus dependencias de Pub e inicializar el modelo.

Cómo configurar tu clave de API

Para usar la API de Gemini, necesitarás una clave de API. Si aún no tienes una, crea una clave en Google AI Studio.

Obtén una clave de API.

Protege tu clave de API

Protege tu clave de API. Te recomendamos que no incluyas la clave de API directamente en tu código ni que verifiques los archivos que la contienen en sistemas de control de versión. En su lugar, debes usar un almacén de secretos para tu clave de API.

En todos los fragmentos de este instructivo, se supone que accedes a tu clave de API como una variable de entorno de proceso. Si estás desarrollando una app de Flutter, puedes usar String.fromEnvironment y pasar --dart-define=API_KEY=$API_KEY a flutter build o flutter run para compilar con la clave de API, ya que el entorno del proceso será diferente cuando se ejecute la app.

Instala el paquete del SDK

Para usar la API de Gemini en tu aplicación, debes add el paquete google_generative_ai en tu app de Dart o Flutter:

Dart 

dart pub add google_generative_ai

Flutter 

flutter pub add google_generative_ai

Inicializa el modelo generativo

Antes de que puedas hacer llamadas a la API, debes importar e inicializar el modelo generativo.

import 'package:google_generative_ai/google_generative_ai.dart';

// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
  print('No \$API_KEY environment variable');
  exit(1);
}

final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);

Cuando especifiques un modelo, ten en cuenta lo siguiente:

  • Usa un modelo que sea específico para tu caso de uso (por ejemplo, gemini-pro-vision es para la entrada multimodal). En esta guía, las instrucciones para cada implementación incluyen el modelo recomendado para cada caso de uso.

Implementa casos de uso comunes

Ahora que tu proyecto está configurado, puedes explorar el uso de la API de Gemini para implementar diferentes casos de uso:

En la sección de casos de uso avanzados, puedes encontrar información sobre la API de Gemini y las incorporaciones.

Cómo generar texto a partir de entradas de solo texto

Cuando la entrada de la instrucción incluya solo texto, usa el modelo gemini-pro con el método generateContent para generar una salida de texto:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(model: 'gemini-pro', apiKey: apiKey);
  final content = [Content.text('Write a story about a magic backpack.')];
  final response = await model.generateContent(content);
  print(response.text);
}

Generar texto a partir de entradas de texto e imagen (multimodal)

Gemini proporciona un modelo multimodal (gemini-pro-vision), por lo que puedes ingresar imágenes y texto. Asegúrate de revisar los requisitos de las imágenes para la entrada.

Cuando la entrada de la instrucción incluya imágenes y texto, usa el modelo gemini-pro-vision con el método generateContent para generar una salida de texto:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-and-image input (multimodal), use the gemini-pro-vision model
  final model = GenerativeModel(model: 'gemini-pro-vision', apiKey: apiKey);
  final (firstImage, secondImage) = await (
    File('image0.jpg').readAsBytes(),
    File('image1.jpg').readAsBytes()
  ).wait;
  final prompt = TextPart("What's different between these pictures?");
  final imageParts = [
    DataPart('image/jpeg', firstImage),
    DataPart('image/jpeg', secondImage),
  ];
  final response = await model.generateContent([
    Content.multi([prompt, ...imageParts])
  ]);
  print(response.text);
}

Crea conversaciones de varios turnos (chat)

Con Gemini, puedes desarrollar conversaciones de formato libre en varios turnos. El SDK simplifica el proceso mediante la administración del estado de la conversación, por lo que, a diferencia de generateContent, no tienes que almacenar el historial de la conversación.

Para crear una conversación de varios turnos (como el chat), usa el modelo gemini-pro e inicializa el chat llamando a startChat(). Luego, usa sendMessage() para enviar un mensaje de usuario nuevo, que también agregará el mensaje y la respuesta al historial de chat.

Hay dos opciones posibles para role asociado con el contenido en una conversación:

  • user: Es el rol que proporciona las indicaciones. Este valor es el predeterminado para las llamadas a sendMessage, y la función arrojará una excepción si se pasa una función diferente.

  • model: Es la función que proporciona las respuestas. Esta función se puede usar cuando se llama a startChat() con history existente.

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

Future<void> main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(
      model: 'gemini-pro',
      apiKey: apiKey,
      generationConfig: GenerationConfig(maxOutputTokens: 100));
  // Initialize the chat
  final chat = model.startChat(history: [
    Content.text('Hello, I have 2 dogs in my house.'),
    Content.model([TextPart('Great to meet you. What would you like to know?')])
  ]);
  var content = Content.text('How many paws are in my house?');
  var response = await chat.sendMessage(content);
  print(response.text);
}

Usa la transmisión para interacciones más rápidas

Según la configuración predeterminada, el modelo muestra una respuesta después de completar todo el proceso de generación. Puedes lograr interacciones más rápidas si no esperas a que se complete el resultado y, en su lugar, usa la transmisión para controlar los resultados parciales.

En el siguiente ejemplo, se muestra cómo implementar la transmisión con el método generateContentStream para generar texto a partir de una solicitud de entrada de imagen y texto.

// ...

final response = model.generateContentStream([
  Content.multi([prompt, ...imageParts])
]);
await for (final chunk in response) {
  print(chunk.text);
}

// ...

Puedes usar un enfoque similar para los casos de uso de chat y entradas de solo texto.

// Use streaming with text-only input
final response = model.generateContentStream(content);

// Use streaming with multi-turn conversations (like chat)
final response = chat.sendMessageStream(content);

Implementa casos de uso avanzados

Los casos de uso comunes descritos en la sección anterior de este instructivo te ayudarán a familiarizarte con el uso de la API de Gemini. En esta sección, se describen algunos casos de uso que podrían considerarse más avanzados.

Usa incorporaciones

La incorporación es una técnica que se usa para representar información como una lista de números de punto flotante en un array. Con Gemini, puedes representar texto (palabras, oraciones y bloques de texto) en un formato vectorizado, lo que facilita la comparación y el contraste de las incorporaciones. Por ejemplo, dos textos que comparten una opinión o un tema similar deben tener incorporaciones similares, que se pueden identificar a través de técnicas de comparación matemática, como la similitud coseno.

Usa el modelo embedding-001 con el método embedContent (o el método batchEmbedContent) para generar incorporaciones. En el siguiente ejemplo, se genera una incorporación para una sola string:

final model = GenerativeModel(model: 'embedding-001', apiKey: apiKey);
final content = Content.text('The quick brown fox jumps over the lazy dog.');
final result = await model.embedContent(content);
print(result.embedding.values);

Contar tokens

Cuando se usan instrucciones largas, puede ser útil contar los tokens antes de enviar contenido al modelo. En los siguientes ejemplos, se muestra cómo usar countTokens() para varios casos de uso:

// For text-only input
final tokenCount = await model.countTokens(Content.text(prompt));
print('Token count: ${tokenCount.totalTokens}');

// For text-and-image input (multimodal)
final tokenCount = await model.countTokens([
  Content.multi([prompt, ...imageParts])
]);
print('Token count: ${tokenCount.totalTokens}');

// For multi-turn conversations (like chat)
final prompt = Content.text(message);
final allContent = [...chat.history, prompt];
final tokenCount = await model.countTokens(allContent);
print('Token count: ${tokenCount.totalTokens}');

Opciones para controlar la generación de contenido

Puedes controlar la generación de contenido mediante la configuración de los parámetros del modelo y la configuración de seguridad.

Ten en cuenta que, si pasas generationConfig o safetySettings a un método de solicitud de modelo (como generateContent), se anulará por completo el objeto de configuración con el mismo nombre que se pasó en getGenerativeModel.

Configura los parámetros del modelo

Cada instrucción que envías al modelo incluye valores de parámetros que controlan cómo el modelo genera una respuesta. El modelo puede generar resultados diferentes para los valores de parámetros diferentes. Obtén más información sobre los parámetros del modelo. La configuración se mantiene durante el ciclo de vida de la instancia de modelo.

final generationConfig = GenerationConfig(
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
);
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

Usar la configuración de seguridad

Puedes usar la configuración de seguridad para ajustar la probabilidad de obtener respuestas que puedan considerarse perjudiciales. De forma predeterminada, la configuración de seguridad bloquea el contenido con probabilidad media o alta de ser contenido inseguro en todas las dimensiones. Obtén más información sobre la configuración de seguridad.

Para establecer una configuración de seguridad, sigue estos pasos:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  safetySettings: safetySettings,
);

También puedes establecer más de una configuración de seguridad:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
  SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];

Próximos pasos

  • El diseño de instrucciones es el proceso de crear instrucciones que producen la respuesta deseada de los modelos de lenguaje. Escribir instrucciones bien estructuradas es una parte esencial de garantizar respuestas precisas y de alta calidad desde un modelo de lenguaje. Obtén más información sobre las prácticas recomendadas para la escritura de instrucciones.

  • Gemini ofrece muchas variaciones del modelo para satisfacer las necesidades de distintos casos de uso, como los tipos de entrada y la complejidad, las implementaciones para chat y otras tareas de lenguaje de diálogo, y las restricciones de tamaño. Obtén más información sobre los modelos de Gemini disponibles.

  • Gemini ofrece opciones para solicitar aumentos del límite de frecuencia. El límite de frecuencia de los modelos Gemini Pro es de 60 solicitudes por minuto (RPM).