Zum Inhalt springen

Einen KI-Assistenten mit lokalen Modellen bauen · Teil 4 von 13 der Serie

Teil 4: Werkzeuge, oder wie das Modell das Licht schaltet

Bau ein kleines virtuelles Zuhause und gib dem Modell sein erstes Werkzeug. Lerne, wie Tool Calling wirklich funktioniert: Das Modell bittet nur, dein Code handelt, und das Ergebnis geht zurück ins Gespräch.

Quest-Ziele

  • Ein virtuelles Zuhause mit einer Lampe in jedem Raum bauen
  • Ein Werkzeug so beschreiben, dass ein Modell versteht, wann es gebraucht wird
  • Die Schleife hinter Tool Calling verstehen
  • Prüfen, was das Modell schickt, bevor du danach handelst
  • Lampen schalten, indem du in eigenen Worten sagst, was du willst

Ein Sprachmodell kann nur Text erzeugen. Es kann keine Lampe schalten, keinen Timer starten und nichts nachschlagen. Trotzdem tun Assistenten genau das. Der Trick heißt Tool Calling, also das Aufrufen von Werkzeugen, und er ist einfacher, als er klingt:

  1. Mit dem Gespräch schickst du dem Modell eine Liste von Werkzeugen: einen Namen, eine Beschreibung und die Argumente, die jedes annimmt.

  2. Statt in Worten zu antworten, darf das Modell antworten: „Ruf dieses Werkzeug mit diesen Argumenten auf“. Auch das ist nur Text, in einer festen Form.

  3. Dein Code führt das Werkzeug aus und hängt das, was es meldet, an das Gespräch an.

  4. Du schickst das Gespräch noch einmal. Jetzt antwortet das Modell in Worten und weiß dabei, was das Werkzeug getan hat.

Das Modell tut nie selbst etwas. Es bittet, und dein Programm entscheidet, ob und wie es das tut. Merk dir das: Genau das macht einen Assistenten sicher.

Ein Zuhause

Der echte Assistent hinter dieser Serie schaltet echte Lampen über das Netzwerk. Damit du keine Hardware brauchst, bekommt Pixel ein virtuelles Zuhause: fünf Räume mit je einer Lampe, die nur im Arbeitsspeicher existieren. Zuerst die Räume und Farben, denn sie haben Namen, und Namen sind Sprache. Füg das in src/language.ts ein, den Import ganz oben und den Rest am Ende:

src/language.ts
import type { Change, Lamp } from './home.ts';

export interface Room {
  name: string;
  /** wie ein Satz sagt, wo: "in der Küche" */
  where: string;
  /** wie die Leute den Raum nennen */
  words: string[];
}

export const ROOMS: Room[] = [
  { name: 'Wohnzimmer', where: 'im Wohnzimmer', words: ['wohnzimmer', 'stube'] },
  { name: 'Küche', where: 'in der Küche', words: ['küche'] },
  { name: 'Schlafzimmer', where: 'im Schlafzimmer', words: ['schlafzimmer'] },
  { name: 'Bad', where: 'im Bad', words: ['badezimmer', 'bad'] },
  { name: 'Flur', where: 'im Flur', words: ['flur', 'gang', 'vorzimmer'] },
];

export interface Color {
  name: string;
  words: string[];
  /** wie die Seite sie malt */
  css: string;
}

export const COLORS: Color[] = [
  { name: 'weiß', words: ['weiß', 'weiss'], css: '#fff4e0' },
  { name: 'warmweiß', words: ['warmweiß', 'warmweiss', 'warm weiß', 'warm weiss', 'warm'], css: '#ffd08a' },
  { name: 'rot', words: ['rot'], css: '#ff5a4d' },
  { name: 'orange', words: ['orange'], css: '#ff9a3c' },
  { name: 'gelb', words: ['gelb'], css: '#ffe14d' },
  { name: 'grün', words: ['grün'], css: '#5fe07a' },
  { name: 'blau', words: ['blau'], css: '#5aa2ff' },
  { name: 'violett', words: ['violett', 'lila'], css: '#b06cff' },
  { name: 'rosa', words: ['rosa', 'pink'], css: '#ff7ac8' },
];

