Compartilhar via

Resumir, escrever e reescrever texto com as APIs de Assistência de Escrita

As APIs de Assistência de Escrita são APIs Web experimentais que lhe permitem resumir, escrever e reescrever texto através de um pequeno modelo de linguagem (SLM) incorporado no Microsoft Edge, a partir do código JavaScript do seu site ou da extensão do browser

Para obter informações introdutórias sobre a API do Summarizer, a API de Escritor e a API Rewriter, veja Writing Assistance APIs Explainer (Explicação das APIs de Assistência de Escrita).

Conteúdo detalhado:

Disponibilidade das APIs de Assistência de Escrita

As APIs Summarizer, Writer e Rewriter estão disponíveis como pré-visualização para programadores nos canais Microsoft Edge Canary ou Dev, a partir da versão 138.0.3309.2.

As APIs de Assistência de Escrita estão otimizadas para tarefas específicas para gerar, modificar e resumir conteúdos de texto. Para saber mais sobre uma alternativa para cenários de engenharia de pedidos mais personalizados que podem não ser servidos por estas APIs, veja Prompt a built-in language model with the Prompt API (Pedir um modelo de linguagem incorporado com a API Prompt).

Alternativas e benefícios das APIs de Assistência de Escrita

Para tirar partido das capacidades de IA em sites e extensões de browser, também pode utilizar os seguintes métodos:

As APIs de Assistência de Escrita utilizam um pequeno modelo de linguagem (SLM) que é executado no mesmo dispositivo onde são utilizadas as entradas e saídas do modelo (ou seja, localmente). Isto tem os seguintes benefícios em comparação com as soluções baseadas na cloud:

  • Custo reduzido: Não existem custos associados à utilização de um serviço de IA na cloud.

  • Independência da rede: Para além da transferência do modelo inicial, não existe latência de rede ao pedir o modelo e também pode ser utilizada quando o dispositivo está offline.

  • Privacidade melhorada: A entrada de dados para o modelo nunca sai do dispositivo e não é recolhida para preparar modelos de IA.

As APIs de Assistência de Escrita utilizam um modelo fornecido pelo Microsoft Edge e incorporado no browser, que inclui os benefícios adicionais em soluções locais personalizadas, como as baseadas em WebGPU, WebNN ou WebAssembly:

  • Custo único partilhado: O modelo fornecido pelo browser é transferido na primeira vez que a API é chamada e partilhada em todos os sites que são executados no browser, reduzindo os custos de rede para o utilizador e programador.

  • Utilização simplificada para programadores Web: O modelo incorporado pode ser executado através de APIs Web simples e não requer conhecimentos de IA/ML ou com arquiteturas de terceiros.

O modelo Phi-4-mini

A API De Pedido permite-lhe pedir à Phi-4-mini - um poderoso modelo de linguagem pequena que se destaca em tarefas baseadas em texto - incorporadas no Microsoft Edge. Para saber mais sobre a Phi-4-mini e as suas capacidades, consulte o modelo card em microsoft/Phi-4-mini-instruct.

Aviso de isenção

Tal como outros modelos de linguagem, a família de modelos Phi pode comportar-se potencialmente de formas injustas, pouco fiáveis ou ofensivas. Para saber mais sobre as considerações de IA do modelo, veja Considerações de IA Responsável.

Requisitos de hardware

A pré-visualização do programador da API Prompt destina-se a trabalhar em dispositivos com capacidades de hardware que produzem saídas de SLM com qualidade e latência previsíveis.

A API prompt está atualmente limitada a:

  • Sistema operativo: Windows 10 ou 11 e macOS 13.3 ou posterior.

  • Armazenamento: Pelo menos 20 GB disponíveis no volume que contém o seu perfil edge. Se o armazenamento disponível ficar abaixo dos 10 GB, o modelo será eliminado para garantir que outras funcionalidades do browser têm espaço suficiente para funcionar.

  • GPU: 5,5 GB de VRAM ou mais.

  • Rede: Plano de dados ilimitado ou ligação não atendida. O modelo não é transferido se estiver a utilizar uma ligação com tráfego limitado.

Para marcar se o seu dispositivo suportar a pré-visualização do programador das APIs de Assistência de Escrita, consulte Ativar as APIs de Assistência de Escrita abaixo e marcar a classe de desempenho do dispositivo.

Devido à natureza experimental das APIs de Assistência de Escrita, poderá observar problemas em configurações de hardware específicas. Se vir problemas em configurações de hardware específicas, envie feedback ao abrir um novo problema no repositório MSEdgeExplainers.

Disponibilidade do modelo

