Kurs Python · Moduł 10: AI i modele językowe

Production Deployment - wdrożenie AI

6 min czytania ·
W tej lekcji6

Kod z poprzedniej lekcji działa u Ciebie w terminalu i nikt poza Tobą nie ma do niego dostępu. Wdrożenie to zamiana notatnika terenowego na stację radiową: liczy się nie tylko to, że nadaje, ale też ile kosztuje i czy widać, gdy zamilknie.

Endpoint /chat - najprostsze wystawienie modelu

FastAPI opisuje endpoint dekoratorem @app.post, a kształt danych wejściowych i wyjściowych - klasą Pydantic BaseModel. Dzięki temu nie sprawdzasz ręcznie, czy klient przysłał pole message: biblioteka sama odrzuci błędne zapytanie.

from fastapi import FastAPI
from pydantic import BaseModel
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI()

class ChatRequest(BaseModel):
    message: str

class ChatResponse(BaseModel):
    response: str

@app.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
    completion = await client.chat.completions.create(
        model="gpt-5",
        messages=[{"role": "user", "content": request.message}]
    )
    return ChatResponse(response=completion.choices[0].message.content)

ChatRequest opisuje, co przychodzi, ChatResponse - co wychodzi, a response_model pilnuje, żeby odpowiedź miała ten kształt. Klasa AsyncOpenAI pozwala użyć await, więc serwer w czasie oczekiwania obsługuje innych klientów. Instrukcja return oddaje całą odpowiedź naraz, więc użytkownik kilkanaście sekund patrzy w pustkę.

Streaming: StreamingResponse i generator asynchroniczny

Zwykłego return nie da się namówić na streaming. To nie kwestia ustawienia, tylko definicji: return kończy funkcję i oddaje wartość, więc wartość musi już być kompletna. Nie pomogą pliki tymczasowe - zapis następuje i tak po otrzymaniu całego tekstu. Da się to jednak zrobić: potrzebujesz funkcji oddającej tekst kawałkami i klasy StreamingResponse, która opakuje ją w odpowiedź HTTP.

from fastapi.responses import StreamingResponse

@app.post("/chat/stream")
async def chat_stream(request: ChatRequest):
    async def generate():
        stream = await client.chat.completions.create(
            model="gpt-5",
            messages=[{"role": "user", "content": request.message}],
            stream=True
        )
        async for chunk in stream:
            content = chunk.choices[0].delta.content
            if content:
                yield f"data: {content}\n\n"
        yield "data: [DONE]\n\n"

    return StreamingResponse(generate(), media_type="text/event-stream")

Cała różnica siedzi w słowie yield. Funkcja generate nie zwraca wyniku i nie kończy się - oddaje fragment i zawiesza się, aż ktoś poprosi o następny. Taka funkcja to generator asynchroniczny, a StreamingResponse wysyła jej fragmenty klientowi na bieżąco.

Dwie ciche awarie warto zapamiętać bo żadna nie zgłasza błędu. Bez warunku if content: w środku strumienia wyląduje tekst None, bo skrajne fragmenty mają puste delta.content. A bez końcowego yield z [DONE] klient kręci wskaźnik ładowania mimo skończonej pracy serwera.

WebSocket - kiedy jeden kierunek to za mało

Streaming rozwiązuje połowę problemu: serwer mówi dłużej, ale wciąż tylko w odpowiedzi na pytanie. HTTP działa w schemacie zapytanie-odpowiedź i serwer nie ma jak odezwać się pierwszy - a przy chatbocie chcesz wysyłać powiadomienia albo wynik zadania, o które nikt akurat nie pyta.

WebSocket utrzymuje jedno otwarte połączenie, w którym obie strony wysyłają wiadomości w dowolnym momencie - to właśnie dwukierunkowa komunikacja w czasie rzeczywistym. I to jedyny prawdziwy powód, żeby po niego sięgnąć. Nie jest "szybszy niż HTTP": jedzie po tym samym TCP. Nie jest bezpieczniejszy - ws:// idzie otwartym tekstem, a wss:// używa tego samego TLS co https. I na pewno nie jest tak, że nie wymaga serwera: wymaga go bardziej, bo ten trzyma połączenie otwarte przez całą rozmowę.

from fastapi import WebSocket, WebSocketDisconnect

active_connections: dict[str, WebSocket] = {}

