Kurs Python · Moduł 12: Projekt końcowy
Dokumentacja Techniczna
W tej lekcji3
Najlepszy przewodnik po sawannie jest bezużyteczny, jeśli jego wiedza znika razem z nim. Nowy członek ekspedycji dostaje wtedy tylko kopię tropów bez legendy. Z kodem jest tak samo: projekt bez dokumentacji umie uruchomić jedna osoba, a po trzech miesiącach nawet ona zapomina, jak to robiła. Dokumentacja to most między kodem a ludźmi. Dobra dokumentacja sprawia, że projekt żyje nawet wtedy, gdy Ty śpisz, a rekruter albo nowy współpracownik rozumie go w pięć minut.
Dokumentację budujemy na trzech poziomach: README dla człowieka, który widzi repozytorium pierwszy raz, docstringi dla osoby czytającej kod oraz automatyczna dokumentacja API dla tych, którzy z niego korzystają. Dobra kolejność pracy to najpierw README, potem docstringi, potem konfiguracja generowanej dokumentacji API, a na koniec CHANGELOG.md, czyli dziennik zmian w kolejnych wersjach.
README.md - wizytówka projektu
README to pierwsza rzecz, którą GitHub pokazuje pod listą plików. Typowa kolejność sekcji: tytuł, opis lub funkcje, szybki start, a na końcu licencja. Oto kompletny przykład dla naszego asystenta:
# AI Document Assistant
Inteligentny asystent do przeszukiwania dokumentów wykorzystujący RAG.
## Funkcje
- Semantic search w dokumentach
- Odpowiedzi w języku naturalnym
- Obsługa PDF, DOCX, TXT
- Szybkie odpowiedzi (<2s)
## Quick Start
### Wymagania
- Python 3.12+
- Docker (dla Qdrant)
### Instalacja
```bash
# Klonuj repo
git clone https://github.com/user/ai-doc-assistant.git
cd ai-doc-assistant
# Utwórz środowisko
python -m venv venv
source venv/bin/activate
# Zainstaluj zależności
pip install -r requirements.txt
# Uruchom Qdrant
docker compose up -d qdrant
# Ustaw zmienne środowiskowe
cp .env.example .env
# Edytuj .env i dodaj OPENAI_API_KEY
# Uruchom aplikację
uvicorn app.main:app --reload
```
## API Documentation
Po uruchomieniu: http://localhost:8000/docs
## Architecture
[Link do diagramu architektury]
## Testing
```bash
pytest tests/ -v
```
## License
MITInstrukcja instalacji to kolejne polecenia, które da się skopiować i uruchomić: klon, wirtualne środowisko, zależności, baza, zmienne środowiskowe, start. Zwróć uwagę na cp .env.example .env: prawdziwe klucze nigdy nie trafiają do repozytorium, tylko wzór pliku. docker compose (ze spacją) to obecna wersja narzędzia, wbudowana w Dockera jako plugin.
Docstrings - dokumentacja w kodzie
Docstring to napis w potrójnych cudzysłowach zaraz pod definicją klasy lub funkcji. PEP 257 opisuje ogólne konwencje, a sam format sekcji wybierasz. Najpopularniejsze są Google style i NumPy style, oba czytane przez Sphinx (rozszerzenie napoleon). My używamy Google style: sekcje Attributes, Args, Returns, Raises i Example.
from typing import Optional
class RAGService:
"""
Serwis RAG do odpowiadania na pytania na podstawie dokumentów.
Ten serwis implementuje pełny pipeline RAG:
1. Embedding pytania
2. Wyszukiwanie podobnych dokumentów
3. Generowanie odpowiedzi z kontekstem
Attributes:
vector_store: Klient do vector database
llm: Klient do modelu językowego
embedder: Serwis do tworzenia embeddingów
Example:
>>> service = RAGService(vector_store, llm, embedder)
>>> response = await service.query("Co to jest Python?")
>>> print(response.answer)
Python to język programowania...
"""Docstring klasy mówi, co serwis robi i z czego się składa. Przykład w formacie >>> pokazuje użycie, a linia pod nim to wypisany wynik. Konstruktor jest prosty i nie wymaga osobnego opisu:
def __init__(
self,
vector_store: VectorStore,
llm: LLMClient,
embedder: EmbeddingService
):
self.vector_store = vector_store
self.llm = llm
self.embedder = embedderTypy argumentów (VectorStore, LLMClient, EmbeddingService) to interfejsy z warstwy infrastruktury, zgodnie z architekturą z poprzedniej lekcji. Najwięcej opisu wymaga metoda publiczna:
async def query(
self,
question: str,
top_k: int = 5,
filters: Optional[dict] = None
) -> Response:
"""
Wykonuje zapytanie RAG.
Args:
question: Pytanie użytkownika w języku naturalnym
top_k: Liczba dokumentów do pobrania (default: 5)
filters: Opcjonalne filtry metadanych
Returns:
Response: Obiekt zawierający odpowiedź i źródła
Raises:
ValueError: Gdy pytanie jest puste
LLMError: Gdy wystąpi błąd generowania
Example:
>>> response = await service.query(
... "Jak działa RAG?",
... top_k=3,
... filters={"category": "ai"}
... )
"""
if not question.strip():
raise ValueError("Question cannot be empty")
# Implementation...Sekcja Raises jest często pomijana, a to ona mówi, co może pójść źle. Docstring możesz odczytać w konsoli przez help(RAGService.query), więc to dokumentacja, która zawsze jest pod ręką. Uwaga: przykład z await służy do czytania, zwykły doctest go nie uruchomi.
API Documentation z FastAPI
FastAPI generuje dokumentację API w standardzie OpenAPI (dawniej Swagger) automatycznie, na podstawie typów i modeli Pydantic. Najpierw metadane aplikacji:
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
app = FastAPI(
title="AI Document Assistant API",
description="REST API dla inteligentnego asystenta dokumentów",
version="1.0.0",
docs_url="/docs",
redoc_url="/redoc"
)Pod /docs dostajesz interaktywne Swagger UI, pod /redoc alternatywny widok ReDoc. Teraz modele żądania i odpowiedzi. Pydantic waliduje dane, a Field dodaje ograniczenia i opisy:
class QueryRequest(BaseModel):
"""Request do zapytania RAG."""
question: str = Field(
...,
description="Pytanie w języku naturalnym",
examples=["Co to jest machine learning?"]
)
top_k: int = Field(
default=5,
ge=1,
le=20,
description="Liczba dokumentów źródłowych"
)
class QueryResponse(BaseModel):
"""Odpowiedź z systemu RAG."""
answer: str = Field(description="Wygenerowana odpowiedź")
sources: list[dict] = Field(description="Dokumenty źródłowe")
latency_ms: float = Field(description="Czas odpowiedzi w ms")ge=1, le=20 oznacza "od 1 do 20", więc top_k=50 zostanie odrzucone z błędem 422, zanim trafi do Twojego kodu. Przykładowe wartości podajemy przez examples=[...]. Stary parametr example= jest w Pydantic v2 przestarzały i generuje ostrzeżenie. Na koniec endpoint:
@app.post(
"/query",
response_model=QueryResponse,
summary="Zadaj pytanie",
description="Wykonuje zapytanie RAG i zwraca odpowiedź z źródłami"
)
async def query(request: QueryRequest) -> QueryResponse:
"""
Endpoint do zadawania pytań systemowi RAG.
- **question**: Pytanie w języku naturalnym
- **top_k**: Liczba dokumentów do przeszukania
"""
passsummary i description pojawią się w Swagger UI, a docstring z markdownem również. Nie piszesz żadnego osobnego pliku dokumentacji, schemat powstaje z kodu, więc nie rozjedzie się z rzeczywistością.
Moja rada: pisz README w tym samym dniu, w którym zakładasz repozytorium, a nie na końcu projektu. Dokumentacja pisana na bieżąco jest krótsza i prawdziwsza. W następnej lekcji przejdziemy do deploymentu.
Pamiętaj: dokumentacja to dziennik ekspedycji, dzięki któremu następna wyprawa pójdzie Twoimi tropami bez zgadywania.
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. Który styl docstringów jest zalecany dla Pythona?
2. Który standard jest używany do dokumentacji REST API w Pythonie?
Zadania praktyczne w grze
- Edytor kodu
Stwórz profesjonalny docstring
- Układanie w pionie
Uporządkuj kroki:
- Układanie w poziomie
Ułóż typowe sekcje README.md: