RAG-асістэнт па дакументацыі API на LlamaIndex
Будуем асістэнта па дакументацыі API на LlamaIndex: загружаем Markdown, разбіваем праз SentenceSplitter, робім эмбедынгі, захоўваем у Chroma і пытаемся праз RAG QueryEngine.
Крыніцы: Building a RAG-Powered API Documentation Assistant with LlamaIndex (Part 1: Components)
Вы ствараеце новы API для платэжаў. Вы ачынаеце дасяглівы, нажымаеце Ctrl+F, пісваеце „refund“ і атрымляеце дванаццац рэзультатаў на чатыро стораніцы; палова з іх неактуальныя, таму што толькі згадваюць гэта слова. Чэрэз чверць гадзіны вы знаходзіце неабходны элемент, але забываеце, чым саме займаліся.
Цяпер уявіце, што вы пісваеце „Як выдаты вярненне?“ і атрымляеце чыстае, яснае адказа прымусова з дасяглівых. Гэта і ёсць мета: маленькі асістэнт для вымышленага API для е-камеры пад назвай ShopSphere. Ён не паводзіцца на загальныя знанні мовнага модэлю і не выдумвае адказаў. Ён шукае рэальныя дасяглівы ShopSphere і адпавядае на пытанні на ўсходзе з іх. LlamaIndex выконвае важкую работу, а кожны элемент адпаведзення пояснюецца, укладаючыся ў тое, дзе фрэймворк можа здавацца чымсь чародзкім.
Проблема, якая рашаецца
Мадэлі мовы ведаюць багато пра свет, але нічога пра дапаможнік API вашай компаніі. Калі копіюваць сотні стороніцаў у кожны запіт, гэта будзе медленна, дорога і спрычыніць занадто большую колькасць даных. Лепшы план — спачатку знайсці неабходныя фрагменты, а потым папросіць мадэль дастаць адпаведныя адказы на адповіднае пытанне. Калі хтось запітвае, як стварыць замовленне, сістэма знаходзіць раздзел пра стварэнне замовленняў, і гэты тэкст разам з пытаннем падае мадэлі.
Гэтыя методы называюцца Retrieval-Augmented Generation (RAG): спачатку выкарыстоўваецца механізм пошуку, а потым — генераванне. Усё, што пасля гэтага, стосуецца стварэння часткі сістэмы для пошуку і, ў канцэ наступнае, дазволу агенту выбраць, якую інфармацыю чы засоб прыменіць.
Чатыры ідэі ў LlamaIndex
Этая платформа організуе ўсё навакол чатырох канцэпцый, і як толькі ўсе ўсвядомляюць гэта, яна перастае выглядаць як лабірынт імен класаў. Маленькая кухня рэсторана ёсць добрым прыкладам для параджэння:
- Компаненты — гэта інгрэнты і прылады: печ, холадзік, мука. Гэта первасныя можлівасці.
- Інструменты — гэта рэцепты, прыкрыпленыя да прыладаў, напісаныя так, каб новы кухар мог ужоўваць іх без запытанняў.
- Агенты — гэта шафар, які рашае, які рэцепт і ў какой последоўнасці выкорыстаць, на адной засадзе таго, чаго хоча кліент.
- Працэсы — гэта распісаныя карточкі рэцептав, якія вікорыстоўваюцца, калі не хочаце імпровізаваць і патрэбна фіксованая последоўнасць кожны раз.
Падрабнік ствараецца паўтарэнням гэтых чатырох элементаў у такой самай последоўнасці.
Компаненты: ператварэнне дакументаў у фармаце Markdown у базу знаёмых, якую можна шукаць
Гэта ўраджэнняя стадыя. Перш чым пачнёцца які-лебе аналіз, пяць файлаў дакументацыі (аутантыкацыя, продукты, замовленні, каштанкі і webhooks) павінны быць у такой форме, каб камп’ютар могаў іх шукаты па значэнні, а не толькі па ключоўым слову. Для гэтага трэба пяць крокаў.
Крок 1: завантажэнне
from llama_index.core import SimpleDirectoryReader
def load_documents():
reader = SimpleDirectoryReader(input_dir="data", required_exts=[".md"])
documents = reader.load_data()
return documents
Чытач адкрывае кожны файл у фармаце Markdown у папцы data/ і абгружае кожны з яго ў об’ект Document — фармат, які вікорыстоўвае LlamaIndex для прэдставлення тэксту плюс інфармацыі пра яго выхадны джэрэла. Частка, якая апісвае джэрэла, ўжоць карыстная, чым здаецца. Автэнтычны назыв файлу застаёцца як метаданы, таму калі асістэнт пазней даўа адказ, ён можа сказаць, што інфармацыя падышла з кантэксту файлу 03-cart-orders.md, без неабяжнай ручной фіксацыі.
Шаг 2: разбіўка на часткі
Адна з проблем: файл 03-cart-orders.md аб’еднвае інфармацыю пра кошыкі, працэс адплатаў, замовленні, вярненні грошаў і анулюваннях у ўсём у одны файл. Калі яго спрыятаць як адну елементарную еўрэку для пошуку, ён можа даць адказ на пытанне пра вярнення грошаў, адмаўляючы несувязаныя дэталі анулювання. Таму кожны документ разбіваецца на меншыя часткі, якія LlamaIndex называе вузламі; гэта супадае з ператварэнням кнігі ў стос картак, кожная з якіх памятае пра свайной кнізе.
from llama_index.core.node_parser import SentenceSplitter
splitter = SentenceSplitter(chunk_size=400, chunk_overlap=40)
Розрызання тэксту кожні 400 сімволів можа роздыліты рэчэння навпіл або, што гіршэ, перэрваты команду curl. SentenceSplitter замест гэтага шукае прыродні межы рэчэнь. Невелікій перэкрытця у 40 сімволів таксама дозволяе повторыты кінець одніеі частыні на початку наступноі, што допомагае зберэгты пов’язаній матэрыал разом — напрыклад, кодовій прыклад і рэчэння, якое яго пояснюе.
Крок 3: ембеддынг
Пошук за значэнням залежыць ад гэтага кроку. Кожна частына тэксту проходыць праз мадэль ембеддынгів, якая перэтворуе тэкст у довгій спіс чысел — вектор. Фрагменты з схожым значэнням опіняюцца у схожых векторах, навіць калі вікорыстані слова абсолютно рызні.
Вядома адміністрацыя можа запытаць: «Як мне адзначыць грошы назад?», тады калі ў дасяглівых матэрыялах ёсць раздзіл пад назвай «Выдача вярнення». У гэтых двух фразах няма спаканых слоў, але яны выражаюць адно і тое ж падзея. Мадэль аналізу тэксту фіксуе гэты зв’язак, таму семантычны пошук можа паказаць дасяглівыя матэрыялы пра вярнення грошаў.
from llama_index.embeddings.huggingface import HuggingFaceInferenceAPIEmbedding
embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-en-v1.5",
)
Крок 4: зберагчыце падставы
Падстава кожнага фрагмента трывае час і можа коштаць грошы за дзвянкі API, і ніхто не хоча практыкуваць гэта ў кожны раз, калі запускае програму. Таму вектары зберагаюцца ў базе дадзеных вектароў, якая можа быць перыіскораная. У гэтым случыку гэта Chroma — безкоштовная локальная база дадзеных, якая спрыяе простам зберагчыцю і пошуку падстав.
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 можа адгрупаваць крокі 2-4 ў адзін працэс – IngestionPipeline. Заадрэсаваўшы этапы аднойчы, кожны документ автаматычна праходзіць праз яе, практычна дзеля роздзелення, вбудоввання, а пасля – запісу ў Chroma.
from llama_index.core.ingestion import IngestionPipeline
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=400, chunk_overlap=20),
embed_model
],
vector_store=vector_store,
)
Заўёршыце ўвядзенне адной раз, і ў папке chroma_db будзе створаны надзейны, можна шукаць індэкс. Яго трэба перзаснаваць толькі тады, калі змянююцца дакументы.
Шаг 5: запіты
Цяпер наступае гэта самае важлівая частка. Сохраненыя вектары ўкладаюцца ў VectorStoreIndex, які становіць QueryEngine — аб’ект, да якога вы насправды задаеце запіты:
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?")
Калі прыходзіць запіт, выдзейваецца троха рэчаў:
- Запіт становіцца векторам, выкарыстоўваючы той жа мадэль эмбедынгу, што і пад час прыемкі даных. Гэта важна, таму што запіт і фрагменты даных павінны знаходзіцца ў там самым вектарным прасторэ. Гэта як мерканне всьго ў одной едыніцы — адныя разы выкарыстоўваюцца дзюймы, а іншыя сантыметры, і тады параболіка стае беззначнаю.
- Выбіраюцца самыя супадзельныя фрагменты з хранілішча вектораў. У нашым случае гэта тры фрагменты, значэнне якіх наіболей блізкае да запіту.
- Этыя фрагменты падаюць у LLM як кантэкст, і мадэль пішае свой адказ на ўснове іх, а не толькі на базе дадзеных з трэнавання.
Гэта ўсё, што трэба для праграмы RAG, і сама по сабе яна вельмі прыдатная. Аднак яна можа выконваць толькі адну задачу: запрашаць інфармацыю, а потым даваць адказ. У яе няма можлівасці з’ясавіць, чы рэшэння певнага запіту вымагае іншага пошуку. Для гэтага патрэбны дадзеныя і спецыяльны агент.
Выконанне самостойна
Готовы праект можна клонаваць і запускаць локальна. Створыце віртуальную срэду, установіце неабяжлівыя компоненты і запішыце токен Hugging Face у файл .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
Што будзе далей
На даны момент існуеячы рэшучык для дасягління інфармацыі ў дакументацыі, але ён толькі знаходзіць і адпавядае. Наступны этап даёт асістэнту інструменты і дазволяе агенту выбраць, калія з іх вжыць. Ён таксама адкрывае частку працэйных практыкаў LlamaIndex, якія спачатку здаюцца чымсь чародзкім: як працэйная практыка ведае, калія крок павінен выконвацца далей.