Пошагово: разработка настоящей системы поиска данных RAG для ИИ-агентов

Замена агента по извлечению игрушек на реальную систему RAG — это хороший момент, чтобы сбавить темпы и поэтапно выполнять работу. В многопроцессной корпоративной платформе RetrievalAgent изначально работал с использованием намеренно простой локальной реализации. Этого было достаточно для демонстрации архитектуры, но в производственных условиях требуются настоящие документы, эмбеддинги, векторное хранилище и семантический поиск. Целевой процесс включает обработку документов: их загрузку, разбиение на части, генерацию эмбеддингов и сохранение в ChromaDB, а затем семантическое извлечение информации, работу RetrievalAgent и функционирование всей платформы.

Вместо того чтобы создавать всё сразу, план предусматривает добавление по одному слою за раз, с тестированием на каждом этапе и поддержкой стабильной работы CI-пайплайна. Целями являются постепенные улучшения, надежный CI-пайплайн и прочная архитектура.

Компоненты системы RAG

Полная цепочка обработки объединяет несколько независимых инженерных аспектов, которые показаны на приведённой ниже диаграмме, начиная с исходных документов.

Source Documents
       ↓
Document Ingestion
       ↓
    Chunking
       ↓
   Embeddings
       ↓
 Vector Storage
       ↓
Semantic Search
       ↓
Retrieved Context
       ↓
Retrieval Agent

Возможно одновременное создание всех компонентов, но это затрудняет выявление причин сбоев. Когда качество получаемых данных низкое, где искать ошибку? Она может быть связана с парсингом документов, разбиением их на части, генерацией эмбеддингов, хранением векторов, логикой запросов, метаданными или интеграцией с агентами. Чёткое определение ответственности каждого слоя, наличие контракта и границ тестирования позволяют ответить на эти вопросы. Ритм работы: создание, тестирование, загрузка, проверка в CI, поддержание стабильной работы, затем продолжение.

Начните с контракта данных

Прежде чем использовать эмбеддинги или ChromaDB, первым шагом должен быть контракт данных. В работающей цепочке необходимо чётко разграничивать два понятия: SourceDocument и DocumentChunk.

SourceDocument — это исходный источник знаний до его разделения. Это может быть файл PDF, DOCX или TXT, внутренняя документация, финансовые отчеты, корпоративные правила, технические руководства или контент базы знаний. Его концептуальная структура выглядит следующим образом:

SourceDocument
 ├── document_id
 ├── content
 ├── source
 └── metadata

Таким образом, каждый оригинальный документ получает стабильную идентичность внутри архитектуры поиска.

Документы крупных предприятий обычно не следует встраивать в виде одного огромного блока текста. Их необходимо разделить на более мелкие, осмысленные единицы, и именно для этого предназначен DocumentChunk:

DocumentChunk
 ├── chunk_id
 ├── document_id
 ├── content
 ├── source
 ├── chunk_index
 └── metadata

Отношение между ними — один к многим:

SourceDocument
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       Chunk 0       Chunk 1      Chunk 2
          │            │            │
          └────────────┼────────────┘
                       ↓
                 Same document_id
                  + source metadata

Один источник может дать десятки фрагментов, а со временем — сотни, но каждый фрагмент сохраняет ссылку на свой исходный document_id и источник. Эта ссылка становится критически важной, когда семантическое поиск начинает возвращать отдельные фрагменты гораздо более крупных документов.

Почему принцип отслеживаемости встроен с самого начала

Представьте 50-страничный финансовый отчет. Система может разделить его на десятки фрагментов, а семантический поиск может вернуть лишь три. Тем не менее система должна всё равно уметь указать, из какого исходного документа поступила информация. Восстановление этой связи после поиска является хрупким процессом, поэтому она должна сохраняться на каждом этапе обработки.

Original Document
       ↓
SourceDocument
       ↓
DocumentChunk
       ↓
Embedding
       ↓
Vector Record
       ↓
Semantic Search
       ↓
RetrievedDocument
       ↓
Original Source

Принцип отслеживаемости является частью архитектуры данных с самого начала, а не добавляется позже.

Тестирование контрактов

После определения моделей автоматизированные тесты охватывают как SourceDocument, так и DocumentChunk. Они проверяют, что модели формируются корректно и что ключевые поля ведут себя так, как ожидается, включая идентификаторы документов, детали источника, содержимое и индексы фрагментов.

Это может показаться незначительным этапом, однако эти модели лягут в основу всего процесса извлечения данных:

Document Models
      ↓
   Chunking
      ↓
  Embeddings
      ↓
   ChromaDB
      ↓
  Retrieval
      ↓
    Agents

