Kurs Python · Moduł 12: Projekt końcowy

Architektura Systemu AI

6 min czytania ·
W tej lekcji4

Obóz na sawannie, w którym namioty, zapasy wody i ognisko stoją w jednym bałaganie, działa tylko do pierwszej burzy. Potem nie wiadomo, co przenieść, a co zostawić. Aplikacja AI bez architektury wygląda podobnie: endpoint sam łączy się z bazą wektorową, sam woła model językowy i sam liczy embeddingi. Zmiana dostawcy bazy oznacza wtedy przepisywanie połowy projektu. Architektura to szkielet, który pozwala wymieniać części bez burzenia całego obozu.

Clean Architecture dla aplikacji AI

Clean Architecture dzieli system na warstwy. Najważniejsza zasada: zależności wskazują do środka, czyli warstwa zewnętrzna może znać wewnętrzną, ale nigdy odwrotnie. Oto cztery warstwy naszego asystenta dokumentów, od interfejsu na górze do infrastruktury na dole:

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   REST API  │  │  WebSocket  │  │    CLI      │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
├─────────┼────────────────┼────────────────┼─────────────────┤
│         └────────────────┼────────────────┘                 │
│                          ▼                                   │
│                  Application Layer                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Use Cases / Services                    │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │   │
│  │  │  Query   │  │  Upload  │  │  Search  │          │   │
│  │  │ Service  │  │ Service  │  │ Service  │          │   │
│  │  └──────────┘  └──────────┘  └──────────┘          │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                     Domain Layer                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Entities & Business Logic               │   │
│  │  Document │ Query │ Response │ User │ Embedding     │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                  Infrastructure Layer                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Vector DB│  │   LLM    │  │ Database │  │   Cache  │  │
│  │  Qdrant  │  │  OpenAI  │  │ Postgres │  │  Redis   │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────────┘

Presentation Layer przyjmuje żądania (REST, WebSocket, CLI), Application Layer zawiera przypadki użycia, Domain Layer trzyma encje i logikę biznesową, a Infrastructure Layer to konkretne narzędzia: Qdrant, OpenAI, Postgres, Redis. W oryginalnym opisie Roberta C. Martina te same kręgi nazywają się Entities, Use Cases, Interface Adapters oraz Frameworks & Drivers. Nazwy się różnią, idea jest ta sama: logika biznesowa nie wie, jakiej bazy używasz.

Implementacja Domain Layer

Domena to serce obozu. Zaczynamy od encji, czyli obiektów, które mają tożsamość. Użyjemy field(default_factory=...), bo domyślna wartość typu list albo dict musi być tworzona osobno dla każdego obiektu, a uuid4 generuje losowy identyfikator.

from dataclasses import dataclass, field
from datetime import datetime
from uuid import UUID, uuid4
from abc import ABC, abstractmethod

# Entities
@dataclass
class Document:
    id: UUID = field(default_factory=uuid4)
    title: str = ""
    content: str = ""
    metadata: dict = field(default_factory=dict)
    created_at: datetime = field(default_factory=datetime.now)
    chunks: list["DocumentChunk"] = field(default_factory=list)

@dataclass
class DocumentChunk:
    id: UUID = field(default_factory=uuid4)
    document_id: UUID | None = None
    content: str = ""
    embedding: list[float] = field(default_factory=list)
    metadata: dict = field(default_factory=dict)

DocumentChunk to fragment dokumentu razem z jego embeddingiem, czyli wektorem liczb. Adnotacja UUID | None mówi uczciwie, że fragment może jeszcze nie należeć do żadnego dokumentu. Zapis "DocumentChunk" w cudzysłowie to odwołanie do klasy zdefiniowanej niżej. Teraz pytanie i odpowiedź:

@dataclass
class Query:
    id: UUID = field(default_factory=uuid4)
    text: str = ""
    user_id: UUID | None = None
    created_at: datetime = field(default_factory=datetime.now)

@dataclass
class Response:
    query_id: UUID | None = None
    answer: str = ""
    sources: list[DocumentChunk] = field(default_factory=list)
    confidence: float = 0.0
    latency_ms: float = 0.0

Żadna z tych klas nie importuje Qdranta ani FastAPI. To celowe: domenę możesz przetestować bez uruchamiania czegokolwiek.

Repository Pattern

Repository Pattern to abstrakcja dostępu do danych. Domena mówi "zapisz dokument" albo "znajdź podobne fragmenty", ale nie wie, gdzie te dane leżą. Klasa abstrakcyjna ABC z dekoratorem @abstractmethod definiuje kontrakt: metody, które każda implementacja musi dostarczyć.

from abc import ABC, abstractmethod
from typing import Optional

