此页面由 Cloud Translation API 翻译。

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 的输出非常相似。

配置项目

在 build.gradle 配置中添加 ML Kit Prompt API 作为依赖项：

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

实现生成模型

如需在项目中实现代码，请按以下步骤操作：

创建 generativeModel 对象：

Kotlin

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

Java

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

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

提供纯文本输入

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

或者，添加可选参数：

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

如需详细了解可选参数，请参阅可选配置。

提供多模态（图片和文本）输入

在 generateContentRequest() 函数中将图片和文本输入内容捆绑在一起，其中文本提示是与图片相关的问题或命令：

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

处理推理结果

运行推理并检索结果。您可以选择等待完整结果，也可以选择在生成响应时以流式传输方式获取响应，无论是纯文本提示还是多模态提示，都可以采用这种方式。

此示例使用非流式推理，即先从 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")

Java

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
}

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

如需详细了解流式推理和非流式推理，请参阅流式与非流式。

延迟时间优化

为了针对首次推理调用进行优化，您的应用可以选择性地调用 warmup()。这会将 Gemini Nano 加载到内存中并初始化运行时组件。

可选配置

在每个 GenerateContentRequest 中，您可以设置以下可选参数：

temperature：用于控制 token 选择的随机程度。
seed：启用生成稳定且确定性的结果。
topK：控制结果的随机性和多样性。
candidateCount：请求返回的唯一回答的数量。请注意，回答的确切数量可能与 candidateCount 不同，因为系统会自动移除重复的回答。
maxOutputTokens：用于定义回答中可生成的词元数量上限。

如需有关设置可选配置的更多指导，请参阅 GenerateContentRequest。

支持的功能和限制

输入内容必须少于 4,000 个 token（或大约 3,000 个英文单词）。如需了解详情，请参阅 countTokens 参考文档。
应避免使用需要长输出（超过 256 个令牌）的用例。
AICore 会针对每个应用强制执行推理配额。如需了解详情，请参阅每个应用的配额。
以下语言已针对 Prompt API 进行了验证：
- 英语
- 韩语

常见设置问题

ML Kit GenAI API 依赖于 Android AICore 应用来访问 Gemini Nano。当设备刚刚设置（包括重置）或 AICore 应用刚刚重置（例如清除数据、卸载然后重新安装）时，AICore 应用可能没有足够的时间来完成初始化（包括从服务器下载最新配置）。因此，ML Kit GenAI API 可能无法按预期运行。以下是您可能会看到的常见设置错误消息以及处理方法：

错误消息示例	如何处理
AICore 失败，出现错误类型 4-CONNECTION_ERROR 和错误代码 601-BINDING_FAILURE：AICore 服务绑定失败。	如果您在设备设置完毕后立即使用 ML Kit GenAI API 安装应用，或者在应用安装完毕后卸载 AICore，则可能会出现这种情况。更新 AICore 应用，然后重新安装您的应用，应该就能解决此问题。
AICore 失败，错误类型为 3-PREPARATION_ERROR，错误代码为 606-FEATURE_NOT_FOUND：功能 ... 不可用。	如果 AICore 尚未完成下载最新配置，可能会发生这种情况。当设备连接到互联网时，更新通常需要几分钟到几小时。重新启动设备可以加快更新速度。请注意，如果设备的引导加载程序处于解锁状态，您也会看到此错误消息，因为此 API 不支持引导加载程序处于解锁状态的设备。
AICore 失败，错误类型为 1-DOWNLOAD_ERROR，错误代码为 0-UNKNOWN：功能 ... 失败，失败状态为 0，错误 esz 为：UNAVAILABLE：无法解析主机 ...	保持网络连接，等待几分钟，然后重试。

Prompt API 使用入门 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

[可选] 使用 Gemma 3n 模型测试提示

配置项目

实现生成模型

Kotlin

Java

Kotlin

Java

提供纯文本输入

Kotlin

Java

Kotlin

Java

提供多模态（图片和文本）输入

Kotlin

Java

处理推理结果

Kotlin

Java

Kotlin

Java

延迟时间优化

可选配置

支持的功能和限制

常见设置问题

Prompt API 使用入门