Será necessária uma transferência inicial do modelo da primeira vez que um site chamar uma API de IA incorporada. Pode monitorizar a transferência do modelo com a opção de monitor ao criar uma nova sessão de API Summarizer, Writer ou Rewriter. Para saber mais, veja Monitorizar o progresso da transferência do modelo, abaixo.

Ativar as APIs de Assistência de Escrita

Para utilizar qualquer uma das APIs de Assistência de Escrita no Microsoft Edge:

  1. Certifique-se de que está a utilizar a versão mais recente do Microsoft Edge Canary ou Dev (versão 138.0.3309.2 ou mais recente). Consulte Tornar-se um Microsoft Edge Insider.

  2. No Microsoft Edge Canary ou Dev, abra um novo separador ou janela e aceda a edge://flags/.

  3. Na caixa de pesquisa, na parte superior da página:

    • Para ativar a API do Summarizer, introduza API de Resumo para Phi mini.
    • Para ativar a API de Escritor, introduza API de Escritor para Phi mini.
    • Para ativar a API Rewriter, introduza Rewriter API for Phi mini.

    A página é filtrada para mostrar o sinalizador correspondente.

  4. Selecione Ativado junto ao sinalizador da API que pretende ativar:

    Página sinalizadores do browser

  5. Opcionalmente, para registar informações localmente que possam ser úteis para depurar problemas, ative também o sinalizador Ativar registos de depuração do modelo de IA no dispositivo .

  6. Reinicie o Microsoft Edge Canary ou o Dev.

  7. Para marcar se o seu dispositivo cumprir os requisitos de hardware para a pré-visualização do programador das APIs de Assistência para Escrita, abra um novo separador, aceda a edge://on-device-internalse marcar o valor da Classe de desempenho do dispositivo.

    Se a classe de desempenho do dispositivo for Alta ou superior, as APIs de Assistência de Escrita devem ser suportadas no seu dispositivo. Se continuar a deparar-se com problemas, submeta um novo problema.

Ver exemplos de trabalho

Para ver as APIs de Assistência de Escrita em ação e rever o código existente que utiliza estas APIs:

  1. Ative as APIs de Assistência de Escrita, conforme descrito acima.

  2. No browser Microsoft Edge Canary ou Dev, abra um separador ou janela e aceda ao playground de IA incorporado.

  3. No painel de navegação esquerdo:

    • Para a API summarizer, clique em Summarizer.
    • Para a API de Escritor, clique em Escritor.
    • Para a API de Rewriter, clique em Rewriter (Rewriter).

  4. Na faixa de informações na parte superior, marcar o status: inicialmente lê Transferência de modelos. Aguarde:

    Indicador de estado a mostrar o progresso da transferência do modelo

    Após a transferência do modelo, a faixa de informações lê API e modelo prontos, indicando que a API e o modelo podem ser utilizados:

    Indicador de estado a mostrar a API e o modelo prontos

    Se a transferência do modelo não iniciar, reinicie o Microsoft Edge e tente novamente.

    As APIs de Assistência de Escrita só são suportadas em dispositivos que cumpram determinados requisitos de hardware. Para obter mais informações, veja Requisitos de hardware acima.

  5. Para executar as APIs, altere opcionalmente as definições nas páginas de recreio, como o texto para resumir, escrever ou reescrever ou o comprimento e formato da saída esperada.

  6. Clique no botão Resumir, Escrever ou Reescrever , na parte inferior da página.

    O resultado é gerado na secção de resposta da página.

  7. Clique no botão Parar em qualquer altura para parar de gerar texto:

    O botão Parar

Para ver o código fonte do playground das APIs de Assistência de Escrita, consulte o repositório MicrosoftEdge/Demos no GitHub.

Utilizar as APIs de Assistência de Escrita

As três APIs de Assistência de Escrita ( Summarizer, Writer e Rewriter) são utilizadas de forma muito semelhante e estão documentadas em conjunto nas secções abaixo.

Verificar se as APIs estão ativadas

Antes de utilizar qualquer uma das APIs de Assistência de Escrita no código do seu site, marcar que a API está ativada ao testar a presença dos Summarizerobjetos , Writerou Rewriter :

if (!Summarizer) {
  // The Summarizer API is not available.
}

if (!Writer) {
  // The Writer API is not available.
}

if (!Rewriter) {
  // The Rewriter API is not available.
}

Verificar se o modelo pode ser utilizado

As APIs de Assistência de Escrita só podem ser utilizadas se o dispositivo suportar a execução do modelo e depois de o modelo de linguagem e o runtime do modelo terem sido transferidos pelo Microsoft Edge.

Para marcar se a API puder ser utilizada, utilize o método da availability() API. Por exemplo, para marcar a disponibilidade do modelo com a API de Escritor:

