В мире искусственного интеллекта, особенно в сфере обработки естественного языка (NLP), мы наблюдаем фундаментальный сдвиг парадигмы. Долгое время стандартом де-факто для работы с корпоративными знаниями оставалась классическая архитектура Retrieval-Augmented Generation (RAG). Однако, как показывает практика, простой подход «загрузил документы — получил эмбеддинги — выполнил один векторный поиск» часто оказывается недостаточным для сложных, многошаговых задач. Особенно это касается таких областей, как юриспруденция, финансовый аудит и техническая документация, где точность, контекст и возможность верификации каждого утверждения критически важны.
Команда LlamaIndex, один из лидеров в области инфраструктуры для работы с LLM, представила публичный референсный проект под названием legal-kb. Это не просто библиотека или набор сниппетов кода, а полноценное веб-приложение, демонстрирующее новую модель извлечения знаний — Agentic Retrieval Harness (Агентная система извлечения). Проект построен на базе LlamaIndex Index v2 (платформа LlamaParse) и демонстрирует, как агенты могут использовать набор инструментов, напоминающих файловую систему, для навигации по большим массивам документов. В этой статье мы подробно разберем, как это работает, почему это лучше классического RAG, и как вы можете применить эти принципы в своих проектах.
01Что такое legal-kb и зачем он нужен?
legal-kb — это рабочее веб-приложение, созданное на стеке TanStack Start. Его главная цель — показать разработчикам и архитекторам AI-систем, как построить надежный, масштабируемый и точный интерфейс для работы с юридическими документами. В отличие от многих демонстрационных проектов, которые часто бывают «хрупкими» и требуют сложной настройки, legal-kb предлагает готовый паттерн: пользователь входит в систему, создает проект, загружает файлы (PDF, DOCX и др.), и начинает общаться с агентом.
Ключевая особенность системы заключается в том, что каждый проект автоматически синхронизируется с управляемым индексом LlamaCloud Index v2. Загруженные файлы парсятся и индексируются в фоновом режиме. Это означает, что когда пользователь задает вопрос, агент не просто ищет по векторам, а работает с живым, актуальным индексом, который обновляется по мере добавления новых документов или версий файлов.
Почему именно юридическая сфера? Юридические документы — это идеальный полигон для тестирования новых подходов к RAG. Они длинные, содержат сложную структуру, ссылаются друг на друга и требуют высокой точности цитирования. Ошибка в интерпретации одного пункта договора может стоить миллионов. Поэтому подход, предлагаемый legal-kb, направлен на минимизацию галлюцинаций LLM за счет строгой верификации фактов через прямое чтение исходных файлов.
02Агентная система извлечения: от одного поиска к многошаговому процессу
Чтобы понять инновационность legal-kb, нужно сравнить его с традиционным подходом. В классическом RAG (так называемом Naive RAG) процесс выглядит так: пользователь задает вопрос, система выполняет один векторный поиск, извлекает топ-K наиболее похожих фрагментов текста и передает их вместе с вопросом в LLM. LLM генерирует ответ на основе этого ограниченного контекста.
Проблема этого подхода в том, что он «одношаговый». Если ответ не найден в первых K фрагментах, или если вопрос требует сравнения информации из разных частей документа, классический RAG часто терпит неудачу или выдает неточный ответ. Он не может «подумать», не может проверить гипотезу, не может прочитать файл целиком, чтобы найти конкретную формулировку.
Вместо этого legal-kb использует Retrieval Harness (Систему извлечения). Это постоянный конвейер данных, который не только индексирует документы, но и предоставляет агенту набор инструментов, имитирующих операции с файловой системой. Агент получает возможность:
- Списывать файлы в проекте (аналог
ls). - Читать содержимое файлов (аналог
cat). - Искать по регулярным выражениям внутри файлов (аналог
grep). - Выполнять гибридный семантический и ключевой поиск (аналог
find+grep).
Этот подход позволяет агенту действовать как опытный юрист или аудитор: он сначала составляет список всех релевантных документов, затем читает их, ищет конкретные пункты, сравнивает версии и только после этого формирует ответ с точными цитатами.
03Четыре ключевых инструмента агента
В основе агента, реализованного в файле src/lib/agent.ts, лежат четыре конкретных инструмента. Каждый из них напрямую связан с API LlamaIndex Index v2. Давайте разберем каждый из них подробно, чтобы понять, какую задачу он решает.
1. retrieve (Гибридный поиск)
Этот инструмент использует метод beta.retrieval.retrieve. Он выполняет семантический поиск, но с важными дополнениями. В отличие от простого векторного поиска, retrieve поддерживает:
- Гибридный поиск: Комбинация векторной близости и ключевых слов.
- Реранкинг (Reranking): Возможность указать
rerank_top_n, чтобы отсортировать результаты по релевантности с помощью отдельной модели. - Фильтрацию: Можно фильтровать по имени файла (
file_name) и версии (file_version).
Инструмент возвращает не только текст фрагментов, но и метаданные, включая оценки релевантности. Это позволяет агенту оценивать качество найденной информации еще до того, как он начнет формировать ответ.
2. findFiles (Поиск файлов)
Инструмент findFiles использует метод beta.retrieval.find. Его задача — не поиск по содержимому, а навигация по структуре. Агент может искать файлы по точному имени или по подстроке. Это критически важно, когда агенту нужно понять, какие документы вообще есть в базе знаний, прежде чем начинать их анализ. Например, если вопрос касается «NDA с компанией X», агент сначала найдет все файлы, содержащие «NDA» и «X» в имени, а затем перейдет к их содержимому.
3. readFile (Чтение файла)
Инструмент readFile использует метод beta.retrieval.read. Он позволяет агенту прочитать «сырое» содержимое файла. Важнейшая особенность — поддержка окон чтения через параметры offset и max_length. Это означает, что агент не обязан загружать весь файл в контекстное окно LLM (что часто невозможно из-за ограничений по токенам). Он может читать файл частями, анализируя раздел за разделом. Это делает возможным работу с очень длинными документами, такими как годовые отчеты или многостраничные контракты.
4. grepFile (Поиск по регулярным выражениям)
Инструмент grepFile использует метод beta.retrieval.grep. Он ищет совпадения с заданным паттерном (регулярным выражением) внутри одного файла. В отличие от семантического поиска, который ищет по смыслу, grep ищет по точной форме. Это незаменимо для поиска конкретных формулировок, номеров статей, дат или идентификаторов, которые могут быть написаны по-разному в разных частях документа, но имеют строгий формат.
findFiles для инвентаризации, затем retrieve для семантического поиска, и только потом readFile или grepFile для верификации. Это снижает вероятность галлюцинаций, так как агент не может сослаться на текст, который он не прочитал напрямую.04Как это работает «под капотом»?
Понимание внутренней механики legal-kb помогает оценить его надежность. Процесс загрузки документов строго регламентирован и описан в файле src/lib/files.ts.
Когда пользователь загружает файл, байты отправляются в исходную директорию проекта в LlamaCloud. Одновременно в базе данных PostgreSQL (через ORM Prisma) создаются записи для File и ProjectFile. Важно отметить, что синхронизация индекса запускается асинхронно. Пользовательский интерфейс не блокируется; вместо этого он опрашивает статус готовности индекса. Это обеспечивает отзывчивость приложения даже при загрузке больших файлов.
Особое внимание уделено версионированию. Версия привязана к паре (проект, имя файла). Если вы загрузите nda.pdf повторно, система создаст новую версию (v2, v3 и т.д.), сохраняя предыдущие. При поиске агент может явно указать, с какой версией он работает, используя параметр file_version. Это открывает возможности для отслеживания изменений в документах с течением времени, что критически важно для юридического комплаенса.
Агент сам по себе реализован с использованием ToolLoopAgent из Vercel AI SDK 6. Это гибкая архитектура, позволяющая выбирать модель для каждого шага (OpenAI или Anthropic) и использовать собственные API-ключи. Поддержка потоковой передачи ответов (streaming) и использование моделей с расширенным мышлением (extended thinking у Claude или medium reasoning effort у OpenAI) значительно повышают качество сложных логических выводов.
Пример кода: Инструмент retrieve
Ниже приведен упрощенный, но точный фрагмент кода, показывающий, как инструмент retrieve оборачивает API LlamaCloud. Обратите внимание на обработку фильтров и формирование цитат.
import LlamaCloud from '@llamaindex/llama-cloud'
import { tool } from 'ai'
import { z } from 'zod'
import makeCitationId from './citations'
// Один замыкание инструмента на индекс. Оборачивает API Index v2.
function createLlamaParseTools(apiKey, projectId, indexId) {
const client = new LlamaCloud(apiKey)
const retrieveTool = tool({
description: 'Run a semantic retrieval query against an index.',
inputSchema: z.object({
query: z.string(),
top_k: z.number().optional(),
score_threshold: z.number().optional(),
rerank_top_n: z.number().optional(), // set to enable reranking
file_name: z.string().optional(), // metadata filter
file_version: z.number().optional()
}),
execute: async ({ query, top_k, score_threshold, rerank_top_n, file_name, file_version }) => {
const custom_filters = file_name
? { file_name: { operator: 'eq' as const, value: file_name } }
: undefined
const response = await client.beta.retrieval.retrieve({
index_id: indexId,
project_id: projectId,
query,
top_k,
score_threshold,
rerank: rerank_top_n != null ? { enabled: true, top_n: rerank_top_n } : undefined,
custom_filters
})
// Возвращает список, понятный модели, и цитаты для UI
const citations = response.results.map(r => ({
id: makeCitationId(r), // например, "c7f2qa"
fileName: r.metadata.file_name,
score: r.rerank_score ?? r.score ?? null,
preview: r.content.slice(0, 500)
}))
const formatted = response.results.map((r, i) =>
`### Result #${i + 1}\n\n${r.content.slice(0, 600)}`
).join('\n\n---\n\n')
return { formatted, citations }
}
})
// findFiles / readFile / grepFile имеют аналогичную структуру
return { retrieveTool /* , findFiles, readFile, grepFile */ }
}
05Визуальные цитаты: Прозрачность ответов
Одной из самых впечатляющих особенностей legal-kb является система визуальных цитат. Когда агент генерирует ответ, он не просто говорит «согласно документу», а вставляет в текст специальные идентификаторы, такие как cite:c7f2qa.
Фронтенд приложения преобразует эти идентификаторы в кликабельные чипы. При нажатии на такой чип пользователь видит не просто текст, а скриншот страницы исходного документа с выделенными прямоугольниками (bounding boxes) вокруг цитируемого текста. Это обеспечивает беспрецедентный уровень доверия к системе. Юрист или аудитор может мгновенно проверить, правильно ли агент интерпретировал контекст, просто взглянув на выделение на странице.
06Сравнение: Naive RAG против Агента
Давайте резюмируем различия между традиционным RAG и предложенным подходом в виде таблицы:
| Измерение | Naive / Single-shot RAG | Agentic Retrieval Harness (Index v2) |
|---|---|---|
| Поток извлечения | Один векторный поиск на запрос | Многошаговый цикл инструментов: find → retrieve → read/grep |
| Режимы поиска | Только векторное сходство | Гибридный семантический поиск, ключевые слова и regex grep |
| Контекст | Фиксированное количество фрагментов (top-k) | Агент читает полные файлы или окна по требованию |
| Актуальность | Статический индекс | Постоянный конвейер с синхронизацией и версионированием |
| Контроль точности | Скрыт | Открытые параметры: top_k, score_threshold, rerank_top_n |
| Цитаты | ID фрагментов | Визуальные цитаты со скриншотами страниц и bounding boxes |
| Лучшее применение | Краткие вопросы и ответы | Долгосрочные задачи по работе с документами |
07Примеры использования
Дизайн legal-kb ориентирован на домены, где агенты должны ориентироваться в больших наборах документов. Вот несколько типичных сценариев:
- Вопрос по контракту: «Какое уведомление требуется для расторжения MSA?» Агент сначала использует
findFilesдля поиска всех MSA-контрактов. Затем он используетretrieveдля поиска разделов о расторжении. Наконец, он используетgrepFileдля поиска точных формулировок сроков уведомления. Ответ сопровождается ссылкой на конкретную страницу контракта. - Due Diligence (Проверка благонадежности): Аудитор загружает папку с документами (data room). Агент может использовать
findFilesдля поиска всех финансовых отчетов за последний год, а затемreadFileдля последовательного чтения каждого кандидата. Он может перекрестно проверять пункты без необходимости человеку открывать каждый PDF. - Версионирование политик: Поскольку
retrieveпринимает фильтрfile_version, агент может запросить информацию только из конкретной версии документа. Это позволяет отслеживать изменения в политиках компании с течением времени.
08Технологический стек
Legal-kb построен на современном и надежном стеке технологий:
- Frontend/Backend: TanStack Start (фреймворк для создания SSR-приложений на React).
- AI SDK: Vercel AI SDK 6 для управления состоянием агентов и потоковой передачи.
- База данных: PostgreSQL с ORM Prisma для хранения метаданных и связей.
- Аутентификация: WorkOS для безопасного входа пользователей.
- Безопасность: Ключи API хранятся зашифрованными для каждого пользователя.
09Что это значит на практике
Появление legal-kb и концепции Agentic Retrieval Harness сигнализирует о конце эпохи «простого RAG». Для разработчиков и компаний это означает несколько важных вещей:
Во-первых, точность важнее скорости. В критически важных областях, таких как право и финансы, лучше потратить лишние секунды на многошаговую проверку фактов, чем получить быстрый, но неточный ответ. Агенты, способные «думать» и проверять себя, становятся новым стандартом.
Во-вторых, инфраструктура становится важнее моделей. Хотя выбор LLM (Claude, GPT-4o и др.) важен, именно архитектура системы — как она управляет контекстом, как она верифицирует ответы — определяет конечное качество. LlamaIndex Index v2 предлагает именно такую инфраструктуру.
В-третьих, прозрачность — ключ к доверию. Визуальные цитаты и возможность отследить путь агента от вопроса к ответу через конкретные файлы и страницы делают AI-системы пригодными для внедрения в корпоративную среду, где требуется аудит и объяснимость решений.
Если вы работаете с большими объемами неструктурированных документов, стоит рассмотреть переход от классического RAG к агентным системам. Проект legal-kb на GitHub предоставляет отличную отправную точку для экспериментов и адаптации под свои нужды. Попробуйте запустить его локально, загрузите свои документы и посмотрите, как агент справляется с вашими сложными вопросами. Возможно, это станет первым шагом к созданию более умных, надежных и полезных AI-ассистентов в вашей организации.
Для тех, кто хочет углубиться в тему, репозиторий legal-kb доступен на GitHub. Также рекомендуем следить за обновлениями LlamaIndex и сообщества Vercel AI SDK, так как эта область развивается очень быстро.
Источник: MarkTechPost ↗