La magie de Colab

Ce notebook présente les commandes magiques de Colab pour PaLM. Les commandes magiques permettent de développer, de tester, de comparer et d'évaluer facilement des requêtes à partir d'un notebook Colab.

Afficher sur ai.google.dev Essayer un notebook Colab Afficher le notebook sur GitHub

Configuration

Suivez les étapes ci-dessous pour installer et tester les fonctionnalités magiques.

Installer la magie PaLM

Pour utiliser les commandes magiques PaLM dans Colab ou un autre environnement IPython, vous devez d'abord télécharger et installer le package Python google-generativeai.

%pip install -q google-generativeai

Charger la magie PaLM

Ensuite, chargez la commande magique %%palm à l'aide de la commande magique %load_ext:

%load_ext google.generativeai.notebook

Tester l'installation

Pour vérifier que l'installation des commandes magiques est correcte, exécutez %%palm --help. Notez que vous aurez également besoin d'une clé API PaLM si vous n'en avez pas encore (voir l'étape suivante).

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

Obtenir une clé API PaLM

Pour utiliser l'API PaLM, vous devez créer une clé API. Vous n'avez besoin d'effectuer cette étape qu'une seule fois.

Définir la clé API dans le notebook

Définissez votre clé API en exécutant la cellule ci-dessous.

%env GOOGLE_API_KEY=YOUR PALM KEY

Commandes magiques PaLM: run, compile, compare et evaluate

Les commandes magiques PaLM proposent quatre commandes différentes:

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

Commande : palm run

La commande run envoie le contenu de la cellule au modèle.

L'exécution d'invites étant très courante, la commande magique PaLM utilise par défaut la commande run si aucune commande n'est fournie. Par exemple, les deux cellules suivantes sont identiques.

%%palm run
The opposite of hot is
%%palm
The opposite of hot is

Comprendre le résultat

La colonne Prompt affiche le texte envoyé au modèle, et la colonne text_result affiche le résultat. Les autres colonnes seront introduites au fur et à mesure que vous progresserez dans ce guide.

Modèles de requêtes

Les requêtes n'ont pas besoin d'être des chaînes fixes. Vous pouvez injecter des valeurs dans une requête à l'aide d'espaces réservés de modèle à l'aide de {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

Comprendre le résultat

La colonne Input Num suit l'index du mot d'entrée dans la ou les listes. Dans ces exemples, Input Num de 0 est 'hot', et 1 est 'cold'.

Spécifier plusieurs ensembles d'entrées

Vous pouvez également spécifier plusieurs ensembles d'entrées à la fois.

extreme_temperatures = {
    'word': ['hot', 'cold']
}
minor_temperatures = {
    'word': ['warm', 'chilly']
}
%%palm --inputs extreme_temperatures minor_temperatures
The opposite of {word} is

Lire des données à partir de Google Sheets

La magie PaLM peut également lire et écrire dans Google Sheets. Vous devez être connecté pour accéder aux données Sheets. Cette section porte sur la lecture de données à partir de Sheets. Une section ultérieure vous montre comment écrire les résultats dans une feuille de calcul Google Sheets.

Se connecter et autoriser l'accès à Sheets

<ph type="x-smartling-placeholder">

Mettre en forme une feuille de calcul pour l'utiliser avec la magie PaLM

Transmettez l'ID ou l'URL d'une feuille de calcul Google Sheets à l'indicateur --sheets_input_names pour la charger en tant que données de modèle.

Pour utiliser les données dans un modèle de requête, utilisez le format suivant dans votre feuille de calcul:

  1. Placez les noms des variables (de votre modèle de requête) sur la première ligne de la feuille.
  2. Indiquez les données à remplacer pour chaque variable dans les lignes ci-dessous.

Par exemple, si votre modèle de requête comporte deux variables à remplacer, name et temperament, vous devez écrire votre feuille de calcul comme suit:

nom caractère
Milo espiègle
Bigsly détendu
Subra timide
%%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.

Essayez par vous-même !

Pour tester cette fonction avec vos propres données, créez une feuille de calcul Sheets et transmettez l'ID à --sheets_input_names. En plus de l'ID et de l'URL, vous pouvez rechercher vos feuilles par titre, par exemple %%palm --sheets_input_names "Animal adjectives"

Combiner des entrées Sheets avec des entrées Python

Les entrées Sheets peuvent également être combinées avec --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.

Commande : palm eval

Utilisez %%palm eval pour comparer le résultat d'une requête avec des données de vérité terrain connues.

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:

Post-traitement des sorties du modèle

Pour effectuer des tests de vérité terrain, vous devrez peut-être post-traiter la sortie du modèle.

Les fonctions de post-traitement vous permettent de définir une fonction qui traite la sortie du modèle. Dans le cas de la commande eval, seule la colonne de résultat est utilisée dans le contrôle d'égalité final.

Utilisez le décorateur post_process_replace_fn pour définir une fonction permettant de post-traiter les résultats:

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

