API GenAI Image Description

API này được cung cấp ở giai đoạn thử nghiệm và không tuân theo bất kỳ SLA hoặc chính sách ngừng sử dụng nào. Các thay đổi có thể được thực hiện đối với API này, làm mất khả năng tương thích ngược.

Với API Mô tả hình ảnh GenAI của Bộ công cụ học máy, bạn có thể tạo nội dung mô tả ngắn cho hình ảnh. Điều này có thể hữu ích trong các trường hợp sử dụng sau:

• Tạo tiêu đề cho hình ảnh
• Tạo văn bản thay thế (văn bản alt) để giúp người dùng khiếm thị hiểu rõ hơn nội dung của hình ảnh
• Sử dụng nội dung mô tả được tạo làm siêu dữ liệu để giúp người dùng tìm kiếm hoặc sắp xếp hình ảnh
• Sử dụng nội dung mô tả ngắn về hình ảnh khi người dùng không thể nhìn vào màn hình, chẳng hạn như khi họ đang lái xe hoặc nghe podcast

Các chức năng chính

• Trả về nội dung mô tả ngắn gọn cho hình ảnh đầu vào

Kết quả mẫu

Input	Kết quả
	Một rô-bốt Android nhỏ màu xanh lục có thiết kế giống cây xương rồng đang nằm trên một bề mặt màu đen.
	Một chú chó nhỏ màu trắng có mũi đen và lưỡi hồng chạy trên một cánh đồng cỏ có cầu ở phía sau.

Bắt đầu

Lưu ý: API này yêu cầu API Android cấp 26 trở lên.

Để bắt đầu sử dụng API mô tả hình ảnh GenAI, hãy thêm phần phụ thuộc này vào tệp bản dựng của dự án.

implementation("com.google.mlkit:genai-image-description:1.0.0-beta1")

Để tích hợp Image Description API vào ứng dụng, bạn sẽ bắt đầu bằng cách lấy một ứng dụng ImageDescriber. Sau đó, bạn phải kiểm tra trạng thái của các tính năng mô hình cần thiết trên thiết bị và tải mô hình xuống nếu mô hình đó chưa có trên thiết bị. Sau khi chuẩn bị dữ liệu đầu vào hình ảnh trong ImageDescriptionRequest, bạn sẽ chạy quy trình suy luận bằng ứng dụng để lấy văn bản mô tả hình ảnh. Cuối cùng, hãy nhớ đóng ứng dụng để giải phóng tài nguyên.

Kotlin

// Create an image describer
val options = ImageDescriberOptions.builder(context).build()
val imageDescriber = ImageDescription.getClient(options)

suspend fun prepareAndStartImageDescription(
    bitmap: Bitmap
) {
  // Check feature availability, status will be one of the following:
  // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
  val featureStatus = imageDescriber.checkFeatureStatus().await()

  if (featureStatus == FeatureStatus.DOWNLOADABLE) {
      // Download feature if necessary.
      // If downloadFeature is not called, the first inference request
      // will also trigger the feature to be downloaded if it's not
      // already downloaded.
      imageDescriber.downloadFeature(object : DownloadCallback {
          override fun onDownloadStarted(bytesToDownload: Long) { }

          override fun onDownloadFailed(e: GenAiException) { }

          override fun onDownloadProgress(totalBytesDownloaded: Long) {}

          override fun onDownloadCompleted() {
              startImageDescriptionRequest(bitmap, imageDescriber)
          }
      })
  } else if (featureStatus == FeatureStatus.DOWNLOADING) {
      // Inference request will automatically run once feature is
      // downloaded.
      // If Gemini Nano is already downloaded on the device, the
      // feature-specific LoRA adapter model will be downloaded
      // very quickly. However, if Gemini Nano is not already
      // downloaded, the download process may take longer.
      startImageDescriptionRequest(bitmap, imageDescriber)
  } else if (featureStatus == FeatureStatus.AVAILABLE) {
      startImageDescriptionRequest(bitmap, imageDescriber)
  }
}

fun startImageDescriptionRequest(
    bitmap: Bitmap,
    imageDescriber: ImageDescriber
) {
    // Create task request
    val imageDescriptionRequest = ImageDescriptionRequest
        .builder(bitmap)
        .build()
}

  // Run inference with a streaming callback
  val imageDescriptionResultStreaming =
      imageDescriber.runInference(imageDescriptionRequest) { outputText ->
          // Append new output text to show in UI
          // This callback is called incrementally as the description
          // is generated
      }

  // You can also get a non-streaming response from the request
  // val imageDescription = imageDescriber.runInference(
  //        imageDescriptionRequest).await().description
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
imageDescriber.close()

Java

// Create an image describer
ImageDescriberOptions options = ImageDescriberOptions.builder(context).build();
ImageDescriber imageDescriber = ImageDescription.getClient(options);

void prepareAndStartImageDescription(
      Bitmap bitmap
) throws ExecutionException, InterruptedException {
  // Check feature availability, status will be one of the following:
  // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
  try {
      int featureStatus = imageDescriber.checkFeatureStatus().get();
      if (featureStatus == FeatureStatus.DOWNLOADABLE) {
          // Download feature if necessary.
          // If downloadFeature is not called, the first inference request
          // will also trigger the feature to be downloaded if it's not
          // already downloaded.
          imageDescriber.downloadFeature(new DownloadCallback() {
              @Override
              public void onDownloadCompleted() {
                  startImageDescriptionRequest(bitmap, imageDescriber);
              }

              @Override
              public void onDownloadFailed(GenAIException e) {}

              @Override
              public void onDownloadProgress(long totalBytesDownloaded) {}

              @Override
              public void onDownloadStarted(long bytesDownloaded) {}
          });
      } else if (featureStatus == FeatureStatus.DOWNLOADING) {
          // Inference request will automatically run once feature is
          // downloaded.
          // If Gemini Nano is already downloaded on the device, the
          // feature-specific LoRA adapter model will be downloaded
          // very quickly. However, if Gemini Nano is not already
          // downloaded, the download process may take longer.
          startImageDescriptionRequest(bitmap, imageDescriber);
      } else if (featureStatus == FeatureStatus.AVAILABLE) {
          startImageDescriptionRequest(bitmap, imageDescriber);
      }
  } catch (ExecutionException | InterruptedException e) {
      e.printStackTrace();
  }
}