const availability = await Writer.availability();

if (availability == "unavailable") {
  // The model is not available.
}

if (availability == "downloadable" || availability == "downloading") {
  // The model can be used, but it needs to be downloaded first.
}

if (availability == "available") {
  // The model is available and can be used.
}

Para marcar a disponibilidade do modelo com as APIs Rewriter e Summarizer, altere Writer para Rewriter ou Summarizer no código acima.

Criar uma nova sessão

Criar uma sessão indica ao browser para carregar o modelo de idioma na memória, para que possa ser utilizado. Antes de poder utilizar as APIs de Assistência de Escrita para resumir, escrever ou reescrever texto, crie uma nova sessão com o create() método :

// Create a Summarizer session.
const summarizerSession = await Summarizer.create();

// Create a Writer session.
const writerSession = await Writer.create();

// Create a Rewriter session.
const rewriterSession = await Rewriter.create();

Para personalizar a sessão do modelo, pode transmitir opções para o create() método :

// Create a Writer session with options.
const session = await Writer.create(options);

Algumas opções são comuns às três APIs de Assistência de Escrita, enquanto outras opções são diferentes ou assumem valores diferentes. As opções disponíveis, por API, estão listadas abaixo:

Opção Summarizer API API de Escritor Rewriter API
monitor Monitorizar objeto Monitorizar objeto Monitorizar objeto
type Cadeia: "tl;dr", , "teaser""key-points","headline" Sem suporte Sem suporte
tone Sem suporte Cadeia: "formal", , "neutral""casual" Cadeia: "as-is", , "more-formal""more-casual"
length Cadeia: "short", , "medium""long" Cadeia: "short", , "medium""long" Cadeia: "as-is", , "shorter""longer"
format Cadeia: "plain-text", "markdown" Cadeia: "plain-text", "markdown" Cadeia: "as-is", , "plain-text""markdown"

Estas opções estão documentadas abaixo.

Monitorizar o progresso da transferência do modelo

Pode seguir o progresso da transferência do modelo com a opção monitor . Isto é útil quando o modelo ainda não foi totalmente transferido para o dispositivo onde será utilizado, para informar os utilizadores do seu site de que devem aguardar.

// Create a Summarizer session with the monitor option to monitor the model
// download.
const session = await Summarizer.create({
  monitor: m => {
    // Use the monitor object argument to add an listener for the 
    // downloadprogress event.
    m.addEventListener("downloadprogress", event => {
      // The event is an object with the loaded and total properties.
      if (event.loaded == event.total) {
        // The model is fully downloaded.
      } else {
        // The model is still downloading.
        const percentageComplete = (event.loaded / event.total) * 100;
      }
    });
  }
});
Definir o tipo de resumo

A type opção só é suportada pela API do Summarizer. Utilize a opção type para pedir ao modelo de linguagem para gerar um resumo de um dos seguintes tipos:

  • tl;dr
  • key-points
  • teaser
  • headline

Exemplo de criação de uma Summarizer sessão com a opção de resumo type de key-points:

const session = await Summarizer.create({
  type: "key-points"
});
Definir o tom do texto gerado

As APIs writer and Rewriter suportam a opção tone .

Utilize a opção tone para definir o tom do texto que será escrito ou reescrito.

A API de Escritor suporta os seguintes valores para a opção tone :

  • formal
  • neutral
  • casual

A API Rewriter suporta os seguintes valores para a opção tone :

  • as-is
  • more-formal
  • more-casual

Exemplo de criação de uma Rewriter sessão, pedir ao modelo para reescrever texto para utilizar um tone de more-formal:

const session = await Rewriter.create({
  tone: "more-formal"
});
Definir o comprimento do texto gerado

A length opção é suportada pelas APIs Summarizer, Writer e Rewriter e é utilizada para controlar o comprimento do texto gerado.

As APIs writer e Summarizer suportam os seguintes valores:

  • short
  • medium
  • long

A API de Rewriter suporta os seguintes valores:

  • as-is
  • shorter
  • longer

Exemplo de criação de uma Writer sessão, pedir ao modelo para gerar texto com length :long

const session = await Writer.create({
  length: "long"
});
Definir o formato do texto gerado

A format opção é suportada pelas APIs Summarizer, Writer e Rewriter e é utilizada para pedir ao modelo para gerar texto simples ou texto formatado como markdown.

As APIs writer e Summarizer suportam os seguintes valores:

  • plain-text
  • markdown

A API de Rewriter suporta os seguintes valores:

  • as-is
  • plain-text
  • markdown

Exemplo de criação de uma Rewriter sessão, pedir ao modelo para reescrever o texto fornecido para produzir o format como markdown:

const session = await Rewriter.create({
  format: "markdown"
});