Нарушение контракта на начальном этапе этой цепочки может повлиять на всё, что находится дальше по потоку, поэтому основа данных защищается ещё до того, как сверху будет добавлена дополнительная инфраструктура.

Ещё одним осознанным решением стало сохранение этого этапа без внешних зависимостей. Здесь не происходит никаких вызовов OpenAI и ChromaDB, а тесты проверяют только контракты документов. Благодаря этому быстрая система CI остается детерминистичной.

Code Change
     ↓
Local Fast Tests
     ↓
Commit
     ↓
Push to GitHub
     ↓
GitHub Actions
     ↓
Clean CI Environment
     ↓
Fast Unit Tests
     ↓
CI PASSED ✅

Быстрый набор инструментов постоянно расширяется, в то время как тесты на внешнюю интеграцию остаются в отдельной группе. Правило здесь простое: каждый новый слой попадает в платформу с автоматизированной защитой.

Полная дорожная карта

Механизм управления документами — это всего лишь первый слой. Вот вся целевая архитектура:

Enterprise Documents
        │
        ▼
     Ingestion
        │
        ▼
      Chunking
        │
        ▼
     Embeddings
        │
        ▼
     ChromaDB
   Vector Storage
        │
        ▼
 Semantic Retrieval
        │
        ▼
 Retrieved Context
        │
        ▼
  RetrievalAgent
        │
        ▼
Multi-Agent Platform

Каждый этап имеет свою конкретную задачу и должен оставаться понятным и подлежащим тестированию самостоятельно.

Далее идет разбиение на части

Следующим компонентом является Служба разбиения на части, которая преобразует SourceDocument в несколько объектов DocumentChunk.

SourceDocument
      │
      ▼
ChunkingService
      │
      ├── DocumentChunk 0
      ├── DocumentChunk 1
      ├── DocumentChunk 2
      └── DocumentChunk N

С течением времени сервису необходимо управлять размером и перекрытием фрагментов, передавать метаданные и информацию о исходных данных, присваивать каждому фрагменту индекс и генерировать стабильные идентификаторы. Особое внимание заслуживает один архитектурный принцип: процесс разбиения на фрагменты не должен входить в обязанности агента по получению данных. Агент уже использует функции по поиску информации, и ему не следует также брать на себя задачи подготовки документов.

Эмбеддинги и хранение

После реализации и тестирования процесса разбиения на фрагменты следующий уровень отвечает за генерацию векторных эмбеддингов.

DocumentChunk
      ↓
Embedding Service
      ↓
Embedding Model
      ↓
Vector Representation

Каждый фрагмент преобразуется в вектор, который кодирует его смысл. Затем эти векторы сравниваются с встроенным запросом пользователя для поиска связанного материала.

DocumentChunk
      ↓
EmbeddingService
      ↓
Embedding Provider
      ↓
Vector

Замена модели эмбеддингов позже почти не повлияет на остальную часть архитектуры RAG.

После генерации эмбеддингов они сохраняются в хранилище персистентных векторов. Для локальной разработки клиент ChromaDB с поддержкой персистентности позволяет сохранять индексированные данные между перезапусками приложения.

DocumentChunk
      +
Embedding
      +
Metadata
      ↓
   ChromaDB
      ↓
Persistent Vector Collection

Для хранения записи требуется нечто большее, чем просто вектор. Она также содержит достаточно информации для сохранения контекста и возможности отслеживания:

Vector Record
 ├── chunk_id
 ├── embedding
 ├── content
 ├── document_id
 ├── source
 ├── chunk_index
 └── metadata

Это позволяет при поиске возвращать значимый контекст документа, а не просто похожие векторы.

Запросы

После заполнения хранилища система может выполнять семантический поиск. Путь запроса следующий:

User Query
    ↓
Query Embedding
    ↓
ChromaDB Similarity Search
    ↓
Top-K Relevant Chunks
    ↓
Scores + Metadata
    ↓
Retrieved Context

Вместо полной зависимости от точного совпадения ключевых слов семантический поиск находит фрагменты, концептуально связанные с запросом пользователя. Затем результаты преобразуются в стандартизированный формат, уже используемый платформой.

Воссоединение агента

Только тогда, когда инфраструктура поиска работает корректно, весь поток данных снова подключается к RetrievalAgent. С точки зрения агента ситуация остается простой:

AgentRequest
     ↓
RetrievalAgent
     ↓
RetrievalService
     ↓
Relevant Documents
     ↓
Structured RetrievalResult

За пределами RetrievalService реализация становится гораздо более сложной:

RetrievalService
      ↓
Query Embedding
      ↓
ChromaDB
      ↓
Semantic Search
      ↓
Ranking
      ↓
Retrieved Context

