Kurs Python · Moduł 11: RAG i systemy wieloagentowe

Production RAG - Enterprise Systems

10 min czytania ·
W tej lekcji8

Twój prototyp RAG działa świetnie na laptopie. Potem korzysta z niego sto osób naraz, rachunek za API rośnie z godziny na godzinę, jedno pytanie czeka dziesięć sekund, a gdy coś się psuje, nikt nie wie, na którym etapie. Obóz na jedną noc to nie to samo co stała baza wyprawy.

Budowanie produkcyjnych systemów RAG wymaga uwzględnienia czterech rzeczy naraz: wydajności, skalowalności, monitoringu i bezpieczeństwa. To jak projektowanie całego ekosystemu - każdy element musi współgrać z innymi.

Architektura produkcyjnego RAG

Schemat pokazuje warstwy, przez które przechodzi każde zapytanie:

┌─────────────────────────────────────────────────────────────────────┐
│                    Production RAG Architecture                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────┐              │
│  │  Client  │───▶│ Load Balancer│───▶│  API Gateway │              │
│  └──────────┘    └──────────────┘    └──────────────┘              │
│                                               │                      │
│                                               ▼                      │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │                     RAG Service Layer                       │    │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐           │    │
│  │  │  Retrieval │  │ Augment    │  │ Generation │           │    │
│  │  │  Service   │  │ Service    │  │ Service    │           │    │
│  │  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘           │    │
│  └────────┼───────────────┼───────────────┼──────────────────┘    │
│           │               │               │                        │
│  ┌────────▼───────┐  ┌────▼────┐  ┌──────▼──────┐                │
│  │ Vector Database│  │  Cache  │  │  LLM APIs   │                │
│  │ (Pinecone/     │  │ (Redis) │  │ (OpenAI/    │                │
│  │  Qdrant)       │  │         │  │  Anthropic) │                │
│  └────────────────┘  └─────────┘  └─────────────┘                │
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                    Observability Layer                         │ │
│  │  Prometheus │ Grafana │ Jaeger │ LangSmith │ Weights & Biases │ │
│  └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Od góry: load balancer i API Gateway, warstwa serwisu RAG z trzema etapami, niżej baza wektorowa, cache Redis i API modeli, a pod wszystkim warstwa obserwowalności.

FastAPI RAG Service

Serwis piszemy w FastAPI, bo obsługuje async i sam waliduje dane. Najpierw importy i modele Pydantic opisujące żądanie i odpowiedź:

from fastapi import FastAPI, HTTPException, BackgroundTasks
from pydantic import BaseModel
from typing import Optional
import asyncio
import hashlib
from contextlib import asynccontextmanager
import uvicorn

# Modele
class QueryRequest(BaseModel):
    question: str
    top_k: int = 5
    filters: Optional[dict] = None

class QueryResponse(BaseModel):
    answer: str
    sources: list[dict]
    latency_ms: float

QueryRequest przyjmuje pytanie, liczbę dokumentów i opcjonalne filtry. Żądanie bez pola question FastAPI odrzuci samo.

Klasa serwisu łączy się z trzema usługami. Klienty są asynchroniczne, więc czekanie na jedną usługę nie blokuje innych żądań:

class RAGService:
    """Produkcyjny serwis RAG."""

    def __init__(self):
        self.vector_store = None
        self.llm = None
        self.cache = None

    async def initialize(self):
        """Inicjalizacja połączeń."""
        # Vector store
        from qdrant_client import AsyncQdrantClient
        self.vector_store = AsyncQdrantClient(host="qdrant", port=6333)

        # Cache
        import redis.asyncio as redis
        self.cache = redis.Redis(host="redis", port=6379)

        # LLM
        from openai import AsyncOpenAI
        self.llm = AsyncOpenAI()

Połączenia tworzymy w initialize, bo wymagają await. Nazwy hostów qdrant i redis to nazwy usług z pliku Docker Compose, który zobaczysz na końcu lekcji.

