Kurs Python · Moduł 12: Projekt końcowy
Planowanie Projektu AI
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ższyPole 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. Co to jest User Story w metodologii Agile?
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: