Руководство: Начало работы с Gemini API


Этот учебник демонстрирует, как получить доступ к API Gemini для вашего приложения GO, используя Google AI GO SDK.

В этом уроке вы узнаете, как сделать следующее:

Кроме того, этот урок содержит разделы о передовых вариантах использования (например, встраивания и токенов подсчета ), а также опции для управления генерацией контента .

Предварительные условия

Этот учебник предполагает, что вы знакомы с строительными приложениями с Go.

Чтобы завершить этот урок, убедитесь, что ваша среда разработки соответствует следующим требованиям:

  • Go 1.20+

Настройте свой проект

Прежде чем вызывать API Gemini, вам необходимо настроить свой проект, который включает настройку ключа API, установку пакета SDK и инициализацию модели.

Установите свой ключ API

Чтобы использовать API Gemini, вам понадобится ключ API. Если у вас его еще нет, создайте ключ в Google AI Studio.

Получить ключ API

Закрепите свой ключ API

Настоятельно рекомендуется, чтобы вы не проверяли ключ API в системе управления версиями. Вместо этого вы должны использовать секреты для вашего ключа API.

Все фрагменты в этом уроке предполагают, что вы получаете доступ к своему клавишу API в качестве переменной среды.

Установите пакет SDK

Чтобы использовать API Gemini в вашем собственном приложении, вам нужно get пакет GO SDK в своем каталоге модуля:

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

Инициализировать генеративную модель

Прежде чем вы сможете сделать какие -либо вызовы API, вам необходимо импортировать и инициализировать генеративную модель.

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")

При указании модели обратите внимание на следующее:

  • Используйте модель, специфичную для вашего варианта использования (например, gemini-1.5-flash для мультимодального входа). В рамках этого руководства в инструкциях для каждой реализации перечислены рекомендуемая модель для каждого варианта использования.

Реализовать общие варианты использования

Теперь, когда ваш проект настроен, вы можете изучить, используя API Gemini для реализации различных вариантов использования:

В разделе Advanced Caser Cassion вы можете найти информацию об API и встраивании Близнецов.

Создать текст из ввода только текста

Когда ввод подсказки включает только текст, используйте модель Gemini 1.5 или модель Gemini 1.0 Pro с generateContent для генерации вывода текста:

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

Создать текст с ввода текста и изображения (мультимодальный)

Gemini предоставляет различные модели, которые могут обрабатывать мультимодальный вход (модели Gemini 1.5), чтобы вы могли вводить как текст, так и изображения. Обязательно просмотрите требования к изображению для подсказок .

Когда ввод подсказки включает в себя как текст, так и изображения, используйте модель Gemini 1.5 с помощью метода generateContent для генерации вывода текста:

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

Создайте многократные разговоры (чат)

Используя Gemini, вы можете создавать свободные разговоры по нескольким поворотам. SDK упрощает процесс, управляя состоянием разговора, поэтому, в отличие от GenerateContent , вам не нужно хранить историю разговора самостоятельно.

Чтобы построить многообразование разговора (например, чат), используйте модель Gemini 1.5 или модель Gemini 1.0 Pro, и инициализируйте чат, позвонив startChat() . Затем используйте sendMessage() , чтобы отправить новое пользовательское сообщение, которое также добавит сообщение и ответ на историю чата.

Есть два возможных варианта role , связанных с содержанием в разговоре:

  • user : роль, которая предоставляет подсказки. Это значение является по умолчанию для вызовов SendMessage .

  • model : роль, которая обеспечивает ответы. Эта роль может быть использована при вызове StartChat() с существующей history .

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

Используйте потоковую передачу для более быстрых взаимодействий

По умолчанию модель возвращает ответ после завершения всего процесса генерации. Вы можете достичь более быстрых взаимодействий, не ожидая всего результата, и вместо этого использовать потоковую передачу для обработки частичных результатов.

В следующем примере показано, как реализовать потоковую передачу с помощью метода GenerateContentStream для генерации текста из подсказки ввода текста и изображения.

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
}

Вы можете использовать аналогичный подход для ввода только текста и вариантов использования чата.

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)

Внедрить расширенные варианты использования

Общие варианты использования, описанные в предыдущем разделе этого учебника, помогают вам понять API Gemini. В этом разделе описываются некоторые варианты использования, которые можно считать более продвинутыми.

Используйте встраивание

Встраивание - это метод, используемый для представления информации в качестве списка номеров с плавающей запятой в массиве. С Близнецами вы можете представлять текст (слова, предложения и блоки текста) в векторизованной форме, что облегчает сравнение и сопоставление встраиваний. Например, два текста, в которых разделяют сходные темы или чувства, должны иметь сходные встроенные встроения, которые могут быть идентифицированы с помощью математических методов сравнения, таких как сходство косинуса.

Используйте модель embedding-001 с помощью метода EmbedContent (или метода BatchEmbedContent ), чтобы генерировать вставки. Следующий пример генерирует встроение для одной строки:

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)

Функция вызова

Функциональный вызов облегчает вам структурированные выходные данные из генеративных моделей. Затем вы можете использовать эти выходы для вызова других API и вернуть соответствующие данные ответа в модель. Другими словами, функциональный вызов помогает вам подключить генеративные модели к внешним системам, чтобы сгенерированный контент включал самую современную и точную информацию. Узнайте больше в функции, вызову обучения .

Считайте токены

При использовании длинных подсказок может быть полезно подсчитать токены перед отправкой какого -либо контента в модель. Следующие примеры показывают, как использовать CountTokens() для различных вариантов использования:

// 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)

Параметры для контроля генерации контента

Вы можете управлять генерацией содержания, настраивая параметры модели и с помощью настройки безопасности.

Настройте параметры модели

Каждое приглашение, которое вы отправляете в модель, включает значения параметров, которые управляют тем, как модель генерирует ответ. Модель может генерировать различные результаты для разных значений параметров. Узнайте больше о параметрах модели . Конфигурация поддерживается для срока службы экземпляра модели.

// ...

// 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)

// ...

Используйте настройки безопасности

Вы можете использовать настройки безопасности, чтобы скорректировать вероятность получения ответов, которые можно считать вредными. По умолчанию настройки безопасности блокируют содержание со средней и/или высокой вероятностью быть небезопасным содержанием во всех измерениях. Узнайте больше о настройках безопасности .

Вот как установить одну настройку безопасности:

// ...

// 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,
  },
}

// ...

Вы также можете установить более одного настройки безопасности:

// ...

// 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,
  },
}

// ...

Что дальше

  • Обратный дизайн - это процесс создания подсказок, которые вызывают желаемый ответ от языковых моделей. Написание хорошо структурированных подсказок является неотъемлемой частью обеспечения точных, высококачественных ответов из языковой модели. Узнайте о лучших практиках для быстрого написания .

  • Gemini предлагает несколько вариаций модели для удовлетворения потребностей различных вариантов использования, таких как типы вводов и сложность, реализации для чата или другие языковые задачи диалоговых языков и ограничения размера. Узнайте о доступных моделях Близнецов .