Làm quen với Prompt API

Trang này mô tả cách thực hiện những việc sau:

  • Định cấu hình dự án để sử dụng Prompt API
  • Chỉ nhập văn bản và nhận câu trả lời
  • Cung cấp một hình ảnh đầu vào cùng với văn bản đầu vào liên quan và nhận được câu trả lời

Để biết thêm thông tin chi tiết về Prompt API, hãy xem tài liệu tham khảo cho Kotlin (com.google.mlkit.genai.prompt) và Java (com.google.mlkit.genai.prompt.java, com.google.mlkit.genai.prompt).

[Không bắt buộc] Thử nghiệm câu lệnh với mô hình Gemma 3n

Trước khi triển khai, hãy cân nhắc kiểm thử câu lệnh của bạn trong AI Studio bằng mô hình Gemma 3n E4B. Bạn có thể kỳ vọng kết quả đầu ra của Gemma 3n sẽ rất giống với kết quả đầu ra của nano-v3.

Định cấu hình dự án

Thêm ML Kit Prompt API làm phần phụ thuộc trong cấu hình build.gradle:

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

Triển khai mô hình tạo sinh

Để triển khai mã trong dự án của bạn, hãy làm theo các bước sau:

  • Tạo một đối tượng generativeModel:

    Kotlin

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

    Java

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

  • Kiểm tra xem Gemini Nano có phải là AVAILABLE, DOWNLOADABLE hay UNAVAILABLE hay không. Sau đó, hãy tải tính năng xuống nếu có thể tải xuống:

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

    Java

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

Chỉ cung cấp dữ liệu đầu vào là văn bản

Kotlin

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

Java

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

Ngoài ra, hãy thêm các tham số không bắt buộc:

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

Java

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

Để biết thêm thông tin về các tham số không bắt buộc, hãy xem phần Cấu hình không bắt buộc.

Cung cấp dữ liệu đầu vào đa phương thức (hình ảnh và văn bản)

Gộp một hình ảnh và một dữ liệu đầu vào văn bản với nhau trong hàm generateContentRequest(), trong đó câu lệnh văn bản là một câu hỏi hoặc lệnh liên quan đến hình ảnh:

Kotlin

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

Java

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

Xử lý kết quả suy luận

  • Chạy quy trình suy luận và truy xuất kết quả. Bạn có thể chọn đợi kết quả đầy đủ hoặc truyền trực tuyến phản hồi khi kết quả được tạo cho cả câu lệnh chỉ có văn bản và câu lệnh đa phương thức.

    • Thao tác này sử dụng suy luận không truyền trực tuyến, tức là truy xuất toàn bộ kết quả từ mô hình AI trước khi trả về kết quả:

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

    Java

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

    • Các đoạn mã sau đây là ví dụ về cách sử dụng suy luận truyền trực tuyến, giúp truy xuất kết quả theo từng phần khi kết quả được tạo:

    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
}

    Java

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

Để biết thêm thông tin về suy luận truyền trực tuyến và không truyền trực tuyến, hãy xem phần Truyền trực tuyến so với không truyền trực tuyến.

Tối ưu hoá độ trễ

Để tối ưu hoá cho lệnh gọi suy luận đầu tiên, ứng dụng của bạn có thể gọi warmup() (không bắt buộc). Thao tác này tải Gemini Nano vào bộ nhớ và khởi động các thành phần thời gian chạy.

Cấu hình không bắt buộc

Trong mỗi GenerateContentRequest, bạn có thể đặt các tham số không bắt buộc sau:

  • temperature : Kiểm soát mức độ ngẫu nhiên trong việc chọn mã thông báo.
  • seed : Cho phép tạo ra kết quả ổn định và có thể xác định.
  • topK : Kiểm soát tính ngẫu nhiên và đa dạng trong kết quả.
  • candidateCount : Yêu cầu số lượng phản hồi riêng biệt được trả về. Xin lưu ý rằng số lượng phản hồi chính xác có thể không giống với candidateCount vì các phản hồi trùng lặp sẽ tự động bị xoá.
  • maxOutputTokens : Xác định số lượng mã thông báo tối đa có thể được tạo trong phản hồi.

Để biết thêm hướng dẫn về cách thiết lập cấu hình không bắt buộc, hãy xem phần GenerateContentRequest.

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

  • Câu lệnh phải có dưới 4.000 mã thông báo (hoặc khoảng 3.000 từ tiếng Anh). Để biết thêm thông tin, hãy xem tài liệu tham khảo về countTokens.
  • Bạn nên tránh các trường hợp sử dụng cần đầu ra dài (hơn 256 mã thông báo).
  • AICore áp dụng một hạn mức suy luận cho mỗi ứng dụng. Để biết thêm thông tin, hãy xem phần Hạn mức cho mỗi ứng dụng.
  • Prompt API đã được xác thực cho các ngôn ngữ sau:
    • Tiếng Anh
    • Tiếng Hàn

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

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 thiết bị vừa được thiết lập (bao gồm cả thiết lập lại) hoặc ứng dụng AICore vừa được thiết lập 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 động (bao gồm cả việc tải các cấu hình mới nhất xuống từ máy chủ). Do đó, các API AI tạo sinh của Bộ công cụ học máy có thể không hoạt động như mong đợi. Sau đây là các thông báo lỗi thiết lập thường gặp mà bạn có thể gặp phải 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 hoạt động được do lỗi loại 4-CONNECTION_ERROR và mã lỗi 601-BINDING_FAILURE: Không liên kết được 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. Việc cập nhật ứng dụng AICore rồi cài đặt lại ứng dụng của bạn sẽ khắc phục được vấn đề này.
AICore không hoạt động được do lỗi loại 3 – PREPARATION_ERROR và mã lỗi 606 – FEATURE_NOT_FOUND: Không có tính năng .... Đ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. Khi thiết bị kết nối với Internet, quá trình cập nhật thường mất từ vài phút đến vài giờ. Việc khởi động lại thiết bị có thể giúp quá trình cập nhật diễn ra nhanh hơn.

Xin lưu ý rằng nếu trình tải khởi động của thiết bị bị 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 gặp lỗi loại 1 – DOWNLOAD_ERROR và mã lỗi 0 – UNKNOWN: Tính năng ... gặp lỗi với trạng thái lỗi 0 và esz lỗi: UNAVAILABLE: Không thể phân giải máy chủ ... Giữ kết nối mạng, chờ vài phút rồi thử lại.