Prompt API 시작하기

이 페이지에서는 다음 작업을 수행하는 방법을 설명합니다.

• 프롬프트 API를 사용하도록 프로젝트 구성
• 텍스트 전용 입력을 제공하고 대답 받기
• 관련 텍스트 입력과 함께 이미지 입력을 제공하고 응답을 받습니다.

프롬프트 API에 관한 자세한 내용은 Kotlin (com.google.mlkit.genai.prompt) 및 Java (com.google.mlkit.genai.prompt.java, com.google.mlkit.genai.prompt) 참조 문서를 참고하세요.

[선택사항] Gemma 3n 모델로 프롬프트 테스트

구현하기 전에 Gemma 3n E4B 모델을 사용하여 AI Studio에서 프롬프트를 테스트하는 것이 좋습니다. Gemma 3n의 출력은 nano-v3의 출력과 매우 유사할 것으로 예상됩니다.

프로젝트 구성

참고: 이 API에는 Android API 수준 26 이상이 필요합니다.

build.gradle 구성에 ML Kit 프롬프트 API를 종속 항목으로 추가합니다.

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

생성 모델 구현

프로젝트에 코드를 구현하려면 다음 단계를 따르세요.

• generativeModel 객체를 만듭니다.

  Kotlin

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

  자바

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

• Gemini Nano가 AVAILABLE,, DOWNLOADABLE 또는 UNAVAILABLE인지 확인합니다. 그런 다음 다운로드할 수 있는 경우 기능을 다운로드합니다.

  Kotlin

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

텍스트 전용 입력 제공

Kotlin

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

또는 선택적 매개변수를 추가합니다.

Kotlin

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() 함수에서 이미지와 텍스트 입력을 함께 번들로 묶습니다. 텍스트 프롬프트는 이미지와 관련된 질문이나 명령입니다.

Kotlin

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

추론 결과 처리

• 추론을 실행하고 결과를 가져옵니다. 텍스트 전용 프롬프트와 멀티모달 프롬프트 모두에 대해 전체 결과를 기다리거나 응답이 생성될 때 스트리밍할 수 있습니다.

  • 이는 결과를 반환하기 전에 AI 모델에서 전체 결과를 가져오는 비스트리밍 추론을 사용합니다.

  Kotlin

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

  • 다음 스니펫은 생성되는 대로 청크로 결과를 가져오는 스트리밍 추론을 사용하는 예입니다.

  Kotlin

  // 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을 참고하세요.

지원되는 기능 및 제한사항

• 입력은 4,000개 미만의 토큰 (영문 기준 약 3,000단어)이어야 합니다. 자세한 내용은 countTokens 참조를 확인하세요.
• 긴 출력 (256개 이상의 토큰)이 필요한 사용 사례는 피해야 합니다.
• AICore는 앱별 추론 할당량을 적용합니다. 자세한 내용은 애플리케이션별 할당량을 참고하세요.
• 다음 언어가 Prompt API에 대해 검증되었습니다.
  • 영어
  • 한국어

참고: 더 많은 언어를 검증하는 중입니다. 다른 언어로도 실험하여 품질 기준을 충족하는지 확인하고 관심 있는 다른 언어에 대한 의견을 제공해 주시기 바랍니다.

일반적인 설정 문제

참고: 이 API는 잠금 해제된 부트로더가 있는 기기에서 지원되지 않습니다.

ML Kit GenAI API는 Android AICore 앱을 사용하여 Gemini Nano에 액세스합니다. 기기가 설정된 직후 (초기화 포함) 또는 AICore 앱이 초기화된 직후 (예: 데이터 삭제, 제거 후 재설치)에는 AICore 앱이 초기화 (서버에서 최신 구성 다운로드 포함)를 완료할 시간이 충분하지 않을 수 있습니다. 따라서 ML Kit 생성형 AI API가 예상대로 작동하지 않을 수 있습니다. 표시될 수 있는 일반적인 설정 오류 메시지와 처리 방법은 다음과 같습니다.

오류 메시지 예	처리 방법
AICore가 오류 유형 4-CONNECTION_ERROR 및 오류 코드 601-BINDING_FAILURE로 실패했습니다. AICore 서비스가 바인딩되지 않았습니다.	이는 기기 설정 직후 ML Kit 생성형 AI API를 사용하여 앱을 설치하거나 앱이 설치된 후 AICore가 제거된 경우 발생할 수 있습니다. AICore 앱을 업데이트한 후 앱을 다시 설치하면 문제가 해결됩니다.
AICore가 오류 유형 3-PREPARATION_ERROR 및 오류 코드 606-FEATURE_NOT_FOUND로 실패했습니다. 기능 ...을 사용할 수 없습니다.	이는 AICore가 최신 구성 다운로드를 완료하지 않은 경우 발생할 수 있습니다. 기기가 인터넷에 연결되어 있으면 업데이트하는 데 보통 몇 분에서 몇 시간이 걸립니다. 기기를 다시 시작하면 업데이트 속도를 높일 수 있습니다. 기기의 부트로더가 잠금 해제된 경우에도 이 오류가 표시됩니다. 이 API는 부트로더가 잠금 해제된 기기를 지원하지 않습니다.
AICore가 오류 유형 1-DOWNLOAD_ERROR 및 오류 코드 0-UNKNOWN으로 실패했습니다. 기능 ...이 실패 상태 0 및 오류 esz: UNAVAILABLE로 실패했습니다. 호스트 ...를 확인할 수 없습니다.	네트워크 연결을 유지하고 몇 분 정도 기다린 후 다시 시도합니다.

참고: 개발자에게는 다양한 재설정이 일반적이지만 사용자에게는 훨씬 덜 일반적입니다. 또한 이러한 모든 설정 실패 사례는 checkFeatureStatus() 또는 checkStatus() API로 포착할 수 있습니다. 관련 UI를 표시하기 전에 먼저 checkFeatureStatus() 또는 checkStatus()을 호출하여 앱 사용자에게 이러한 오류가 표시되지 않도록 하세요.