Создание помощника для документации 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, которая сначала кажется волшебством: как рабочий процесс определяет, какой шаг следует выполнить дальше.