@app.websocket("/ws/{client_id}")
async def websocket_endpoint(websocket: WebSocket, client_id: str):
    await websocket.accept()
    active_connections[client_id] = websocket
    try:
        while True:
            question = await websocket.receive_text()
            answer = await ask_model(question)
            await websocket.send_text(answer)
    except WebSocketDisconnect:
        del active_connections[client_id]

Funkcja ask_model to wywołanie modelu z pierwszego przykładu, a pętla while True obsługuje kolejne wiadomości bez rozłączania. Słownik active_connections trzyma połączenia po identyfikatorze klienta - dzięki temu wyślesz komuś wiadomość nawet wtedy, gdy o nic nie pytał. Pominięcie usunięcia wpisu przy WebSocketDisconnect to wyciek pamięci: serwer działa tygodniami, a słownik puchnie od martwych wpisów.

Cache i limity - żeby rachunek nie rósł w nieskończoność

Każde wywołanie modelu to osobna opłata za tokeny: gdy sto osób zapyta o to samo, zapłacisz sto razy za identyczną odpowiedź. Caching zmniejsza koszty API i przyspiesza odpowiedzi, bo zapamiętany wynik wraca w milisekundach, bez ruszania sieci.

from cachetools import TTLCache
from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
response_cache = TTLCache(maxsize=1000, ttl=3600)

@app.post("/chat/cached")
@limiter.limit("10/minute")
async def chat_cached(request: ChatRequest):
    key = request.message.strip().lower()
    if key in response_cache:
        return {"response": response_cache[key], "cached": True}

    response_cache[key] = await ask_model(request.message)
    return {"response": response_cache[key], "cached": False}

TTLCache sam usuwa wpisy po godzinie (ttl=3600), więc odpowiedzi nie zestarzeją się na dobre, a kluczem jest treść pytania - dwa identyczne pytania trafiają w ten sam wpis.

Warto jednak wiedzieć, że cache nie poprawia jakości odpowiedzi - zwraca ten sam tekst, który padł wcześniej, więc słaba odpowiedź wróci równie słaba, tylko szybciej. Nie jest też wymagany przez żadne prawo, to Twoja decyzja o kosztach. Dekorator @limiter.limit("10/minute") z biblioteki slowapi ogranicza zapytania z jednego adresu, żeby jeden klient nie wyczerpał budżetu w kwadrans.

Zanim wystawisz to na świat

Przed wdrożeniem LLM do produkcji najważniejsze są trzy rzeczy: testowanie, monitoring i zabezpieczenie kluczy API. Klucz musi przyjść ze zmiennej środowiskowej, nigdy z kodu - wpisany na stałe trafia do repozytorium, a stamtąd na cudzy rachunek. Monitoring zaczyna się od endpointu /health, po którym hosting poznaje, że proces jeszcze żyje.

import logging
import os

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("safari-ai")

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

@app.get("/health")
async def health_check():
    logger.info("health ok")
    return {"status": "healthy"}

Odczyt os.environ["OPENAI_API_KEY"] ma dodatkową zaletę: gdy zmiennej brakuje, aplikacja przerywa start, zamiast przyjmować ruch i dopiero przy pierwszym pytaniu zwrócić błąd. Wywołanie modelu warto opakować w try, żeby awaria dostawcy wróciła jako HTTPException, a logger.exception zapisał ślad do logów.

Trzy pokusy, którym trzeba się oprzeć. Najnowszy model bez testowania wygląda niewinnie, bo nazwa modelu to zwykły napis - tyle że nowy model inaczej formatuje odpowiedzi i cicho psuje parsowanie po Twojej stronie. Wyłączanie logowania dla szybkości oszczędza ułamek milisekundy, a odbiera jedyne źródło wiedzy o tym, co stało się w nocy. API bez limitów kończy się rachunkiem: klucz jest Twój, więc cudze zapytania też opłacasz Ty.

