0%

Tools · Übung

Eine Funktion als Tool beschreiben

Das Modell kann nur ein Tool anfordern, das die Anfrage beschreibt. Eine Beschreibung sagt ihm drei Dinge: den Namen des Tools, was es tut und welche Argumente es annimmt. In dieser Lektion beschreibst du list_notes und read_note, und das geskriptete Modell beginnt, sie anzufordern.

Der Aufbau einer Tool-Beschreibung

Eine Tool-Beschreibung ist ein Dictionary. Hier ist die in tools.py namens MISNAMED_READ_NOTE, die die Demonstration später in dieser Lektion verwendet:

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,
        },
    },
}

Lies sie von außen nach innen:

  • "type": "function" sagt, dass dieses Tool eine Funktion ist. Das ist die einzige Art, die der Dienst akzeptiert.

  • "name" ist der Name, den das Modell schreibt, wenn es das Tool anfordert, und der Name, den dein Programm in Lektion 4 nachschlägt. Nur Buchstaben, Ziffern, _ und -.

  • "description" ist ein Satz, den das Modell liest. Ein Live-Modell entscheidet anhand dieses Satzes und des Namens, ob ein Tool helfen würde. Schreib ihn also für jemanden, der deinen Code nie gesehen hat.

  • "parameters" beschreibt die Argumente, als JSON Schema: dieselbe Art von Beschreibung, die QuizSet.model_json_schema() in Kapitel 4 erzeugt hat.

Das Parameter-Schema beschreibt immer genau ein Objekt, weil die Argumente als ein JSON-Objekt ankommen, zum Beispiel {"note_id": "03-lists"}. Darin gilt:

  • "properties" hat einen Eintrag pro Argument, mit seinem JSON-Typ ("string", "integer", "boolean" und so weiter) und einer eigenen "description".

  • "required" listet die Argumente auf, die vorhanden sein müssen.

  • "additionalProperties": False sagt, dass kein anderes Argument erlaubt ist.

Das Dictionary ist Python, deshalb steht dort False. Der Client wandelt es beim Senden der Anfrage in JSON um, wo daraus false wird. Die Anfrage trägt eine Liste solcher Beschreibungen als tools:

client.chat.completions.create(model=MODEL, messages=messages, tools=TOOL_DESCRIPTIONS)

Was das geskriptete Modell prüft

MISNAMED_READ_NOTE hat den richtigen Namen, nennt sein einziges Argument aber id. Das geskriptete Modell möchte {"note_id": "03-lists"} senden und prüft diese Argumente vorher gegen das Schema in deiner Anfrage. Hier lehnen zwei Regeln sie ab: required verlangt id, das fehlt, und additionalProperties: False verbietet note_id, das im Schema nicht vorkommt. Also antwortet es mit Text, statt das Tool anzufordern.

Diese Prüfung ist alles, worauf das geskriptete Modell schaut. Es liest deine Beschreibungen nicht, und es lehnt nur ab, was ein Schema verbietet. Ein Schema, das id nennt, aber keine required-Liste und kein additionalProperties: False hat, verbietet nichts und würde den Aufruf mit note_id trotzdem bekommen. Ein Live-Modell arbeitet anders: Es liest die Namen und Beschreibungen und schreibt Argumente, die dazu passen. Eine falsch benannte oder vage Beschreibung führt es also in die Irre. Deshalb verlangt diese Lektion beide Regeln und echte Beschreibungen. Das geskriptete Modell würde ein richtig benanntes Tool auch ohne die beiden Regeln aufrufen. Die Regeln zählen, wenn die Argumente falsch sind, und die Beschreibungen zählen für ein Live-Modell.

Schreibe TOOL_DESCRIPTIONS

Ersetze in tools.py die Zeile TOOL_DESCRIPTIONS = [] durch eine Liste mit zwei Beschreibungen, zuerst list_notes und dann read_note. Übernimm für beide den Aufbau von MISNAMED_READ_NOTE.

  • list_notes nimmt keine Argumente. Sein Parameter-Schema ist ein Objekt ohne Properties: "properties": {}, "required": [] und "additionalProperties": False.

  • read_note nimmt ein Argument, note_id. Es ist ein String, und es ist erforderlich: "required": ["note_id"]. Gib ihm eine "description", die sagt, wie eine ID aussieht, und setze "additionalProperties": False.

Gib jedem Tool eine "description", die sagt, was es zurückgibt. Eigene Worte sind in Ordnung, solange jede davon ein nicht leerer String ist.

Ausführen

Führe python tools.py aus. Die Demonstration schickt die Frage aus Lektion 1 noch zweimal: einmal mit tools=TOOL_DESCRIPTIONS und einmal mit tools=[MISNAMED_READ_NOTE]. Sie gibt für jede Antwort den finish_reason aus und für die zweite auch den Text:

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" ist ein neuer Finish-Reason. Er bedeutet, dass das Modell angehalten hat, um bei deinem Programm etwas anzufordern, und nicht, weil seine Antwort fertig ("stop") oder abgeschnitten ("length") war. Lektion 3 liest, was es angefordert hat. Wenn deine Ausgabe auch für deine eigenen Beschreibungen finish_reason: stop zeigt, lies den Antworttext auf dieselbe Weise: Er sagt, welches Tool oder welche Argumente nicht gepasst haben.

Eine Beschreibung für read_note nennt ihre Property id und hat "required": ["id"] und "additionalProperties": False. Das geskriptete Modell möchte das Tool mit {"note_id": "03-lists"} aufrufen. Was passiert?

Wer liest die "description"-Strings in deinen Tool-Beschreibungen?

list_notes nimmt keine Argumente. Welches Parameter-Schema beschreibt das?

Aufgabe

Ersetze in tools.py TOOL_DESCRIPTIONS = [] durch eine Liste mit zwei Tool-Beschreibungen, in dieser Reihenfolge:

  • list_notes: "type": "function" und eine "function" mit "name": "list_notes", einer nicht leeren "description" und "parameters", gesetzt auf ein Objekt-Schema mit "properties": {}, "required": [] und "additionalProperties": False.

  • read_note: derselbe Aufbau, mit "name": "read_note", einer nicht leeren "description" und einem Parameter-Schema, dessen einzige Property note_id ist, mit "type": "string" und einer nicht leeren "description", dazu "required": ["note_id"] und "additionalProperties": False.

Übernimm den Aufbau von MISNAMED_READ_NOTE weiter unten in der Datei. Führe python tools.py aus, um zu sehen, wie das Modell dein Tool anfordert, und prüfe dann deine Arbeit.