Начните работу с API Gemini в приложениях Dart или Flutter.

В этом руководстве показано, как получить доступ к API Gemini для вашего приложения Dart или Flutter с помощью Google AI Dart SDK. Вы можете использовать этот SDK, если не хотите напрямую работать с REST API для доступа к моделям Gemini в вашем приложении.

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

• Настройте свой проект, включая ключ API
• Генерировать текст из текстового ввода
• Генерация текста из ввода текста и изображения (мультимодальный)
• Создавайте многоходовые беседы (чат)
• Используйте потоковую передачу для более быстрого взаимодействия

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

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

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

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

• Дартс 3.2.0+

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

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

Настройте свой ключ API

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

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

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

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

Во всех фрагментах этого руководства предполагается, что вы обращаетесь к своему ключу API как к переменной среды процесса. Если вы разрабатываете приложение Flutter, вы можете использовать String.fromEnvironment и передать --dart-define=API_KEY=$API_KEY для flutter build или flutter run для компиляции с ключом API, поскольку при запуске приложения среда процесса будет другой. .

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

Чтобы использовать API Gemini в своем приложении, вам необходимо add пакет google_generative_ai в приложение Dart или Flutter:

dart pub add google_generative_ai

flutter pub add google_generative_ai

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

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

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

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

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

Реализация распространенных случаев использования

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

• Генерировать текст из текстового ввода
• Генерация текста из ввода текста и изображения (мультимодальный)
• Создавайте многоходовые беседы (чат)
• Используйте потоковую передачу для более быстрого взаимодействия

В разделе «Продвинутые варианты использования» вы можете найти информацию об API Gemini и встраиваниях .

Генерировать текст из текстового ввода

Если входные данные подсказки включают только текст, используйте модель gemini-pro с generateContent для генерации текстового вывода:

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

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

Gemini предоставляет мультимодальную модель ( gemini-pro-vision ), поэтому вы можете вводить как текст, так и изображения. Обязательно ознакомьтесь с требованиями к изображениям для ввода .

Если входные данные подсказки включают в себя как текст, так и изображения, используйте модель gemini-pro-vision с методом generateContent для генерации текстового вывода:

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

Создавайте многоходовые беседы (чат)

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

Чтобы построить многоходовой разговор (например, чат), используйте модель gemini-pro и инициализируйте чат, вызвав startChat() . Затем используйте sendMessage() для отправки нового сообщения пользователя, которое также добавит сообщение и ответ в историю чата.

Существует два возможных варианта role , связанной с содержимым беседы:

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

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

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

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

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

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

// ...

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

// ...

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

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

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

Реализация расширенных вариантов использования

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

Вызов функции

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

Используйте вложения

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

Используйте модель embedding-001 с методом embedContent (или методом batchEmbedContent ) для создания внедрений. В следующем примере создается внедрение для одной строки:

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

Подсчитайте жетоны

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

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

Возможности управления созданием контента

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

Обратите внимание, что передача generationConfig или safetySettings в метод запроса модели (например, generateContent ) полностью переопределит объект конфигурации с тем же именем, переданный в getGenerativeModel .

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

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

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

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

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

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

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

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

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

Что дальше

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

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

• Gemini предлагает варианты запроса увеличения лимита ставок . Ограничение скорости для моделей Gemini Pro составляет 60 запросов в минуту (об/мин).