Serce serwisu to metoda query. Najpierw sprawdza cache, a dopiero przy chybieniu wykonuje pełny pipeline:

    async def query(self, request: QueryRequest) -> QueryResponse:
        """Przetwarza zapytanie RAG."""
        import time
        start = time.time()

        # 1. Sprawdź cache
        cache_key = f"rag:{hashlib.sha256(request.question.encode()).hexdigest()}"
        cached = await self.cache.get(cache_key)
        if cached:
            return QueryResponse.model_validate_json(cached)

        # 2. Embedding
        embedding = await self._get_embedding(request.question)

        # 3. Retrieval
        docs = await self._retrieve(embedding, request.top_k, request.filters)

        # 4. Generation
        answer = await self._generate(request.question, docs)

        # 5. Response
        response = QueryResponse(
            answer=answer,
            sources=[{"text": d.payload["text"], "score": d.score} for d in docs],
            latency_ms=(time.time() - start) * 1000
        )

        # 6. Cache
        await self.cache.setex(cache_key, 3600, response.model_dump_json())

        return response

Klucz cache liczymy przez SHA-256, a nie wbudowane hash(). To poprawka ważna w produkcji: hash() dla stringów jest losowany przy każdym starcie procesu, więc dwa workery liczyłyby różne klucze dla tego samego pytania. setex zapisuje odpowiedź na 3600 sekund, czyli godzinę.

Trzy metody pomocnicze robią embedding, wyszukiwanie i generowanie:

    async def _get_embedding(self, text: str) -> list[float]:
        """Generuje embedding."""
        response = await self.llm.embeddings.create(
            model="text-embedding-3-small",
            input=text
        )
        return response.data[0].embedding

    async def _retrieve(self, embedding, top_k, filters):
        """Pobiera dokumenty."""
        response = await self.vector_store.query_points(
            collection_name="documents",
            query=embedding,
            limit=top_k,
            query_filter=filters
        )
        return response.points

    async def _generate(self, question: str, docs) -> str:
        """Generuje odpowiedź."""
        context = "\n".join([d.payload["text"] for d in docs])

        response = await self.llm.chat.completions.create(
            model="gpt-4o-mini",
            messages=[
                {"role": "system", "content": f"Kontekst:\n{context}"},
                {"role": "user", "content": question}
            ]
        )
        return response.choices[0].message.content

Wyszukiwanie używa query_points, bo metoda search zniknęła z nowych wersji qdrant-client. Tekst dokumentu leży w payload, dlatego źródła budujemy z d.payload["text"].

Na końcu aplikacja FastAPI i endpoint:

# FastAPI app
rag_service = RAGService()

@asynccontextmanager
async def lifespan(app: FastAPI):
    await rag_service.initialize()
    yield

app = FastAPI(title="RAG API", lifespan=lifespan)

@app.post("/query", response_model=QueryResponse)
async def query(request: QueryRequest):
    try:
        return await rag_service.query(request)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

lifespan uruchamia initialize raz, przy starcie aplikacji. Każdy błąd staje się kodem 500, ale w produkcji nie odsyłaj klientowi str(e).

Monitoring i Observability

Bez pomiarów o awarii dowiesz się od użytkowników. Prometheus zbiera trzy typy metryk: licznik, histogram i wskaźnik:

from prometheus_client import Counter, Histogram, Gauge
import logging
import structlog

# Metryki Prometheus
QUERY_COUNT = Counter(
    "rag_queries_total",
    "Total number of RAG queries",
    ["status"]
)

QUERY_LATENCY = Histogram(
    "rag_query_latency_seconds",
    "Query latency in seconds",
    buckets=[0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0]
)

RETRIEVAL_SCORE = Gauge(
    "rag_retrieval_score",
    "Average retrieval score"
)

# Structured logging
structlog.configure(
    processors=[
        structlog.stdlib.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer()
    ]
)
logger = structlog.get_logger()

Counter tylko rośnie, a etykieta status rozdziela sukcesy od błędów. Histogram układa czasy odpowiedzi w przedziały, a structlog wypisuje logi jako JSON.

Serwis z monitoringiem owija przetwarzanie pomiarem czasu:

class MonitoredRAGService:
    """RAG z monitoringiem."""

    async def query(self, request: QueryRequest) -> QueryResponse:
        with QUERY_LATENCY.time():
            try:
                response = await self._process_query(request)
                QUERY_COUNT.labels(status="success").inc()

                # Log
                logger.info(
                    "query_completed",
                    question=request.question[:50],
                    latency_ms=response.latency_ms,
                    num_sources=len(response.sources)
                )

                return response
            except Exception as e:
                QUERY_COUNT.labels(status="error").inc()
                logger.error("query_failed", error=str(e))
                raise

QUERY_LATENCY.time() mierzy czas bloku with, a wyjątek zwiększa licznik błędów i leci dalej dzięki raise. _process_query oznacza tu logikę z metody query serwisu.

