Tools · Übung
Eine Funktion über ihren Namen finden
Ein Tool-Aufruf nennt eine Funktion mit einem String: "read_note". Dein Programm muss von diesem String zur Funktion read_note kommen und sie aufrufen. Diese Lektion macht das mit einem Dictionary und liest unterwegs die drei mitgelieferten Tool-Funktionen.
Eine Funktion ist ein Wert
In Python verweist der Name einer Funktion auf einen Wert, so wie count = 3 dafür sorgt, dass count auf 3 verweist. Ohne Klammern ist read_note die Funktion selbst. Mit Klammern ruft read_note(...) sie auf und liefert dir ihr Ergebnis. Weil die Funktion ein Wert ist, kannst du sie in einem Dictionary speichern und später über das Dictionary aufrufen:
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] schlägt die Funktion nach, und die Klammern dahinter rufen sie mit einem Argument auf. Die letzte Zeile macht beides in einem Ausdruck. So kann ein Programm eine Funktion aufrufen, deren Namen es erst während der Ausführung erfährt, zum Beispiel aus der Antwort eines Modells.
Lass die Klammern weg, wenn du das Dictionary baust. {"shout": shout()} würde shout sofort aufrufen, ohne Argument, und mit TypeError scheitern. Selbst bei einer Funktion, die keine Argumente braucht, würde das Dictionary dann ihr Ergebnis enthalten, einen String, und es gäbe nichts mehr aufzurufen.
Die Tool-Funktionen
Lies jetzt die drei fertigen Funktionen oben in tools.py.
def note_ids():
ids = []
for path in NOTES_DIR.glob("*.md"):
ids.append(path.stem)
ids.sort()
return ids
NOTES_DIR ist Path("notes"), der Notizenordner als pathlib-Pfad. NOTES_DIR.glob("*.md") liefert einen Pfad für jede Datei darin, deren Name auf .md endet, und path.stem ist der Dateiname ohne Ordner und Endung: 03-lists für notes/03-lists.md. Die IDs werden sortiert, weil glob keine Reihenfolge verspricht. note_ids ist eine Hilfsfunktion, kein Tool: Das Modell fragt nie über den Namen nach ihr.
def list_notes(arguments):
return "\n".join(note_ids())
list_notes ist das erste Tool. Es gibt die IDs als einen String zurück, eine pro Zeile, weil das Ergebnis eines Tools als Text an das Modell zurückgeht. Es nimmt ein Argument, das es nie verwendet, arguments, weil jede Tool-Funktion in diesem Kapitel dieselbe Form hat: ein Argument, das dekodierte Dictionary mit den Argumenten, und ein String als Ergebnis. Genau das erlaubt es einer einzigen Codezeile, jede von ihnen aufzurufen.
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 liest note_id mit .get, sodass ein fehlender Schlüssel None statt KeyError ergibt, und prüft, dass es ein String ist. Dann prüft es die ID gegen die echte Liste der Notizen, bevor es irgendetwas öffnet. NOTES_DIR / f"{note_id}.md" setzt Ordner und Dateinamen zu einem Pfad zusammen, notes/03-lists.md, und die Datei wird als UTF-8 gelesen, wie in Python in der Praxis.
Diese zweite Prüfung ist wichtig, weil es darauf ankommt, wer die ID geschrieben hat. Das Modell war es, nicht du, und ein Modell kann beliebigen Text schreiben. Ohne die Prüfung würde read_note NOTES_DIR / f"{note_id}.md" für alles öffnen, was es bekommt, und aus "../MODEL_SERVICE" würde notes/../MODEL_SERVICE.md, also MODEL_SERVICE.md in deinem Arbeitsordner, außerhalb des Notizenordners. Das .md am Ende begrenzt, welche Dateien ein Modell auf diese Weise erreichen kann, aber nicht, welche Ordner: Weitere ../ klettern höher. Der Abgleich mit note_ids() sorgt dafür, dass read_note nur die Notizen selbst öffnen kann. Allgemein gilt: Ein Tool sollte nie einen Dateipfad, einen Befehl oder eine Abfrage aus Modelltext bauen, den es nicht gegen das Erlaubte geprüft hat.
Beide Prüfungen lösen ValueError aus, mit einer Meldung, die für das Modell geschrieben ist. In Lektion 6 gehen diese Meldungen an das Modell zurück, statt dein Programm anzuhalten.
Fülle TOOLS und baue run_tool
Ersetze in tools.py die Zeile TOOLS = {} durch ein Dictionary, das den Namen jedes Tools seiner Funktion zuordnet:
TOOLS = {"list_notes": list_notes, "read_note": read_note}
Die Schlüssel sind die Namen aus deinen Beschreibungen, denn das sind die Namen, die das Modell schreibt. TOOLS steht in der Datei nach den drei Funktionen, sodass die Namen schon existieren, wenn Python das Dictionary baut.
Baue dann run_tool(call, tools). Es nimmt ein Aufruf-Dictionary aus read_tool_calls und ein Dictionary wie TOOLS entgegen:
Dekodiere die Argumente mit
json.loads(call["arguments"]).Schlage die Funktion mit
tools[call["name"]]nach.Rufe sie einmal mit dem dekodierten Dictionary auf und gib zurück, was sie zurückgibt.
Verwende den Parameter tools, nicht das globale TOOLS. Das Projekt übergibt TOOLS, aber die Prüfungen übergeben eigene Dictionaries, und Kapitel 7 übergibt verschiedene Tools für verschiedene Aufgaben.
Dieses run_tool vertraut dem Modell vollständig. Ein unbekannter Name löst KeyError aus, Argumente, die kein JSON sind, lösen einen Fehler in json.loads aus, und eine fehlende Notiz löst den ValueError aus read_note aus. Lektion 6 behebt all das.
Ausführen
Führe python tools.py aus. Die Demonstration übergibt die beiden Aufrufe aus Lektion 3 an dein run_tool: zuerst den Aufruf von list_notes, dann den Aufruf von read_note. Dessen Ergebnis ist lang, deshalb gibt sie nur die Länge und die ersten sieben Zeichen aus:
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.
Das Modell hat gefragt, und dein Programm hat die Funktion ausgeführt. Das Modell hat noch keines der Ergebnisse gesehen. Darum geht es in der nächsten Lektion.
Was geht schief bei TOOLS = {"list_notes": list_notes(), "read_note": read_note}?
Warum prüft read_note note_id gegen note_ids(), bevor es eine Datei öffnet?
Warum nimmt list_notes einen Parameter arguments, den es nie verwendet?
Aufgabe
In tools.py:
Ersetze
TOOLS = {}durch ein Dictionary, das"list_notes"der Funktionlist_notesund"read_note"der Funktionread_notezuordnet. Speichere die Funktionen selbst, ohne Klammern.Ersetze den unfertigen Rumpf von
run_tool(call, tools): Dekodierecall["arguments"]mitjson.loads, schlagetools[call["name"]]nach, rufe diese Funktion einmal mit dem dekodierten Dictionary auf und gib ihr Ergebnis zurück.
Verwende innerhalb von run_tool den Parameter tools, nicht das globale TOOLS. Diese Version muss fehlerhafte Aufrufe noch nicht behandeln; das übernimmt Lektion 6. Führe python tools.py aus, um zu sehen, wie dein Programm die Aufrufe des Modells ausführt, und prüfe dann deine Arbeit.