Zum Inhalt springen

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

Teil 8: Ein Gedächtnis, das nach Bedeutung findet

Gib dem Assistenten ein Gedächtnis, das einen Neustart übersteht. Lern, was Embeddings sind, speichere Fakten mit ihnen, finde die richtigen nach ihrer Bedeutung statt nach ihren Wörtern und leg sie dem Modell vor.

Quest-Ziele

  • Verstehen, was ein Embedding ist
  • Sätze mit einem zweiten lokalen Modell in Vektoren verwandeln
  • Zwei Vektoren mit der Kosinus-Ähnlichkeit vergleichen
  • Fakten speichern, finden und vergessen
  • Was das Gedächtnis weiß, in jede Anfrage schreiben

Erzähl Pixel, dass Anna allergisch gegen Nüsse ist, schließ den Chat, öffne ihn wieder, und Pixel hat noch nie von Anna gehört. Du weißt, warum: Das Modell behält nichts, und der Verlauf fasst drei Wortwechsel und liegt im Arbeitsspeicher. Ein Assistent für ein Zuhause sollte die Menschen kennen, die darin wohnen.

Fakten zu speichern ist einfach: Eine Datei genügt. Schwierig ist, die richtigen wiederzufinden. Wenn jemand fragt „Kann ich Walnüsse in den Kuchen für Anna geben?“, dann hilft der Fakt „Anna ist allergisch gegen Nüsse“, und die beiden Sätze haben genau ein Wort gemeinsam. Eine Suche nach Wörtern würde nach „Walnüsse“ und „Kuchen“ suchen und nichts finden.

Embeddings

Ein Embedding-Modell ist ein kleiner Verwandter eines Sprachmodells. Es schreibt nichts. Es liest einen Text und antwortet mit einer langen Liste von Zahlen, einem Vektor, der für das steht, was der Text bedeutet. Stell ihn dir als Koordinaten auf einer Karte vor, die Hunderte Richtungen hat statt zwei. Der Trick liegt darin, wie die Karte angelegt ist: Texte, die Ähnliches bedeuten, landen nah beieinander, egal mit welchen Wörtern. „Walnüsse im Kuchen für Anna“ landet nahe bei „Anna ist allergisch gegen Nüsse“ und weit weg von „Die Lampe im Flur ist orange“.

Ein Gedächtnis braucht also drei Schritte:

  1. Wenn ein Fakt gespeichert wird: seinen Vektor berechnen und beides speichern.

  2. Wenn eine Frage kommt: den Vektor der Frage berechnen.

  3. Die Fakten heraussuchen, deren Vektoren ihm am nächsten liegen.

Ollama führt auch Embedding-Modelle aus. Lad eines herunter; es ist klein:

~/projects/pixel-assistant
$ ollama pull embeddinggemma

embeddinggemma versteht über hundert Sprachen und braucht etwa 600 MB. Trag es in src/config.ts ein:

src/config.ts
/** The model that turns sentences into vectors for the memory. */
export const EMBED_MODEL = process.env.EMBED_MODEL ?? 'embeddinggemma';

Und ergänze am Ende von src/ollama.ts eine Funktion dafür; oben kommt EMBED_MODEL in den Import aus ./config.ts dazu:

src/ollama.ts
/** Turns each text into a vector: a list of numbers that stands for its meaning. */
export async function embed(texts: string[]): Promise<number[][]> {
  const response = await post('/api/embed', { model: EMBED_MODEL, input: texts });
  const data = (await response.json()) as { embeddings: number[][] };
  return data.embeddings;
}

Du schickst Texte und bekommst pro Text einen Vektor zurück, jeder eine Liste von 768 Zahlen.

Das Gedächtnis

Leg src/memory.ts an:

src/memory.ts
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { embed } from './ollama.ts';

interface Memory {
  text: string;
  /** the text as a vector, from the embedding model */
  vector: number[];
  at: string;
}

const FILE = 'memory.json';
/** How alike two texts must be to count as a hit. Print the scores and tune this for your model. */
const ALIKE = 0.5;
/** Above this, two texts say the same thing. */
const SAME = 0.9;

const memories: Memory[] = existsSync(FILE) ? JSON.parse(readFileSync(FILE, 'utf8')) : [];

const save = () => writeFileSync(FILE, JSON.stringify(memories));

/** How alike two vectors are: 1 means the same direction, 0 nothing in common. */
export function cosine(a: number[], b: number[]): number {
  let dot = 0;
  let lengthA = 0;
  let lengthB = 0;
  for (let i = 0; i < a.length; i += 1) {
    dot += a[i]! * b[i]!;
    lengthA += a[i]! ** 2;
    lengthB += b[i]! ** 2;
  }
  return dot / (Math.sqrt(lengthA * lengthB) || 1);
}

/** The memories with their likeness to the text, the most alike first. */
async function ranked(text: string): Promise<Array<{ memory: Memory; score: number }>> {
  if (memories.length === 0) return [];
  const [vector] = await embed([text]);
  return memories
    .map((memory) => ({ memory, score: cosine(vector!, memory.vector) }))
    .sort((a, b) => b.score - a.score);
}

export async function remember(text: string): Promise<void> {
  const [best] = await ranked(text);
  if (best && best.score >= SAME) return; // known already
  const [vector] = await embed([text]);
  memories.push({ text, vector: vector!, at: new Date().toISOString() });
  save();
}

/** What the memory holds about the text, at most `limit` entries. */
export async function recall(text: string, limit = 3): Promise<string[]> {
  const hits = await ranked(text);
  return hits.filter((hit) => hit.score >= ALIKE).slice(0, limit).map((hit) => hit.memory.text);
}

/** Removes the memory most like the text and returns it, or null when nothing is alike. */
export async function forget(text: string): Promise<string | null> {
  const [best] = await ranked(text);
  if (!best || best.score < ALIKE) return null;
  memories.splice(memories.indexOf(best.memory), 1);
  save();
  return best.memory.text;
}

Das Gedächtnis ist eine Liste von Fakten, jeder mit seinem Vektor, in einer Datei namens memory.json. Öffne sie, nachdem du etwas gespeichert hast: Darin steckt kein Geheimnis, nur deine Sätze und eine Menge Zahlen.

cosine misst, wie nah sich zwei Vektoren sind. Das Maß heißt Kosinus-Ähnlichkeit: Es vergleicht die Richtungen, in die zwei Vektoren zeigen. Das Ergebnis ist 1, wenn sie in dieselbe Richtung zeigen, und nahe 0, wenn die Texte nichts miteinander zu tun haben. Die Schleife multipliziert die Vektoren Zahl für Zahl und zählt alles zusammen; die Division am Ende macht das Ergebnis unabhängig davon, wie lang die Vektoren sind.

ranked vergleicht einen Text mit jeder Erinnerung und sortiert nach Ähnlichkeit. Mit allem zu vergleichen klingt verschwenderisch, aber bei den paar hundert Fakten, die ein Haushalt sammelt, dauert es deutlich weniger als eine Millisekunde. Datenbanken für Vektoren gibt es für den Tag, an dem du hunderttausend hast.

  • remember speichert einen Fakt, außer es ist schon einer da, der dasselbe sagt.

  • recall gibt die Fakten zurück, die ähnlich genug sind.

  • forget entfernt den, der am besten passt.

Zwei Wege in den Prompt

Wie kommt das Modell an das Gedächtnis? Es gibt zwei Wege, und Pixel nutzt beide.

Als Werkzeuge. Das Modell entscheidet, zu speichern, zu suchen oder zu vergessen. Leg src/tools/memory.ts an:

src/tools/memory.ts
import { say } from '../language.ts';
import { forget, recall, remember } from '../memory.ts';
import type { Tool } from '../tools.ts';

export const memoryTools: Tool[] = [
  {
    name: 'remember',
    description:
      'Stores a lasting fact about the household: names, birthdays, allergies, likes and dislikes, plans.',
    parameters: {
      type: 'object',
      properties: {
        fact: { type: 'string', description: 'the fact as one full sentence, such as "Anna is allergic to nuts."' },
      },
      required: ['fact'],
    },
    async run(args) {
      if (typeof args.fact !== 'string' || !args.fact.trim()) return { info: 'fact is missing.' };
      await remember(args.fact.trim());
      return { say: say.noted };
    },
  },
  {
    name: 'recall',
    description: 'Searches the memory for what is known about a person or a topic.',
    parameters: {
      type: 'object',
      properties: { about: { type: 'string', description: 'what to look for' } },
      required: ['about'],
    },
    async run(args) {
      const hits = await recall(String(args.about ?? ''), 5);
      return { info: hits.length ? hits.join('\n') : 'The memory holds nothing about this.' };
    },
  },
  {
    name: 'forget',
    description: 'Removes a fact from the memory.',
    parameters: {
      type: 'object',
      properties: { fact: { type: 'string', description: 'the fact to remove, roughly as it was stored' } },
      required: ['fact'],
    },
    async run(args) {
      const gone = await forget(String(args.fact ?? ''));
      return { say: gone === null ? say.nothingToForget : say.forgotten(gone) };
    },
  },
];

Die Beschreibung von remember verlangt „one full sentence“, einen ganzen Satz, mit einem Beispiel (die Beschreibungen der Werkzeuge bleiben auch im deutschen Projekt englisch, das Modell versteht sie und antwortet trotzdem auf Deutsch). Der ganze Satz ist wichtig: Ein gespeichertes „Nüsse“ ist nächste Woche nutzlos, während „Anna ist allergisch gegen Nüsse.“ immer noch alles sagt. Nimm die Werkzeuge in die Liste in src/tools.ts auf:

src/tools.ts
import { lightTools } from './tools/lights.ts';
import { memoryTools } from './tools/memory.ts';
import { timerTools } from './tools/timers.ts';
import { weatherTools } from './tools/weather.ts';

// ...

export const tools: Tool[] = [...lightTools, ...timerTools, ...weatherTools, ...memoryTools];

Ungefragt. Ein Modell, das selbst entscheiden muss, in seinem Gedächtnis zu suchen, tut es oft nicht, weil es nicht weiß, was es wissen könnte. Also schlägt Pixel selbst nach, vor jeder Anfrage, und schreibt das Gefundene in die Notiz, die du aus Teil 3 kennst. Ersetz in src/prompt.ts die Funktion contextBlock:

src/prompt.ts
/**
 * What changes from one request to the next: the date and time, a small calendar and what
 * the memory knows. It goes in front of the user's words, not into the system prompt.
 */
export function contextBlock(memories: string[] = [], now = new Date()): string {
  const lines = [`${LABELS.now}: ${day.format(now)}, ${time.format(now)}`];
  // small models are bad at counting weekdays, so the next days come ready-made
  const next = Array.from({ length: 6 }, (_, i) => day.format(new Date(now.getTime() + (i + 1) * 86_400_000)));
  lines.push(`${LABELS.nextDays}: ${next.join('; ')}`);
  if (memories.length) lines.push(`${LABELS.known}:`, ...memories.map((memory) => `- ${memory}`));
  return `[${lines.join('\n')}]`;
}

Die Beschriftungen und Sätze, in src/language.ts:

src/language.ts
/** Die Beschriftungen der Notiz, die vor jeder Anfrage steht. */
export const LABELS = {
  // ...
  known: 'Was du über den Haushalt weißt',
};

/** Die Sätze, die Pixel ohne das Modell sagt. */
export const say = {
  // ...
  noted: 'Gemerkt.',
  forgotten: (text: string) => `Vergessen: ${text}`,
  nothingToForget: 'So etwas habe ich nicht im Gedächtnis.',
};

Und in src/model.ts ergänzt du import { recall } from './memory.ts'; und ersetzt den Anfang von askModel, bis zum Ende der Liste der Nachrichten:

src/model.ts
export async function askModel(text: string): Promise<Reply | null> {
  if (!(await available())) return null;
  const signal = AbortSignal.timeout(BUDGET_MS);
  const memories = await recall(text).catch(() => []);

  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(memories)}\n${text}` },
  ];

Die Erinnerungen reisen in der Notiz am Ende des Prompts mit, zusammen mit Datum und Uhrzeit, weil sie sich von Frage zu Frage ändern. Das .catch macht das Gedächtnis optional: Fehlt das Embedding-Modell, arbeitet Pixel wie bisher und weiß einfach nichts über dich.

Dieses Muster, das Passende zur Frage zu holen und dem Modell vorzulegen, hat einen Namen, dem du überall begegnen wirst: Retrieval-Augmented Generation, kurz RAG. Genau so etwas hast du gerade gebaut.

Probier es aus

~/projects/pixel-assistant
$ npm run chatTalk to Pixel. /bye ends the chat.you> Anna ist allergisch gegen Nüsse.pixel> Gemerkt.  (model, 1480 ms)you> Meine Schwester Maria hat am 3. März Geburtstag.pixel> Gemerkt.  (model, 1390 ms)you> /bye$ npm run chatTalk to Pixel. /bye ends the chat.you> Kann ich Walnüsse in den Kuchen für Anna geben?pixel> Lieber nicht: Anna ist allergisch gegen Nüsse.  (model, 1720 ms)you> Vergiss das mit Marias Geburtstag.pixel> Vergessen: Meine Schwester Maria hat am 3. März Geburtstag.  (model, 1510 ms)you> /bye

Der erste Chat hat mit dem Werkzeug remember zwei Fakten gespeichert. Der zweite Chat ist ein neues Programm, das nichts weiß, und trotzdem wurde die Frage nach den Walnüssen richtig beantwortet: Bevor das Modell sie gesehen hat, hatte recall den Fakt über Anna gefunden und in die Notiz geschrieben. Die Wörter „Nüsse“ und „Walnüsse“ sind verschieden. Ihre Bedeutungen liegen nah beieinander.

Damit ist der Kern eines Assistenten fertig: Regeln, ein Modell mit Werkzeugen, Prüfungen und ein Gedächtnis, in weniger als tausend Zeilen, und du hast jede davon gelesen. Die übrigen Teile geben ihm einen Körper. Im nächsten Teil verlässt Pixel das Terminal und zieht in eine Seite in deinem Browser, wo du die Lampen endlich sehen kannst.

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.