Kurs Python · Moduł 11: RAG i systemy wieloagentowe
Production RAG - Enterprise Systems
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: floatQueryRequest 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 responseKlucz 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.contentWyszukiwanie 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))
raiseQUERY_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 responseUwaga: 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 resultsEvaluator 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. Co jest kluczowe w produkcyjnym systemie RAG?
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
Zadania po tej lekcji
- PytanieProduction RAG
- PytanieCaching w RAG
- Zadanie z kodemFastAPI RAG Endpoint
- Ułóż w kolejnościRAG Service Architecture
- PytanieBest Practices RAG
- Zadanie z kodemProjekt: Simple RAG System
- Kliknij w kolejnościChain Invoke
- Zadanie z kodemProjekt: Vector Search Engine
- Zadanie z kodemProjekt: Multi-Agent Content Creator