Kurs Python · Moduł 12: Projekt końcowy

Planowanie Projektu AI

6 min czytania ·
W tej lekcji3

Witaj w finale Python Safari! Wyobraź sobie ekspedycję, która rusza w sawannę bez mapy, bez listy zapasów i bez celu. Po trzech dniach ktoś pyta "po co właściwie tu jesteśmy?", a nikt nie umie odpowiedzieć. Z projektami programistycznymi jest dokładnie tak samo: najczęściej nie upadają przez zły kod, tylko przez to, że nikt nie zapisał, jaki problem rozwiązują i kiedy można uznać je za skończone. W tym module połączysz wszystkie zdobyte umiejętności w jeden kompleksowy projekt, a zaczniemy od mapy ekspedycji.

Czego się nauczysz

  • zapisywać problem i miary sukcesu projektu w kodzie Pythona, zamiast trzymać je w głowie
  • formułować user stories z kryteriami akceptacji
  • szacować zadania w story points i układać je w sprinty
  • uzasadniać wybór stosu technologicznego

Metodologia planowania projektu

1. Definiowanie problemu

Zanim napiszemy pierwszą linię aplikacji, nazwijmy rodzaj projektu. Do zamkniętej listy wariantów Python ma typ Enum z modułu enum: każdy członek wyliczenia ma nazwę i wartość, a literówka w nazwie od razu kończy się błędem, zamiast cicho przejść dalej.

from dataclasses import dataclass
from enum import Enum

class ProjectType(Enum):
    WEB_APP = "web_application"
    API = "api_service"
    ML_PIPELINE = "ml_pipeline"
    RAG_SYSTEM = "rag_system"
    AUTOMATION = "automation"

Na razie to tylko słownik rodzajów wypraw, nic się jeszcze nie dzieje. Teraz opiszmy samą wyprawę. Dekorator @dataclass z modułu dataclasses sam generuje __init__, __repr__ i porównywanie na podstawie pól z adnotacjami typów, więc klasa z danymi mieści się w kilku linijkach.

@dataclass
class ProjectDefinition:
    """Definicja projektu."""
    name: str
    problem_statement: str
    target_users: list[str]
    success_metrics: list[str]
    project_type: ProjectType
    tech_stack: list[str]

Adnotacje typu list[str] to dokumentacja i podpowiedź dla edytora oraz narzędzi takich jak mypy. Python ich nie wymusza w czasie działania, więc dataclass nie odrzuci złego typu. Zobaczmy wypełnioną definicję projektu:

# Przykład
capstone_project = ProjectDefinition(
    name="AI Document Assistant",
    problem_statement="Użytkownicy tracą czas na szukanie informacji w dokumentach",
    target_users=["analitycy", "prawnicy", "badacze"],
    success_metrics=[
        "Redukcja czasu wyszukiwania o 70%",
        "Dokładność odpowiedzi > 90%",
        "Czas odpowiedzi < 2s"
    ],
    project_type=ProjectType.RAG_SYSTEM,
    tech_stack=["Python", "FastAPI", "LlamaIndex", "Qdrant", "React"]
)

Najważniejsze są tu metryki sukcesu. "Czas odpowiedzi < 2s" da się zmierzyć, a "szybka aplikacja" już nie. To są cele, które sami sobie stawiamy, a nie gotowe dane: przy każdej metryce warto od razu zapisać, jak ją zmierzysz.

2. User Stories

User story to opis funkcji z perspektywy użytkownika, w stałym formacie "jako [kto] chcę [co], aby [po co]". Kryteria akceptacji mówią, kiedy historia jest skończona. W kodzie zapiszemy to kolejną dataclass:

@dataclass
class UserStory:
    """User story w formacie Agile."""
    as_a: str
    i_want: str
    so_that: str
    acceptance_criteria: list[str]
    priority: int  # 1-5, 1 = najwyższy

Pole priority to zwykła liczba, a komentarz ustala umowę, że 1 oznacza najwyższy priorytet. Teraz dwie konkretne historie, dla analityka i dla administratora:

stories = [
    UserStory(
        as_a="analityk",
        i_want="zadać pytanie o dokumenty w języku naturalnym",
        so_that="szybko znajdę potrzebne informacje",
        acceptance_criteria=[
            "System rozumie pytania po polsku",
            "Odpowiedź zawiera źródła",
            "Czas odpowiedzi < 3s"
        ],
        priority=1
    ),
    UserStory(
        as_a="administrator",
        i_want="łatwo dodawać nowe dokumenty",
        so_that="baza wiedzy była aktualna",
        acceptance_criteria=[
            "Upload przez drag & drop",
            "Obsługa PDF, DOCX, TXT",
            "Automatyczna indeksacja"
        ],
        priority=2
    )
]

Zwróć uwagę, że historie nie mówią nic o technologii. Analityk nie wie, czym jest wektorowa baza danych, i nie musi. Kryteria typu "Odpowiedź zawiera źródła" staną się później testami, więc pisz je tak, by dało się je sprawdzić.