Разделение имеет значение. Агент по поиску должен рассматривать процесс поиска как отдельную функцию и не должен знать ничего о векторных базах данных, генерации эмбеддингов, хранении данных в блоках или загрузке документов.

Исходный агент работал с локальными данными, и архитектура выглядела примерно так:

RetrievalAgent
      ↓
RetrievalService
      ↓
Local Documents

Теперь реализация может развиваться в направлении чего-то более совершенного:

RetrievalAgent
      ↓
RetrievalService
      ↓
Semantic Retrieval
      ↓
ChromaDB
      ↓
Embedded Enterprise Documents

Обратите внимание на то, что остаётся неизменным: ссылка от RetrievalAgent к RetrievalService. Изменяется только инфраструктура, лежащая в основе этого контракта, и именно поэтому абстракция получения данных была создана ещё до появления векторных баз данных. Инфраструктура должна иметь возможность развиваться без необходимости полной переработки архитектуры агента.

Интеграция в платформу

Пайплайн RAG существует не сам по себе. Его задача — обеспечивать основанные на реальных данных корпоративные знания для более крупной многоагентной системы.

User
                          │
                          ▼
                    Supervisor Agent
                          │
                          ▼
                     Planning Agent
                          │
                          ▼
                    Execution Plan
                          │
                          ▼
                     Agent Registry
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
       RetrievalAgent  ResearchAgent AnalysisAgent
             │
             ▼
      RetrievalService
             │
             ▼
         RAG Pipeline
             │
             ▼
      Relevant Context
             │
             ▼
       Downstream Agents

На этом изображении агент по поиску связывает слой, где выполняются несколько агентов, с слоем, в котором хранится корпоративные знания.

Один момент заслуживает особого внимания: RAG — это не просто «добавь векторную базу данных». Качественная архитектура поиска включает в себя множество решений:

• Формирование контрактов документов и их загрузка
• Разбиение на части и генерация векторных представлений
• Хранение векторов и метаданных
• Семантический поиск и ранжирование
• Отслеживаемость источников
• Интеграция агентов
• Тестирование и возможность наблюдения за работой системы

Векторная база данных — это лишь один компонент в гораздо более крупной системе поиска.

Целенаправленно повторяющийся паттерн

Инженерный цикл для достижения этой вехи преднамеренно является повторяющимся:

Build One Layer
      ↓
Add Unit Tests
      ↓
Run Fast Suite
      ↓
Push to GitHub
      ↓
CI Validates
      ↓
Keep Green
      ↓
Build Next Layer

Это позволяет увеличивать сложность при сохранении уверенности в существующей системе. Вместо того чтобы добавлять пять компонентов сразу и отлаживать их все вместе, каждая функциональность проверяется перед добавлением следующей.

Первый этап реальной инфраструктуры завершен: контракты SourceDocument и DocumentChunk, тесты для обоих моделей, а также успешная быстрая проверка в рамках CI. Далее следует план развития:

1. Document Contract             ✅ COMPLETE
          ↓
2. Chunking Service              ← NEXT
          ↓
3. Embedding Service
          ↓
4. ChromaDB Integration
          ↓
5. Semantic Retrieval
          ↓
6. RetrievalAgent Integration
          ↓
7. End-to-End RAG Pipeline

Каждый слой реализуется и тестируется независимо перед переходом к следующему.

Почему это важно

Первый агент по поиску показал, что архитектура агентов функционирует. Теперь цель — заменить его временный механизм поиска на реальную инфраструктуру, перейдя от локального поиска к системе обработки документов, разбиению на фрагменты, генерации векторных представлений, хранению векторов, семантическому поиску и, наконец, к агенту с поддержкой технологии RAG. Поскольку агент зависит от абстракции сервиса, а не напрямую от ChromaDB, всё это можно реализовать без перепроектирования платформы для множества агентов.

Действует более общий принцип: необходимо создавать стабильные интерфейсы вокруг тех компонентов, которые могут изменяться. Модели будут меняться, векторные базы данных могут быть заменены, стратегии разбиения на фрагменты будут совершенствоваться, а алгоритмы поиска — улучшаться, но платформа вокруг них не должна переписываться каждый раз.

Создаётся механизм поиска, предназначенный для использования в корпоративной многоагентной платформе, а не для однократной демонстрации технологии RAG. В такой среде Супервайзер координирует действия, Реестр определяет доступные возможности, специализированные агенты выполняют задачи, технология RAG обеспечивает точные знания, тесты контролируют поведение системы, инструменты CI отслеживают каждое изменение, а механизмы наблюдаемости оценивают работу в производственных условиях. Метод остаётся неизменным: создаётся новый слой, он тестируется, затем внедряется, поддерживается стабильная работа инструментов CI, после чего начинается разработка следующего слоя.