Mágica do Colab

Este notebook apresenta os comandos mágicos do Colab para o PaLM. Com esse recurso, é mais fácil desenvolver, testar, comparar e avaliar comandos em um bloco do Colab.

Ver em ai.google.dev Executar no Google Colab Consulte o código-fonte no GitHub

Configuração

Siga as etapas abaixo para instalar e testar os comandos mágicos.

Como instalar o comando mágico do PaLM

Para usar os comandos mágicos do PaLM no Colab ou em outro ambiente IPython, primeiro você precisa fazer o download e a instalação do pacote Python do google-generativeai.

%pip install -q google-generativeai

Como carregar o comando mágico do PaLM

Em seguida, carregue o comando mágico %%palm usando o comando %load_ext:

%load_ext google.generativeai.notebook

Teste a instalação

Para testar a instalação correta dos comandos mágicos, execute %%palm --help. Você também vai precisar de uma chave da API PaLM, se ainda não tiver uma (consulte a próxima etapa).

%%palm --help

usage: palm [-h] {run,compile,compare,eval} ...

A system for interacting with LLMs.

positional arguments:
  {run,compile,compare,eval}

options:
  -h, --help            show this help message and exit

Gerar uma chave da API PaLM

Para usar a API PaLM, você precisa criar uma chave de API. Você só precisa concluir esta etapa uma vez.

Defina a chave de API no notebook

Execute a célula abaixo para definir sua chave de API.

%env GOOGLE_API_KEY=YOUR PALM KEY

Comandos mágicos do PaLM: run, compile, compare e evaluate

Os comandos mágicos do PaLM oferecem quatro comandos diferentes:

  1. run
  2. compile
  3. compare
  4. evaluate

Comando: palm run

O comando run envia o conteúdo da célula ao modelo.

Como a execução de prompts é muito comum, os comandos mágicos do PaLM assumem run como padrão quando nenhum comando é fornecido. Por exemplo, as próximas duas células são idênticas.

%%palm run
The opposite of hot is

%%palm
The opposite of hot is

Como entender a saída

A coluna Prompt mostra o texto que foi enviado ao modelo, e a coluna text_result mostra o resultado. As outras colunas serão introduzidas à medida que você avança neste guia.

Modelos de comandos

Os comandos não precisam ser strings fixas. É possível injetar valores em um comando usando marcadores de posição de modelo com {curly braces}.

english_words = {
    # Each value here (hot, cold) will be substituted in for {word} in the prompt
    'word': ['hot', 'cold']
}

%%palm --inputs english_words
The opposite of {word} is

Como entender a saída

A coluna Input Num rastreia o índice da palavra de entrada na(s) lista(s). Nesses exemplos, Input Num de 0 é 'hot' e 1 é 'cold'.

Especificar vários conjuntos de entradas

Também é possível especificar vários conjuntos de entradas de uma só vez.

extreme_temperatures = {
    'word': ['hot', 'cold']
}
minor_temperatures = {
    'word': ['warm', 'chilly']
}

%%palm --inputs extreme_temperatures minor_temperatures
The opposite of {word} is

Como ler dados do Planilhas Google

O comando mágico do PaLM também pode ler e gravar nas Planilhas Google. Você precisa fazer login para acessar os dados do app Planilhas. Esta seção se concentra na leitura de dados do Planilhas. Uma seção posterior mostra como gravar saídas em um arquivo do Planilhas Google.

Faça login e autorize o acesso ao Planilhas

Como formatar uma planilha para uso com o comando mágico do PaLM

Transmita o ID ou URL de uma Planilha Google à sinalização --sheets_input_names para carregá-la como dados de modelo.

Use o seguinte formato na sua planilha para usar os dados em um modelo de comando:

  1. Coloque os nomes das variáveis do seu modelo de comando na primeira linha da planilha.
  2. Insira os dados a serem substituídos para cada variável nas linhas abaixo.

Por exemplo, se o modelo de comando tiver duas variáveis para substituir, name e temperament, você escreveria a planilha assim:

name temperamento
Milo atrevido
Bigsly relaxado
Subra tímido 
%%palm --sheets_input_names https://docs.google.com/spreadsheets/d/1UHfpkmBqIX5RjeJcGXOevIEhMmEoKlf5f9teqwQyHqc/edit
Create a single sentence description of a monkey's personality. The monkey's name is {name} and it has a {temperament} temperament.

