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 Go con el SDK de la IA de Google para Go.

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

Además, este instructivo contiene secciones sobre casos de uso avanzados (como incorporaciones y recuento de tokens), además de 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 Go.

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

  • Go 1.20 y versiones posteriores

Configura tu proyecto

Antes de llamar a la API de Gemini, debes configurar tu proyecto, lo que incluye configurar la clave de API, instalar el paquete del SDK 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, créala en Google AI Studio.

Obtén una clave de API.

Protege tu clave de API

Te recomendamos que no incluyas una clave de API en tu sistema 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.

Instala el paquete del SDK

Para usar la API de Gemini en tu propia aplicación, debes realizar una operación get en el paquete del SDK de Go en el directorio de tu módulo:

go get github.com/google/generative-ai-go

Inicializa el modelo generativo

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

import "github.com/google/generative-ai-go/genai"
import "google.golang.org/api/option"

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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 entrada multimodal). En esta guía, las instrucciones para cada implementación enumeran 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.

Genera texto a partir de entradas de solo texto

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

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 imágenes y texto. Asegúrate de revisar los requisitos de imágenes para las instrucciones.

Cuando la entrada de la instrucción incluya imágenes y texto, usa un modelo de Gemini 1.5 con el método generateContent para generar salida de texto:

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

imgData1, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

imgData2, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

prompt := []genai.Part{
  genai.ImageData("jpeg", imgData1),
  genai.ImageData("jpeg", imgData2),
  genai.Text("What's different between these two pictures?"),
}
resp, err := model.GenerateContent(ctx, prompt...)

if err != nil {
  log.Fatal(err)
}

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, 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 de Gemini 1.5 o el modelo de Gemini 1.0 Pro, e 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.

Existen dos opciones posibles para role asociado al contenido de una conversación:

  • user: Es la función que proporciona los mensajes. Este valor es el predeterminado para las llamadas SendMessage.

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
model := client.GenerativeModel("gemini-1.5-flash")
// Initialize the chat
cs := model.StartChat()
cs.History = []*genai.Content{
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Hello, I have 2 dogs in my house."),
    },
    Role: "user",
  },
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Great to meet you. What would you like to know?"),
    },
    Role: "model",
  },
}

resp, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
if err != nil {
  log.Fatal(err)
}

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

De forma 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 todo el resultado y, en su lugar, usa la transmisión para controlar 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 un mensaje de entrada de imagen y texto.

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

imageBytes, err := os.ReadFile(pathToImage)

img := genai.ImageData("jpeg", imageBytes)
prompt := genai.Text("Tell me a story about this animal")
iter := model.GenerateContentStream(ctx, img, prompt)

for {
  resp, err := iter.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }

  // ... print resp
}

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

prompt := genai.Text("Tell me a story about a lumberjack and his giant ox")
iter := model.GenerateContentStream(ctx, prompt)

prompt := genai.Text("And how do you feel about that?")
iter := cs.SendMessageStream(ctx, prompt)

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 la 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) de forma vectorizada, lo que facilita la comparación y el contraste de las incorporaciones. Por ejemplo, dos textos que comparten un tema o una opinión similares deben tener incorporaciones similares, que pueden identificarse 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 el método BatchEmbedContent) para generar incorporaciones. En el siguiente ejemplo, se genera una incorporación para una sola cadena:

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()
// For embeddings, use the embedding-001 model
em := client.EmbeddingModel("embedding-001")
res, err := em.EmbedContent(ctx, genai.Text("The quick brown fox jumps over the lazy dog."))

if err != nil {
  panic(err)
}
fmt.Println(res.Embedding.Values)

Llamada a función

Las llamadas a función facilitan 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, las llamadas a función te ayudan 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
text := "Parrots can be green and live a long time."
resp, err := model.CountTokens(ctx, genai.Text(text))
if err != nil {
  log.Fatal(err)
}
fmt.Println(resp.TotalTokens)

// For text-and-image input (multimodal)
text := "Parrots can be green and live a long time."
imageBytes, err := os.ReadFile(pathToImage)
if err != nil {
  log.Fatal(err)
}

resp, err := model.CountTokens(
    ctx,
    genai.Text(text),
    genai.ImageData("png", imageBytes))
  if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.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 el uso de 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 toda la vida útil de tu instancia de modelo.

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

// Configure model parameters by invoking Set* methods on the model.
model.SetTemperature(0.9)
model.SetTopK(1)

// ...

Usar la configuración de seguridad

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

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

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
}

// ...

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

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
  {
    Category:  genai.HarmCategoryHateSpeech,
    Threshold: genai.HarmBlockMediumAndAbove,
  },
}

// ...

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