Кейс 4. RAG для внутренней документации с использованием LLPhant

В этом кейсе мы делаем осознанный шаг от "чистого PHP" к первому специализированному PHP-фреймворку для работы с LLM – LLPhant. Это переходный момент: механика RAG уже понятна, и теперь нас интересует не изобретение инфраструктуры, а сохранение инженерного контроля при использовании готовых компонентов.

LLPhant хорош тем, что он не превращает RAG в магию. Архитектура остаётся прозрачной, а код читается как обычный PHP-проект.

Цель кейса

Построить систему вопросов-ответов по внутренней документации компании, где:

• ответы формируются строго на основе документов

• исключаются галлюцинации и домыслы

• архитектура RAG остаётся прозрачной и контролируемой

• инфраструктурная сложность минимизирована с помощью LLPhant

Бизнес-сценарий

В компании есть внутренняя документация:

• Markdown-файлы с регламентами

• README-файлы сервисов

• SLA и операционные инструкции

• Политики безопасности

Сотрудники задают вопросы в свободной форме:

Какой SLA у сервиса X?

Как часто происходит ротация API-ключей?

Где описан процесс восстановления после сбоя?

Важно: модель не должна придумывать ответы.

Если информации в документации нет – система должна честно сообщить об этом.

Архитектура решения

Мы реализуем классический RAG-пайплайн:

1. Документы разбиваются на чанки

2. Для чанков считаются эмбеддинги

3. Эмбеддинги сохраняются во векторное хранилище

4. По пользовательскому запросу извлекаются Top-K фрагментов

5. Из них формируется контролируемый контекст

6. LLM генерирует ответ строго на его основе

LLPhant закрывает инфраструктурную часть (эмбеддинги + vector store), но не принимает архитектурных решений за нас.

Этап 1. Индексация документов

На этом этапе мы:

• загружаем документы,

• создаём эмбеддинги,

• сохраняем их во векторное хранилище.

use LLPhant\Embeddings\OpenAIEmbeddingGenerator;
use LLPhant\VectorStores\Memory\MemoryVectorStore;
use LLPhant\Document;

$embeddingGenerator = new OpenAIEmbeddingGenerator(
    apiKey: config('OPENAI_API_KEY')
);

$vectorStore = new MemoryVectorStore($embeddingGenerator);

$documents = [
    new Document('SLA сервиса X составляет 99.9% в месяц.'),
    new Document('Ротация API-ключей происходит каждые 90 дней.'),
    // ... other documents
];

$vectorStore->addDocuments($documents);

Что здесь происходит:

• LLPhant автоматически создаёт эмбеддинги для каждого документа

• Векторные представления сохраняются в MemoryVectorStore

• Мы не пишем вручную код для работы с embeddings

Важно:

LLPhant берёт на себя расчёт эмбеддингов и их хранение, но не вмешивается в архитектуру RAG как системы.

Этап 2. Поиск релевантных фрагментов

Теперь пользователь задаёт вопрос:

$query = 'Как часто происходит ротация API-ключей?';

$relevantDocs = $vectorStore->similaritySearch($query, 2);

Что делает система:

• создаёт embedding для запроса

• сравнивает его с embedding документов

• возвращает Top-K наиболее релевантных фрагментов

Ключевой момент:

Мы получаем не ответ, а строительный материал для него – релевантные куски документации.

LLM на этом этапе ещё не участвует.

Этап 3. Context Building: контроль вместо магии

Это самый важный шаг во всём кейсе.

$context = "Ты отвечаешь строго на основе контекста ниже. ";
$context .= "Если ответа нет – скажи, что информации недостаточно.\n\n";
$context .= "Контекст:\n";

foreach ($relevantDocs as $doc) {
    $context .= "- " . $doc->content . "\n";
}

$context .= "\nВопрос: {$query}";

Здесь происходит превращение retrieval в управляемую систему:

• мы явно формулируем правила поведения модели

• ограничиваем её доступным контекстом

• запрещаем добавлять факты вне базы знаний

Даже при использовании фреймворка именно здесь RAG становится инженерной системой, а не просто вызовом LLM.

Если этот шаг реализован плохо – вся система начинает галлюцинировать

Этап 4. Генерация ответа

Теперь передаём собранный контекст в LLM:

use LLPhant\Chat\OpenAIChat;
use LLPhant\Chat\Message;

$chat = new OpenAIChat(apiKey: config('OPENAI_API_KEY'));

$response = $chat->generate([
    Message::system($context)
]);

echo $response->content;

LLM:

• видит только отобранные фрагменты

• получает строгую инструкцию

• формирует ответ

Если документация содержит:

Ротация API-ключей происходит каждые 90 дней.

Модель ответит:

Ротация API-ключей происходит каждые 90 дней.

Если информации нет — модель должна сообщить об этом.

Что происходит под капотом

Полный RAG-процесс выглядит так:

Пользовательский запрос

→ Embedding запроса

→ Similarity search

→ Top-K документы

→ Контролируемый prompt

→ LLM

→ Ответ

LLPhant автоматизирует инфраструктуру, но:

• не принимает решений о логике

• не строит контекст за нас

• не скрывает механику RAG

Типичные ошибки

1. Передавать в LLM слишком много документов

   → контекст размывается

2. Не ограничивать модель инструкциями

   → начинаются галлюцинации

3. Использовать similaritySearch без ограничения K

   → падает релевантность

Преимущества такого подхода

• Минимум кода для embeddings

• Читаемая архитектура

• Полный контроль над prompt

• Простота масштабирования

MemoryVectorStore можно заменить на Qdrant или другой векторный движок без изменения логики.

Ограничения

• Чанкование нужно проектировать отдельно (для реальной документации это критично)

• MemoryVectorStore не подходит для продакшена

• Нужен контроль над размером контекста

Выводы по кейсу

Этот кейс показывает важный принцип:

LLPhant не делает RAG за нас, он:

• убирает инфраструктурный шум

• ускоряет разработку

• сохраняет контроль над логикой и контекстом

Он не превращает систему в "магический чёрный ящик". Именно поэтому LLPhant отлично подходит как первый фреймворк для внедрения RAG в PHP-проектах:

• мы уже не пишем всё вручную

• но ещё полностью контролируем архитектуру