Tools · oefening
Zoek een functie op naam op
Een toolaanroep noemt een functie met een string: "read_note". Je programma moet van die string naar de functie read_note komen en hem aanroepen. Deze les doet dat met een dictionary, en onderweg lees je de drie meegeleverde toolfuncties.
Een functie is een waarde
In Python verwijst de naam van een functie naar een waarde, net zoals count = 3 ervoor zorgt dat count naar 3 verwijst. Zonder haakjes is read_note de functie zelf. Met haakjes roept read_note(...) hem aan en krijg je zijn resultaat. Omdat de functie een waarde is, kun je hem in een dictionary opslaan en later via de dictionary aanroepen:
def shout(arguments):
return arguments["text"].upper() + "!"
def whisper(arguments):
return arguments["text"].lower() + "..."
actions = {"shout": shout, "whisper": whisper}
name = "whisper"
function = actions[name]
print(function({"text": "Hello"}))
print(actions["shout"]({"text": "Hello"}))
actions[name] zoekt de functie op, en de haakjes erachter roepen de functie aan met één argument. De laatste regel doet beide in één expressie. Zo kan een programma een functie aanroepen waarvan het de naam pas tijdens het draaien te weten komt, bijvoorbeeld uit het antwoord van een model.
Laat de haakjes weg als je de dictionary bouwt. {"shout": shout()} zou shout meteen aanroepen, zonder argument, en mislukken met TypeError. Zelfs bij een functie die geen argumenten nodig heeft, zou de dictionary dan zijn resultaat bevatten, een string, en zou er niets meer zijn om aan te roepen.
De toolfuncties
Lees nu de drie afgeronde functies bovenaan tools.py.
def note_ids():
ids = []
for path in NOTES_DIR.glob("*.md"):
ids.append(path.stem)
ids.sort()
return ids
NOTES_DIR is Path("notes"), de notitiemap als pathlib-pad. NOTES_DIR.glob("*.md") geeft een pad voor elk bestand daarin waarvan de naam eindigt op .md, en path.stem is de bestandsnaam zonder map en extensie: 03-lists voor notes/03-lists.md. De ids worden gesorteerd omdat glob geen volgorde belooft. note_ids is een hulpfunctie, geen tool: het model vraagt er nooit bij naam om.
def list_notes(arguments):
return "\n".join(note_ids())
list_notes is de eerste tool. Hij geeft de ids terug als één string, één per regel, omdat het resultaat van een tool als tekst teruggaat naar het model. Hij neemt een argument aan dat hij nooit gebruikt, arguments, omdat elke toolfunctie in dit hoofdstuk dezelfde vorm heeft: één argument, de gedecodeerde dictionary met argumenten, en een string als resultaat. Daardoor kan één regel code elk van die functies aanroepen.
def read_note(arguments):
note_id = arguments.get("note_id")
if not isinstance(note_id, str):
raise ValueError("read_note needs a note_id string, such as 03-lists.")
if note_id not in note_ids():
raise ValueError(f"There is no note called {note_id}. Call list_notes to see the ids.")
with open(NOTES_DIR / f"{note_id}.md", "r", encoding="utf-8") as handle:
return handle.read()
read_note leest note_id met .get, zodat een ontbrekende sleutel None geeft in plaats van KeyError, en controleert of het een string is. Daarna controleert hij het id tegen de echte lijst met notities voordat hij iets opent. NOTES_DIR / f"{note_id}.md" voegt de map en de bestandsnaam samen tot één pad, notes/03-lists.md, en het bestand wordt gelezen als UTF-8, zoals in Python in de praktijk.
Die tweede controle is belangrijk vanwege wie het id schreef. Dat deed het model, niet jij, en een model kan elke tekst schrijven. Zonder de controle zou read_note NOTES_DIR / f"{note_id}.md" openen voor alles wat hij kreeg, en "../MODEL_SERVICE" zou notes/../MODEL_SERVICE.md worden, en dat is MODEL_SERVICE.md in de map van je werkruimte, buiten de notitiemap. De .md aan het eind beperkt welke bestanden een model zo kan bereiken, maar niet welke mappen: met meer ../ klim je hoger. Door te vergelijken met note_ids() kan read_note alleen de notities zelf openen. In het algemeen mag een tool nooit een bestandspad, een opdracht of een query bouwen uit modeltekst die niet is gecontroleerd tegen wat is toegestaan.
Beide controles werpen ValueError op met een bericht dat geschreven is om door het model gelezen te worden. In les 6 gaan die berichten terug naar het model in plaats van je programma te stoppen.
Vul TOOLS in en bouw run_tool
Vervang in tools.py de regel TOOLS = {} door een dictionary die de naam van elke tool koppelt aan zijn functie:
TOOLS = {"list_notes": list_notes, "read_note": read_note}
De sleutels zijn de namen uit je beschrijvingen, omdat het model die namen schrijft. TOOLS staat in het bestand na de drie functies, dus de namen bestaan al als Python de dictionary bouwt.
Bouw daarna run_tool(call, tools). Die krijgt één aanroepdictionary uit read_tool_calls en een dictionary zoals TOOLS:
Decodeer de argumenten met
json.loads(call["arguments"]).Zoek de functie op met
tools[call["name"]].Roep die één keer aan met de gedecodeerde dictionary en geef terug wat ze teruggeeft.
Gebruik de parameter tools, niet de globale TOOLS. Het project geeft TOOLS mee, maar de controles geven eigen dictionaries mee, en hoofdstuk 7 geeft verschillende tools mee voor verschillende taken.
Deze run_tool vertrouwt het model volledig. Een onbekende naam werpt KeyError op, argumenten die geen JSON zijn geven een fout uit json.loads, en een ontbrekende notitie werpt de ValueError uit read_note op. Les 6 lost dat allemaal op.
Voer het uit
Voer python tools.py uit. De demonstratie geeft de twee aanroepen uit les 3 aan je run_tool: eerst de aanroep van list_notes, dan die van read_note. Dat resultaat is lang, dus ze drukt alleen de lengte en de eerste zeven tekens af:
Running the calls:
01-variables
02-strings
03-lists
04-loops
05-functions
06-dictionaries
07-errors
08-files
09-modules
10-classes
11-comprehensions
12-testing
read_note returned 1226 characters. They start with: # Lists
Sending the result back:
Run stopped at the next function to build: assistant_turn is built in Lesson 5.
Het model vroeg erom en je programma voerde de functie uit. Het model heeft nog geen van beide resultaten gezien. Dat komt in de volgende les.
Wat gaat er mis met TOOLS = {"list_notes": list_notes(), "read_note": read_note}?
Waarom controleert read_note note_id tegen note_ids() voordat hij een bestand opent?
Waarom neemt list_notes een parameter arguments aan die hij nooit gebruikt?
Opdracht
In tools.py:
Vervang
TOOLS = {}door een dictionary die"list_notes"koppelt aan de functielist_notesen"read_note"aan de functieread_note. Sla de functies zelf op, zonder haakjes.Vervang de onafgemaakte body van
run_tool(call, tools): decodeercall["arguments"]metjson.loads, zoektools[call["name"]]op, roep die functie één keer aan met de gedecodeerde dictionary en geef zijn resultaat terug.
Gebruik in run_tool de parameter tools, niet de globale TOOLS. Deze versie hoeft nog geen slechte aanroepen af te handelen; dat doet les 6. Voer python tools.py uit om je programma de aanroepen van het model te zien uitvoeren, en controleer daarna je werk.