Startseite / Artikel

Entwicklung eines RAG-Dokumentations-Assistenten für eine API mit LlamaIndex

Erstelle einen API-Dokumentations-Assistenten mit LlamaIndex: Lade Markdown-Dokumente, teile sie mit SentenceSplitter in Abschnitte auf, embede die Inhalte, speichere sie in Chroma und stelle Anfragen mit einem RAG QueryEngine.

Verlag: REACTAPP.TOP6 Min. Lesezeit1271 Wörter

Quellen: Building a RAG-Powered API Documentation Assistant with LlamaIndex (Part 1: Components)

Man setzt eine neue Zahlungs-API ein. Man öffnet die Dokumentation, drückt Ctrl+F, gibt „Rückerstattung“ ein und erhält zwölf Treffer auf vier Seiten, von denen die Hälfte irrelevant ist, weil dort lediglich das Wort erwähnt wird. Nach einer Viertelstunde hat man schließlich den Endpunkt gefunden, doch man hat den Überblick darüber verloren, was man ursprünglich tun wollte.

Stellen Sie sich nun vor, man tippt „Wie stelle ich eine Rückerstattung aus?“ ein und erhält direkt aus der Dokumentation eine klare Antwort. Das ist das Ziel hier: ein kleiner Assistent für eine fiktive E-Commerce-API namens ShopSphere. Er stützt sich nicht auf das allgemeine Wissen des Sprachmodells oder erfindet eine Antwort, sondern durchsucht die echten ShopSphere-Dokumentationen und gibt Antworten daraus. LlamaIndex übernimmt die schwierige Arbeit, wobei jeder Schritt erklärt wird – einschließlich der Stellen, an denen das Framework wie Magie wirken kann.

Das zu lösende Problem

Sprachmodelle wissen viel über die Welt, aber nichts über die API-Dokumentation Ihres Unternehmens. Hunderte von Seiten in jeden Prompt einzufügen, wäre langsam, teuer und unübersichtlich. Ein besseres Vorgehen besteht darin, zunächst die relevanten Abschnitte zu finden und das Modell anschließend dazu aufzufordern, daraus zu antworten. Wenn jemand fragt, wie ein Auftrag erstellt wird, findet das System den Abschnitt zur Erstellung von Aufträgen, und dieser Text gelangt zusammen mit der Frage zum Modell.

Diese Technik heißt Retrieval-Augmented Generation (RAG): Zuerst Informationen abrufen, dann generieren. Alles Weitere bezieht sich auf den Aufbau des Informationsabrufteils sowie darauf, einem Agenten schließlich die Wahl zu ermöglichen, welche Informationen oder Werkzeuge verwendet werden sollen.

Vier Konzepte in LlamaIndex

Das Framework organisiert alles um vier Konzepte herum, und sobald man diese versteht, sieht es nicht mehr wie ein Labyrinth aus Klassennamen aus. Eine kleine Restaurantküche liefert dazu einen nützlichen Vergleich:

  • Komponenten sind Zutaten und Geräte: der Ofen, der Kühlschrank, das Mehl. Es handelt sich dabei um rohe Fähigkeiten.
  • Werkzeuge sind Rezepte, die an den Geräten befestigt sind und so formuliert sind, dass ein neuer Koch sie ohne Fragen befolgen kann.
  • Agenten sind der Koch, der für jeden Auftrag entscheidet, welches Rezept und in welcher Reihenfolge verwendet werden soll, basierend auf dem Wunsch des Kunden.
  • Arbeitsabläufe sind die ausgedruckten Rezeptkarten, die verwendet werden, wenn keine Improvisation gewünscht ist und jederzeit eine feste Reihenfolge eingehalten werden muss.

Der Assistent wird durch das Stapeln dieser vier Elemente in dieser Reihenfolge erstellt.

Komponenten: Markdown-Dokumente in eine suchbare Wissensbasis umwandeln