Podsumowanie

  • Streaming w FastAPI implementujesz przez StreamingResponse z generatorem asynchronicznym, czyli funkcją używającą yield.
  • Zwykły return streamingu nie daje, bo oddaje kompletną wartość i kończy funkcję. Pliki tymczasowe też nie pomagają, a zadanie jest wykonalne.
  • WebSocket wybierasz dlatego, że pozwala na dwukierunkową komunikację w czasie rzeczywistym. Nie jest szybszy niż HTTP, nie jest bezpieczniejszy i na pewno wymaga serwera trzymającego otwarte połączenie.
  • Endpoint /chat to @app.post i modele Pydantic: ChatRequest na wejściu, ChatResponse na wyjściu przez response_model.
  • Przed wdrożeniem LLM do produkcji najważniejsze są testowanie, monitoring i zabezpieczenie kluczy API w zmiennych środowiskowych. Najnowszy model bez testowania, wyłączone logowanie i API bez limitów to trzy najprostsze sposoby na zepsucie produkcji.
  • Caching zmniejsza koszty API i przyspiesza odpowiedzi. Nie poprawia ich jakości i nie jest wymagany przez prawo.

W następnej lekcji poznasz wzorzec ReAct, w którym agent na przemian myśli i działa, powtarzając cykl Thought - Action - Observation. Na razie zapamiętaj: wdrożenie to nie ostatni commit, tylko pierwszy dzień, gdy ktoś inny płaci Twoim kluczem za Twoje błędy.

Kod do tej lekcji: main.py
# ===========================================
# Safari Lab: FastAPI + LLM Integration
# ===========================================
# Build a REST API that connects to an LLM
# to serve safari wildlife information.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from openai import OpenAI

app = FastAPI(title="Safari AI Guide API")
client = OpenAI(api_key="your-api-key-here")

# --- Request/Response models ---
class AnimalQuery(BaseModel):
    animal: str
    question: str
    max_tokens: int = 150

class GuideResponse(BaseModel):
    animal: str
    answer: str
    tokens_used: int

# --- Safari guide endpoint ---
@app.post("/ask-guide", response_model=GuideResponse)
async def ask_safari_guide(query: AnimalQuery):
    """Ask the safari guide AI about any animal."""
    try:
        response = client.chat.completions.create(
            model="gpt-4",
            messages=[
                {
                    "role": "system",
                    "content": "You are Darwin, an expert safari guide. "
                               "Give concise, factual answers about wildlife."
                },
                {
                    "role": "user",
                    "content": f"About the {query.animal}: {query.question}"
                }
            ],
            max_tokens=query.max_tokens,
            temperature=0.7
        )

        return GuideResponse(
            animal=query.animal,
            answer=response.choices[0].message.content,
            tokens_used=response.usage.total_tokens
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

# --- Health check endpoint ---
@app.get("/health")
async def health_check():
    return {"status": "active", "service": "Safari AI Guide"}

# --- List available species ---
@app.get("/species")
async def list_species():
    return {
        "species": [
            "Lion", "Elephant", "Giraffe", "Zebra",
            "Cheetah", "Hippo", "Rhino", "Leopard"
        ]
    }

# TODO: Add an endpoint for batch animal queries
# class BatchQuery(BaseModel):
#     animals: list[str]
#     question: str
#
# @app.post("/ask-guide/batch")
# async def batch_query(query: BatchQuery):
#     results = []
#     for animal in query.animals:
#         single_query = AnimalQuery(animal=animal, question=query.question)
#         result = await ask_safari_guide(single_query)
#         results.append(result)
#     return {"results": results}

# TODO: Add a streaming endpoint
# from fastapi.responses import StreamingResponse
#
# @app.post("/ask-guide/stream")
# async def stream_guide(query: AnimalQuery):
#     async def generate():
#         stream = client.chat.completions.create(
#             model="gpt-4",
#             messages=[{"role": "user", "content": query.question}],
#             stream=True
#         )
#         for chunk in stream:
#             if chunk.choices[0].delta.content:
#                 yield chunk.choices[0].delta.content
#     return StreamingResponse(generate(), media_type="text/plain")

print("=== Safari AI Guide API ===")
print("Endpoints:")
print("  POST /ask-guide - Ask about an animal")
print("  GET  /health    - Health check")
print("  GET  /species   - List species")
print("\nRun with: uvicorn main:app --reload")

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. Jak zaimplementować streaming odpowiedzi AI w FastAPI?

  2. 2. Dlaczego WebSocket jest dobry dla chatbotów AI?

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

Zadania praktyczne w grze

  • Edytor kodu

    Zaimplementuj endpoint /chat przyjmujący wiadomość i zwracający odpowiedź AI.

  1. PytanieStreaming w FastAPI
  2. PytanieWebSocket chat
  3. Zadanie z kodemFastAPI + LLM
  4. PytanieProduction checklist
  5. PytanieCaching AI

Przydatne artykuły