Ollama w Docker Compose z GPU i trwałym magazynowaniem modeli
Serwer Ollama w stylu Compose-first z obsługą GPU i trwałym zapisem danych.
Ollama świetnie działa na “gołym” metalu (bez warstwy wirtualizacji). Staje się jeszcze ciekawszy, gdy traktujesz go jak usługę: stabilny punkt końcowy, przypięte wersje, trwałe przechowywanie danych oraz GPU, które jest dostępne, lub go nie ma.
Ten artykuł koncentruje się na jednym celu: odtwarzalny lokalny lub jednotelematyczny “serwer” Ollama z użyciem Docker Compose, z akceleracją GPU i trwałym przechowywaniem modeli.
Świadomie pomijam ogólne podstawy Dockera i Compose’a. Gdy potrzebujesz zwartej listy najczęściej używanych poleceń (obrazy, kontenery, wolumeny, docker compose), Ściągawka Docker będzie dobrym towarzyszem.
Gdy chcesz HTTPS przed Ollama, prawidłowe strumieniowanie i proxy WebSocket oraz kontrolę na brzegu (uwierzytelnianie, limity czasu, limity przepustowości), zobacz Ollama za reverse proxy z Caddy lub Nginx dla HTTPS streaming.
Aby dowiedzieć się, jak Ollama współgra z vLLM, Docker Model Runner, LocalAI oraz jakie są kompromisy przy chmurowym hostingu, zobacz LLM Hosting w 2026: Lokalnie, Self-Hosted i Chmura w porównaniu.
Gdy ta stos Compose’a obsługuje już realny ruch równoległy, często pojawia się pytanie, czy Ollama nadal jest właściwym silnikiem pod spodem. Ollama do vLLM: Kiedy migrować swój lokalny serwer LLM przedstawia etapową ścieżkę migracji, która pozwala obu kontenerom działać obok siebie podczas walidacji.
Kiedy Compose wygrywa z instalacją na gołym metalu
Natywna instalacja jest bezproblemowa dla jednego dewelopera na jednej maszynie. W momencie, gdy masz cokolwiek z poniższych elementów, Compose zaczyna wygrywać ergonomią:
Konfiguracja zespołowa odnosi z tego korzyści, ponieważ definicja usługi jest plikiem, który można przeglądać, wersjonować i udostępniać. Serwer jednostelematyczny odnosi korzyści, ponieważ aktualizacje sprowadzają się do zmiany tagu obrazu i restartu, podczas gdy przechowywane modele pozostają na swoim miejscu (o ile znajdują się na wolumenie). Ollama często mieszka obok usług pomocniczych (sidecarów): interfejsu Web UI, reverse proxy, bramki uwierzytelniania, bazy wektorowej lub silnika agentów. Compose jest dobry w “jednym poleceniu na start całego stosu”, nie zamieniając przy tym hosta w unikatowego egzemplarza (“snowflake”).
To podejście dobrze współgra z tym, jak zaprojektowany jest oficjalny kontener Ollama: obraz domyślnie uruchamia ollama serve, wystawia port 11434 i jest przeznaczony do przechowywania stanu w montowalnym katalogu. Pełny zestaw zmiennych środowiskowych OLLAMA_*, które odczytuje ollama serve — OLLAMA_HOST, OLLAMA_CONTEXT_LENGTH, OLLAMA_KEEP_ALIVE, OLLAMA_NUM_PARALLEL i pozostałe — jest udokumentowany w Ściągawce CLI Ollama.
Szkielet Compose’a, który faktycznie przydaje się w Ollama
Zacznij od dwóch decyzji:
Po pierwsze, jak będziesz przypinać wersje. Obraz na Docker Hub to ollama/ollama, więc możesz przypisać konkretny tag w pliku .env zamiast polegać na latest.
Po drugie, gdzie będą mieszkać dane modeli. Oficjalna dokumentacja montuje wolumen do /root/.ollama, aby modele nie były ponownie pobierane za każdym razem, gdy kontener jest zastępowany.
Oto plik Compose’a, który wbudowuje te decyzje i utrzymuje “regulatory” blisko usługi:
services:
ollama:
image: ollama/ollama:${OLLAMA_IMAGE_TAG:-latest}
container_name: ollama
restart: unless-stopped
# Domysłnie tylko lokalnie, wystaw później, jeśli będzie to potrzebne.
ports:
- "${OLLAMA_BIND_IP:-127.0.0.1}:11434:11434"
# Trwałe modele i stan serwera.
volumes:
- ollama:/root/.ollama
environment:
# Oficjalny obraz domyślnie używa 0.0.0.0:11434 wewnątrz kontenera,
# ale zachowanie tego wprost pomaga, gdy później będziesz to nadpisywać.
- OLLAMA_HOST=0.0.0.0:11434
# Dostrojenie usługi.
- OLLAMA_KEEP_ALIVE=${OLLAMA_KEEP_ALIVE:-5m}
- OLLAMA_NUM_PARALLEL=${OLLAMA_NUM_PARALLEL:-1}
- OLLAMA_MAX_LOADED_MODELS=${OLLAMA_MAX_LOADED_MODELS:-1}
# Opcjonalne, ale istotne, gdy interfejs oparty na przeglądarce rozmawia bezpośrednio z Ollama.
# Zobacz sekcję Sieć, aby dowiedzieć się, po co to istnieje.
- OLLAMA_ORIGINS=${OLLAMA_ORIGINS:-}
# Rezerwacja GPU to osobna sekcja poniżej.
# Dodawaj ją tylko na hostach, które faktycznie mają GPU NVIDIA.
volumes:
ollama: {}
Pasujący do tego plik .env sprawia, że aktualizacje są nudne (w dobrym sensie):
# Przypnij wersję obrazu, którą przetestowałeś.
OLLAMA_IMAGE_TAG=latest
# Domyślnie lokalnie. Zmień na 0.0.0.0, gdy świadomie chcesz to wystawić na zewnątrz.
OLLAMA_BIND_IP=127.0.0.1
# Keep-alive balansuje opóźnienie zimnego startu z zapotrzebowaniem na pamięć.
OLLAMA_KEEP_ALIVE=5m
# Regulatory równoległości.
OLLAMA_NUM_PARALLEL=1
OLLAMA_MAX_LOADED_MODELS=1
# Pozostaw puste, chyba że obsługujesz klientów przeglądarkowych, którzy uderzają bezpośrednio w Ollama.
OLLAMA_ORIGINS=
Mała, ale ważna niuans: sam Ollama ma domyślnie wiązanie hosta 127.0.0.1:11434 w ogólnej konfiguracji, ale oficjalny obraz kontenera ustawia OLLAMA_HOST=0.0.0.0:11434, aby usługa była osiągalna przez wystawione porty.
Jeśli chcesz szybkiego sprawdzenia bez angażowania jakichkolwiek SDK klienckich, API Ollama zawiera punkt końcowy “lista modeli lokalnych” pod GET /api/tags.
Trwałe przechowywanie modeli i naj mniej bolesny sposób jego przenoszenia
Jeśli masz zapamiętać tylko jedną rzecz, niech to będzie ta: kontener musi mieć trwałe przechowywanie, inaczej każda przebudowa oznacza ponowne pobieranie modeli.
Ollama pozwala wybrać katalog modeli za pomocą OLLAMA_MODELS. W implementacji referencyjnej domyślnym jest $HOME/.ollama/models, a ustawienie OLLAMA_MODELS to nadpisuje.
Wewnątrz oficjalnego obrazu Dackera $HOME naturalnie mapuje się na układ /root używany w udokumentowanym montowaniu wolumenu (/root/.ollama), co jest dokładnie przyczyną, dla której oficjalne przykłady docker run montują ten katalog.
Są dwa wzorce przechowywania, które dobrze sprawdzają się w praktyce:
Nazwany wolumen Dockera jest najprostszy i przenośny. Łatwo go jednak przypadkowo osierocić, więc warto nadać mu świadomą nazwę (na przykład ollama) i utrzymywać ją stabilnie podczas refaktoryzacji Compose’a.
Montowanie bezpośrednio (bind mount) na dedykowany dysk jest lepsze, gdy rozmiary modeli zaczynają dominować nad systemem plików głównego. W takim przypadku montujesz całe /root/.ollama na ten dysk lub montujesz własny katalog i wskazujesz OLLAMA_MODELS na niego.
Jeśli aktywnie reorganizujesz przechowywanie, tutaj przydaje się jawna “instrukcja przenoszenia modeli”. Zobacz: move-ollama-models .
Obsługa GPU NVIDIA z Compose i NVIDIA Container Toolkit
Ollama może korzystać z GPU NVIDIA w Dockerze, ale obraz nie jest w stanie zmaglować GPU z niczego. Host potrzebuje działających sterowników NVIDIA i NVIDIA Container Toolkit, a Docker musi być skonfigurowany tak, aby z niego korzystać. Dokumentacja Docker Ollama wyraźnie wskazuje na instalację nvidia-container-toolkit, konfigurację mechanizmu działania (runtime) za pomocą nvidia-ctk runtime configure --runtime=docker oraz restart Dockera.
Po stronie Compose’a czysty, nowoczesny sposób to rezerwacje urządzeń. Docker dokumentuje dostęp do GPU w Compose za pomocą deploy.resources.reservations.devices, z capabilities: [gpu], driver: nvidia oraz count (w tym all) lub device_ids.
Dodaj to do usługi ollama, gdy jesteś na hoście NVIDIA:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
Jeśli masz wiele GPU i chcesz utrzymać Ollama na konkretnych urządzeniach, przełącz się z count na device_ids, jak udokumentował Docker (są wzajemnie wykluczające się).
Czasami zobaczysz starsze przykłady Compose’a używające runtime: nvidia. Może to zawieść w nowszych konfiguracjach z błędami typu “nieznana lub nieprawidłowa nazwa mechanizmu działania: nvidia”, co jest silną podpowiedzią, aby przejść na wspierany wzorzec rezerwacji urządzeń i upewnić się, że toolkit jest skonfigurowany na hoście.
Użyteczny detal ukryty na widoku: oficjalny obraz ollama/ollama ustawia NVIDIA_VISIBLE_DEVICES=all i NVIDIA_DRIVER_CAPABILITIES=compute,utility. To standardowe regulatory rozpoznawane przez mechanizm działania kontenera NVIDIA i są one już obecne, chyba że je nadpiszesz.
Aby potwierdzić, czy faktycznie otrzymujesz wnioskowanie na GPU (a nie tylko kontener, który się uruchamia), Ollama zaleca użycie ollama ps i sprawdzenie kolumny “Processor”, która pokazuje, czy model znajduje się w pamięci GPU.
Sprawdzian rzeczywistości platformowej: Ollama wskazuje, że akceleracja GPU w Dockerze jest dostępna na Linuxie (i Windowsie z WSL2), a niedostępna na Docker Desktop dla macOS z powodu braku przejrzystości GPU (passthrough).
Wybory sieciowe: host vs bridge, porty i CORS
To tutaj rodzi się większość błędów typu “działa, ale moja aplikacja nie może się połączyć”.
Sieć mostkowa (bridge) z wystawionymi portami
Domyślna sieć Compose to sieć mostkowa (bridge). W tym ustawieniu wystawienie 11434:11434 sprawia, że Ollama jest osiągalny z hosta na porcie 11434, podczas gdy inne kontenery powinny rozmawiać z nim używając nazwy usługi ollama (nie localhost). Wielu ludzi potyka się o to, ponieważ localhost wewnątrz kontenera oznacza “ten kontener”, a nie “kontener Ollama”.
Sam Ollama uruchamia serwer HTTP na porcie 11434 (obraz go wystawia), a powszechna konwencja polega na tym, że klienci używają http://localhost:11434 na hoście, gdy porty są wystawione.
Sieć hosta (host networking)
network_mode: host może być kuszący na serwerze jednostelematycznym, ponieważ eliminuje wystawianie portów i upraszcza semantykę localhost. Kompromisem jest utrata izolacji i korzyści z nazewnictwa (namespacing) sieci mostkowej oraz większe prawdopodobieństwo kolizji portów.
Świadome wystawianie Ollama
Ollama przy zwykłej instalacji domyślnie wiąże się z 127.0.0.1, a udokumentowanym sposobem zmiany adresu wiązania jest OLLAMA_HOST.
W Dockerze masz dwie warstwy:
Adres wiązania Ollama, kontrolowany przez OLLAMA_HOST (obraz kontenera domyślnie wiąże się ze wszystkimi interfejsami wewnątrz kontenera).
Osiągalność z zewnątrz kontenera, kontrolowana przez ports w Compose i zaparę firewall hosta.
Wzorzec, który lubię, to “domyślnie wiąż lokalnie” przez 127.0.0.1:11434:11434, a następnie przełączam na 0.0.0.0:11434:11434 tylko wtedy, gdy mam powód, aby to wystawić.
Klienci przeglądarkowe i OLLAMA_ORIGINS
Jeśli oparty na przeglądarce UI lub rozszerzenie wywołuje Ollama bezpośrednio, jesteś w obszarze CORS. Ollama domyślnie pozwala na żądania z innych pochodów (cross-origin) z 127.0.0.1 i 0.0.0.0, a dodatkowe pochody można skonfigurować za pomocą OLLAMA_ORIGINS.
Ma to znaczenie nawet na pojedynczym węźle, ponieważ “działa z curl” nie oznacza “działa z aplikacji przeglądarkowej”.
Wzorce aktualizacji i rollbacku pasujące do serwera jednostelematycznego
Ollama szybko się rozwija. Twój plik Compose może sprawić, że będzie to spokojny proces, a nie nocna niespodzianka.
Aktualizacja przez zmianę tagu, nie przez nadzieję, że “latest” będzie się zachowywać
Najbardziej praktyczną strategią aktualizacji jest przypięcie obrazu do sprawdzonego tagu w .env i świadomego jego podniesienia. Obraz jest publikowany jako ollama/ollama na Docker Hub.
Ponieważ dane modeli i stan serwera są przechowywane w zamontowanym katalogu (/root/.ollama w oficjalnej dokumentacji), zastąpienie kontenera nie implikuje ponownego pobierania modeli.
Rollback to po prostu przełączenie tagu z powrotem
Rollback to ten sam mechanizm w odwrotności: ustaw poprzedni tag, odtwórz kontener, zachowaj ten sam wolumen. Tutaj przypinanie wersji zwraca się z nawiązką.
Migracja danych to w dużej mierze kwestia ścieżek przechowywania
Większość “migracji” w konfiguracji jednostelematycznej nie dotyczy schematów baz danych. Dotyczy układu dysków. Jeśli zmienisz katalog modeli (przez OLLAMA_MODELS) lub przeniesiesz zamontowany wolumen na nowy dysk, wykonujesz migrację danych, nazwij ją jak chcesz.
Jeśli chcesz praktycznego przewodnika po reorganizacji katalogu modeli na prawdziwych maszynach, zobacz: move-ollama-models .
Ostatnia uwaga, o której łatwo zapomnieć: Dokumentacja API Ollama wyraźnie mówi, że API ma być stabilne i kompatybilne wstecz, z rzadkimi wycofaniemiami ogłaszanymi w notatkach wydania. Sprawia to, że “zaktualizuj serwer, zachowaj działanie klientów” jest rozsądnym domyślnym oczekiwaniem dla jednostelematycznego punktu końcowego usługi.
Częste awarie: uprawnienia GPU, niespójność sterowników i OOM
Ta sekcja jest celowo oparta na symptomach. Celem nie jest “każdy możliwy błąd Dockera”, tylko awarie, które pojawiają się specyficznie w konfiguracjach Ollama + GPU + trwałe przechowywanie.
GPU widoczne na hoście, brakujące w kontenerze
Jeśli host ma działający sterownik NVIDIA, ale kontener nie widzi GPU, częstymi przyczynami są:
NVIDIA Container Toolkit nie jest zainstalowany lub mechanizm działania Dockera nie jest skonfigurowany przez nvidia-ctk. Dokumentacja Docker Ollama wskazuje na to bezpośrednio.
Compose nie rezerwuje urządzenia GPU. Wspieranym sposobem jest deploy.resources.reservations.devices z funkcjonalnością gpu, jak udokumentował Docker.
Stara konfiguracja runtime: nvidia jest używana na demonie, który jej nie rozpoznaje, co generuje “nieznana lub nieprawidłowa nazwa mechanizmu działania: nvidia”.
Do walidacji ollama ps daje pragmatyczny sprawdzian: pokazuje, czy model jest załadowany w pamięci GPU.
Permission denied na urządzeniach GPU
Rodzaj błędu GPU typu “permission denied” zwykle wskazuje na ograniczenia środowiskowe, a nie na samego Ollama. Przykłady obejmują uruchamianie Dockera bez uprawnień root (rootless Docker), polityki bezpieczeństwa lub węzły urządzeń nie wystawione zgodnie z oczekiwaniem. Dokumentacja wsparcia GPU w Docker Compose jest jednoznaczna co do tego, że host musi mieć urządzenia GPU, a demon Dockera musi być odpowiednio ustawiony.
W razie wątpliwości zmniejsz liczbę zmiennych: potwierdź konfigurację toolkitu (host), następnie potwierdź rezerwację GPU (Compose), a następnie potwierdź użycie GPU (ollama ps).
Zły sterownik, złe oczekiwania
Ollama w Dockerze opiera się na stosie sterowników hosta. Jeśli sterownik hosta jest brakujący, zbyt stary lub źle skonfigurowany, zobaczysz awarie wyglądające na “Ollama jest zepsuty”, ale w rzeczywistości będą to “stos CUDA jest nie do użycia”. Oficjalna dokumentacja stawia toolkit kontenera i konfigurację demona Dockera jako wymagania wstępne dla użycia GPU NVIDIA.
Brak pamięci: VRAM lub RAM znika szybko
OOM (Out of Memory) jest najbardziej przewidywalnym trybem awarii przy lokalnym wnioskowaniu i zwykle jest samowyzwolonym przez konfigurację.
Ollama wspiera równoległe przetwarzanie przez wiele załadowanych modeli i równoległe obsłużenie żądań, ale jest ograniczane przez dostępną pamięć (systemowa RAM przy wnioskowaniu CPU, VRAM przy wnioskowaniu GPU). Gdy używane jest wnioskowanie GPU, nowe modele muszą mieścić się w VRAM, aby umożliwić równoległe ładowanie modeli.
Dwa szczegóły konfiguracji warto traktować jako pierwszorzędne “ustawienia serwera”:
OLLAMA_NUM_PARALLEL zwiększa równoległe przetwarzanie żądań na model, ale wymagana pamięć skaluje się z OLLAMA_NUM_PARALLEL * OLLAMA_CONTEXT_LENGTH.
OLLAMA_KEEP_ALIVE kontroluje, jak długo modele pozostają załadowane (domyślnie 5 minut). Utrzymywanie modeli załadowanych zmniejsza opóźnienie zimnego startu, ale również przypina pamięć.
Jeśli stabilizujesz jednostelematową usługę pod obciążeniem, niewiarygodne poprawki wyglądają zwykle tak:
Obniż równoległość i domyślne wartości kontekstu, zanim zmienisz cokolwiek innego.
Ogranicz, ile modeli może pozostawać jednocześnie załadowanych.
Rozważ funkcje redukcji pamięci, takie jak Flash Attention (OLLAMA_FLASH_ATTENTION=1) i typy cache K/V o niższej precyzji (OLLAMA_KV_CACHE_TYPE), gdy twoim wąskim gardłem jest pamięć, a nie surowa moc obliczeniowa.
Kiedy to nie jest wina Ollama: wybór Docker Model Runner
Czasami “awaria” to faktycznie niespójność narzędzi. Jeśli twoja organizacja jest już znormalizowana na artefaktach i przepływach natywnych dla Dockera, Docker Model Runner (DMR) może być lepszym dopasowaniem niż uruchamianie Ollama jako długotrwałego kontenera usługi.
Docker pozycjonuje DMR jako sposób na zarządzanie, uruchamianie i serwowanie modeli bezpośrednio przez Dockera, pobieranie z Docker Hub lub innych rejestrów OCI oraz serwowanie API kompatybilnych z OpenAI i Ollama.
Wsparcie dla wielu silników wnioskowania (w tym llama.cpp i vLLM na Linuxie z GPU NVIDIA) może mieć znaczenie, jeśli zależy ci na charakterystyce przepustowości, a nie tylko na “uruchomieniu jednego modelu lokalnie”.
Jeśli chcesz praktycznej referencji poleceń i głębszego porównania, zobacz: Docker Model Runner Cheatsheet: Polecenia i Przykłady.