Łańcuchy LangChain

W ekosystemie produkcyjnym często spotkasz LangChain. Jego podstawowy wzorzec to łańcuch: prompt połączony z modelem operatorem | i wywołany metodą invoke:

from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_template("Odpowiedz krótko na pytanie: {input}")
chain = prompt | ChatOpenAI(model="gpt-4o-mini")

user_query = "Czym jest cache w systemie RAG?"
result = chain.invoke({"input": user_query})
print(result.content)

invoke przyjmuje słownik, którego klucze pasują do zmiennych w szablonie, tu {input}. Wynik to wiadomość modelu, a tekst leży w polu content.

LangSmith Tracing

LangSmith to platforma twórców LangChain do śledzenia wywołań. Dekorator @traceable zapisuje całą funkcję, a trace tworzy w niej zagnieżdżone etapy:

from langsmith import traceable, trace
from langsmith.wrappers import wrap_openai
from openai import OpenAI

# Każde wywołanie przez ten klient trafia do LangSmith jako osobny etap
openai_client = wrap_openai(OpenAI())

@traceable(name="RAG Query")
async def traced_query(question: str) -> str:
    """Zapytanie RAG z tracingiem."""

    # Embedding
    with trace("embedding", metadata={"model": "text-embedding-3-small"}):
        embedding = get_embedding(question)

    # Retrieval
    with trace("retrieval") as span:
        docs = retrieve(embedding)
        span.add_metadata({"num_docs": len(docs)})

    # Generation
    with trace("generation", metadata={"model": "gpt-4o-mini"}):
        response = generate(question, docs)

    return response

Uwaga: trace to osobna funkcja z pakietu langsmith, a nie metoda obiektu Client. get_embedding, retrieve i generate to funkcje z wcześniejszych lekcji.

Ewaluacja uruchamia system na zbiorze pytań z oczekiwanymi odpowiedziami. Funkcja traced_query jest asynchroniczna, więc używamy aevaluate:

from langsmith import aevaluate

async def target(inputs: dict) -> dict:
    """Adapter: LangSmith podaje słownik z pytaniem i oczekuje słownika z odpowiedzią."""
    return {"answer": await traced_query(inputs["question"])}

def contains_expected(outputs: dict, reference_outputs: dict) -> bool:
    """Prosty evaluator: czy odpowiedź zawiera oczekiwaną frazę?"""
    return reference_outputs["answer"].lower() in outputs["answer"].lower()

async def evaluate_rag():
    """Ewaluacja systemu RAG."""
    # Dataset z pytaniami i oczekiwanymi odpowiedziami, utworzony wcześniej w LangSmith
    results = await aevaluate(
        target,
        data="rag-eval-dataset",
        evaluators=[contains_expected]
    )
    return results

Evaluator to zwykła funkcja zwracająca True albo False. Metryki takie jak faithfulness czy context precision liczy się podobnie, tylko sędzią jest model językowy.

Rate Limiting i Bezpieczeństwo

Publiczne API bez limitów to zaproszenie do nadużyć. Najpierw prosty limiter z oknem jednej minuty:

from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import time

# Rate limiter
class RateLimiter:
    """Prosty rate limiter."""

    def __init__(self, requests_per_minute: int = 60):
        self.rpm = requests_per_minute
        self.requests: dict[str, list[float]] = {}

    async def check(self, user_id: str) -> bool:
        now = time.time()
        minute_ago = now - 60

        if user_id not in self.requests:
            self.requests[user_id] = []

        # Usuń stare requesty
        self.requests[user_id] = [
            t for t in self.requests[user_id] if t > minute_ago
        ]

        if len(self.requests[user_id]) >= self.rpm:
            return False

        self.requests[user_id].append(now)
        return True

rate_limiter = RateLimiter()
security = HTTPBearer()

Limiter pamięta czasy żądań każdego użytkownika i usuwa te starsze niż 60 sekund. Trzyma dane w pamięci procesu, więc przy kilku instancjach serwisu przenieś go do Redisa.

Teraz podłączamy autoryzację i limiter do endpointu przez Depends:

async def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    """Weryfikacja tokenu."""
    # W produkcji: JWT verification
    if credentials.credentials == "invalid":
        raise HTTPException(status_code=401, detail="Invalid token")
    return credentials.credentials