void startImageDescriptionRequest(
     Bitmap bitmap,
     ImageDescriber imageDescriber
) {
  // Create task request
  ImageDescriptionRequest imageDescriptionRequest =
          ImageDescriptionRequest.builder(bitmap).build();

  // Start image description request with streaming response
  imageDescriber.runInference(imageDescriptionRequest, newText -> {
      // Append new output text to show in UI
      // This callback is called incrementally as the description
      // is generated
  });

  // You can also get a non-streaming response from the request
  // String imageDescription = imageDescriber.runInference(
  //        imageDescriptionRequest).get().getDescription();
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
imageDescriber.close();

Các tính năng được hỗ trợ và giới hạn

API Nội dung mô tả hình ảnh GenAI hỗ trợ tiếng Anh, và sẽ hỗ trợ thêm nhiều ngôn ngữ khác trong tương lai. API này trả về một nội dung mô tả ngắn về hình ảnh.

Khả năng hoạt động của cấu hình tính năng cụ thể (do ImageDescriberOptions chỉ định) có thể thay đổi tuỳ thuộc vào cấu hình của thiết bị cụ thể và các mô hình đã được tải xuống thiết bị.

Cách đáng tin cậy nhất để nhà phát triển đảm bảo rằng tính năng API dự kiến được hỗ trợ trên thiết bị có ImageDescriberOptions được yêu cầu là gọi phương thức checkFeatureStatus(). Phương thức này cung cấp trạng thái xác định về khả năng sử dụng tính năng trên thiết bị trong thời gian chạy.

Lưu ý: Sự khác biệt về phần cứng giữa các loại thiết bị có thể dẫn đến sự khác biệt về phiên bản mô hình cơ sở Gemini Nano và do đó, dẫn đến sự khác biệt về đầu ra API GenAI của Bộ công cụ học máy. Bộ chuyển đổi LoRA được áp dụng để giảm thiểu các điểm khác biệt.

Các vấn đề thường gặp khi thiết lập

Lưu ý: API này không được hỗ trợ trên các thiết bị có trình tải khởi động đã mở khoá.

Các API GenAI của Bộ công cụ học máy dựa vào ứng dụng Android AICore để truy cập vào Gemini Nano. Khi một thiết bị vừa được thiết lập (bao gồm cả việc đặt lại) hoặc ứng dụng AICore vừa được đặt lại (ví dụ: xoá dữ liệu, gỡ cài đặt rồi cài đặt lại), ứng dụng AICore có thể không có đủ thời gian để hoàn tất quá trình khởi chạy (bao gồm cả việc tải cấu hình mới nhất xuống từ máy chủ). Do đó, các API GenAI của Bộ công cụ học máy có thể không hoạt động như mong đợi. Dưới đây là các thông báo lỗi thiết lập thường gặp mà bạn có thể thấy và cách xử lý các lỗi đó:

Ví dụ về thông báo lỗi	Cách xử lý
AICore không thành công với loại lỗi 4-CONNECTION_ERROR và mã lỗi 601-BINDING_FAILURE: Không thể liên kết dịch vụ AICore.	Điều này có thể xảy ra khi bạn cài đặt ứng dụng bằng các API GenAI của Bộ công cụ học máy ngay sau khi thiết lập thiết bị hoặc khi AICore bị gỡ cài đặt sau khi ứng dụng của bạn được cài đặt. Bạn có thể khắc phục vấn đề này bằng cách cập nhật ứng dụng AICore rồi cài đặt lại ứng dụng.
AICore không thành công với loại lỗi 3-PREPARATION_ERROR và mã lỗi 606-FEATURE_NOT_FOUND: Tính năng ... không có sẵn.	Điều này có thể xảy ra khi AICore chưa tải xong các cấu hình mới nhất. Duy trì kết nối mạng và đợi từ vài phút đến vài giờ. Xin lưu ý rằng nếu trình tải khởi động của thiết bị đã được mở khoá, bạn cũng sẽ thấy lỗi này – API này không hỗ trợ các thiết bị có trình tải khởi động đã mở khoá.
AICore không thành công với loại lỗi 1-DOWNLOAD_ERROR và mã lỗi 0-UNKNOWN: Tính năng ... không thành công với trạng thái lỗi 0 và lỗi esz: UNAVAILABLE: Unable to resolve host ...	Duy trì kết nối mạng, đợi vài phút rồi thử lại.

Lưu ý: Mặc dù các nhà phát triển thường xuyên đặt lại, nhưng người dùng lại ít khi đặt lại. Ngoài ra, API checkFeatureStatus() có thể phát hiện tất cả các trường hợp thiết lập không thành công này. Hãy nhớ gọi checkFeatureStatus() trước khi hiển thị bất kỳ giao diện người dùng liên quan nào để người dùng ứng dụng của bạn không thấy những lỗi này trong mọi trường hợp.