Strona główna / Artykuły

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.

Wydawca: REACTAPP.TOP6 min czytania1271 słów

Ź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:

  1. 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.
  2. Z magazynu wektorowego pobierane są najbardziej podobne fragmenty. Oznacza to tutaj te trzy fragmenty, których znaczenie jest najbliższe pytaniu.
  3. 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.