Tools · oefening
Beschrijf een functie als tool
Het model kan alleen vragen om een tool die het request beschrijft. Een beschrijving vertelt het drie dingen: de naam van de tool, wat die doet en welke argumenten die aanneemt. In deze les beschrijf je list_notes en read_note, en het gescripte model begint erom te vragen.
De vorm van een toolbeschrijving
Een toolbeschrijving is een dictionary. Hier is de beschrijving in tools.py met de naam MISNAMED_READ_NOTE, die de demonstratie verderop in deze les gebruikt:
MISNAMED_READ_NOTE = {
"type": "function",
"function": {
"name": "read_note",
"description": "Return the full text of one course note.",
"parameters": {
"type": "object",
"properties": {"id": {"type": "string", "description": "The id of the note, such as 03-lists."}},
"required": ["id"],
"additionalProperties": False,
},
},
}
Lees hem van buiten naar binnen:
"type": "function"zegt dat deze tool een functie is. Dat is de enige soort die de dienst accepteert."name"is de naam die het model schrijft als het om de tool vraagt, en de naam die je programma in les 4 opzoekt. Alleen letters, cijfers,_en-."description"is een zin die het model leest. Een live model beslist aan de hand van deze zin en de naam of een tool zou helpen, dus schrijf hem voor een lezer die je code nooit heeft gezien."parameters"beschrijft de argumenten, als JSON Schema: hetzelfde soort beschrijving datQuizSet.model_json_schema()in hoofdstuk 4 opleverde.
Het parameterschema beschrijft altijd één object, omdat de argumenten aankomen als één JSON-object, zoals {"note_id": "03-lists"}. Daarin:
"properties"heeft één item per argument, met het JSON-type ("string","integer","boolean"enzovoort) en een eigen"description"."required"somt de argumenten op die aanwezig moeten zijn."additionalProperties": Falsezegt dat geen enkel ander argument is toegestaan.
De dictionary is Python, dus er staat False. De client zet hem om naar JSON als hij het request verstuurt, en daar wordt het false. Het request bevat een lijst van deze beschrijvingen als tools:
client.chat.completions.create(model=MODEL, messages=messages, tools=TOOL_DESCRIPTIONS)
Wat het gescripte model controleert
MISNAMED_READ_NOTE heeft de juiste naam, maar noemt zijn enige argument id. Het gescripte model wil {"note_id": "03-lists"} versturen, en voordat het dat doet, controleert het die argumenten tegen het schema in je request. Hier wijzen twee regels ze af: required vraagt om id, dat ontbreekt, en additionalProperties: False verbiedt note_id, dat niet in het schema staat. Daarom antwoordt het met tekst in plaats van om de tool te vragen.
Die controle is het enige waar het gescripte model naar kijkt. Het leest je beschrijvingen niet, en het weigert alleen wat een schema verbiedt. Een schema dat id noemt maar geen required-lijst en geen additionalProperties: False heeft, verbiedt niets en zou de aanroep met note_id nog steeds krijgen. Een live model werkt anders: het leest de namen en beschrijvingen en schrijft argumenten die erbij passen, dus een verkeerd benoemde of vage beschrijving zet het op het verkeerde been. Daarom vraagt deze les om beide regels en om echte beschrijvingen. Het gescripte model zou een tool met de juiste naam ook zonder die regels aanroepen. De regels zijn belangrijk als de argumenten fout zijn, en de beschrijvingen zijn belangrijk voor een live model.
Schrijf TOOL_DESCRIPTIONS
Vervang in tools.py de regel TOOL_DESCRIPTIONS = [] door een lijst van twee beschrijvingen, eerst list_notes en dan read_note. Neem voor beide de vorm van MISNAMED_READ_NOTE over.
list_notesneemt geen argumenten aan. Het parameterschema is een object zonder properties:"properties": {},"required": []en"additionalProperties": False.read_noteneemt één argument aan,note_id. Dat is een string en het is verplicht:"required": ["note_id"]. Geef het een"description"die zegt hoe een id eruitziet, en stel"additionalProperties": Falsein.
Geef elke tool een "description" die zegt wat de tool teruggeeft. Je eigen woorden zijn prima, zolang elke beschrijving een niet-lege string is.
Voer het uit
Voer python tools.py uit. De demonstratie stuurt de vraag uit les 1 nog twee keer: een keer met tools=TOOL_DESCRIPTIONS en een keer met tools=[MISNAMED_READ_NOTE]. Ze drukt van elk antwoord de finish_reason af, en van het tweede ook de tekst:
The same question with your tool descriptions:
finish_reason: tool_calls
With MISNAMED_READ_NOTE instead:
finish_reason: stop
I would call the tool read_note with arguments {"note_id": "03-lists"}, but the parameters schema in this request's tools does not accept them.
The tool calls in the reply:
Run stopped at the next function to build: read_tool_calls is built in Lesson 3.
"tool_calls" is een nieuwe finish reason. Die betekent dat het model stopte om je programma ergens om te vragen, en niet omdat zijn antwoord klaar was ("stop") of werd afgekapt ("length"). Les 3 leest waar het om vroeg. Toont je uitvoer ook voor je eigen beschrijvingen finish_reason: stop, lees de tekst van het antwoord dan op dezelfde manier: die zegt welke tool of welke argumenten niet pasten.
Een beschrijving van read_note noemt haar property id en heeft "required": ["id"] en "additionalProperties": False. Het gescripte model wil de tool aanroepen met {"note_id": "03-lists"}. Wat gebeurt er?
Wie leest de "description"-strings in je toolbeschrijvingen?
list_notes neemt geen argumenten aan. Welk parameterschema beschrijft dat?
Opdracht
Vervang in tools.py TOOL_DESCRIPTIONS = [] door een lijst van twee toolbeschrijvingen, in deze volgorde:
list_notes:"type": "function", en een"function"met"name": "list_notes", een niet-lege"description"en"parameters"ingesteld op een objectschema met"properties": {},"required": []en"additionalProperties": False.read_note: dezelfde vorm, met"name": "read_note", een niet-lege"description"en een parameterschema waarvan de enige propertynote_idis, met"type": "string"en een niet-lege"description", plus"required": ["note_id"]en"additionalProperties": False.
Neem de vorm over van MISNAMED_READ_NOTE, verderop in het bestand. Voer python tools.py uit om het model om je tool te zien vragen, en controleer daarna je werk.