Contextual Retrieval mit 80 Zeilen Code: Anthropics Chunk-Prefix-Trick im Praxischeck

Hier ist ein Ausschnitt aus einem Quartalsbericht: „Der Umsatz des Unternehmens wuchs im Vergleich zum Vorquartal um 3 %.“ Welches Unternehmen? Welches Quartal? Gewachsen wovon? Innerhalb des Berichts ergab der Satz Sinn. Herausgeschnitten, eingebettet und eigenständig indexiert trägt er nichts davon mehr, und eine Anfrage nach dem Q2-2023-Umsatz von ACME findet fast nichts, woran sie anknüpfen könnte.

Das Beispiel stammt aus Anthropics Ausarbeitung zu Contextual Retrieval, veröffentlicht am 19. September 2024. Die vorgeschlagene Lösung ist klein. Bevor man einen Chunk einbettet oder für BM25 indexiert, bittet man ein Modell, anhand des gesamten Dokuments einen kurzen Kontext dafür zu schreiben, und setzt diesen Kontext an den Anfang des Chunks. Der Chunk lautet dann: „Dieser Chunk stammt aus einem SEC-Filing zur Q2-2023-Performance von ACME corp; der Umsatz des Vorquartals lag bei 314 Millionen Dollar. Der Umsatz des Unternehmens wuchs im Vergleich zum Vorquartal um 3 %.“

Auf ihren Testmengen senkten contextual embeddings plus contextual BM25 die Top-20-Retrieval-Fehlerrate um 49 Prozent, von 5,7 % auf 2,9 %. Ein zusätzlicher Reranker brachte die Reduktion auf 67 %, also auf 1,9 %. Das sind ihre Zahlen auf ihren Daten. Dieser Beitrag liefert Ihnen Ihre eigenen: etwa 80 Zeilen Python, die Ihre Dokumente auf beide Weisen indexieren, jeden Chunk mithilfe von Prompt Caching kontextualisieren, sodass jedes Dokument nur einmal bezahlt wird, und recall@5 vor und nachher auf 30 Fragen ausgeben, die Sie selbst beschriften.

Die Kennzahl in der Ausarbeitung ist 1 minus recall@20: der Anteil relevanter Chunks, die nicht in den Top-20-Ergebnissen auftauchten. Die Testdaten umfassten Codebasen, Belletristik, ArXiv-Papiere und Wissenschaftspapiere. Die zentralen Zahlen verwendeten Gemini Text 004 Embeddings und Claude 3 Haiku zum Schreiben der Kontexte, die üblicherweise 50 bis 100 Token lang waren (gleiche Quelle).

Das begleitende Cookbook-Notebook berichtet bei k=5, näher an dem, was dieser Beitrag misst. Sein protokollierter Lauf zeigt Pass@5, das von 80,92 % auf 88,12 % steigt, allein mit contextual embeddings. Die Zusammenfassungstabelle und der Text desselben Notebooks stimmen nicht vollständig mit seiner protokollierten Ausgabe überein, was ein weiterer Grund ist, jede veröffentlichte Zahl nur als Hinweis auf die Richtung zu betrachten.

Nichts davon sagt Ihnen, ob Ihre Dokumente das Problem haben. Chunks, die auf ihre Umgebung angewiesen sind („der oben genannte Endpunkt“, „diese Einstellung“, eine Tabelle, deren Überschrift zwei Chunks weiter hinten liegt), haben am meisten zu gewinnen. Ein Ordner mit in sich geschlossenen FAQ-Einträgen bewegt sich womöglich kaum. Das finden Sie durch Messen heraus.

Anthropics Ausarbeitung von 2024 schlägt außerdem vor, dass Sie bei einer Wissensbasis von unter 200.000 Token alles in den Prompt legen und auf Retrieval verzichten.

Der ganze Trick: Der Chunk behält eine kurze Notiz darüber, woher er stammt.

Installieren Sie die vier Abhängigkeiten und setzen Sie ANTHROPIC_API_KEY und OPENAI_API_KEY:

pip install anthropic openai rank-bm25 numpy Das Skript verwendet das Anthropic Python SDK für die Kontexte, das OpenAI Python SDK für Embeddings, rank-bm25 für die Schlüsselwortsuche und NumPy für die Vektormathematik. Speichern Sie es als ctx_eval.py:

