Instructivo: Comienza a usar la API de Gemini


En este instructivo, se muestra cómo acceder a la API de Gemini directamente desde tu app de Swift con el SDK de Swift de Google AI. Puedes usar este SDK si no quieres trabajar directamente con las APIs de REST o el código del servidor (como Python) para acceder a los modelos de Gemini en tu app de Swift.

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

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

Requisitos previos

En este instructivo, se supone que estás familiarizado con el uso de Xcode para desarrollar apps de Swift.

Para completar este instructivo, asegúrate de que tu entorno de desarrollo y la app de Swift cumplan con los siguientes requisitos:

  • Xcode 15.0 o una versión más reciente
  • Tu app de Swift debe orientarse a iOS 15 o versiones posteriores, o a macOS 12 o versiones posteriores.

Configura tu proyecto

Antes de llamar a la API de Gemini, debes configurar tu proyecto de Xcode, lo que incluye configurar tu clave de API, agregar el paquete del SDK a tu proyecto de Xcode y, luego, 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

Te recomendamos que no registres una clave de API en tu sistema de control de versión. Una opción alternativa es almacenarla en un archivo GenerativeAI-Info.plist y, luego, leer la clave de API desde el archivo .plist. Asegúrate de colocar este archivo .plist en la carpeta raíz de tu app y de excluirlo del control de versión.

También puedes revisar la app de ejemplo para obtener información sobre cómo almacenar tu clave de API en un archivo .plist.

En todos los fragmentos de este instructivo, se supone que accedes a tu clave de API desde este archivo .plist de recursos a pedido.

Agrega el paquete de SDK a tu proyecto

Para usar la API de Gemini en tu app de Swift, agrega el paquete GoogleGenerativeAI a la app:

  1. En Xcode, haz clic con el botón derecho en tu proyecto en el navegador de proyectos.

  2. Selecciona Add Packages en el menú contextual.

  3. En el diálogo Add Packages, pega la URL del paquete en la barra de búsqueda:

    https://github.com/google/generative-ai-swift
    
  4. Haz clic en Add Package. Xcode ahora agregará el paquete GoogleGenerativeAI a tu proyecto.

Inicializa el modelo generativo

Antes de realizar llamadas a la API, debes inicializar el modelo generativo.

  1. Importa el módulo GoogleGenerativeAI:

    import GoogleGenerativeAI
    
  2. Inicializa el modelo generativo:

    // Access your API key from your on-demand resource .plist file
    // (see "Set up your API key" above)
    // The Gemini 1.5 models are versatile and work with most use cases
    let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)
    

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 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:

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

Cuando la entrada de la instrucción incluya solo texto, usa un modelo de Gemini 1.5 o un modelo de Gemini 1.0 Pro con generateContent para generar una salida de texto:

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let prompt = "Write a story about a magic backpack."
let response = try await model.generateContent(prompt)
if let text = response.text {
  print(text)
}

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

Gemini proporciona varios modelos que pueden controlar entradas multimodales (modelos Gemini 1.5 y Gemini 1.0 Pro Vision) para que puedas ingresar texto e imágenes. Asegúrate de revisar los requisitos de las imágenes para los mensajes.

Cuando la entrada de un mensaje incluya imágenes y texto, usa un modelo de Gemini 1.5 o un modelo de Gemini 1.0 Pro Vision con el método generateContent para generar una salida de texto:

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(...)
let image2 = UIImage(...)

let prompt = "What's different between these pictures?"

let response = try await model.generateContent(prompt, image1, image2)
if let text = response.text {
  print(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 un modelo Gemini 1.5 o Gemini 1.0 Pro y, luego, inicializa el chat llamando a startChat(). Luego, usa sendMessage() para enviar un mensaje al usuario nuevo, que también adjuntará 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 es el valor predeterminado para las llamadas a sendMessage.

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

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

let history = [
  ModelContent(role: "user", parts: "Hello, I have 2 dogs in my house."),
  ModelContent(role: "model", parts: "Great to meet you. What would you like to know?"),
]

// Initialize the chat
let chat = model.startChat(history: history)
let response = try await chat.sendMessage("How many paws are in my house?")
if let text = response.text {
  print(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.

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(named: "")!
let image2 = UIImage(named: "")!

let prompt = "What's different between these pictures?"
var fullResponse = ""
let contentStream = model.generateContentStream(prompt, image1, image2)
for try await chunk in contentStream {
  if let text = chunk.text {
    print(text)
    fullResponse += text
  }
}
print(fullResponse)

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

// Use streaming with text-only input
let contentStream = model.generateContentStream(prompt)
// Use streaming with multi-turn conversations (like chat)
let responseStream = chat.sendMessageStream(message)

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.

Llamada a función

La llamada a funciones facilita la obtención de resultados de datos estructurados de modelos generativos. Luego, puedes usar estos resultados para llamar a otras APIs y mostrar los datos de respuesta relevantes al modelo. En otras palabras, la llamada a funciones te ayuda a conectar 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.

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
let response = try await model.countTokens("Why is the sky blue?")
print(response.totalTokens)
// For text-and-image input (multi-modal)
let response = try await model.countTokens(prompt, image1, image2)
print(response.totalTokens)
// For multi-turn conversations (like chat)
let chat = model.startChat()
let history = chat.history
let message = try ModelContent(role: "user", "Why is the sky blue?")
let contents = history + [message]
let response = try await model.countTokens(contents)
print(response.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.

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.

let config = GenerationConfig(
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
  maxOutputTokens: 200,
  stopSequences: ["red"]
)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

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:

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  safetySettings: [
    SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
  ]
)

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

let harassmentSafety = SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
let hateSpeechSafety = SafetySetting(harmCategory: .hateSpeech, threshold: .blockMediumAndAbove)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

¿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 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).