Створення асистента для документації API за технологією RAG з використанням 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, яка спочатку здається магією: як робочий процес визначає, який крок слід виконати далі.