import json, re, sys import numpy as np from anthropic import Anthropic from openai import OpenAI from rank_bm25 import BM25Okapi claude, oai = Anthropic (), OpenAI () usage = { " written ": 0, " read ": 0, " uncached ": 0 } PROMPT = ( " Here is the chunk we want to situate within the whole " " document \n <chunk> \n {chunk} \n </chunk> \n " " Please give a short succinct context to situate this " " chunk within the overall document for the purposes of " " improving search retrieval of the chunk. Answer only " " with the succinct context and nothing else. " ) def chunk ( text, size = 500 ): words = text. split () return [ " ". join ( words [ i: i + size ]) for i in range ( 0, len ( words ), size )] def situate ( doc, piece ): resp = claude. messages. create ( model = " claude-haiku-5-5 ", max_tokens = 300, thinking = { " type ": " disabled " }, messages = [{ " role ": " user ", " content ": [ { " type ": " text ", " text ": f " <document> \n { doc } \n </document> ", " cache_control ": { " type ": " ephemeral " }}, { " type ": " text ", " text ": PROMPT. format ( chunk = piece )}, ]}], ) u = resp. usage usage [ " written " ] += u. cache_creation_input_tokens or 0 usage [ " read " ] += u. cache_read_input_tokens or 0 usage [ " uncached " ] += u. input_tokens return resp. content [ 0 ]. text. strip () def embed ( texts ): vecs = [] for i in range ( 0, len ( texts ), 100 ): r = oai. embeddings. create ( model = " text-embedding-3-small ", input = texts [ i: i + 100 ]) vecs += [ d. embedding for d in r. data ] return np. array ( vecs ) def toks ( s ): return re. findall ( r " \w+ ", s. lower ()) class Index: def __init__ ( self, texts ): self. vecs = embed ( texts ) self. bm25 = BM25Okapi ([ toks ( t ) for t in texts ]) def search ( self, q, k = 5, pool = 20 ): dense = np. argsort ( - ( self. vecs @ embed ([ q ])[ 0 ]))[: pool ] bm = self. bm25. get_scores ( toks ( q )) sparse = [ i for i in np. argsort ( - bm )[: pool ] if bm [ i ] > 0 ] fused = {} for ranking in ( dense, sparse ): for rank, i in enumerate ( ranking, 1 ): fused [ i ] = fused. get ( i, 0 ) + 1 / ( 60 + rank ) return sorted ( fused, key = fused. get, reverse = True )[: k ] def build ( docs, contextual ): ids, texts = [], [] for name, doc in docs. items (): for n, piece in enumerate ( chunk ( doc )): if contextual: piece = situate ( doc, piece ) + " \n\n " + piece ids. append ( f " { name } # { n } " ) texts. append ( piece ) return ids, Index ( texts ) def recall ( ids, index, qa, k = 5 ): def hit ( item ): gold = set ( item [ " gold " ]) top = { ids [ i ] for i in index. search ( item [ " q " ], k )} return len ( top & gold ) / len ( gold ) return sum ( hit ( x ) for x in qa ) / len ( qa ) if __name__ == " __main__ ": qa = json. load ( open ( sys. argv [ 1 ])) docs = { p: open ( p ). read () for p in sys. argv [ 2:]} for contextual in ( False, True ): ids, index = build ( docs, contextual ) r = recall ( ids, index, qa ) print ( f " contextual= { contextual } recall@5= { r:.

1 % } " ) print ( " prompt tokens: ", usage ) Starten Sie es mit python ctx_eval.py qa.json docs/*.md. Hier ist, was jeder Teil macht.

chunk teilt in feste 500-Wort-Fenster. Tauschen Sie Ihren produktiven Chunker ein; beide Läufe müssen nur denselben verwenden, weil die Gold-Labels auf Chunk-Positionen verweisen.

situate sendet Anthropics Kontextualisierungs-Prompt, kopiert aus dem Cookbook. Das Dokument geht in den ersten Content-Block mit cache_control, und der Chunk geht in einen zweiten Block, der nicht gecacht wird. Diese Reihenfolge ist wichtig: Der Cache deckt das Präfix bis zum markierten Block ab, daher muss das Dokument zuerst kommen. Das Modell ist Claude Haiku 5.5, bei dem thinking standardmäßig aktiviert ist. Die Thinking-Dokumentation besagt, dass Haiku 5.5 {"type": "disabled"} bei high effort oder darunter akzeptiert, und die Modelle-Übersicht listet seinen Default-Effort als medium. Das Schreiben eines einzigen Kontextsatzes braucht keine als Output abgerechneten Reasoning-Tokens.