Dies ist die Vorbereitungsphase. Bevor mit der Logikverarbeitung begonnen werden kann, müssen fünf Dokumentationsdateien (Authentifizierung, Produkte, Bestellungen, Fehler und Webhooks) in einer Form vorliegen, die von einem Computer nach Inhalt gesucht werden kann – und nicht nur nach Schlüsselwörtern. Dafür sind fünf Schritte erforderlich.

Schritt 1: Laden

from llama_index.core import SimpleDirectoryReader

def load_documents():

    reader = SimpleDirectoryReader(input_dir="data", required_exts=[".md"])
    documents = reader.load_data()
    return documents

Der Leser öffnet jede Markdown-Datei im Ordner data/ und umhüllt jede davon mit einem Document – LlamaIndex’s Repräsentation eines Textes zusammen mit Informationen über seine Herkunft. Der Herkunftsanteil ist nützlicher, als es auf den ersten Blick scheint. Der ursprüngliche Dateinamen wird als Metadaten beibehalten, sodass der Assistent später antworten kann, dass die Informationen von einer Datei wie 03-cart-orders.md stammen, ohne manuelle Aufzeichnungen vornehmen zu müssen.

Schritt 2: Teilung in Blöcke

Ein Problem: 03-cart-orders.md enthält alle Informationen zu Warenkörben, Bestellvorgängen, Rückerstattungen und Stornierungen in einer einzigen Datei. Wenn diese als eine einzige suchbare Einheit behandelt wird, könnte sie auf eine Frage zur Rückerstattung mit irrelevanten Details zu Stornierungen antworten. Deshalb wird jede Dokumente in kleinere Teile aufgeteilt, die LlamaIndex als Knoten bezeichnet – ähnlich wie ein Buch in einen Stapel Indexkarten umgewandelt wird, von denen jede noch an ihr ursprüngliches Buch erinnert.

from llama_index.core.node_parser import SentenceSplitter

splitter = SentenceSplitter(chunk_size=400, chunk_overlap=40)

Das blinde Abschneiden alle 400 Zeichen könnte einen Satz in zwei Teile teilen oder, noch schlimmer, einen curl-Befehl unterbrechen. SentenceSplitter sucht stattdessen nach natürlichen Satzgrenzen. Eine kleine Überlappung von 40 Zeichen führt außerdem dazu, dass das Ende eines Abschnitts am Anfang des nächsten wiederholt wird, wodurch zusammengehörige Inhalte wie ein Codebeispiel und der dazu gehörende Erklärungssatz zusammenbleiben.

Schritt 3: Embedding

Die suchende Verarbeitung nach Bedeutung hängt von diesem Schritt ab. Jeder Abschnitt wird durch ein Embedding-Modell geführt, das den Text in eine lange Liste von Zahlen umwandelt, die als Vektor bezeichnet werden. Abschnitte mit ähnlicher Bedeutung landen auf ähnlichen Vektoren – auch dann, wenn die verwendeten Wörter völlig unterschiedlich sind.

Ein Benutzer könnte fragen: „Wie bekomme ich mein Geld zurück?“, während in den Dokumenten ein Abschnitt mit dem Titel „Rückerstattung beantragen“ vorhanden ist. Die beiden Aussagen enthalten keine gemeinsamen Schlüsselwörter, drücken aber dieselbe Idee aus. Das Embedding-Modell erkennt diese Verbindung, sodass die semantische Suche die Dokumentation zur Rückerstattung anzeigen kann.

from llama_index.embeddings.huggingface import HuggingFaceInferenceAPIEmbedding

embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-en-v1.5",
)

Schritt 4: Speichern der Embeddings

Das Einbetten jedes Teilsatzes dauert Zeit und kann durch API-Aufrufe Kosten verursachen – niemand möchte das bei jedem Neustart wiederholen. Deshalb werden die Vektoren in eine Vektordatenbank gespeichert, die wiederverwendet werden kann. In diesem Fall handelt es sich um Chroma, eine kostenlose lokale Datenbank, die das Speichern und Suchen von Embeddings erleichtert.

