Начните работу с Prompt API

На этой странице описывается, как сделать следующее:

• Настройте свой проект для использования Prompt API
• Введите только текстовый ввод и получите ответ
• Предоставьте входные данные изображения с соответствующим текстовым вводом и получите ответ.

Более подробную информацию о Prompt API см. в справочной документации по Kotlin ( com.google.mlkit.genai.prompt ) и Java ( com.google.mlkit.genai.prompt.java , com.google.mlkit.genai.prompt ).

[Необязательно] Тестовая подсказка с моделью Gemma 3n

Перед реализацией рекомендуем протестировать подсказку в AI Studio с помощью модели Gemma 3n E4B . Ожидается, что результаты Gemma 3n будут очень похожи на результаты nano-v3 .

Настроить проект

Примечание: для этого API требуется API Android уровня 26 или выше.

Добавьте API-интерфейс ML Kit Prompt в качестве зависимости в конфигурацию build.gradle :

implementation("com.google.mlkit:genai-prompt:1.0.0-alpha1")

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

Чтобы внедрить код в свой проект, выполните следующие действия:

• Создайте объект generativeModel :

  Котлин

  // Get a GenerativeModel instance
  val generativeModel = Generation.getClient()
  

  Ява

  // Get a GenerativeModel instance
  GenerativeModelFutures generativeModelFutures = GenerativeModelFutures
      .from(Generation.INSTANCE.getClient());
  

• Проверьте AVAILABLE, DOWNLOADABLE или UNAVAILABLE . Затем загрузите функцию, если она доступна для скачивания:

  Котлин

  val status = generativeModel.checkStatus()
  when (status) {
      FeatureStatus.UNAVAILABLE -> {
          // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
      }
  
      FeatureStatus.DOWNLOADABLE -> {
          // Gemini Nano can be downloaded on this device, but is not currently downloaded
          generativeModel.download().collect { status ->
              when (status) {
                  is DownloadStatus.DownloadStarted ->
                      Log.d(TAG, "starting download for Gemini Nano")
  
                  is DownloadStatus.DownloadProgress ->
                      Log.d(TAG, "Nano ${status.totalBytesDownloaded} bytes downloaded")
  
                  DownloadStatus.DownloadCompleted -> {
                      Log.d(TAG, "Gemini Nano download complete")
                      modelDownloaded = true
                  }
  
                  is DownloadStatus.DownloadFailed -> {
                      Log.e(TAG, "Nano download failed ${status.e.message}")
                  }
              }
          }
      }
  
      FeatureStatus.DOWNLOADING -> {
          // Gemini Nano currently being downloaded
      }
  
      FeatureStatus.AVAILABLE -> {
          // Gemini Nano currently downloaded and available to use on this device
      }
  }
  

  Ява

  ListenableFuture<Integer> status = generativeModelFutures.checkStatus();
  Futures.addCallback(generativeModelFutures.checkStatus(), new FutureCallback<>() {
      @Override
      public void onSuccess(Integer featureStatus) {
          switch (featureStatus) {
              case FeatureStatus.AVAILABLE - > {
                  // Gemini Nano currently downloaded and available to use on this device
              }
              case FeatureStatus.UNAVAILABLE - > {
                  // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
              }
              case FeatureStatus.DOWNLOADING - > {
                  // Gemini Nano currently being downloaded
              }
              case FeatureStatus.DOWNLOADABLE - > {
                  generativeModelFutures.download(new DownloadCallback() {
                      @Override
                      public void onDownloadStarted(long l) {
                          Log.d(TAG, "starting download for Gemini Nano");
                      }
                      @Override
                      public void onDownloadProgress(long l) {
                          Log.d(TAG, "Nano " + l + " bytes downloaded");
                      }
                      @Override
                      public void onDownloadCompleted() {
                          Log.d(TAG, "Gemini Nano download complete");
                      }
                      @Override
                      public void onDownloadFailed(@NonNull GenAiException e) {
                          Log.e(TAG, "Nano download failed: " + e.getMessage());
                      }
                  });
              }
          }
      }
      @Override
      public void onFailure(@NonNull Throwable t) {
          // Failed to check status
      }
  }, ContextCompat.getMainExecutor(context));
  
  

Предоставить только текстовый ввод

Котлин

val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog.")

Ява

GenerateContentResponse response = generativeModelFutures.generateContent(
  new GenerateContentRequest.Builder(
    new TextPart("Write a 3 sentence story about a magical dog."))
  .build())
  .get();

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

Котлин

val response = generativeModel.generateContent(
    generateContentRequest(
        TextPart("Write a 3 sentence story about a magical dog."),
    ) {
        // Optional parameters
        temperature = 0.2f
        topK = 10
        candidateCount = 3
    },
)

Ява

GenerateContentRequest.Builder requestBuilder =
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."));
requestBuilder.setTemperature(.2f);
requestBuilder.setTopK(10);
requestBuilder.setCandidateCount(3);

GenerateContentResponse response =
        generativeModelFutures.generateContent(requestBuilder.build()).get();

Дополнительную информацию о дополнительных параметрах см. в разделе Дополнительные конфигурации .

Обеспечить многомодальный (изображение и текст) ввод

Объедините изображение и текстовое поле в функции generateContentRequest() , при этом текстовое приглашение должно быть вопросом или командой, относящейся к изображению:

Котлин