Index.search betreibt beide Retriever. Die Dense-Seite ist ein einfaches Punktprodukt, das als Kosinusähnlichkeit funktioniert, weil OpenAI-Embeddings auf die Länge 1 normiert sind. Die BM25-Seite konvertiert selbst in Kleinbuchstaben und splittet an Wortzeichen, da rank-bm25 kein eigenes Preprocessing durchführt. Chunks mit einem BM25-Score von null werden verworfen, damit sie nicht in die Fusion einschleichen. Anthropics Ausarbeitung sagt, die beiden Ergebnismengen mit „rank fusion techniques“ zu verschmelzen, ohne eine zu nennen; daher verwendet dieser Code reciprocal rank fusion mit der Konstante k=60, die Elasticsearch standardmäßig nutzt.

build ist der Ort, an dem das Experiment lebt. Der contextual-Flag ändert den Text, der eingebettet und indexiert wird, und sonst nichts. Die Chunk-IDs bleiben in beiden Läufen gleich, sodass eine Label-Datei beide bewertet.

recall mittelt über alle Fragen den Anteil der Gold-Chunks, die in den Top 5 landen. Bei einer Frage mit einem Gold-Chunk ist das Treffer oder Fehlschlag.

Ohne Caching sendet jeder Chunk-Aufruf das gesamte Dokument erneut mit. Zehn Chunks aus einem Dokument bedeuten, dass man dieses Dokument zehnmal als Input bezahlt. Mit cache_control auf dem Dokumentblock schreibt der erste Aufruf es in den Cache, und die nächsten neun lesen es zurück.

Die Prompt-Caching-Dokumentation preist einen 5-Minuten-Cache-Schreibvorgang mit dem 1,25-fachen des Basis-Inputs und einen Cache-Lesevorgang mit dem 0,1-fachen. Auf der Preisseite Stand Oktober 2026 kostet Claude Haiku 5.5 für Prompts bis 100.000 Token 0,10 Dollar pro Million Input-Token, 0,125 Dollar für 5-Minuten-Cache-Schreibvorgänge, 0,01 Dollar für Cache-Treffer und 0,50 Dollar für Output. Prompts über 100.000 Token wechseln zu einem fünfmal höheren Satz, daher kosten sehr lange Dokumente mehr pro Chunk.

Einige Rechnungen dazu, in der Form, die Anthropic für seine eigene Schätzung verwendete: ein 8.000-Token-Dokument, zehn 800-Token-Chunks, etwa 50 Token Anweisungen und 100 Token generierter Kontext pro Chunk. Mit Caching sind das grob 0,001 Dollar für den einen Cache-Schreibvorgang, 0,0007 Dollar für neun Cache-Lesevorgänge, 0,0009 Dollar für den nicht gecachten Chunk-Text und 0,0005 Dollar für Output. Etwa 0,003 Dollar pro Dokument, also rund 0,38 Dollar pro Million Dokument-Token. Ohne Caching kostet derselbe Auftrag grob 1,17 Dollar pro Million. Das ist meine Rechnung auf Basis der Listenpreise, keine gemessene Abrechnung. Anthropics Zahl von 2024 für dieselbe Konstellation lag bei 1,02 Dollar pro Million Dokument-Token, auf Basis der Claude 3 Haiku Preise.

Einmal schreiben, viele guenstige Lesezugriffe: Das Dokument wird zwischengespeichert und jeder Chunk-Aufruf verwendet es erneut.

Drei Details aus der Caching-Dokumentation entscheiden darueber, ob Sie diese Lesezugriffe tatsaechlich erhalten:

Die Zeile mit den Prompt-Tokens am Ende verraet Ihnen, wie es in Ihrem Durchlauf gelaufen ist. Zum Vergleich: Die Aufnahme von 737 Chunks im Cookbook selbst meldete, dass 61,83 Prozent aller Eingabe-Tokens aus dem Cache gelesen wurden, weniger als die 70 bis 80 Prozent, die der Fliesstext suggeriert. Lesen Sie Ihre Zaehler, bevor Sie der Schaetzung irgendjemandes vertrauen, auch der obigen.