const list = new Intl.ListFormat(LOCALE, { type: 'conjunction' });

/** Die Sätze, die Pixel ohne das Modell sagt. */
export const say = {
  lights(lamps: Lamp[], change: Change): string {
    const everywhere = lamps.length === ROOMS.length;
    const where = list.format(lamps.map((lamp) => ROOMS.find((room) => room.name === lamp.room)!.where));
    const subject = everywhere ? 'Alle Lichter sind' : lamps.length > 1 ? `Die Lichter ${where} sind` : `Das Licht ${where} ist`;
    if (change.on === false) return `${subject} aus.`;
    const now = [change.color, change.brightness && `auf ${change.brightness} Prozent`].filter(Boolean);
    return `${subject} ${now.length ? now.join(' ') : 'an'}.`;
  },
  beyondMe: 'Das übersteigt leider meine Fähigkeiten.',
};

Ein Raum hat einen Namen, die Worte, mit denen ein Satz sagt, wo („in der Küche“), und die Wörter, die Leute für ihn benutzen. Eine Farbe hat einen css-Wert, mit dem die Seite in Teil 9 die Lampe malt. say.lights baut den Satz, der eine Änderung meldet, etwa „Die Lichter in der Küche und im Flur sind aus.“ Intl.ListFormat verbindet die Räume mit Kommas und „und“, so wie die Sprache es tut.

Jetzt das Zuhause selbst, src/home.ts:

src/home.ts
import { COLORS, ROOMS } from './language.ts';

export interface Lamp {
  room: string;
  on: boolean;
  /** 1 to 100 */
  brightness: number;
  color: string;
}

export type Change = Partial<Pick<Lamp, 'on' | 'brightness' | 'color'>>;

/** The home: one lamp per room. It lives in memory and starts dark. */
const lamps: Lamp[] = ROOMS.map((room) => ({
  room: room.name,
  on: false,
  brightness: 100,
  color: COLORS[0]!.name,
}));

const listeners: Array<() => void> = [];

export function getLamps(): Lamp[] {
  return lamps;
}

/** Changes the lamps of the given rooms, or of every room when none is given. */
export function setLamps(rooms: string[], change: Change): Lamp[] {
  if (change.brightness !== undefined) {
    change.brightness = Math.min(100, Math.max(1, Math.round(change.brightness)));
  }
  const hit = lamps.filter((lamp) => rooms.length === 0 || rooms.includes(lamp.room));
  // a new brightness or color switches the lamp on, unless the change says off
  for (const lamp of hit) Object.assign(lamp, { on: true }, change);
  for (const listener of listeners) listener();
  return hit;
}

/** Calls `listener` after every change. */
export function onHomeChange(listener: () => void): void {
  listeners.push(listener);
}

/** The home as a few lines of text, for the terminal. */
export function drawHome(): string {
  return lamps
    .map((lamp) => {
      const state = lamp.on ? `● ${lamp.brightness}% ${lamp.color}` : '○';
      return `  ${lamp.room.padEnd(12)} ${state}`;
    })
    .join('\n');
}

setLamps ist die eine Stelle, an der sich Lampen ändern. Die Funktion hält die Helligkeit zwischen 1 und 100, egal was sie bekommt. Die Listener sind für Teil 9, wo die Seite von jeder Änderung erfahren will; im Moment hört niemand zu. drawHome zeichnet das Zuhause ins Terminal.

Hättest du echte Lampen, dann würdest du in setLamps mit ihnen sprechen. Der Rest des Assistenten würde den Unterschied nicht bemerken.

Ein Werkzeug beschreiben

Ein Werkzeug hat zwei Seiten: eine Beschreibung für das Modell und eine Funktion für dein Programm. Leg src/tools.ts an:

