Warstwa po warstwie: projektowanie rzeczywistego pipeline’u do wyszukiwania RAG dla agentów AI

Zastąpienie agenta do wyszukiwania zabawek prawdziwym pipeline’em RAG to dobry moment, by zwolnić i stopniowo realizować prace. W platformie korporacyjnej z wieloma agentami RetrievalAgent początkowo działał na celowo prostej lokalnej implementacji. To wystarczyło, by udowodnić skuteczność architektury, ale użycie w produkcji wymaga prawdziwych dokumentów, embeddingów, przechowywania wektorowego oraz wyszukiwania semantycznego. Przepływ danych obejmuje przetwarzanie dokumentów poprzez ich pobieranie, dzielenie na fragmenty i generowanie embeddingów w ChromaDB, a następnie przechodzenie do wyszukiwania semantycznego, działania RetrievalAgent oraz integracji z całą platformą.

Zamiast budować wszystko od razu, plan zakłada dodawanie kolejnych warstw stopniowo, z testami na każdym etapie i utrzymywaniem pipeline’u CI w stanie sprawnym. Celem są regularne ulepszenia, skuteczny proces CI oraz solidna architektura.

Części pipeline’u RAG

Kompletny łańcuch przetwarzania obejmuje kilka niezależnych aspektów inżynieryjnych, które poniższy diagram przedstawia począwszy od dokumentów źródłowych.

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

Możliwe jest jednoczesne budowanie każdego komponentu, ale utrudnia to ustalenie przyczyn awarii. Gdy jakość pobierania jest niska, gdzie leży błąd? Może to być problem z parsowaniem dokumentów, dzieleniem ich na fragmenty, embeddingami, przechowywaniem wektorowym, logiką zapytań, metadanymi lub integracją z agentem. Przypisanie każdej warstwie jasnej odpowiedzialności, kontraktu oraz granic testów sprawia, że na te pytania można znaleźć odpowiedzi. Rytmem pracy jest budowanie, testowanie, wdrażanie, weryfikacja w środowisku CI, utrzymywanie jego sprawności, a następnie kontynuacja.

Zacznij od kontraktu danych

Zanim pojawią się jakiekolwiek embeddingi czy ChromaDB, pierwszym krokiem jest stworzenie kontraktu danych. Pipeline musi odróżniać dwa pojęcia: SourceDocument i DocumentChunk.

SourceDocument oznacza oryginalne źródło wiedzy przed jego podziałem. Może to być plik PDF, DOCX lub TXT, dokumentacja wewnętrzna, raporty finansowe, zasady korporacyjne, podręczniki techniczne lub treści bazy wiedzy. Jego koncepcyjny kształt wygląda następująco:

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

Każdy oryginalny dokument otrzymuje w związku z tym stabilną tożsamość w architekturze wyszukiwania.

Dokumenty dużych przedsiębiorstw zazwyczaj nie powinny być umieszczane jako jeden ogromny blok tekstu. Należy je podzielić na mniejsze, znaczące jednostki, a to właśnie jest zadaniem DocumentChunk:

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

Związek pomiędzy nimi jest jeden-do-wielu:

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

Jedno źródło może dostarczyć dziesiątki fragmentów, a nawet setki, ale każdy z nich zawiera odnośnik do swojego początkowego document_id oraz źródła. Ten odnośnik staje się kluczowy, gdy wyszukiwanie semantyczne zaczyna zwracać pojedyncze fragmenty znacznie większych dokumentów.

Dlaczego możliwość śledzenia jest wbudowana od samego początku

Wyobraźmy sobie 50-stronicowy raport finansowy. System może podzielić go na dziesiątki fragmentów, a wyszukiwanie semantyczne może zwrócić tylko trzy. System musi nadal być w stanie określić, z którego oryginalnego dokumentu pochodzą te informacje. Odtworzenie tej relacji po przeszukaniu jest trudne, dlatego powinna być zachowywana na każdym etapie procesu.

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

Śledzalność jest częścią architektury danych od samego początku, a nie dodatkiem późniejszym.

Testowanie umów

Gdy modele są już zdefiniowane, testy automatyczne obejmują zarówno SourceDocument, jak i DocumentChunk. Sprawdzają one, czy modele są poprawnie budowane i czy kluczowe pola zachowują się zgodnie z oczekiwaniami, w tym identyfikatory dokumentów, szczegóły źródła, treść oraz indeksy fragmentów.

Może to wyglądać jak niewielki kamień milowy, jednak te modele stanowią podstawę całego procesu wydobywania danych:

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

Złamanie umowy na początku tej łańcuchowej struktury może wpłynąć na wszystko poniżej, dlatego fundament danych jest chroniony, zanim dodano dodatkową infrastrukturę.

Kolejną świadomą decyzją było utrzymanie tej etapy bez zewnętrznych zależności. Nie ma tu żadnych wywołań do OpenAI ani ChromaDB, a testy weryfikują jedynie umowy dokumentów. Dzięki temu szybki zestaw narzędzi CI pozostaje deterministyczny.

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

Szybki zestaw funkcji się rozszerza, podczas gdy testy integracji zewnętrznej pozostają w osobnej grupie. Zasada jest prosta: każda nowa warstwa trafia do platformy z automatyczną ochroną.

Pełny plan rozwoju

Kontrakt dokumentów to zaledwie pierwsza warstwa. Oto cała docelowa architektura:

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

Każdy etap ma określoną odpowiedzialność i powinien pozostać zrozumiały oraz możliwy do przetestowania samodzielnie.

Następny krok to chunking

Kolejnym komponentem jest Chunking Service, który przekształca SourceDocument w kilka obiektów DocumentChunk.

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

Z upływem czasu usługa musi zarządzać rozmiarem i nakładaniem się fragmentów, przekazywać metadane oraz szczegóły źródłowe, przypisywać każdemu fragmencie indeks oraz generować stabilne identyfikatory. Jeden aspekt architektury wyróżnia się: proces dzielenia na fragmenty nie dotyczy agenta pobierania. Agent wykorzystuje funkcje pobierania i nie powinien również zajmować się przygotowaniem dokumentów.

Embeddingi i przechowywanie

Po wdrożeniu i przetestowaniu mechanizmu dzielenia na fragmenty kolejny warstwa generuje wektorowe embeddingi.

DocumentChunk
      ↓
Embedding Service
      ↓
Embedding Model
      ↓
Vector Representation

Każdy fragment przekształca się w wektor, który koduje jego znaczenie. Później te wektory są porównywane z wplecionym zapytaniem użytkownika, aby znaleźć powiązane materiały.

DocumentChunk
      ↓
EmbeddingService
      ↓
Embedding Provider
      ↓
Vector

Zmiana modelu embeddingu później prawie nie powinna zakłócić reszty projektu RAG.

Po embeddingach następuje przechowywanie wektorów trwałych. Do celów lokalnego rozwoju trwały klient ChromaDB może przechowywać zindeksowaną wiedzę między ponownymi uruchomieniami aplikacji.

DocumentChunk
      +
Embedding
      +
Metadata
      ↓
   ChromaDB
      ↓
Persistent Vector Collection

Zapis przechowywany wymaga czegoś więcej niż tylko wektora. Zawiera również wystarczająco dużo informacji, aby utrzymać kontekst i możliwość śledzenia:

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

To umożliwia odzyskiwanie znaczącego kontekstu dokumentu, a nie tylko podobnych wektorów.

Zapytania

Gdy magazyn jest wypełniony, system może przeprowadzać wyszukiwanie semantyczne. Ścieżka zapytania jest następująca:

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

Zamiast polegać wyłącznie na dokładnych dopasowaniach słów kluczowych, semantyczne wyszukiwanie znajduje fragmenty konceptualnie powiązane z prośbą użytkownika. Wyniki są następnie przekształcane na standaryzowany format używany już przez platformę.

Ponowne połączenie agenta

Tylko wtedy, gdy infrastruktura wyszukiwania działa poprawnie, cały proces jest ponownie podłączany do RetrievalAgent. Z punktu widzenia agenta sytuacja pozostaje prosta:

AgentRequest
     ↓
RetrievalAgent
     ↓
RetrievalService
     ↓
Relevant Documents
     ↓
Structured RetrievalResult

Za RetrievalService implementacja staje się znacznie bardziej złożona:

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

Rozróżnienie to ma znaczenie. Agent pozyskiwania danych powinien traktować proces pozyskiwania jako swoją funkcję i nie musi znać się na bazach danych wektorowych, generowaniu embeddingów, przechowywaniu fragmentów ani przetwarzaniu dokumentów.