3. Estymacja i planowanie sprintów

W Scrumie pracę dzieli się na sprinty, czyli odcinki o stałej długości, najwyżej miesiąc. W praktyce zespoły najczęściej wybierają dwa tygodnie. Zadania szacuje się w story points, czyli względnej złożoności, a nie w godzinach. Popularna skala to ciąg Fibonacciego (1, 2, 3, 5, 8, 13), bo rosnące przerwy między liczbami przypominają, że duże zadania są coraz mniej przewidywalne.

from datetime import datetime, timedelta

@dataclass
class Task:
    name: str
    story_points: int  # Fibonacci: 1, 2, 3, 5, 8, 13
    dependencies: list[str]
    assigned_to: str = ""

Task pamięta też zależności, czyli nazwy zadań, które muszą być gotowe wcześniej. Sprint dostaje dwie właściwości liczone w locie dzięki @property: datę końca i sumę punktów.

@dataclass
class Sprint:
    number: int
    start_date: datetime
    tasks: list[Task]
    velocity: int = 20  # Story points per sprint

    @property
    def end_date(self) -> datetime:
        return self.start_date + timedelta(days=14)

    @property
    def total_points(self) -> int:
        return sum(t.story_points for t in self.tasks)

velocity to liczba punktów, którą zespół realnie domyka w jednym sprincie. Zakładamy 20, ale prawdziwą wartość poznasz dopiero po kilku sprintach. Zobaczmy plan dwóch pierwszych etapów wyprawy:

# Plan projektu
sprints = [
    Sprint(1, datetime(2024, 1, 1), [
        Task("Setup projektu", 2, []),
        Task("Konfiguracja CI/CD", 3, ["Setup projektu"]),
        Task("Podstawowe API", 5, ["Setup projektu"]),
        Task("Integracja Vector DB", 5, ["Podstawowe API"]),
    ]),
    Sprint(2, datetime(2024, 1, 15), [
        Task("RAG Pipeline", 8, ["Integracja Vector DB"]),
        Task("Chat interface", 5, ["Podstawowe API"]),
        Task("Document upload", 5, ["RAG Pipeline"]),
    ])
]

Kolejność wynika z zależności: najpierw setup, potem API, dopiero potem RAG. Pierwszy sprint ma 15 punktów, drugi 18, więc oba mieszczą się w założonym velocity i zostaje zapas na niespodzianki.

Wybór stosu technologicznego

Ostatni element mapy to decyzje technologiczne. Zapisz przy każdym wyborze powody, bo za pół roku ktoś (może Ty) zapyta, dlaczego akurat Qdrant.

tech_decisions = {
    "backend": {
        "choice": "FastAPI",
        "reasons": ["Async", "Type hints", "Auto docs", "Performance"]
    },
    "vector_db": {
        "choice": "Qdrant",
        "reasons": ["Self-hosted", "Filtering", "Rust performance"]
    },
    "llm": {
        "choice": "OpenAI API",
        "reasons": ["Quality", "Function calling", "Reliable"]
    },
    "rag_framework": {
        "choice": "LlamaIndex",
        "reasons": ["Flexibility", "Integrations", "Community"]
    }
}

Przy modelu językowym celowo zapisaliśmy dostawcę, a nie konkretny model. Nazwy modeli zmieniają się co kilka miesięcy, a starsze wersje są wycofywane, więc aktualny model wybierz z listy w dokumentacji dostawcy w dniu startu projektu. Moja rada: trzymaj tę listę decyzji w repozytorium obok kodu, a nie w notatkach, bo wtedy żyje razem z projektem.

Cały cykl życia projektu to kolejno planowanie, implementacja, testowanie, deployment i monitoring. Instalację zależności z pliku requirements.txt robi się poleceniem pip install -r requirements.txt, a konkretną wersję pakietu przypinasz zapisem nazwa==wersja, na przykład pip install numpy==1.26.4. W następnej lekcji zaprojektujemy architekturę systemu, która zamieni ten plan w strukturę kodu.

Pamiętaj: dobry plan ekspedycji to połowa sukcesu, bo mapa narysowana przed wyjazdem oszczędza tygodni błądzenia po sawannie.

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 to jest User Story w metodologii Agile?

  2. 2. Ile trwa typowy Sprint w metodyce Scrum?

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

    Zaimplementuj ProjectDefinition dataclass

  • Układanie w poziomie

    Ułóż elementy:

  • Klikanie w kolejności

    Kliknij w kolejności:

  1. PytanieUser Stories
  2. PytanieSprint w Scrum
  3. PytanieStory Points
  4. Ułóż w kolejnościCykl życia projektu
  5. Zadanie z kodemProject Definition
  6. Ułóż w kolejnościPip install
  7. Kliknij w kolejnościDataclass definition

Przydatne artykuły