class DocumentRepository(ABC):
    @abstractmethod
    async def save(self, document: Document) -> Document:
        pass

    @abstractmethod
    async def get_by_id(self, doc_id: UUID) -> Optional[Document]:
        pass

    @abstractmethod
    async def search(self, query_embedding: list[float], limit: int) -> list[DocumentChunk]:
        pass

Nie da się utworzyć obiektu DocumentRepository bezpośrednio, Python zgłosi TypeError, dopóki podklasa nie zaimplementuje wszystkich metod abstrakcyjnych. Metody są async, bo rozmowa z bazą to operacja wejścia-wyjścia. Oto implementacja dla Qdranta:

class QdrantDocumentRepository(DocumentRepository):
    def __init__(self, client, collection_name: str):
        self.client = client
        self.collection = collection_name

    async def save(self, document: Document) -> Document:
        # Implementation
        pass

    async def get_by_id(self, doc_id: UUID) -> Optional[Document]:
        # Implementation
        pass

    async def search(self, query_embedding: list[float], limit: int) -> list[DocumentChunk]:
        response = await self.client.query_points(
            collection_name=self.collection,
            query=query_embedding,
            limit=limit
        )
        return [self._to_chunk(point) for point in response.points]

W bieżącym qdrant-client wyszukiwanie robi się metodą query_points, która zwraca obiekt z listą points. Starsza metoda search była najpierw oznaczona jako przestarzała, a w nowych wersjach klienta już jej nie ma, więc w starszych tutorialach możesz ją jeszcze spotkać. Żeby await działał, client musi być instancją AsyncQdrantClient. Metody save, get_by_id i pomocnicze _to_chunk zostawiamy jako szkic do uzupełnienia w projekcie.

Dependency Injection

Dependency Injection (wstrzykiwanie zależności) oznacza, że klasa dostaje swoje zależności z zewnątrz, zamiast tworzyć je sama w środku. Dzięki temu w testach podajesz atrapę, a w produkcji prawdziwy Qdrant. Zacznijmy od najprostszego kontenera, czyli słownika "interfejs, implementacja":

from functools import lru_cache

from fastapi import Depends

class Container:
    """Prosty kontener DI."""

    def __init__(self):
        self._services = {}

    def register(self, interface: type, implementation):
        self._services[interface] = implementation

    def resolve(self, interface: type):
        return self._services.get(interface)

register zapamiętuje obiekt pod kluczem typu, resolve go oddaje. Rejestracja wygląda tak (LLMService i OpenAILLMService to analogiczna para interfejsu i implementacji, a qdrant_client i llm_client to klienci utworzeni wcześniej przy starcie aplikacji):

# Setup
container = Container()
container.register(DocumentRepository, QdrantDocumentRepository(qdrant_client, "documents"))
container.register(LLMService, OpenAILLMService(llm_client))

Zauważ, że nic tu się nie zmieniło w klasach domeny, zmieniła się tylko konfiguracja. Na koniec podłączamy kontener do FastAPI przez Depends, czyli wbudowany mechanizm wstrzykiwania zależności w tym frameworku:

# Usage in FastAPI
@lru_cache
def get_container() -> Container:
    return container

def get_document_repo(container: Container = Depends(get_container)):
    return container.resolve(DocumentRepository)

@lru_cache sprawia, że get_container zwraca zawsze ten sam obiekt. Endpoint, który zadeklaruje parametr z Depends(get_document_repo), dostanie repozytorium bez wiedzy, skąd ono pochodzi. W testach podmienisz je przez app.dependency_overrides.

Moja rada: na początek wystarczy taki ręczny kontener i Depends. Biblioteki DI dodawaj dopiero, gdy zależności naprawdę zaczną się mnożyć. W następnej lekcji zobaczysz, jak ta architektura ułatwia testowanie.

Pamiętaj: architektura to plan obozu, w którym każdy namiot da się przenieść bez burzenia pozostałych.

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. Która warstwa w Clean Architecture zawiera logikę biznesową?

  2. 2. Co to jest Dependency Injection?

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

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj kroki:

  • Edytor kodu

    Stwórz DocumentRepository z metodami CRUD

  • Układanie w poziomie

    Ułóż elementy:

  • Klikanie w kolejności

    Kliknij w kolejności:

  • Układanie w pionie

    Ułóż warstwy Clean Architecture od warstwy UI do warstwy danych:

  1. PytanieClean Architecture
  2. PytanieDependency Injection
  3. PytanieRepository Pattern
  4. Ułóż w kolejnościWzorzec Clean Architecture
  5. Zadanie z kodemRepository Implementation
  6. Ułóż w kolejnościABC import
  7. Kliknij w kolejnościAbstract method
  8. Ułóż w kolejnościWarstwy Clean Architecture

Przydatne artykuły