async def rate_limit(user_id: str = Depends(verify_token)):
    """Rate limiting middleware."""
    if not await rate_limiter.check(user_id):
        raise HTTPException(status_code=429, detail="Too many requests")
    return user_id

@app.post("/query")
async def query(request: QueryRequest, user: str = Depends(rate_limit)):
    return await rag_service.query(request)

HTTPBearer wyciąga token z nagłówka Authorization, a verify_token zwraca 401 dla złego tokenu. Przekroczenie limitu kończy się kodem 429. Ten endpoint zastępuje wcześniejszy /query, więc w aplikacji zostaw tylko jeden, bo FastAPI użyje pierwszej pasującej trasy.

Docker Deployment

Na koniec pakujemy serwis w kontener. Dockerfile opisuje obraz aplikacji:

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Instalacja zależności
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Kopiowanie kodu
COPY . .

# Uruchomienie
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Kopiujemy najpierw requirements.txt, a potem kod, więc zmiana kodu nie wymusza ponownej instalacji zależności.

Docker Compose uruchamia całą bazę naraz: API, Qdrant i Redis:

# docker-compose.yml
version: '3.8'

services:
  rag-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - QDRANT_HOST=qdrant
      - REDIS_HOST=redis
    depends_on:
      - qdrant
      - redis

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - qdrant_data:/qdrant/storage

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"

Zapis ${OPENAI_API_KEY} Compose podmienia wartością ze zmiennej środowiskowej hosta, więc klucz nie trafia do repozytorium. Klucz version jest w aktualnym Compose przestarzały i ignorowany.

Dalsza część pliku dodaje warstwę obserwowalności:

  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"

volumes:
  qdrant_data:

Prometheus zbiera metryki, a Grafana rysuje z nich wykresy. Wolumen qdrant_data sprawia, że wektory przetrwają restart kontenera.

Best Practices

Wszystkie lekcje z tego modułu zbiera lista dobrych praktyk:

"""
Production RAG Best Practices:

1. RETRIEVAL
   - Używaj hybrid search (vector + keyword)
   - Implementuj reranking
   - Filtruj po metadanych

2. CHUNKING
   - Eksperymentuj z rozmiarem chunks
   - Używaj overlap
   - Rozważ semantic chunking

3. CACHING
   - Cache embeddings
   - Cache częstych zapytań
   - Invalidacja przy aktualizacji dokumentów

4. MONITORING
   - Śledź latency na każdym etapie
   - Monitoruj jakość retrieval
   - Alerting na anomalie

5. SECURITY
   - Rate limiting
   - Input sanitization
   - PII detection i filtering

6. SCALABILITY
   - Horizontal scaling API
   - Sharding vector database
   - Async processing
"""

Polecam zaczynać od cache i monitoringu, bo zwracają się najszybciej: cache redukuje koszty API i opóźnienia, a metryki pokazują, gdzie szukać problemu. Zwróć uwagę, że na liście nie ma zahardkodowanych promptów: w produkcji prompty trzyma się w konfiguracji albo w systemie wersjonowania.

Gratulacje! Poznałeś zaawansowane systemy RAG i Multi-Agent. W następnej lekcji poznasz LangGraph - framework do budowania złożonych przepływów agentów!

Zapamiętaj: produkcyjny RAG to stała baza wyprawy, w której każdy namiot ma swoje zadanie, a strażnik liczy każdego, kto wchodzi.

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Co jest kluczowe w produkcyjnym systemie RAG?

  2. 2. Dlaczego cache jest ważny w produkcyjnym RAG?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Zaimplementuj produkcyjny endpoint RAG

  • Układanie w pionie

    Ułóż warstwy architektury produkcyjnego RAG:

  • Edytor kodu

    Zaimplementuj kompletny Simple RAG

  • Klikanie w kolejności

    Ułóż wywołanie łańcucha LangChain:

  • Edytor kodu

    Zaimplementuj Semantic Search Engine

  • Edytor kodu

    Zaimplementuj Multi-Agent Content Pipeline

  1. PytanieProduction RAG
  2. PytanieCaching w RAG
  3. Zadanie z kodemFastAPI RAG Endpoint
  4. Ułóż w kolejnościRAG Service Architecture
  5. PytanieBest Practices RAG
  6. Zadanie z kodemProjekt: Simple RAG System
  7. Kliknij w kolejnościChain Invoke
  8. Zadanie z kodemProjekt: Vector Search Engine
  9. Zadanie z kodemProjekt: Multi-Agent Content Creator

Przydatne artykuły