Pierwotny agent pracował z danymi lokalnymi, a architektura wyglądała mniej więcej w ten sposób:

RetrievalAgent
      ↓
RetrievalService
      ↓
Local Documents

Implementacja może teraz rozwijać się w kierunku czegoś bardziej złożonego:

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

Zwróć uwagę na to, co pozostaje niezmienne: link od RetrievalAgent do RetrievalService. Zmienia się jedynie infrastruktura stojąca za tym kontraktem, i to właśnie dlatego abstrakcja pozyskiwania danych została stworzona przed pojawieniem się bazy danych wektorowych. Infrastruktura powinna móc ewoluować bez konieczności przeprojektowania architektury agenta.

Wpisanie się w platformę

Pipeline RAG nie istnieje samodzielnie. Jego celem jest dostarczanie ugruntowanej wiedzy przedsiębiorstwa do większego systemu wieloagentowego.

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

Na tym obrazku agent pobierania łączy warstwę, w której działają liczne agenty, z warstwą przechowującą wiedzę przedsiębiorstwa.

Jedna lekcja zasługuje na podkreślenie: RAG to nie po prostu „dodanie bazy danych wektorowej”. Skuteczna architektura pobierania wymaga podjęcia wielu decyzji:

• Umawianie się na dokumenty i ich przetwarzanie
• Dzielenie na fragmenty i generowanie wektorów reprezentujących te fragmenty
• Przechowywanie wektorów i metadanych
• Pobieranie informacji w sposób semantyczny i ich sortowanie
• Śledzenie źródeł
• Integracja agentów
• Testowanie i możliwość obserwacji

Baza danych wektorowej jest jedynym komponentem w znacznie większym systemie pobierania informacji.

Celowe powtarzanie wzorca

Pętla inżynieryjna dla tego etapu jest celowo powtarzalna:

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

Pozwala to na rosnącą złożoność, dopóki utrzymuje się pewność co do istniejącego systemu. Zamiast dodawać pięć komponentów naraz i debugować je wszystkie jednocześnie, każda nowa funkcjonalność jest weryfikowana przed dodaniem kolejnej.

Pierwszy kamień milowy rzeczywistego procesu został osiągnięty: kontrakt SourceDocument, kontrakt DocumentChunk, testy dla obu modeli oraz pomyślny szybki test CI. Oto plan dalszych działań:

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

Każda warstwa jest wdrażana i testowana niezależnie, zanim przejdziemy dalej.

Dlaczego to ma znaczenie

Pierwszy agent do wyszukiwania pokazał, że architektura agenta funkcjonuje. Celem teraz jest zastąpienie jego tymczasowego mechanizmu wyszukiwania prawdziwą infrastrukturą, przechodząc od lokalnego wyszukiwania do procesu przetwarzania dokumentów, dzielenia ich na fragmenty, tworzenia wektorowych reprezentacji, przechowywania wektorów, wyszukiwania semantycznego, a w końcu do agenta wyposażonego w technologię RAG. Ponieważ agent polega na abstrakcji usług, a nie bezpośrednio na ChromaDB, wszystko to może się zrealizować bez konieczności przeprojektowania platformy wieloagentowej.

Obowiązuje tu szersza zasada: należy tworzyć stabilne umowy dotyczące komponentów, które mogą ulec zmianie. Modele będą się zmieniać, bazy danych wektorowych mogą zostać zastąpione, strategie dzielenia na fragmenty będą ewoluować, a algorytmy wyszukiwania się udoskonalać, ale platforma otaczająca je nie powinna być co raz na nowo przepisywana.

Budowana jest funkcja wyszukiwania, która należy do korporacyjnej platformy wieloagentowej, a nie do jednorazowej demonstracji RAG. W takiej architekturze Supervisor koordynuje działania, Registry rozwiązuje problemy związane z możliwościami agentów, specjalistyczne agenty wykonywają zadania, RAG dostarcza wiarygodną wiedzę, testy chronią zachowanie systemu, CI monitoruje każdą zmianę, a mechanizmy obserwowalności sprawdzają funkcjonowanie w produkcji. Metoda pozostaje niezmienna: tworzy się warstwę, testuje ją, wdraża, utrzymuje CI w stanie sprawnym, a następnie tworzy kolejną warstwę.