Executar as APIs de Assistência de Escrita

Para gerar texto, com as APIs Summarizer, Writer ou Rewriter, depois de criar a sessão de modelo correspondente, utilize os seguintes métodos:

  • summarizerSession.summarize()
  • writerSession.write()
  • rewriterSession.rewrite()

Em alternativa, para apresentar o texto gerado à medida que é gerado, utilize as versões de transmissão em fluxo dos métodos acima:

  • summarizerSession.summarizeStreaming()
  • writerSession.writeStreaming()
  • rewriterSession.rewriteStreaming()

As duas versões destes métodos estão documentadas abaixo.

Aguarde até que o texto seja gerado

Para aguardar que o texto seja totalmente gerado antes de continuar a executar o código, utilize os summarize()métodos , write()e rewrite() assíncronos. Estes métodos devolvem uma promessa que é resolvida assim que a API correspondente terminar de gerar texto.

Exemplo de utilização do método assíncrono summarize() da API summarizer:

// Create a Summarizer session.
const summarizerSession = await Summarizer.create();

// Summarize text and wait for the summary to be done.
const summary = await summarizerSession.summarize(textToBeSummarized);

// Use the summary.
console.log(summary);
Apresentar tokens à medida que são gerados

Para apresentar os tokens à medida que estão a ser gerados, utilize as versões de transmissão em fluxo dos métodos acima. Os summarizeStreaming()métodos , writeStreaming()e rewriteStreaming() devolvem imediatamente um objeto de fluxo. Utilize o objeto de fluxo devolvido para apresentar os tokens de resposta à medida que estão a ser gerados.

Exemplo de utilização do método assíncrono summarizeStreaming() da API summarizer:

// Create a Summarizer session.
const session = await Summarizer.create();

// Ask the model to summarize text.
const stream = session.summarizeStreaming(textToBeSummarized);

// Use the stream object to display tokens that are generated by the model, as
// they are being generated.
for await (const chunk of stream) {
  console.log(chunk);
}

Parar de gerar texto

Para parar de gerar texto antes de a promessa ou fluxo devolvido pelos métodos acima terem sido resolvidos ou terminados, utilize um AbortController sinal:

Exemplo de uma Rewriter sessão com um AbortController sinal:

// Create a Rewriter session.
const session = await Rewriter.create();

// Create an AbortController object.
const abortController = new AbortController();

// Use the model session to generate some text and pass the AbortController
// object by using the signal option.
const stream = session.rewriteStreaming(textToBeRewritten, {
    signal: abortController.signal
});

// Later, perhaps when the user presses a "Stop" button, call the abort()
// method on the AbortController object to stop generating text.
abortController.abort();

Para uma Summarizer sessão ou Writer , no código acima:

  • Altere Rewriter.create() para Summarizer.create() ou Writer.create().
  • Altere a utilização session.rewriteStreaming()de .

Destruir uma sessão

Destrua a sessão para informar o browser de que já não precisa do modelo de linguagem, para que o modelo possa ser descarregado da memória.

Pode destruir uma sessão de duas formas diferentes:

  • Ao utilizar o destroy() método .
  • Ao utilizar um AbortController.
Destruir uma sessão com o método destroy()

Pode utilizar o destroy() método com uma Summarizersessão , Writerou Rewriter .

Exemplo de utilização de uma Summarizer sessão:

const session = await Summarizer.create();

// Later, destroy the session by using the destroy method.
session.destroy();
Destruir uma sessão com um AbortController

Em alternativa, pode criar um AbortController objeto, criar uma Summarizersessão , Writerou Rewriter e, em seguida, chamar abort().

Exemplo de utilização de uma Writer sessão:

// Create an AbortController object.
const controller = new AbortController();

// Create a Summarizer, Writer, or Rewriter session and pass the 
// AbortController object by using the signal option.
const session = await Writer.create({ signal: controller.signal });

// Later, perhaps when the user interacts with the UI, destroy the session by
// calling the abort() function of the AbortController object.
controller.abort();

Enviar comentários

Estamos muito interessados em saber mais sobre o leque de cenários para os quais pretende utilizar as APIs de Assistência de Escrita, quaisquer problemas com as APIs ou modelos de linguagem e se novas APIs, como APIs para verificação linguística, seriam úteis.

Para enviar feedback sobre os seus cenários e as tarefas que pretende alcançar, adicione um comentário ao problema de comentários das APIs de Assistência de Escrita.

Se reparar em problemas ao utilizar as APIs, comunique-o no repositório.

Também pode contribuir para o debate sobre a conceção das APIs de Assistência de Escrita no repositório do Grupo de Trabalho do W3C Web Machine Learning.

Confira também