Experimente!

Para testar isso usando seus próprios dados, crie uma planilha e transmita o ID para --sheets_input_names. Além de ID e URL, você também pode pesquisar suas planilhas por título, por exemplo, %%palm --sheets_input_names "Animal adjectives".

Combinar entradas do Planilhas com entradas do Python

As entradas das Planilhas também podem ser combinadas com --inputs:

new_monkeys = {
    'name': ['Hackerella'],
    'temperament': ['clever'],
}

%%palm --inputs new_monkeys --sheets_input_names 1UHfpkmBqIX5RjeJcGXOevIEhMmEoKlf5f9teqwQyHqc 1UHfpkmBqIX5RjeJcGXOevIEhMmEoKlf5f9teqwQyHqc
Create a single sentence description of a monkey's personality. The monkey's name is {name} and it has a {temperament} temperament.

Comando: palm eval

Use %%palm eval para comparar a saída de um comando com dados de informações empíricas conhecidos.

test_data = {
    "word": ["dog", "cat", "house"]
}
ground_truth = ["chien", "chat", "maison"]

%%palm eval --inputs test_data --ground_truth ground_truth
English: Hello
French: Bonjour
English: {word}
French:

Saídas do modelo pós-processamento

Para realizar testes de informações empíricas, talvez seja necessário pós-processar a saída do modelo.

As funções de pós-processamento permitem definir uma função que processa a saída do modelo. No caso do comando eval, apenas a coluna do resultado é usada na verificação de igualdade final.

Use o decorador post_process_replace_fn para definir uma função para pós-processar os resultados:

from google.generativeai.notebook import magics

# Define a function to extract only the first response.
@magics.post_process_replace_fn
def extract_and_normalize(input):
  first_line, *unused = input.split('English:')
  return first_line.strip().lower()

A função extract_and_normalize definida acima vai usar a saída do modelo e cortar todos os pares de idiomas repetidos, deixando apenas a primeira resposta. Confira a seção de pós-processamento para saber mais sobre o pós-processamento.

%%palm eval --inputs test_data --ground_truth ground_truth | extract_and_normalize
English: Hello
French: Bonjour
English: {word}
French:

Comando: palm compile

Use o comando %%palm compile para converter um prompt com marcadores de posição em uma função chamável no Python.

Todas as flags e o pós-processamento são "compilados" na função e serão usados quando invocados.

Neste exemplo, uma função chamada translate_en_to_fr é criada, usando a função de pós-processamento extract_and_normalize de antes.

%%palm compile translate_en_to_fr | extract_and_normalize
English: Hello
French: Bonjour
English: {word}
French:

'Saved function to Python variable: translate_en_to_fr'

en_words = ['cat', 'dog']
translate_en_to_fr({'word': en_words})

Formatos de saída

Por padrão, uma função "compilada" retorna a saída como um objeto que será exibido como DataFrame do Pandas. No entanto, você pode converter o objeto de resultados em um DataFrame ou dicionário com .as_dict() ou .as_dataframe(), respectivamente.

Para mais informações, consulte a sinalização --outputs.

results = translate_en_to_fr({'word': en_words}).as_dict()

fr_words = results['text_result']

for en, fr in zip(en_words, fr_words):
  print(f'{fr} is French for {en}')

chat is French for cat
chien is French for dog

Comando: palm compare

%%palm compare executa solicitações compiladas e produz uma tabela com os resultados de comparação lado a lado para que você possa inspecionar as diferenças.

%%palm compile few_shot_prompt
English: Hello
French: Bonjour
English: {word}
French:

'Saved function to Python variable: few_shot_prompt'

%%palm compile zero_shot_prompt
{word} translated to French is:

'Saved function to Python variable: zero_shot_prompt'

words = {
    "word": ["dog", "cat", "house"]
}

%%palm compare few_shot_prompt zero_shot_prompt --inputs words

Funções de comparação personalizadas

Por padrão, compare apenas verifica a igualdade nos resultados retornados. No entanto, é possível especificar uma ou mais funções personalizadas com a sinalização --compare_fn:

def average_word_length(lhs, rhs):
  """Count the average number of words used across prompts."""
  return (len(lhs.split(' ')) + len(rhs.split(' '))) / 2

def shortest_answer(lhs, rhs):
  """Label the prompt that generated the shortest output."""
  if len(lhs) < len(rhs):
    return 'first'
  elif len(lhs) > len(rhs):
    return 'second'
  else:
    return 'same'

%%palm compare few_shot_prompt zero_shot_prompt --inputs words --compare_fn average_word_length shortest_answer

Outros comandos

Ajuda

A sinalização --help exibe os comandos compatíveis que podem ser transmitidos diretamente para %%palm.

Anexe --help para ver a documentação detalhada de cada comando. Por exemplo:

%%palm run --help

usage: palm run [-h] [--model_type {echo,text}] [--temperature TEMPERATURE]
                [--model MODEL] [--candidate_count CANDIDATE_COUNT] [--unique]
                [--inputs INPUTS [INPUTS ...]]
                [--sheets_input_names SHEETS_INPUT_NAMES [SHEETS_INPUT_NAMES ...]]
                [--outputs OUTPUTS [OUTPUTS ...]]
                [--sheets_output_names SHEETS_OUTPUT_NAMES [SHEETS_OUTPUT_NAMES ...]]

options:
  -h, --help            show this help message and exit
  --model_type {echo,text}, -mt {echo,text}
                        The type of model to use.
  --temperature TEMPERATURE, -t TEMPERATURE
                        Controls the randomness of the output. Must be
                        positive. Typical values are in the range: [0.0, 1.0].
                        Higher values produce a more random and varied
                        response. A temperature of zero will be deterministic.
  --model MODEL, -m MODEL
                        The name of the model to use. If not provided, a
                        default model will be used.
  --candidate_count CANDIDATE_COUNT, -cc CANDIDATE_COUNT
                        The number of candidates to produce.
  --unique              Whether to dedupe candidates returned by the model.
  --inputs INPUTS [INPUTS ...], -i INPUTS [INPUTS ...]
                        Optional names of Python variables containing inputs
                        to use to instantiate a prompt. The variable must be
                        either: a dictionary {'key1': ['val1', 'val2'] ...},
                        or an instance of LLMFnInputsSource such as
                        SheetsInput.
  --sheets_input_names SHEETS_INPUT_NAMES [SHEETS_INPUT_NAMES ...], -si SHEETS_INPUT_NAMES [SHEETS_INPUT_NAMES ...]
                        Optional names of Google Sheets to read inputs from.
                        This is equivalent to using --inputs with the names of
                        variables that are instances of SheetsInputs, just
                        more convenient to use.
  --outputs OUTPUTS [OUTPUTS ...], -o OUTPUTS [OUTPUTS ...]
                        Optional names of Python variables to output to. If
                        the Python variable has not already been defined, it
                        will be created. If the variable is defined and is an
                        instance of LLMFnOutputsSink, the outputs will be
                        written through the sink's write_outputs() method.
  --sheets_output_names SHEETS_OUTPUT_NAMES [SHEETS_OUTPUT_NAMES ...], -so SHEETS_OUTPUT_NAMES [SHEETS_OUTPUT_NAMES ...]
                        Optional names of Google Sheets to write inputs to.
                        This is equivalent to using --outputs with the names
                        of variables that are instances of SheetsOutputs, just
                        more convenient to use.

Modelos

Use a sinalização --model para especificar a variante do modelo PaLM que você quer usar.

Consulte o método list_models() para recuperar os modelos compatíveis. O comando mágico do PaLM pode ser usado com qualquer modelo que ofereça suporte ao método generateText.

%%palm run --model models/text-bison-001
My favourite color is

Parâmetros do modelo

Também é possível configurar parâmetros do modelo, como --candidate_count e --temperature.

%%palm run --model models/text-bison-001 --temperature 0.5
My favourite color is

Depuração: o modelo echo

Também há um modelo echo disponível que vai transmitir o comando de volta para você. Ele não faz chamadas de API nem consome sua cota. Portanto, essa pode ser uma maneira rápida e simples de testar a saída ou o pós-processamento.

%%palm --model_type echo
A duck's quack does not echo.

Exportar saída para Python

