LocalAI QuickStart: Uruchamianie lokalnie modeli LLM zgodnych z OpenAI

LocalAI to serwer inferencji typu self-hosted i first-local zaprojektowany tak, aby zachowywał się jak kompatybilny zamiennik API OpenAI do uruchamiania obciążeń AI na Twoim własnym sprzęcie (laptop, stacja robocza lub serwer lokalny).

Projekt skupia się na praktycznej kompatybilności w trybie „zastąp URL API chmurowego", przy jednoczesnej obsłudze wielu backendów i modalności (tekst, obrazy, audio, embeddingi i inne).

Czym jest LocalAI i dlaczego inżynierowie go używają

LocalAI prezentuje interfejs HTTP REST, który odzwierciedla kluczowe punkty końcowe OpenAI, w tym końcówki do uzupełniania czatu, embeddingi, generowanie obrazów i audio, dzięki czemu istniejące narzędzia kompatybilne z OpenAI mogą być wskazane na Twoją własną infrastrukturę.

Oprócz podstawowego generowania tekstu, zestaw funkcji LocalAI obejmuje powszechne „bloki konstrukcyjne produkcji", takie jak embeddingi dla RAG, generowanie obrazów na bazie dyfuzji, mowa do tekstu oraz tekst do mowy, z opcjonalną akceleracją GPU i wzorcami rozproszonymi.

Jeśli oceniasz serwisy LLM typu self-hosted, LocalAI jest interesujący, ponieważ skupia się na kompatybilności API (dla łatwiejszej integracji), a jednocześnie zapewnia wbudowany interfejs Web UI oraz workflow galerii modeli, aby zminimalizować tarcie instalacji i konfigurowania modeli.

Dla szerszego porównania opcji hostowania LLM typu self-hosted i chmurowego — w tym Ollama, vLLM, Docker Model Runner oraz zarządzanych dostawców chmurowych — zobacz przewodnik po hostowaniu LLM na 2026 rok.

Jeśli chcesz szczegółowego porównania LocalAI z Ollama, vLLM, LM Studio i innymi, artykuł porównujący główne lokalne narzędzia LLM w 2026 roku omawia wsparcie API, kompatybilność sprzętu i gotowość produkcyjną. Dla szerszego uzasadnienia pozostawiania modeli na własnej infrastrukturze, artykuł self-hosting LLM i suwerenność AI omawia motywacje związane z rezydencją danych i zgodnością.

Opcje instalacji LocalAI, które dobrze sprawdzają się w praktyce

LocalAI można zainstalować na wiele sposobów, ale dla większości zespołów najszybszym i najmniej ryzykownym punktem startowym są kontenery (Docker lub Podman). Jeśli podczas pracy z poniższymi przykładami chcesz mieć referencje do poleceń, podręcznik skrócony do Docker omawia najczęstsze i najbardziej użyteczne polecenia Docker.

Najszybszy start z Docker

To polecenie uruchamia serwer LocalAI i wiąże API oraz Web UI na porcie 8080:

docker run -p 8080:8080 --name local-ai -ti localai/localai:latest

Dokumentacja kontenera LocalAI nazywa to najszybszą ścieżką do uruchomienia działającego serwera, przy czym API jest dostępne pod adresem http://localhost:8080.

Wybór odpowiedniego obrazu kontenera LocalAI

LocalAI publikuje różne warianty obrazów kontenerów, abyś mógł dopasować je do swojego sprzętu:

• Obraz CPU dla szerokiej kompatybilności.
• Obrazy specyficzne dla GPU dla NVIDIA CUDA, AMD ROCm, Intel oneAPI i Vulkan.
• Obrazy All-in-One (AIO), które są konfigurowane z modelami powiązanymi z nazwami podobnymi do OpenAI.

Oficjalna dokumentacja GitHub zawiera konkretne przykłady docker run dla opcji tylko CPU oraz kilku opcji GPU (warianty NVIDIA CUDA, AMD ROCm, Intel, Vulkan), włącznie z wariantami AIO.

Trwałość modeli między restartami

Jeśli nie zamontujesz magazynu danych, pobrane modele mogą nie przetrwać zmian w cyklu życia kontenera. Przewodnik po kontenerze zaleca zamontowanie wolumenu /models, na przykład:

docker run -ti --name local-ai -p 8080:8080 \
  -v "$PWD/models:/models" \
  localai/localai:latest-aio-cpu

To sprawia, że katalog /models wewnątrz kontenera jest trwały na Twoim hoście.

Minimalny szybki start Docker Compose

LocalAI udostępnia również referencyjny plik docker-compose.yaml w repozytorium, demonstrować wspólny wzorzec: wiązanie portu 8080, montowanie wolumenu /models, ustawienie MODELS_PATH=/models oraz opcjonalne wczytanie modelu przez określenie go na liście poleceń (przykład w repozytorium pokazuje phi-2). Podręcznik skrócony do Docker Compose jest przydatną referencją podczas dostosowywania tego do Twojej konfiguracji.

„Domyślne dobre" ustawienie Compose (CPU) wygląda następująco:

