Einen KI-Assistenten mit lokalen Modellen bauen · Teil 5 von 13 der Serie
Teil 5: Timer, das Wetter und Werkzeuge, die selbst antworten
Bau Timer, die von selbst klingeln, und ein Wetter-Werkzeug, das einen kostenlosen Dienst im Internet fragt, und mach den Assistenten doppelt so schnell, indem Werkzeuge, die handeln, für sich selbst sprechen.
Einen KI-Assistenten mit lokalen Modellen bauenTeil 5 von 13
Auf dieser Seite
Quest-Ziele
- Werkzeuge, die handeln, von Werkzeugen unterscheiden, die etwas nachschlagen
- Die Wartezeit bei Befehlen halbieren
- Timer bauen, die sich melden, wenn sie abgelaufen sind
- Das Wetter von einer kostenlosen API holen und dem Modell als Text geben
- Ein neues Werkzeug hinzufügen, ohne die Schleife anzufassen
Am Ende des letzten Teils hat das Schalten einer Lampe zwei Anfragen an das Modell gekostet: eine, in der es das Werkzeug verlangt hat, und eine, in der es aus „Das Licht in der Küche ist an.“ den Satz „Es werde Licht: Die Küche ist jetzt an.“ gemacht hat. Die zweite Anfrage hat die Antwort hübscher gemacht und die Wartezeit verdoppelt.
Zwei Arten von Werkzeugen
Schau dir an, was Werkzeuge tun, und du findest zwei Arten:
Werkzeuge, die handeln: eine Lampe schalten, einen Timer starten. Wenn sie fertig sind, ist alles bekannt, was es zu sagen gibt: „Das Licht in der Küche ist an.“
Werkzeuge, die etwas nachschlagen: welche Lampen an sind, wie das Wetter wird. Ihr Ergebnis ist Rohmaterial, und das Modell muss es lesen, um die Frage zu beantworten, die wirklich gestellt wurde.
Lass die erste Art also für sich selbst sprechen. Ein Werkzeug gibt jetzt eines von zwei Dingen zurück: say mit einem fertigen Satz oder info mit etwas, das das Modell lesen soll. Ersetz src/tools.ts:
import { lightTools } from './tools/lights.ts';
import { timerTools } from './tools/timers.ts';
import { weatherTools } from './tools/weather.ts';
/**
* What a tool hands back: `say` when it did something and has the answer ready, `info`
* when it looked something up that the model should put into words.
*/
export type ToolResult = { say: string } | { info: string };
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>;
run(args: Record<string, unknown>): ToolResult | Promise<ToolResult>;
}
export const tools: Tool[] = [...lightTools, ...timerTools, ...weatherTools];
/** 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<ToolResult> {
const tool = tools.find((candidate) => candidate.name === name);
if (!tool) return { info: `There is no tool called ${name}.` };
try {
return await tool.run(args);
} catch (error) {
return { info: `The tool failed: ${(error as Error).message}` };
}
}Ändere in src/tools/lights.ts, was die beiden run-Funktionen zurückgeben:
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 { info: `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: 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: () => ({ info: JSON.stringify(getLamps()) }),
},Das Ändern der Lampen ist ein say. Der unbekannte Raum ist ein info: Das Modell soll es lesen und es noch einmal versuchen. Und in src/model.ts lernt die Schleife den Unterschied. Ersetz alles vom Kommentar über dem for bis zum Ende der Datei:
// 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));
const said: string[] = [];
for (const call of answer.tool_calls) {
const result = await runTool(call.function.name, call.function.arguments);
if ('say' in result) said.push(result.say);
messages.push({
role: 'tool',
tool_name: call.function.name,
content: 'say' in result ? result.say : result.info,
});
}
// every tool had its answer ready: no need to ask the model again
if (said.length === answer.tool_calls.length) return done(said.join(' '));
}
return done(say.beyondMe);
}Hatte jedes Werkzeug, das das Modell aufgerufen hat, seine Antwort schon parat, dann ist Schluss, und ihre Sätze sind die Antwort. Nur wenn etwas nachgeschlagen wurde, dreht die Schleife noch eine Runde. Ein Lampenbefehl kostet jetzt eine Anfrage statt zwei und dauert damit etwa halb so lang. Kein schnellerer Rechner bringt dir so billig so viel Tempo.
Du verlierst die Witze des Modells über Lampen. Bei einem Assistenten, mit dem du zwanzigmal am Tag sprichst, ist auch das ein Gewinn.
Ungefragt sprechen
Ein Timer antwortet zweimal: einmal, wenn er gestellt wird, und einmal, Minuten später, wenn er klingelt. Beim zweiten Mal hat niemand etwas gefragt. Pixel braucht einen Weg, sich von selbst zu melden. Leg src/announce.ts an:
/**
* Things Pixel says without being asked, such as a timer that is up. Whoever shows or speaks
* Pixel's words (the terminal, later the page) listens here.
*/
type Listener = (speech: string) => void;
const listeners: Listener[] = [];
export function onAnnounce(listener: Listener): void {
listeners.push(listener);
}
export function announce(speech: string): void {
for (const listener of listeners) listener(speech);
}Wer Pixels Worte anzeigt, meldet sich mit onAnnounce an, und wer etwas zu sagen hat, ruft announce auf. Die Timer müssen nicht wissen, ob am anderen Ende ein Terminal, eine Seite oder ein Lautsprecher sitzt.
Timer
Leg src/timers.ts an:
import { announce } from './announce.ts';
import { LOCALE, say } from './language.ts';
interface Timer {
label: string;
/** when it rings, in milliseconds since 1970 */
ends: number;
handle: NodeJS.Timeout;
}
const timers: Timer[] = [];
/** "10 minutes", "1 minute", "30 seconds", in Pixel's language. */
export function length(minutes: number): string {
const [value, unit] = minutes < 1 ? [Math.round(minutes * 60), 'second'] : [minutes, 'minute'];
return new Intl.NumberFormat(LOCALE, { style: 'unit', unit, unitDisplay: 'long', maximumFractionDigits: 1 }).format(value);
}
export function startTimer(minutes: number, label: string): void {
const timer: Timer = {
label,
ends: Date.now() + minutes * 60_000,
handle: setTimeout(() => {
timers.splice(timers.indexOf(timer), 1);
announce(say.timerDone(label));
}, minutes * 60_000),
};
timers.push(timer);
}
/** The running timers with the minutes they have left, the next one first. */
export function listTimers(): Array<{ label: string; minutesLeft: number }> {
return timers
.map((timer) => ({ label: timer.label, minutesLeft: Math.round((timer.ends - Date.now()) / 6000) / 10 }))
.sort((a, b) => a.minutesLeft - b.minutesLeft);
}
/** Stops the timer with this label, or the next one to ring when there is no such label. */
export function cancelTimer(label: string): string | null {
const timer =
timers.find((candidate) => label && candidate.label.toLowerCase() === label.toLowerCase()) ??
timers.toSorted((a, b) => a.ends - b.ends)[0];
if (!timer) return null;
clearTimeout(timer.handle);
timers.splice(timers.indexOf(timer), 1);
return timer.label;
}setTimeout übernimmt das Warten. Ist die Zeit um, entfernt sich der Timer aus der Liste und meldet, dass er fertig ist. Die Timer leben im Arbeitsspeicher, sind also weg, wenn das Programm endet. length schreibt eine Dauer so, wie die Sprache es tut, wieder mit Intl.
Die Werkzeuge drumherum, in src/tools/timers.ts:
import { say } from '../language.ts';
import { cancelTimer, length, listTimers, startTimer } from '../timers.ts';
import type { Tool } from '../tools.ts';
export const timerTools: Tool[] = [
{
name: 'set_timer',
description: 'Starts a timer that rings after the given time.',
parameters: {
type: 'object',
properties: {
minutes: { type: 'number', description: 'how long, in minutes; 0.5 is thirty seconds' },
label: { type: 'string', description: 'what the timer is for, such as "pasta"; may be empty' },
},
required: ['minutes'],
},
run(args) {
const minutes = Number(args.minutes);
if (!(minutes > 0 && minutes <= 24 * 60)) return { info: 'minutes must be between 0 and 1440.' };
const label = typeof args.label === 'string' ? args.label : '';
startTimer(minutes, label);
return { say: say.timerSet(length(minutes), label) };
},
},
{
name: 'list_timers',
description: 'Looks up the running timers and the minutes each has left.',
parameters: { type: 'object', properties: {} },
run: () => ({ info: JSON.stringify(listTimers()) }),
},
{
name: 'cancel_timer',
description: 'Stops a running timer.',
parameters: {
type: 'object',
properties: { label: { type: 'string', description: 'the label of the timer; empty for the next one to ring' } },
},
run(args) {
const label = cancelTimer(typeof args.label === 'string' ? args.label : '');
return { say: label === null ? say.noTimer : say.timerGone(label) };
},
},
];Stellen und Stoppen sind Handlungen und antworten mit say. Das Auflisten ist ein Nachschlagen. Die Prüfung in set_timer sieht seltsam aus, ist aber Absicht: !(minutes > 0 && ...) ist auch dann wahr, wenn minutes gar keine Zahl ist, und das würde ein einfaches minutes <= 0 durchlassen.
Die Sätze gehören in src/language.ts, zusammen mit dem, was das Wetter gleich braucht:
/** Die Beschriftungen der Notiz, die vor jeder Anfrage steht. */
export const LABELS = {
// ...
wind: 'Wind',
rain: 'Regenwahrscheinlichkeit',
to: 'bis',
};
/** WMO-Wettercodes, wie Open-Meteo sie schickt: bis zu diesem Code heißt es so. */
export const WEATHER: Array<[number, string]> = [
[1, 'klar'],
[2, 'leicht bewölkt'],
[3, 'bedeckt'],
[48, 'Nebel'],
[57, 'Nieselregen'],
[67, 'Regen'],
[77, 'Schnee'],
[82, 'Regenschauer'],
[86, 'Schneeschauer'],
[99, 'Gewitter'],
];
/** Die Sätze, die Pixel ohne das Modell sagt. */
export const say = {
// ...
timerSet: (length: string, label: string) => (label ? `Timer gestellt: ${length} für ${label}.` : `Timer auf ${length} gestellt.`),
timerDone: (label: string) => (label ? `Die Zeit ist um: ${label}!` : 'Die Zeit ist um!'),
timerGone: (label: string) => (label ? `Timer für ${label} gestoppt.` : 'Timer gestoppt.'),
noTimer: 'Es läuft kein Timer.',
};Das // ... steht für das, was schon da ist: Füg die neuen Zeilen in LABELS und in say ein, und WEATHER als Ganzes.
Das Wetter
Das Modell weiß nichts über das Wetter von heute, aber Open-Meteo schon. Das ist ein kostenloser Wetterdienst, der kein Konto und keinen Schlüssel braucht. Zwei Anfragen sind nötig: eine, die aus einem Ortsnamen Koordinaten macht, und eine, die für sie die Vorhersage holt. Leg src/weather.ts an:
import { LABELS, LOCALE, WEATHER } from './language.ts';
interface Place {
name: string;
country: string;
latitude: number;
longitude: number;
}
interface Forecast {
current: { temperature_2m: number; weather_code: number; wind_speed_10m: number };
daily: {
time: string[];
weather_code: number[];
temperature_2m_min: number[];
temperature_2m_max: number[];
precipitation_probability_max: number[];
};
}
const language = LOCALE.slice(0, 2);
const weekday = new Intl.DateTimeFormat(LOCALE, { weekday: 'long' });
async function getJson<T>(url: string): Promise<T> {
const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
if (!response.ok) throw new Error(`${new URL(url).host} answered ${response.status}`);
return (await response.json()) as T;
}
const sky = (code: number): string => WEATHER.find(([upTo]) => code <= upTo)?.[1] ?? '';
/** The weather now and for three days, as a few lines of text the model can read. */
export async function weather(placeName: string): Promise<string> {
const found = await getJson<{ results?: Place[] }>(
`https://geocoding-api.open-meteo.com/v1/search?count=1&language=${language}&name=${encodeURIComponent(placeName)}`,
);
const place = found.results?.[0];
if (!place) return `No place called ${placeName} was found.`;
const forecast = await getJson<Forecast>(
'https://api.open-meteo.com/v1/forecast?timezone=auto&forecast_days=3' +
`&latitude=${place.latitude}&longitude=${place.longitude}` +
'¤t=temperature_2m,weather_code,wind_speed_10m' +
'&daily=weather_code,temperature_2m_min,temperature_2m_max,precipitation_probability_max',
);
const { current, daily } = forecast;
const days = daily.time.map(
(date, i) =>
`${weekday.format(new Date(`${date}T12:00`))}: ${Math.round(daily.temperature_2m_min[i]!)} ${LABELS.to} ` +
`${Math.round(daily.temperature_2m_max[i]!)} °C, ${sky(daily.weather_code[i]!)}, ` +
`${LABELS.rain} ${daily.precipitation_probability_max[i]} %`,
);
return [
`${place.name}, ${place.country}`,
`${LABELS.now}: ${Math.round(current.temperature_2m)} °C, ${sky(current.weather_code)}, ` +
`${LABELS.wind} ${Math.round(current.wind_speed_10m)} km/h`,
...days,
].join('\n');
}Die Funktion gibt dem Modell nicht das rohe JSON des Dienstes, das lang ist und voller Zahlen, deren Einheiten ganz woanders stehen. Sie schreibt ein paar schlichte Zeilen:
Wien, Österreich
Jetzt: 7 °C, bedeckt, Wind 10 km/h
Dienstag: 5 bis 14 °C, Regen, Regenwahrscheinlichkeit 100 %
Mittwoch: 10 bis 15 °C, Regenschauer, Regenwahrscheinlichkeit 55 %
Donnerstag: 7 bis 12 °C, Regen, Regenwahrscheinlichkeit 15 %Das solltest du dir merken: Schreib die Ergebnisse von Werkzeugen so, wie du eine Notiz für eine Kollegin schreiben würdest. Ein kleines Modell liest einen kurzen Text viel zuverlässiger als verschachtelte Daten, und jedes Token, das es nicht lesen muss, macht die Antwort schneller. Aus demselben Grund werden die Wettercodes zu Wörtern, und jeder Tag bekommt seinen Wochentag, denn du weißt ja schon, dass man das Modell keine Tage zählen lassen sollte.
AbortSignal.timeout(5000) gibt nach fünf Sekunden auf, damit ein langsamer Dienst den Assistenten nicht hängen lässt. Trag deinen Wohnort in src/config.ts ein:
/** The place the weather is for when nobody names one. */
export const HOME_PLACE = process.env.HOME_PLACE ?? 'Vienna';Und das Werkzeug, in src/tools/weather.ts:
import { HOME_PLACE } from '../config.ts';
import type { Tool } from '../tools.ts';
import { weather } from '../weather.ts';
export const weatherTools: Tool[] = [
{
name: 'get_weather',
description: 'Looks up the weather now and the forecast for today and the next two days.',
parameters: {
type: 'object',
properties: {
place: { type: 'string', description: `a town or city; leave it out for home (${HOME_PLACE})` },
},
},
async run(args) {
const place = typeof args.place === 'string' && args.place.trim() ? args.place : HOME_PLACE;
return { info: await weather(place) };
},
},
];Den Timer hören
Die neuen Werkzeuge stehen schon in der Liste in src/tools.ts, und die Schleife braucht gar keine Änderung: Ein neues Werkzeug ist eine Beschreibung und eine Funktion. Nur der Chat muss noch auf Ansagen hören. Füg in src/chat.ts den Import import { onAnnounce } from './announce.ts'; hinzu und diese Zeilen über der Begrüßung:
// a timer that is up, for example
onAnnounce((speech) => console.log(`\n${name}> ${speech}`));$ npm run chatTalk to Pixel. /bye ends the chat.you> Mach es im Schlafzimmer gemütlich.pixel> Das Licht im Schlafzimmer ist warmweiß auf 30 Prozent. Wohnzimmer ○ Küche ○ Schlafzimmer ● 30% warmweiß Bad ○ Flur ○you> Stell einen Timer für den Tee, eine halbe Minute.pixel> Timer gestellt: 30 Sekunden für Tee.you> Brauche ich heute einen Regenschirm?pixel> Ja, nimm einen mit: Gerade ist es bedeckt bei 7 Grad, und heute regnet es so gut wie sicher.you>pixel> Die Zeit ist um: Tee!
Die Lampe und der Timer wurden von ihren Werkzeugen beantwortet, mit je einer Anfrage. Der Regenschirm hat zwei gebraucht: Das Modell hat get_weather aufgerufen, die Zeilen gelesen und die Frage beantwortet, die gestellt wurde, und die lautete nicht „Wie ist das Wetter?“, sondern „Brauche ich einen Regenschirm?“. Und eine halbe Minute später hat sich Pixel von selbst gemeldet.
Pixel hat jetzt sechs Werkzeuge und braucht eine Anfrage pro Befehl. Aber selbst eine Anfrage an ein Sprachmodell dauert eine Sekunde oder länger, und bei „Küche an“ gibt es wirklich nichts zu überlegen. Im nächsten Teil behelligen einfache Befehle das Modell nicht mehr.
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.