Instructivo: Comienza a usar la API de Gemini


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

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

Además, este instructivo contiene secciones sobre casos de uso avanzados (como las incorporaciones y recuento de tokens), así como 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 requisitos 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/Sub y para 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 uno, crea una clave en Google AI Studio.

Obtén una clave de API.

Protege tu clave de API

Mantén segura tu clave de API. Te recomendamos que no incluyas los La clave de API directamente en tu código o revisa los archivos que contengan la clave en la versión de los sistemas de control de calidad. 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 creada con Flutter, puedes usar String.fromEnvironment y pasa --dart-define=API_KEY=$API_KEY a flutter build o flutter run para compilar con la clave de API, ya que el proceso será diferente cuando ejecutes la app.

Instala el paquete del SDK

Para usar la API de Gemini en tu propia aplicación, debes add el 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 realizar cualquier llamada a la API, debes importar e inicializar el archivo generativo.

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);
  }

  // The Gemini 1.5 models are versatile and work with most use cases
  final model = GenerativeModel(model: 'gemini-1.5-flash', 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-1.5-flash es para entradas multimodales). En esta guía, las instrucciones para cada de implementación, y luego enumerar el modelo recomendado para cada caso de uso.

Implementa casos de uso comunes

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

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

Genera texto a partir de entradas de solo texto

Cuando la entrada de la instrucción solo incluya texto, usa un modelo de Gemini 1.5 o Modelo de Gemini 1.0 Pro con generateContent para generar 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);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', 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 imágenes (multimodal)

Gemini proporciona varios modelos que pueden controlar entradas multimodales (modelos de Gemini 1.5) para que puedas ingresar tanto texto imágenes. Asegúrate de revisar el requisitos de imágenes para las instrucciones.

Cuando la entrada de instrucciones incluya imágenes y texto, usa un modelo de Gemini 1.5. 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);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', 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 entablar conversaciones de formato libre en múltiples turnos. El SDK simplifica el proceso, ya que administra el estado de la conversación, así que, con generateContent, no tienes que almacenar el historial de conversaciones de ti mismo.

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

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

  • user: Es la función que proporciona los mensajes. Este es el valor predeterminado para sendMessage, y la función arrojará una excepción si se trata de el rol de revisor de privacidad.

  • model: Es la función que proporciona las respuestas. Este rol puede usarse cuando Llamando a startChat() con history existentes

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);
  }
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  final model = GenerativeModel(
      model: 'gemini-1.5-flash',
      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 tener interacciones más rápidas

De forma predeterminada, el modelo devuelve una respuesta después de completar toda la generación. el proceso de administración de recursos. Puede lograr interacciones más rápidas si no espera a que todo resultado y, en su lugar, usa la transmisión para manejar 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 entrada de imagen y texto mensaje.

// ...

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 entrada de solo texto y chat.

// 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 ayudan a a que te familiarices con la API de Gemini. En esta sección, se describen algunas que podrían considerarse más avanzados.

Llamada a función

Las llamadas a función facilitan la obtención de resultados de datos estructurados desde generativos. Luego, puedes usar estos resultados para llamar a otras APIs y mostrar los datos de respuesta relevantes para el modelo. En otras palabras, las llamadas a funciones ayudan conecta modelos generativos a sistemas externos para que el contenido generado incluya la información más actualizada y precisa. Obtén más información en el instructivo de llamada a funciones.

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 forma vectorizada, lo que lo hace más fáciles de comparar y contrastar. Por ejemplo, dos textos que comparten un un tema o una opinión similares deben tener incorporaciones similares, que pueden identificados a través de técnicas matemáticas de comparación, como la similitud coseno.

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

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, podría ser útil contar los tokens antes de enviar cualquiera 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 a través de la configuración de los parámetros del modelo y el uso configuración de seguridad.

Ten en cuenta que pasar generationConfig o safetySettings a una solicitud de modelo (como generateContent) anulará por completo el objeto de configuración con el mismo nombre, 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 Parámetros del modelo. La configuración se mantiene durante toda la vida útil de tu instancia de modelo.

final generationConfig = GenerationConfig(
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
);
final model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

Usar la configuración de seguridad

Puedes usar la configuración de seguridad para ajustar la probabilidad de recibir respuestas que puede considerarse perjudicial. Según la configuración predeterminada, la configuración de seguridad bloquea el contenido con o una alta probabilidad de ser contenido no seguro en todas las dimensiones. Aprendizaje Obtén más información sobre la configuración de seguridad.

Sigue estos pasos para establecer una configuración de seguridad:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  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),
];

¿Qué sigue?

  • 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 redacción de instrucciones.

  • Gemini ofrece diversas variaciones de modelos para satisfacer las necesidades de los distintos usos como tipos de entrada y complejidad, implementaciones para chat u otros las tareas de lenguaje de diálogo y las restricciones de tamaño. Obtén más información sobre los modelos de Gemini disponibles.