import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore

db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("shopsphere_api_docs")
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)

LlamaIndex kann die Schritte 2 bis 4 in einen einzigen Prozess, nämlich IngestionPipeline, zusammenfassen. Definieren Sie die Phasen einmal – jedes Dokument durchläuft sie automatisch, wird dabei aufgeteilt, eingebettet und anschließend in Chroma geschrieben.

from llama_index.core.ingestion import IngestionPipeline

pipeline = IngestionPipeline(
        transformations=[
            SentenceSplitter(chunk_size=400, chunk_overlap=20),
            embed_model
        ],
        vector_store=vector_store,
    )

Führen Sie es einmal aus, und ein langlebiger, suchbarer Index wird in der chroma_db-Ordner erstellt. Er muss nur dann neu erstellt werden, wenn sich die Dokumente ändern.

Schritt 5: Abfragen

Nun kommt der Vorteil zum Tragen. Die gespeicherten Vektoren sind in einem VectorStoreIndex eingebettet, der wiederum zu einer QueryEngine wird – dem Objekt, an das Sie tatsächlich Fragen richten:

from llama_index.core import VectorStoreIndex

index = VectorStoreIndex.from_vector_store(vector_store, embed_model=embed_model)
query_engine = index.as_query_engine(llm=llm, similarity_top_k=3)
query_engine.query("How do I create a new order?")

Drei Dinge geschehen, wenn eine Frage eintrifft:

  1. Die Frage wird zu einem Vektor, wobei dasselbe Embedding-Modell wie bei der Eingabe verwendet wird. Das ist wichtig, weil Frage und Frageteile im selben Vektorraum vorhanden sein müssen. Es ist, als würde man alles in derselben Einheit messen – schließlich macht das Mischen von Zoll und Zentimetern Vergleiche sinnlos.
  2. Die am ähnlichstenen Frageteile werden aus dem Vektorlager abgerufen. Das bedeutet hier die drei Frageteile, deren Bedeutung der Frage am nächsten kommt.
  3. Diese Frageteile werden dem LLM als Kontext übergeben, und das Modell formuliert seine Antwort daraufhin, anstatt sich ausschließlich auf Trainingsdaten zu stützen.

Das ist ein vollständiger RAG-Pipeline, und allein schon ist sie nützlich. Sie kann jedoch nur eine Sache tun: Informationen abrufen und anschließend antworten. Sie verfügt nicht über die Möglichkeit, festzustellen, dass eine bestimmte Frage eine andere Abfrage erfordert. Dafür sind Tools und ein Agent notwendig.

Selbst ausführen

Das fertige Projekt kann geklont und lokal ausgeführt werden. Erstellen Sie eine virtuelle Umgebung, installieren Sie die erforderlichen Pakete und fügen Sie einen Hugging Face-Token in die .env-Datei ein:

git clone https://github.com/H11199/API-Documentation-Agent.git
cd API-Documentation-Agent

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1

pip install -r requirements.txt

cp .env.example .env             # then paste your HF token in as HF_TOKEN=hf_...

python ingestion_pipeline.py     # builds the index from the sample docs in data/
python app.py                    # chat with the assistant

Was kommt als Nächstes

Zurzeit gibt es bereits eine funktionierende Suchmaschine für die Dokumentation, doch sie kann nur Daten abrufen und Antworten liefern. In der nächsten Phase erhält der Assistent Werkzeuge, wodurch ein Agent entscheiden kann, welche davon verwendet werden sollen. Zudem wird ein Teil der LlamaIndex Workflows sichtbar, der anfangs wie Magie wirkt: Wie ein Workflow erkennt, welcher Schritt als Nächstes ausgeführt werden sollte.