La fonction extract_and_normalize définie ci-dessus extrait la sortie du modèle et réduit les combinaisons linguistiques éventuelles, ne laissant que la première réponse. Reportez-vous à la section Post-traitement pour en savoir plus à ce sujet.

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

Commande : palm compile

Utilisez la commande %%palm compile pour convertir une invite avec des espaces réservés en fonction appelable depuis Python.

Tous les indicateurs et le post-traitement sont "compilés" dans la fonction et sera utilisée lorsqu'elle sera appelée.

Dans cet exemple, une fonction appelée translate_en_to_fr est créée à l'aide de la fonction de post-traitement extract_and_normalize utilisée avant.

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

Formats de sortie

Par défaut, une version "compilée" renvoie son résultat sous la forme d'un objet qui sera affiché sous la forme DataFrame Pandas. Toutefois, vous pouvez convertir l'objet de résultats en DataFrame ou en dictionnaire avec .as_dict() ou .as_dataframe(), respectivement.

Pour en savoir plus, consultez la section sur l'option --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

Commande : palm compare

%%palm compare exécute des requêtes compilées et génère une table contenant les résultats de la comparaison côte à côte, afin que vous puissiez inspecter les différences.

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

Fonctions de comparaison personnalisées

Par défaut, compare vérifie simplement l'égalité dans les résultats renvoyés. Toutefois, vous pouvez spécifier une ou plusieurs fonctions personnalisées avec l'option --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

Autres commandes

Aide

L'option --help affiche les commandes compatibles que vous pouvez transmettre directement à %%palm.

Ajoutez --help pour afficher la documentation détaillée de chaque commande. Par exemple,

%%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.

Modèles

Utilisez l'option --model pour spécifier la variante de modèle PaLM que vous souhaitez utiliser.

Consultez la méthode list_models() pour récupérer les modèles compatibles. La magie PaLM peut être utilisée avec n'importe quel modèle compatible avec la méthode generateText.

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

Paramètres du modèle

Vous pouvez également configurer des paramètres de modèle, tels que --candidate_count et --temperature.

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

Débogage: le modèle echo

Un modèle echo est également disponible pour renvoyer l'invite. Il n'effectue aucun appel d'API et ne consomme pas votre quota. C'est donc un moyen simple et rapide de tester les résultats ou le post-traitement.

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

Exporter la sortie dans Python

En plus d'afficher les résultats tabulaires, la commande magique PaLM peut enregistrer la sortie du modèle dans des variables Python, ce qui vous permet de les manipuler davantage ou d'exporter vos résultats.

Dans cet exemple, le résultat est enregistré dans une variable Python: fave_colors

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

Les variables de sortie sont des objets personnalisés qui s'affichent par défaut sous la forme de DataFrame Pandas. Ils peuvent être forcés explicitement dans un dictionnaire Python ou un DataFrame en appelant 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.']}

Écrire dans Google Sheets

Vous pouvez réenregistrer le résultat dans Google Sheets en utilisant --sheets_output_names. Vous devez être connecté et disposer des autorisations appropriées pour accéder aux feuilles de calcul privées.

Pour essayer, créez une feuille de calcul Sheets et nommez-la Translation results. Comme l'indicateur d'entrée, l'indicateur --sheets_output_names accepte également l'URL ou l'ID de la feuille à la place du nom textuel.

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

Les résultats sont enregistrés dans un nouvel onglet et contiennent les mêmes données que celles affichées ici dans Colab.

Exemple de feuille enregistrée

Générer plusieurs propositions

Pour générer plusieurs sorties pour une seule requête, vous pouvez transmettre --candidate_count au modèle. Ce paramètre est défini sur 1 par défaut, ce qui signifie que seul le premier résultat est généré.

Parfois, le modèle génère la même sortie pour tous les candidats. Ceux-ci peuvent être filtrés à l'aide de l'option --unique, qui supprime les résultats en double à partir du lot candidat (mais pas pour plusieurs requêtes).

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

La colonne Result Num distingue plusieurs candidats générés à partir de la même requête.

Sortie du modèle de post-traitement

La grande variété des résultats et structures possibles peut rendre difficile l'adaptation des résultats du modèle à votre domaine problématique. La magie PaLM fournit des options de post-traitement qui vous permettent de modifier ou de traiter la sortie du modèle à l'aide de code Python.

Les fonctions de post-traitement peuvent soit ajouter une colonne à la sortie, soit modifier la colonne text_result. La colonne text_result est la dernière colonne. Elle est utilisée par les commandes eval et compare pour déterminer le résultat final.

Voici quelques exemples de fonctions à utiliser en post-traitement. L'un ajoute une colonne, et l'autre met à jour la colonne de résultat à l'aide du décorateur 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

Pour utiliser ces fonctions, ajoutez-les à la commande %%palm à l'aide de l'opérateur pipe (|), comme ceci.

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

L'importance de l'ordre est ici. Lorsque word_count est appelé, la sortie du modèle d'origine est utilisée pour calculer le nombre de mots. Si vous les intervertissez, le nombre de mots correspond au nombre de mots contenus dans la première phrase extraite.

Documentation complémentaire