src/tools.ts
import { lightTools } from './tools/lights.ts';

export interface Tool {
  name: string;
  /** tells the model when to use the tool */
  description: string;
  /** the arguments, as a JSON schema */
  parameters: Record<string, unknown>;
  /** does the work and reports what happened, in words the model can read */
  run(args: Record<string, unknown>): string | Promise<string>;
}

export const tools: Tool[] = [...lightTools];

/** The tools in the form Ollama expects. */
export const toolDefinitions = tools.map((tool) => ({
  type: 'function',
  function: { name: tool.name, description: tool.description, parameters: tool.parameters },
}));

export async function runTool(name: string, args: Record<string, unknown>): Promise<string> {
  const tool = tools.find((candidate) => candidate.name === name);
  if (!tool) return `There is no tool called ${name}.`;
  try {
    return await tool.run(args);
  } catch (error) {
    return `The tool failed: ${(error as Error).message}`;
  }
}

toolDefinitions ist die Liste, die mit jeder Anfrage zu Ollama reist. runTool sucht ein Werkzeug über den Namen heraus, den das Modell verlangt hat, und führt es aus. Zwei Dinge können dabei schiefgehen, und auf beide gibt es eine Antwort in Worten statt eines Absturzes: Ein Modell verlangt manchmal ein Werkzeug, das es nicht gibt, und ein Werkzeug kann scheitern. Das Modell liest die Meldung und kann etwas anderes versuchen.

Die Lampen-Werkzeuge kommen in src/tools/lights.ts:

src/tools/lights.ts
import { type Change, getLamps, setLamps } from '../home.ts';
import { COLORS, ROOMS, say } from '../language.ts';
import type { Tool } from '../tools.ts';

const roomNames = ROOMS.map((room) => room.name);
const colorNames = COLORS.map((color) => color.name);

export const lightTools: Tool[] = [
  {
    name: 'set_lights',
    description: 'Switches lamps on or off, dims them or changes their color.',
    parameters: {
      type: 'object',
      properties: {
        rooms: {
          type: 'array',
          items: { type: 'string', enum: roomNames },
          description: 'The rooms to change. An empty list means the whole home.',
        },
        on: { type: 'boolean', description: 'true switches on, false switches off' },
        brightness: { type: 'number', description: 'from 1 (dark) to 100 (bright)' },
        color: { type: 'string', enum: colorNames },
      },
      required: ['rooms'],
    },
    run(args) {
      // the model wrote these arguments, so check every one of them
      const wanted = Array.isArray(args.rooms) ? args.rooms : [];
      const rooms = wanted.filter((room) => roomNames.includes(room));
      // a room that does not exist must not become "the whole home"
      if (rooms.length < wanted.length) return `Unknown room. The rooms are: ${roomNames.join(', ')}.`;
      const change: Change = {};
      if (typeof args.on === 'boolean') change.on = args.on;
      if (typeof args.brightness === 'number') change.brightness = args.brightness;
      if (typeof args.color === 'string' && colorNames.includes(args.color)) change.color = args.color;
      const changed = setLamps(rooms, change);
      return say.lights(changed, change);
    },
  },
  {
    name: 'get_lights',
    description: 'Looks up which lamps are on, how bright they are and which color they have.',
    parameters: { type: 'object', properties: {} },
    run: () => JSON.stringify(getLamps()),
  },
];

Die parameters sind ein JSON-Schema, eine verbreitete Art, die Form von Daten zu beschreiben. Das Modell liest es, um zu erfahren, welche Argumente es gibt. Ein paar Dinge helfen einem kleinen Modell, sie richtig zu füllen:

  • Ein enum, wo immer es eine feste Auswahl gibt. Stehen die Raumnamen in der Liste, wählt das Modell einen davon und erfindet kein „Esszimmer“.

  • Wenige Argumente, wenige Werkzeuge. Ein Werkzeug, das schaltet, dimmt und färbt, ist für das Modell leichter als drei.

  • Beschreibungen, die sagen, wann, nicht wie. „Looks up which lamps are on“ (schlägt nach, welche Lampen an sind) sagt dem Modell, dass dies das Werkzeug für Fragen ist. Die Beschreibungen und die kurzen Meldungen der Werkzeuge bleiben auch im deutschen Projekt englisch: Das Modell versteht sie problemlos und antwortet trotzdem auf Deutsch.

