Tworzenie asystenta do dokumentacji typu RAG dla API przy użyciu LlamaIndex
Stwórz asystenta do dokumentacji API przy użyciu LlamaIndex: załaduj pliki Markdown, podziel je na fragmenty za pomocą SentenceSplitter, wzbogac dane embeddingami, przechowaj je w Chromie i przeprowadzaj zapytania za pomocą RAG QueryEngine.
Źródła: Building a RAG-Powered API Documentation Assistant with LlamaIndex (Part 1: Components)
Konfigurujesz nowy API do płatności. Otwierasz dokumentację, naciskasz Ctrl+F, wpisujesz „refund” i znajdujesz dwanaście wyników rozproszonych na czterech stronach, z których połowa jest bezwartościowa, ponieważ jedynie wspomina to słowo. Po kwadransie znajdujesz punkt wejścia, ale tracisz wątek tego, co robiłeś.
A teraz wyobraź sobie wpisanie „Jak wystawić zwrot pieniędzy?” i otrzymanie jasnej odpowiedzi bezpośrednio z dokumentacji. To jest cel: mały asystent dla fikcyjnego API e-commerce o nazwie ShopSphere. Nie korzysta on z ogólnej wiedzy modelu językowego ani nie wymyśla odpowiedzi. Szuka w rzeczywistej dokumentacji ShopSphere i odpowiada na podstawie niej. LlamaIndex wykonuje ciężką pracę, a każdy element jest w miarę postępów wyjaśniany, włączając te fragmenty, gdzie framework może sprawiać wrażenie magii.
Problem, który ma zostać rozwiązany
Modele językowe wiedzą wiele o świecie, ale nic o dokumentacji API twojej firmy. Wklejanie setek stron do każdego zapytania byłoby powolne, kosztowne i chaotyczne. Lepszym rozwiązaniem jest najpierw znalezienie odpowiednich fragmentów, a następnie poproszenie modelu o udzielenie odpowiedzi na ich podstawie. Gdy ktoś pyta, jak złożyć zamówienie, system lokalizuje sekcję dotyczącą tworzenia zamówień, a ten tekst trafia do modelu wraz z pytaniem.
Tą techniką jest Retrieval-Augmented Generation (RAG): najpierw pozyskiwanie informacji, potem ich wykorzystanie do generowania odpowiedzi. Wszystko poniżej dotyczy budowy mechanizmu pozyskiwania danych oraz umożliwienia agentowi wyboru odpowiednich informacji lub narzędzi.
Cztery koncepcje w LlamaIndex
To narzędzie organizuje wszystko wokół czterech koncepcji, dzięki czemu przestaje przypominać labirynt nazw klas. Przydatnym porównaniem może być mała kuchnia restauracyjna:
- Komponenty to składniki i urządzenia: piekarnik, lodówka, mąka. Są to surowe możliwości.
- Narzędzia to przepisy przyklejone do urządzeń, napisane w taki sposób, aby nowy kucharz mógł je wykonać bez zadawania pytań.
- Agenci to szef kuchni, który decyduje, który przepis użyć i w jakiej kolejności, krok po kroku, na podstawie tego, czego chce klient.
- Przepływy pracy to wydrukowane karty z przepisami, używane wtedy, gdy nie chce się improwizować i potrzeba stałej sekwencji do stosowania za każdym razem.
Asystent jest tworzony poprzez ułożenie tych czterech elementów w tej kolejności.
Komponenty: przekształcanie dokumentów Markdown w bazę wiedzy do wyszukiwania
To jest etap przygotowawczy. Zanim rozpocznie się jakikolwiek proces rozumowania, pięć plików dokumentacyjnych (autoryzacja, produkty, zamówienia, błędy i webhooki) musi być w formie, którą komputer może wyszukiwać na podstawie znaczenia, a nie tylko słów kluczowych. Wymaga to pięciu kroków.
Krok 1: ładowanie
from llama_index.core import SimpleDirectoryReader
def load_documents():
reader = SimpleDirectoryReader(input_dir="data", required_exts=[".md"])
documents = reader.load_data()
return documents
Czytelnik otwiera każdy plik Markdown w folderze data/ i umieszcza go w obiektach typu Document, których LlamaIndex używa do reprezentowania tekstu wraz z informacjami o jego pochodzeniu. Część dotycząca pochodzenia jest bardziej przydatna, niż się wydaje – oryginalna nazwa pliku jest przechowywana jako metadane, dzięki czemu asystent może później stwierdzić, że informacja pochodzi z pliku takiego jak 03-cart-orders.md, bez konieczności ręcznego prowadzenia rejestrów.
Krok 2: dzielenie na fragmenty
Jednym z problemów jest to, że plik 03-cart-orders.md zawiera informacje o koszykach zakupowych, procesie płatności, zamówieniach, zwrotach pieniędzy oraz anulowaniach w jednym dokumencie. Traktowany jako pojedyncza, wyszukiwalna jednostka, mógłby odpowiedzieć na pytanie o zwrot pieniędzy, podając niepowiązane szczegóły dotyczące anulowań. Dlatego każdy dokument jest dzielony na mniejsze fragmenty, które LlamaIndex nazywa węzłami, podobnie jak przekształcanie książki w stertę kart indeksowych, z których każda pamięta o swojej książce.
from llama_index.core.node_parser import SentenceSplitter
splitter = SentenceSplitter(chunk_size=400, chunk_overlap=40)
Bezrefleksyjne dzielenie co 400 znaków może rozciąć zdanie na pół lub, co gorsza, przerwać komendę curl. SentenceSplitter zamiast tego szuka naturalnych granic zdań. Niewielkie przenikanie się o 40 znaków sprawia również, że koniec jednego fragmentu powtarza się na początku następnego, dzięki czemu powiązane elementy, takie jak przykład kodu i zdanie go opisujące, pozostają razem.
Krok 3: embedding
Poszukiwanie według znaczenia zależy od tego kroku. Każdy fragment przechodzi przez model embedding, który mapuje tekst na długi zestaw liczb, zwany wektorem. Fragmenty o podobnym znaczeniu trafiają na podobne wektory, nawet jeśli użyte słowa są zupełnie inne.
Użytkownik może zapytać: „Jak odzyskać swoje pieniądze?”, podczas gdy w dokumentacji znajduje się sekcja z tytułem „Wydaj zwrot pieniędzy”. Te dwa zdania nie zawierają żadnych wspólnych słów o znaczeniu, ale wyrażają tę samą ideę. Model embeddingowy rozpoznaje ten związek, dzięki czemu wyszukiwanie semantyczne może pokazać dokumentację dotyczącą zwrotu pieniędzy.
from llama_index.embeddings.huggingface import HuggingFaceInferenceAPIEmbedding
embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-en-v1.5",
)
Krok 4: przechowywanie embeddingów
Wbudowanie embeddingów do każdego fragmentu tekstu zajmuje czas i może generować koszty poprzez wywołania API, a nikt nie chce tego robić przy każdym uruchomieniu. Dlatego wektory trafiają do bazy danych wektorowej, którą można ponownie wykorzystać. W tym przypadku jest to Chroma – bezpłatna lokalna baza danych ułatwiająca przechowywanie i wyszukiwanie embeddingów.
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 może połączyć kroki 2 do 4 w jeden proces, IngestionPipeline. Definiuje się etapy tylko raz, a każdy dokument przechodzi przez nie automatycznie – jest dzielony, wstawiany, a następnie zapisywany do Chromy.
from llama_index.core.ingestion import IngestionPipeline
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=400, chunk_overlap=20),
embed_model
],
vector_store=vector_store,
)
Zainstaluj go raz, a trwały, wyszukiwalny indeks zostanie utworzony w folderze chroma_db. Musi być ponownie utworzony tylko wtedy, gdy zmienią się dokumenty.
Krok 5: wyszukiwanie
Teraz następuje efekt końcowy. Przechowywane wektory są umieszczone w strukturze VectorStoreIndex, która staje się QueryEngine – obiektem, do którego faktycznie kierujemy zapytania:
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?")
Gdy przychodzi pytanie, dzieje się trzy rzeczy:
- Pytanie staje się wektorem, wykorzystującym ten sam model embeddingu co przy procesowaniu danych. Jest to istotne, ponieważ pytanie oraz fragmenty tekstu muszą znajdować się w tym samym przestrzeni wektorowej. To tak, jakby mierzyć wszystko w jednej jednostce – mieszanie cali i centymetrów sprawia, że porównania tracą sens.
- Z magazynu wektorowego pobierane są najbardziej podobne fragmenty. Oznacza to tutaj te trzy fragmenty, których znaczenie jest najbliższe pytaniu.
- Ty fragmenty trafiają do modelu LLM jako kontekst, a model tworzy swoją odpowiedź na ich podstawie, zamiast polegać wyłącznie na danych treningowych.
To jest kompletny pipeline RAG, który sam w sobie już jest przydatny. Może jednak wykonywać tylko jedną czynność: pobierać informacje, a następnie odpowiadać. Nie ma możliwości stwierdzenia, że konkretne pytanie wymaga innego wyszukiwania – do tego potrzebne są dodatkowe narzędzia i agent.
Ruch własnoręczny
Gotowy projekt można sklonować i uruchomić lokalnie. Utwórz środowisko wirtualne, zainstaluj wymagane pakietów i wklej token Hugging Face do pliku .env:
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
Co następuje
W tym momencie istnieje działający silnik wyszukiwania dla dokumentacji, ale może on jedynie przeszukiwać i odpowiadać. Kolejny etap dostarcza asystentowi narzędzia i pozwala agentowi zdecydować, które z nich użyć. Ujawnia on również część procesów LlamaIndex Workflows, która na początku wydaje się magiczna: sposób, w jaki proces wie, który krok powinien zostać wykonyany dalej.