services:
  localai:
    image: localai/localai:latest
    container_name: local-ai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - MODELS_PATH=/models

Kluczowa idea jest taka sama jak w przykładzie upstream: katalog modeli na hoście ↔ katalog /models w kontenerze.

Jeśli również korzystasz z natywnego narzędzia docker model w Docker obok LocalAI, podręcznik skrócony do Docker Model Runner omawia polecenia pull, run, package i konfiguracji.

Niekontenerowe instalacje LocalAI

LocalAI obsługuje również instalacje poprzez metody specyficzne dla platformy (na przykład plik DMG dla macOS i binarki dla Linux), oraz szersze opcje wdrażania, takie jak Kubernetes.

Jeśli wolisz zainstalowane skryptami na Linuxie, szybki start z DeepWiki opisuje ścieżkę install.sh, która automatycznie wykrywa sprzęt i konfiguruje system zgodnie z tym.

Przewidywalna sekwencja używania

Niezawodny workflow LocalAI to:

Uruchom LocalAI → zainstaluj lub zaimportuj model → zweryfikuj załadowane modele → wywołaj punkty końcowe kompatybilne z OpenAI.

Ta sekwencja pasuje do oficjalnych wytycznych „Wypróbuj to" i „Konfigurowanie modeli", które ramują proces wokół uruchomienia serwera, instalowania modeli za pomocą galerii lub CLI, a następnie testowania punktów końcowych z curl.

Uruchom serwer i potwierdź jego zdrowie

Gdy serwer jest uruchomiony, powszechnym sprawdzianem jest punkt końcowy gotowości:

curl http://localhost:8080/readyz

Przewodnik rozwiązywania problemów używa /readyz jako pierwszej diagnostyki, aby potwierdzić, że LocalAI jest responsywny.

Zainstaluj model z galerii lub zaimportuj URI

LocalAI zapewnia dwa główne przepływy obsługi modeli:

• Instalacja z Galerii Modeli przez Web UI, gdzie otwierasz UI, przechodzisz do zakładki Models, przeglądasz modele i klikasz Install.
• Instalacja i uruchomienie sterowane CLI, używając local-ai models list, local-ai models install i local-ai run.

Dokumentacja obsługuje również importowanie modeli przez URI (repozytoria Hugging Face, bezpośrednie URI plików modeli i inne rejestry), a Web UI zawiera dedykowany przepływ Import Model z edytorem YAML do zaawansowanej konfiguracji.

Zweryfikuj, co LocalAI uważa za dostępne do serwowania

Aby wylistować wdrożone modele poprzez API kompatybilne z OpenAI:

curl http://localhost:8080/v1/models

To jest jawnie zalecane zarówno jako „kolejny krok" po instalacji kontenera, jak i jako diagnostyka rozwiązywania problemów.

Główne parametry wiersza poleceń, które warto poznać

CLI LocalAI jest zbudowane wokół polecenia local-ai run, z kompleksową powierzchnią konfiguracji. Musimy podkreślić dwa ważne zachowania operacyjne:

• Każdy flag CLI można ustawić za pomocą zmiennej środowiskowej.
• Zmienne środowiskowe mają pierwszeństwo przed flagami CLI.

Poniżej znajdują się parametry, które praktycy najczęściej używają na początku, pogrupowane według intencji. Wszystkie domyślne wartości i nazwy zmiennych środowiskowych pochodzą z oficjalnej referencji CLI. Jeśli oceniasz Ollama obok LocalAI, podręcznik skrócony CLI Ollama omawia jego polecenia serve, run, ps i zarządzanie modelami do porównania.

Flagi serwera i magazynu danych

FAQ LocalAI dokumentuje również domyślne lokalizacje magazynu modeli i jawnie zaleca LOCALAI_MODELS_PATH lub --models-path, jeśli chcesz mieć modele poza domyślnym katalogiem (na przykład, aby uniknąć wypełnienia katalogu domowego).

Flagi wydajności i pojemności

Dla szerszej kompatybilności i ograniczeń akceleracji, tabela kompatybilności modeli dokumentuje, które backendy obsługują które tryby akceleracji (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), a także zauważa, że modele niekonfigurowane jawnie mogą być automatycznie ładowane, podczas gdy konfiguracja YAML pozwala na przypięcie zachowania. Dla wdrożeń wielogpu o wysokiej przepustowości z PagedAttention, przewodnik szybkiego startu vLLM przeprowadza przez porównywalny serwer kompatybilny z OpenAI z konfiguracją nastawioną na produkcję.

Flagi API, bezpieczeństwa i UI

Jeśli wystawiasz LocalAI zdalnie, powinieneś chronić punkty końcowe i możesz ograniczyć dostęp z kluczem API, klucz API skutecznie przyznaje pełny dostęp.

Przejście po interfejsie Web UI i jak to mapuje się na system

Domyślnie LocalAI serwuje wbudowany Web UI obok API (chyba że go wyłączysz). Dokumentacja mówi, że UI jest dostępne na tym samym hoście i porcie co serwer, zazwyczaj http://localhost:8080.

Co możesz zrobić we wbudowanym UI

Web UI to interfejs oparty na przeglądarce, który obejmuje:

• Zarządzanie modelami i doświadczenie przeglądania galerii
• Interakcje czatu
• Interfejsy generowania obrazów i tekstu do mowy
• Konfigurację rozproszoną i P2P

Struktura tras daje jasny model mentalny powierzchni UI:

• / dla panelu sterowania
• /browse dla przeglądarki galerii modeli
• /chat/ dla czatu
• /text2image/ dla generowania obrazów
• /tts/ dla tekstu do mowy
• /talk/ dla interakcji głosowej
• /p2p dla ustawień i monitorowania P2P

Workflow Galerii Modeli i „Import Model"

Dla inżynierów najważniejszą funkcją UI jest obsługa modeli. Oficjalny przewodnik „Setting Up Models" opisuje:

• Instalowanie modeli za pomocą zakładki Models z instalacją jednym kliknięciem.
• Importowanie modeli przez UI Import Model, które obsługuje tryb prosty (URI + preferencje) i tryb zaawansowany z edytorem YAML i narzędziami walidacji.

To ma znaczenie, ponieważ LocalAI w końcu uruchamia modele na bazie konfiguracji YAML: możesz zarządzać pojedynczymi plikami YAML w katalogu modeli, używać jednego pliku z wieloma definicjami modeli poprzez --models-config-file, lub odwoływać się do zdalnych adresów URL YAML przy starcie.

Przykłady, które możesz wkleić do terminala

Punkty końcowe LocalAI kompatybilne z OpenAI są zaprojektowane tak, aby akceptować znane formaty żądań i zwracać odpowiedzi JSON (z punktami końcowymi audio zwracającymi payloady audio).

Przykład uzupełnień czatu z curl

Strona „Try it out" LocalAI pokazuje wywoływanie punktu końcowego uzupełnień czatu bezpośrednio:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Write a one paragraph explanation of what LocalAI is." }
    ],
    "temperature": 0.2
  }'

Obrazy AIO dostarczają skonfigurowane modele powiązane z nazwami podobnymi do OpenAI, takimi jak gpt-4, a dokumentacja kontenera wyjaśnia, że są one obsługiwane przez modele open-source.

Jeśli nie używasz obrazu AIO, zamień "model" na nazwę modelu, który zainstalowałeś (sprawdź z /v1/models).

Przykład embeddingi dla pipeline’ów RAG

LocalAI obsługuje embeddingi i dokumentuje, że endpoint embeddingi jest kompatybilny z wieloma backendami, w tym llama.cpp, bert.cpp i sentence-transformers.

Minimalne żądanie „osadz ten tekst" do punktu końcowego kompatybilnego z OpenAI wygląda następująco:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "LocalAI embeddings are handy for semantic search and RAG."
  }'

Dokumentacja embeddingi LocalAI pokazuje również, jak embeddingi są włączane poprzez konfigurację YAML poprzez ustawienie embeddings: true.

Przykład używania klienta kompatybilnego z OpenAI

LocalAI jest zaprojektowany tak, abyś mógł użyć standardowych bibliotek klienta OpenAI, wskazując je na bazowy adres URL LocalAI (i opcjonalnie ustawiając klucz API, jeśli włączyłeś autoryzację). Cel „kompatybilnego zamiennika" jest opisany zarówno w oficjalnym README, jak i w dokumentacji kompatybilności OpenAI.

Typowa konfiguracja to:

• Bazowy adres URL: http://localhost:8080/v1
• Klucz API: albo nie wymagany (domyślnie), albo wymagany, jeśli skonfigurowałeś --api-keys

Podstawy bezpieczeństwa i rozwiązywania problemów

Zabezpiecz serwer LocalAI przed jego wystawieniem

LocalAI może działać całkowicie otwarty na localhost domyślnie. Jeśli wiążesz z publiczny interfejs lub wystawiasz go przez ingress, dodaj przynajmniej jeden z tych elementów kontrolnych:

• Włącz autoryzację klucza API używając --api-keys / API_KEY.
• Postaw reverse proxy i kontrole sieciowe przed nim (zapora, biała lista, VPN).
• Wyłącz Web UI, jeśli potrzebujesz tylko API (--disable-webui).
• Zostaw CORS wyłączony, chyba że klient oparty na przeglądarce naprawdę tego potrzebuje.

Gdy klucze API są włączone, punkty końcowe kompatybilne z OpenAI akceptują poświadczenia w common miejscach, takich jak nagłówek Bearer Authorization lub nagłówek x-api-key.

Szybka diagnostyka, gdy coś nie działa

Przewodnik rozwiązywania problemów LocalAI sugeruje mały zestaw sprawdzianów, które rozwiązują większość incydentów „czy działa":

# gotowość
curl http://localhost:8080/readyz

# lista modeli
curl http://localhost:8080/v1/models

# wersja
local-ai --version

Dokumentuje również włączanie logów debugowania poprzez DEBUG=true lub --log-level=debug, a dla wdrożeń Docker sprawdzanie logów kontenera z docker logs local-ai.