Und dann die wichtigsten Zeilen dieses Teils, am Anfang von run: Das Modell hat diese Argumente geschrieben, also prüf jedes einzelne. Ein Schema ist eine Bitte an das Modell, kein Versprechen. Es kann eine Zahl als String schicken, eine Farbe, die nicht in der Liste steht, oder einen Raum, den es nicht gibt. Ohne die Prüfung würde ein erfundener Raum aussortiert, die Liste wäre leer, und „leer“ heißt das ganze Zuhause: ein halluziniertes Wort, und jede Lampe im Haus ändert sich. Deshalb wird ein unbekannter Raum zurückgemeldet, zusammen mit der Liste der Räume, die es wirklich gibt.

Werkzeugaufrufe im Client

Ollama muss die Werkzeuge bekommen, und die Nachrichten erhalten zwei neue Felder. Ersetz in src/ollama.ts alles zwischen der Import-Zeile und chatStream durch das hier:

src/ollama.ts
export interface ToolCall {
  function: { name: string; arguments: Record<string, unknown> };
}

export interface Message {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
  /** on an assistant message: the tools the model wants to call */
  tool_calls?: ToolCall[];
  /** on a tool message: the tool whose result this is */
  tool_name?: string;
}

export interface ChatOptions {
  /** the tools the model may call, as Ollama expects them */
  tools?: object[];
}

async function post(path: string, body: object): Promise<Response> {
  const response = await fetch(`${OLLAMA_URL}${path}`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!response.ok) throw new Error(`Ollama answered ${response.status}: ${await response.text()}`);
  return response;
}

/** Sends the conversation to the model and returns its whole answer. */
export async function chat(messages: Message[], options: ChatOptions = {}): Promise<Message> {
  const response = await post('/api/chat', {
    model: MODEL,
    messages,
    tools: options.tools,
    stream: false,
    think: false,
    options: { temperature: 0.2, num_predict: 300 },
  });
  const data = (await response.json()) as { message: Message };
  return data.message;
}

Wenn das Modell ein Werkzeug will, enthält seine Nachricht keinen Text, sondern eine Liste von tool_calls:

json
{
  "role": "assistant",
  "content": "",
  "tool_calls": [
    {
      "function": {
        "name": "set_lights",
        "arguments": { "rooms": ["Küche"], "on": true }
      }
    }
  ]
}

Und die Antwort darauf ist eine Nachricht mit einer neuen Rolle, tool, die enthält, was das Werkzeug gemeldet hat.

Die Schleife

Ersetz src/model.ts:

src/model.ts
import { keep, recent } from './history.ts';
import { PERSONA, say } from './language.ts';
import { chat, type Message } from './ollama.ts';
import { contextBlock, spoken } from './prompt.ts';
import { runTool, toolDefinitions } from './tools.ts';

export interface Reply {
  speech: string;
}

/** Asks the local model, which may call tools on the way to its answer. */
export async function askModel(text: string): Promise<Reply> {
  const messages: Message[] = [
    // first what never changes, so Ollama can reuse its work from the last request ...
    { role: 'system', content: PERSONA },
    ...recent(),
    // ... and last what is new
    { role: 'user', content: `${contextBlock()}\n${text}` },
  ];
  const done = (speech: string): Reply => {
    keep(text, speech);
    return { speech };
  };

  // a call, its result, another call ...: after four rounds it is enough
  for (let round = 0; round < 4; round += 1) {
    const answer = await chat(messages, { tools: toolDefinitions });
    messages.push(answer);
    if (!answer.tool_calls?.length) return done(spoken(answer.content));

    // the model asked for tools: run each one and add what it reports to the conversation
    for (const call of answer.tool_calls) {
      const result = await runTool(call.function.name, call.function.arguments);
      messages.push({ role: 'tool', tool_name: call.function.name, content: result });
    }
  }
  return done(say.beyondMe);
}