val response = generativeModel.generateContent(
    generateContentRequest(ImagePart(bitmap), TextPart(textPrompt)) {
        // optional parameters
        ...
    },
)

Ява

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new ImagePart(bitmap),
        new TextPart("textPrompt"))
    // optional parameters
    .build())
.get();

Результат процесса вывода

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

  • При этом используется непотоковый вывод, который извлекает весь результат из модели ИИ перед возвратом результата:

  Котлин

  // Call the AI model to generate content and store the complete
  // in a new variable named 'response' once it's finished
  val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog")
  

  Ява

  GenerateContentResponse response = generativeModelFutures.generateContent(
          new GenerateContentRequest.Builder(
                  new TextPart("Write a 3 sentence story about a magical dog."))
                  .build())
          .get();
  

  • В следующих фрагментах приведены примеры использования потокового вывода, который извлекает результат порциями по мере его генерации:

  Котлин

  // Streaming inference
  var fullResponse = ""
  generativeModel.generateContentStream("Write a 3 sentence story about a magical dog").collect { chunk ->
      val newChunkReceived = chunk.candidates[0].text
      print(newChunkReceived)
      fullResponse += newChunkReceived
  }
  

  Ява

  // Streaming inference
  StringBuilder fullResponse = new StringBuilder();
  generativeModelFutures.generateContent(new GenerateContentRequest.Builder(
      (new TextPart("Write a 3 sentence story about a magical dog"))).build(),
          chunk -> {
              Log.d(TAG, chunk);
              fullResponse.append(chunk);
          });
  

Дополнительную информацию о потоковом и непотоковом выводе см. в разделе Потоковая передача и непотоковая передача .

Оптимизация задержки

Для оптимизации первого вызова вывода ваше приложение может дополнительно вызвать warmup() . Это загрузит Gemini Nano в память и инициализирует компоненты среды выполнения.

Дополнительные конфигурации

В рамках каждого GenerateContentRequest вы можете задать следующие необязательные параметры:

• temperature : контролирует степень случайности выбора токенов.
• seed : позволяет генерировать стабильные и детерминированные результаты.
• topK : контролирует случайность и разнообразие результатов.
• candidateCount : запрашивает количество возвращенных уникальных ответов. Обратите внимание, что точное количество ответов может не совпадать с candidateCount поскольку дублирующиеся ответы автоматически удаляются.
• maxOutputTokens : определяет максимальное количество токенов, которые могут быть сгенерированы в ответе.

Дополнительные рекомендации по настройке дополнительных конфигураций см. в разделе GenerateContentRequest .

Поддерживаемые функции и ограничения

• Ввод должен содержать не более 4000 токенов (или примерно 3000 английских слов). Подробнее см. в справочнике countTokens .
• Следует избегать случаев, требующих длинного вывода (более 256 токенов).
• AICore устанавливает квоту вывода для каждого приложения. Подробнее см. в разделе «Квота для каждого приложения» .
• Для Prompt API проверены следующие языки:
  • Английский
  • корейский

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

Распространенные проблемы с настройкой

Примечание: этот API не поддерживается на устройствах с разблокированным загрузчиком .

API ML Kit GenAI используют приложение Android AICore для доступа к Gemini Nano. Если устройство только что настроено (включая сброс настроек) или приложение AICore только что сброшено (например, для удаления данных, удаления и последующей переустановки), приложению AICore может не хватить времени для завершения инициализации (включая загрузку последних конфигураций с сервера). В результате API ML Kit GenAI могут работать некорректно. Ниже приведены распространённые сообщения об ошибках настройки и способы их устранения:

Пример сообщения об ошибке	Как обращаться
Произошла ошибка AICore с типом ошибки 4-CONNECTION_ERROR и кодом ошибки 601-BINDING_FAILURE: Службе AICore не удалось выполнить привязку.	Это может произойти, если вы устанавливаете приложение с помощью API GenAI из ML Kit сразу после настройки устройства или если AICore удаляется после установки приложения. Обновление AICore и его переустановка должны исправить проблему.
Произошла ошибка AICore с типом ошибки 3-PREPARATION_ERROR и кодом ошибки 606-FEATURE_NOT_FOUND: Функция ... недоступна.	Это может произойти, если AICore не завершил загрузку последних конфигураций. При подключении устройства к интернету обновление обычно занимает от нескольких минут до нескольких часов. Перезапуск устройства может ускорить обновление. Обратите внимание: если загрузчик устройства разблокирован, вы также увидите эту ошибку — этот API не поддерживает устройства с разблокированными загрузчиками.
Ошибка AICore: тип ошибки 1-DOWNLOAD_ERROR и код ошибки 0-UNKNOWN: Функция ... завершилась неудачей со статусом ошибки 0 и ошибкой esz: UNAVAILABLE: Не удалось разрешить хост ...	Сохраните сетевое подключение, подождите несколько минут и повторите попытку.

Примечание: Хотя различные сбросы настроек — обычное дело для разработчиков, пользователи сталкиваются с ними гораздо реже. Кроме того, все эти случаи сбоев настройки могут быть обнаружены API-функциями checkFeatureStatus() или checkStatus() . Обязательно вызывайте checkFeatureStatus() или checkStatus() перед отображением любого связанного пользовательского интерфейса, чтобы пользователи вашего приложения не увидели эти ошибки ни при каких обстоятельствах.