Die Zahl, die dieses Skript ausgibt, ist nur so ehrlich wie die Datei qa.json. Um etwas zu labeln, muessen Sie zunaechst die Chunk-IDs sehen. Ein Helfer, der denselben Chunker wiederverwendet:

import sys from ctx_eval import chunk for path in sys. argv [ 1:]: for n, piece in enumerate ( chunk ( open ( path ). read ())): print ( f " { path } # { n } \t { piece [: 90 ] } " ) Enter fullscreen mode Exit fullscreen mode Das Importieren von ctx_eval erzeugt beide API-Clients, lassen Sie also die Umgebungsvariablen gesetzt. Schreiben Sie dann die Label-Datei:

[ { "q": "How long do refunds take on annual plans?", "gold": [ "docs/billing.md#3" ]}, { "q": "Which header carries the idempotency key?", "gold": [ "docs/api.md#7", "docs/api.md#8" ]} ] Enter fullscreen mode Exit fullscreen mode Einige Regeln verhindern, dass der Satz einen der beiden Durchlaeufe schmeichelt:

Bei 30 Fragen ist jede einzelne etwa 3,3 Punkte von recall@5 wert. Eine Differenz von ein bis zwei Fragen zwischen den Durchlaeufen liegt innerhalb des Rauschens. Schauen Sie sich daher neben den Summen auch die Wechsel an. Innerhalb des __main__-Blocks gibt das Skript nach jedem Aufbau einen Treffer oder Misserfolg pro Frage aus:

for item in qa: top = { ids [ i ] for i in index. search ( item [ " q " ])} print ( bool ( top & set ( item [ " gold " ])), item [ " q " ][: 60 ]) Enter fullscreen mode Exit fullscreen mode Fragen, die vom Misserfolg zum Treffer wechseln, zeigen Ihnen, wo der Praefix geholfen hat. Fragen, die vom Treffer zum Misserfolg wechseln, verdienen eine genaue Lektuere: Wenn jeder Chunk eines Dokuments einen aehnlichen Einstiegssatz erhaelt, koennen diese Chunks fuer den Retriever aehnlich aussehen.

Bewegt sich recall@5 kaum, ist das ein echtes Ergebnis. Ihre Chunks sind moeglicherweise bereits in sich abgeschlossen, oder Ihre Baseline ist bereits hoch, und Sie haben sich einfach eine Indexierungsschritte bei jeder Dokumentaktualisierung gespart.

Bewegt sich der Wert, nennt Anthropics Ausfuehrung die naechsten Hebel. Sie haben durch das Abrufen der Top 150 und das Verengen auf 20 mit einem Cohere-Reranker neu sortiert, daher stammt die Zahl von 67 Prozent. Sie haben uebergeben von 5, 10 und 20 Chunks getestet und fanden, dass 20 fuer sie am besten funktionierte, wiesen die Leser aber gleichzeitig an, dies an ihrem eigenen Anwendungsfall zu pruefen. Sie empfehlen zudem einen contextualizer prompt, der auf Ihre Domain zugeschnitten ist, etwa einen, der ein Glossar von Begriffen enthaelt, die an anderer Stelle der Knowledge Base definiert sind. Aendern Sie jeweils nur einen Hebel und fuehren Sie dieselben eingefrorenen 30 Fragen erneut aus.

Behalten Sie die Indexierungskosten im Blick, sobald dies ueber ein Experiment hinausgeht. Kontexte werden zur Indexierungszeit aus dem gesamten Dokument erzeugt, sodass sich bei einer Aenderung eines Dokuments der Kontext seiner Chunks veralten kann. Kontextualisieren Sie das gesamte Dokument neu, nicht nur den bearbeiteten Chunk.

Das Skript ist das Messinstrument; die Entscheidungen drumherum, wie Sie chunking betreiben, wann hybride Suche besser ist als rein dichte Suche und wann sich ein Reranker seine Latenzzeit verdient, behandelt der RAG Pocket Guide unter seinem Untertitel ueber Retrieval-, Chunking- und Reranking-Muster fuer die Produktion. Fuehren Sie zuerst die 30 Fragen aus und waehlen Sie dann das Kapitel, das zu den Misserfolgen passt.