API de resumo da GenAI

Essa API é oferecida na versão Beta e não está sujeita a SLAs nem a políticas de descontinuação. Mudanças podem ser feitas nessa API que quebram a compatibilidade com versões anteriores.

Com a API GenAI Summarization do Kit de ML, é possível gerar automaticamente resumos de artigos e conversas como uma lista de marcadores. Isso ajuda os usuários a entender grandes quantidades de texto.

A sumarização se beneficia da IA generativa no dispositivo porque aborda preocupações sobre privacidade de dados e custo-benefício. Os apps que resumem chats pessoais, e-mails, notas e lembretes geralmente processam informações sensíveis, o que torna o processamento no dispositivo importante para a privacidade do usuário. Além disso, as tarefas de sumarização, especialmente aquelas com contextos longos ou muitos itens, podem exigir uma capacidade de processamento significativa. O processamento desse conteúdo no dispositivo reduz a carga do servidor e diminui os custos de veiculação, mantendo os dados do usuário privados.

Principais recursos

A API GenAI Summarization abrange os seguintes recursos:

• Resumir texto, categorizado como artigo ou conversa.
• Gerar a sumarização em um, dois ou três marcadores.

Primeiros passos

**Observação** :essa API exige o nível 26 ou mais recente da API Android.

Adicione a API de sumarização do Kit de ML como uma dependência na configuração build.gradle.

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

Em seguida, implemente o código no seu projeto:

1. Crie um Summarizer objeto.
2. Faça o download do recurso, se disponível.
3. Crie uma solicitação de sumarização.
4. Execute a inferência e recupere o resultado.

Kotlin

val articleToSummarize = "Announcing a set of on-device GenAI APIs..."

// Define task with required input type, output type, and language
val summarizerOptions = SummarizerOptions.builder(context)
    .setInputType(InputType.ARTICLE)
    .setOutputType(OutputType.ONE_BULLET)
    .setLanguage(Language.ENGLISH)
    .build()
val summarizer = Summarization.getClient(summarizerOptions)

suspend fun prepareAndStartSummarization() {
    // Check feature availability. Status will be one of the following:
    // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
    val featureStatus = summarizer.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.
        summarizer.downloadFeature(object : DownloadCallback {
            override fun onDownloadStarted(bytesToDownload: Long) { }

            override fun onDownloadFailed(e: GenAiException) { }

            override fun onDownloadProgress(totalBytesDownloaded: Long) {}

            override fun onDownloadCompleted() {
                startSummarizationRequest(articleToSummarize, summarizer)
            }
        })
    } 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
        // quickly. However, if Gemini Nano is not already downloaded, the
        // download process may take longer.
        startSummarizationRequest(articleToSummarize, summarizer)
    } else if (featureStatus == FeatureStatus.AVAILABLE) {
        startSummarizationRequest(articleToSummarize, summarizer)
    }
}

fun startSummarizationRequest(text: String, summarizer: Summarizer) {
    // Create task request
    val summarizationRequest = SummarizationRequest.builder(text).build()

    // Start summarization request with streaming response
    summarizer.runInference(summarizationRequest) { newText ->
        // Show new text in UI
    }

    // You can also get a non-streaming response from the request
    // val summarizationResult = summarizer.runInference(
    //     summarizationRequest).get().summary
}

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

Java

String articleToSummarize = "Announcing: a set of on-device GenAI AI APIs.";

// Define task with required input type, output type, and language
SummarizerOptions summarizerOptions = 
    SummarizerOptions.builder(context)
        .setInputType(SummarizerOptions.InputType.ARTICLE)
        .setOutputType(SummarizerOptions.OutputType.ONE_BULLET)
        .setLanguage(SummarizerOptions.Language.ENGLISH)
        .build();
Summarizer summarizer = Summarization.getClient(summarizerOptions);