Além de exibir a saída tabular, o comando mágico do PaLM pode salvar a saída do modelo em variáveis do Python, permitindo que você os manipule ainda mais ou exporte seus resultados.

Neste exemplo, a saída é salva em uma variável Python: fave_colors

%%palm --outputs fave_colors
The best colors to wear in spring-time are

As variáveis de saída são objetos personalizados exibidos como DataFrames do Pandas por padrão. Eles podem ser convertidos em um dicionário ou DataFrame Python explicitamente chamando as_dict() ou as_pandas_dataframe().

from pprint import pprint

pprint(fave_colors.as_dict())

{'Input Num': [0],
 'Prompt': ['The best colors to wear in spring-time are'],
 'Prompt Num': [0],
 'Result Num': [0],
 'text_result': ['* Pastels: These soft, muted colors are perfect for the '
                 'springtime, as they are fresh and airy. Some popular pastel '
                 'colors include baby blue, mint green, and pale pink.\n'
                 '* Brights: If you want to make a statement, bright colors '
                 'are a great option for spring. Some popular bright colors '
                 'include fuchsia, cobalt blue, and yellow.\n'
                 '* Neutrals: Neutral colors are always a good choice, as they '
                 'can be easily dressed up or down. Some popular neutrals '
                 'include beige, gray, and white.\n'
                 '\n'
                 'When choosing colors to wear in the spring, it is important '
                 'to consider the occasion and your personal style. For '
                 'example, if you are attending a formal event, you may want '
                 'to choose a more muted color palette, such as pastels or '
                 'neutrals. If you are going for a more casual look, you may '
                 'want to choose brighter colors, such as brights or pastels.']}

Escrever no Planilhas Google

Você pode salvar o resultado no Planilhas Google usando --sheets_output_names. Você precisa fazer login e ter as permissões apropriadas para acessar as Planilhas Google particulares.

Para testar, crie uma nova planilha com o nome Translation results. Assim como a flag de entrada, a flag --sheets_output_names também aceita o URL ou ID da planilha no lugar do nome textual.

%%palm --inputs english_words --sheets_output_names "Translation results"
English: Hello
French: Bonjour
English: {word}
French:

Os resultados são salvos em uma nova guia e contêm os mesmos dados que você vê aqui no Colab.

Exemplo de uma página salva

Como gerar vários candidatos

Para gerar mais de uma saída para um único comando, transmita --candidate_count ao modelo. Por padrão, esse valor é definido como 1, o que gera apenas o resultado principal.

Às vezes, o modelo gera a mesma saída entre os candidatos. Eles podem ser filtrados com a flag --unique, que remove a duplicação dos resultados do lote de candidatos, mas não em várias solicitações.

%%palm run --temperature 1.0 --candidate_count 8 --unique
In a single word, my favourite color is

A coluna Result Num distingue vários candidatos gerados a partir do mesmo comando.

Saída do modelo de pós-processamento

A ampla gama de saídas e estruturas possíveis pode dificultar a adaptação da saída do modelo ao domínio do problema. O comando mágico do PaLM oferece opções de pós-processamento que permitem modificar ou processar a saída do modelo usando código Python.

As funções de pós-processamento podem adicionar uma nova coluna à saída ou modificar a coluna text_result. A coluna text_result é a última e é usada pelos comandos eval e compare para determinar a saída final.

Estes são alguns exemplos de funções que podem ser usadas no pós-processamento. Uma adiciona uma nova coluna e a outra atualiza a coluna de resultados usando o decorador post_process_replace_fn.

import re
from google.generativeai.notebook import magics

# Add a new column.
def word_count(result):
  return len(result.split(' '))

# Modify the text_result column
@magics.post_process_replace_fn
def extract_first_sentence(result):
  """Extracts the first word from the raw result."""
  first, *_ = re.split(r'\.\s*', result)
  return first

Para usar essas funções, anexe-as ao comando %%palm usando o operador de barra vertical (|) dessa forma.

%%palm run | word_count | extract_first_sentence
The happiest thing I can imagine is

A ordem é importante aqui. Quando word_count é invocado, a saída do modelo original é usada para calcular o número de palavras. Se você os inverter, a contagem de palavras será o número de palavras na primeira frase extraída.

Leia mais