Das ist die Schleife vom Anfang dieses Teils, als Code. Frag das Modell. Antwortet es in Worten, ist das die Antwort. Verlangt es Werkzeuge, führ jedes aus, häng eine tool-Nachricht mit dem Ergebnis an und frag noch einmal. Eine Anfrage kann mehrere Runden brauchen: Um die Küche „ein bisschen dunkler“ zu machen, muss das Modell erst nachschlagen, wie hell sie ist. Nach vier Runden ist Schluss, damit sich ein verwirrtes Modell nicht ewig im Kreis dreht.

Auch die Persona muss von den Werkzeugen wissen. Ersetz in src/language.ts den letzten Abschnitt von PERSONA:

src/language.ts
Das machst du:
- Für alles, was du in diesem Zuhause tun kannst, hast du ein Werkzeug. Um etwas zu tun, rufst
  du das Werkzeug auf.
- Sag nie, dass etwas erledigt ist, wenn es kein Werkzeug getan hat.
- Wenn du etwas nicht weißt, sag das in einem Satz. Rate nicht.

Und der Chat soll das Zuhause zeigen, sobald es sich geändert hat. Ersetz src/chat.ts:

src/chat.ts
import { createInterface } from 'node:readline/promises';
import { NAME } from './config.ts';
import { drawHome } from './home.ts';
import { askModel } from './model.ts';

const terminal = createInterface({ input: process.stdin, output: process.stdout });
// Ctrl+D closes the input: leave without an error
terminal.on('close', () => process.exit());
const name = NAME.toLowerCase();

console.log(`Talk to ${NAME}. /bye ends the chat.\n`);
let home = drawHome();

while (true) {
  const text = (await terminal.question('you> ')).trim();
  if (text === '/bye') break;
  if (!text) continue;

  const answer = await askModel(text);
  console.log(`${name}> ${answer.speech}`);
  // show the home whenever it has changed
  if (drawHome() !== home) {
    home = drawHome();
    console.log(home);
  }
}
terminal.close();
~/projects/pixel-assistant
$ npm run chatTalk to Pixel. /bye ends the chat.you> In der Küche ist es ein bisschen dunkel.pixel> Es werde Licht: Die Küche ist jetzt an.  Wohnzimmer   ○  Küche        ● 100% weiß  Schlafzimmer ○  Bad          ○  Flur         ○you> Mach es im Schlafzimmer gemütlich.pixel> Das Schlafzimmer ist jetzt warmweiß auf 30 Prozent. Sehr gemütlich.  Wohnzimmer   ○  Küche        ● 100% weiß  Schlafzimmer ● 30% warmweiß  Bad          ○  Flur         ○you> Welche Lichter sind an?pixel> Die Küche mit voller Helligkeit und das Schlafzimmer warmweiß auf 30 Prozent.you> /bye

Niemand hat „einschalten“ gesagt oder eine Helligkeit genannt. Das Modell hat sich erschlossen, dass eine dunkle Küche Licht braucht und dass gemütlich warm und gedimmt bedeutet, hat das Werkzeug gewählt und die Argumente ausgefüllt. Genau das kann ein Sprachmodell gut, und keine Liste von Befehlen könnte es.

Jede dieser Antworten hat zwei Anfragen an das Modell gebraucht: eine, die zum Werkzeugaufruf geführt hat, und eine, um das Ergebnis in Worte zu fassen. Im nächsten Teil kommen Timer und das Wetter dazu, und du halbierst das.

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.