void prepareAndStartSummarization()
        throws ExecutionException, InterruptedException {
    // Check feature availability. Status will be one of the following:
    // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
    try {
        int featureStatus = summarizer.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.
            summarizer.downloadFeature(new DownloadCallback() {
                @Override
                public void onDownloadCompleted() {
                    startSummarizationRequest(articleToSummarize, summarizer);
                }

                @Override
                public void onDownloadFailed(GenAiException e) { /* handle error */ }

                @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 quickly. However, if Gemini Nano is not already
            // downloaded, the download process may take longer.
            startSummarizationRequest(articleToSummarize, summarizer);
        } else if (featureStatus == FeatureStatus.AVAILABLE) {
            startSummarizationRequest(articleToSummarize, summarizer);
        }
    } catch (ExecutionException | InterruptedException e) {
        e.printStackTrace();
    }
}

void startSummarizationRequest(String text, Summarizer summarizer) {
    // Create task request
    SummarizationRequest summarizationRequest =
        SummarizationRequest.builder(text).build();

    // Start summarization request with streaming response
    summarizer.runInference(summarizationRequest, newText -> {
        // Show new text in UI
    });

    // You can also get a non-streaming response from the request
    // ListenableFuture<SummarizationResult> summarizationResult
    //         = summarizer.runInference(summarizationRequest);
    // String summary = summarizationResult.get().getSummary();
}

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

Como o modelo processa diferentes tipos de entrada

Quando a entrada de texto é especificada como InputType.CONVERSATION, o modelo espera a entrada no seguinte formato:

<name>: <message>
<name2>: <message2>
<name>: <message3>
<name3>: <message4>

Isso permite que o modelo produza um resumo mais preciso, oferecendo uma melhor compreensão da conversa e das interações.

Recursos e limitações compatíveis

A entrada precisa ter menos de 4.000 tokens (ou aproximadamente 3.000 palavras em inglês). Se a entrada exceder 4.000 tokens, considere estas opções:

• Priorize a sumarização dos primeiros 4.000 tokens. Os testes indicam que isso geralmente gera bons resultados para entradas mais longas. Considere ativar o trunca mento automático chamando setLongInputAutoTruncationEnabled para que a entrada extra seja truncada automaticamente.
• Segmente a entrada em grupos de 4.000 tokens e resuma-os individualmente.
• Considere uma solução de nuvem mais adequada para a entrada maior.

Para InputType.ARTICLE, a entrada também precisa ter mais de 400 caracteres, com o modelo funcionando melhor quando o artigo tem pelo menos 300 palavras.

A API GenAI Summarization oferece suporte a inglês, japonês e coreano e é definida em SummarizerOptions.Language.

A disponibilidade da configuração de recurso específica (especificada por SummarizerOptions) pode variar dependendo da configuração do dispositivo e dos modelos que foram baixados para ele.

A maneira mais confiável para os desenvolvedores garantirem que o recurso de API pretendido seja compatível com um dispositivo com as SummarizerOptions solicitadas é chamar o checkFeatureStatus() método. Esse método fornece o status definitivo da disponibilidade de recursos no dispositivo durante a execução.

Observação: as variações de hardware em diferentes tipos de dispositivos podem levar a diferenças nas versões do modelo base do Gemini Nano e, consequentemente, nas saídas da API GenAI do Kit de ML. Os adaptadores LoRA são aplicados para atenuar as diferenças.

Problemas comuns de configuração

**Observação**: essa API está indisponível em dispositivos com um bootloader desbloqueado.

As APIs GenAI do Kit de ML dependem do app AICore do Android para acessar o Gemini Nano. Quando um dispositivo é configurado (incluindo a redefinição) ou o app AICore é redefinido (por exemplo, dados limpos, desinstalados e reinstalados), o app AICore pode não ter tempo suficiente para concluir a inicialização (incluindo o download das configurações mais recentes do servidor). Como resultado, as APIs GenAI do Kit de ML podem não funcionar como esperado. Confira as mensagens de erro de configuração comuns que podem aparecer e como processá-las:

Exemplo de mensagem de erro	Como processar
O AICore falhou com o tipo de erro 4-CONNECTION_ERROR e o código de erro 601-BINDING_FAILURE: falha ao vincular o serviço do AICore.	Isso pode acontecer quando você instala o app usando as APIs GenAI do Kit de ML imediatamente após a configuração do dispositivo ou quando o AICore é desinstalado após a instalação do app. Atualizar o app AICore e reinstalar o app deve corrigir o problema.
O AICore falhou com o tipo de erro 3-PREPARATION_ERROR e o código de erro 606-FEATURE_NOT_FOUND: o recurso ... não está disponível.	Isso pode acontecer quando o AICore não terminou de baixar as configurações mais recentes. Quando o dispositivo está conectado à Internet, geralmente leva alguns minutos a algumas horas para atualizar. Reiniciar o dispositivo pode acelerar a atualização. Observação: se o carregador de inicialização do dispositivo estiver desbloqueado, você também verá esse erro. Essa API não oferece suporte a dispositivos com carregadores de inicialização desbloqueados.
O AICore falhou com o tipo de erro 1-DOWNLOAD_ERROR e o código de erro 0-UNKNOWN: o recurso ... falhou com o status de falha 0 e o erro esz: UNAVAILABLE: não foi possível resolver o host ...	Mantenha a conexão de rede, aguarde alguns minutos e tente novamente.

Observação: embora várias redefinições sejam comuns para desenvolvedores, elas são muito menos frequentes para os usuários. Além disso, todos esses casos de falha de configuração podem ser detectados pelas APIs checkFeatureStatus() ou checkStatus(). Chame checkFeatureStatus() ou checkStatus() primeiro antes de mostrar qualquer interface relacionada para que os usuários do app não vejam esses erros em nenhum caso.

Exemplo de código

• Exemplos de GenAI do Kit de ML