Lokalna LLM w Python: Szybki start z Ollama i LiteLLM

Lokalne LLM w Pythonie: Szybki start z Ollama i LiteLLM dla programistów

Wielu programistów, rozpoczynających swoją przygodę ze światem dużych modeli językowych (LLM), napotyka bariery: konieczność rejestracji w usługach chmurowych, zarządzanie kluczami API i stałe koszty tokenów. Podejście to, choć skuteczne, nie zawsze jest optymalne dla pierwszych eksperymentów i lokalnego rozwoju. Niniejszy artykuł oferuje efektywną alternatywę: wdrożenie i integrację LLM bezpośrednio na Twoim komputerze. Krok po kroku skonfigurujemy lokalne środowisko, wykorzystując Ollama do uruchamiania modeli i LiteLLM do ich integracji z aplikacjami Python, pokazując, jak uzyskać pierwszą sensowną odpowiedź od własnego LLM bez zależności od zewnętrznych usług.

Zalety lokalnego rozwoju LLM

Lokalne wdrażanie LLM ma szereg niezaprzeczalnych zalet, zwłaszcza w kontekście nauki i prototypowania. Po pierwsze, całkowicie eliminuje potrzebę posiadania kluczy API i związanych z nimi kosztów finansowych, umożliwiając przeprowadzanie nieograniczonej liczby eksperymentów. Po drugie, znika zależność od połączenia internetowego dla każdego zapytania, co jest kluczowe dla rozwoju offline lub pracy w warunkach niestabilnej sieci. Po trzecie, takie podejście sprawia, że proces interakcji z LLM jest maksymalnie przejrzysty: widzisz, jak Twój kod Python komunikuje się z LiteLLM, który z kolei przekazuje zapytanie do Ollama, a ten do lokalnego modelu. To nie jest "magia AI", lecz jasno śledzona logika programistyczna, co znacznie upraszcza debugowanie i zrozumienie architektury. Dla programistów, którzy dążą do głębokiego zrozumienia mechaniki integracji LLM, podejście lokalne jest idealnym punktem wyjścia.

Ollama i LiteLLM: Kluczowe komponenty architektury

Zanim przejdziemy do instalacji, ważne jest, aby rozróżnić funkcje dwóch głównych narzędzi, których będziemy używać: Ollama i LiteLLM.

• Ollama — to potężne narzędzie do lokalnego uruchamiania dużych modeli językowych. Działa jako serwer, który zarządza pobieraniem, przechowywaniem i wykonywaniem LLM na Twoim komputerze, zapewniając ujednolicony interfejs API do dostępu do nich. Zasadniczo Ollama to środowisko uruchomieniowe (runtime) dla lokalnych LLM, umożliwiające łatwą pracę z różnymi modelami, takimi jak Llama, Mistral, Qwen i innymi.
• LiteLLM — to lekka biblioteka Python, zaprojektowana w celu ujednolicenia zapytań API do różnych dostawców LLM. Jej kluczową cechą jest zapewnienie jednolitego interfejsu do interakcji zarówno z usługami chmurowymi (OpenAI, Anthropic, Google Gemini), jak i z rozwiązaniami lokalnymi, takimi jak Ollama. Oznacza to, że kod napisany dla modelu lokalnego za pośrednictwem LiteLLM może być łatwo dostosowany do pracy z dostawcami chmurowymi przy minimalnych zmianach.

W ten sposób Ollama "podnosi" lokalny model, LiteLLM zapewnia ustandaryzowany sposób odwoływania się do niego z Pythona, a Twój kod tworzy wokół tego pełnoprawną aplikację.

Instalacja Ollama i pobieranie lokalnego modelu

Aby rozpocząć pracę z lokalnym LLM, należy wykonać kilka kolejnych kroków.

Instalacja Ollama

Najpierw pobierz i zainstaluj Ollama z oficjalnej strony (ollama.com) dla swojego systemu operacyjnego (Windows, macOS, Linux). Po instalacji upewnij się, że instalacja przebiegła poprawnie, wykonując polecenie w terminalu:

ollama --version

Pomyślne wyświetlenie numeru wersji potwierdzi gotowość Ollama do pracy. W systemie Windows upewnij się, że ikona Ollama (🦙) jest widoczna w zasobniku systemowym, wskazując na aktywną usługę działającą w tle.

Pobieranie lokalnego LLM

Ollama sama w sobie nie jest modelem, a jedynie platformą do ich uruchamiania. Teraz należy pobrać konkretny duży model językowy. Do naszych celów doskonale nada się qwen2.5:3b — kompaktowy, ale wystarczająco wydajny model, dobrze działający na większości laptopów i obsługujący język rosyjski. Uruchom pobieranie przez terminal:

ollama run qwen2.5:3b

Przy pierwszym uruchomieniu rozpocznie się pobieranie modelu, który zostanie zapisany lokalnie. Po zakończeniu pobierania znajdziesz się w interaktywnym czacie Ollama. Sprawdź działanie modelu, zadając mu pytanie w języku rosyjskim, na przykład: Hello! Tell me in two sentences, what is Python. Jeśli model odpowie, oznacza to, że główna bariera została pokonana. Aby wyjść z czatu, użyj /bye.

Uwaga: Jeśli wydajność qwen2.5:3b jest niewystarczająca dla Twojego sprzętu, spróbuj lżejszej wersji: ollama run qwen2.5:1.5b. Logika kodu Python pozostanie niezmieniona.

Przygotowanie środowiska Python

Dla izolacji zależności projektu zaleca się użycie wirtualnego środowiska.

• Utwórz folder projektu i przejdź do niego:

```bash

mkdir llm-chat

cd llm-chat

```

• Zainicjuj wirtualne środowisko:

```bash

python -m venv venv

```

• Aktywuj je.

* Windows: venv\Scripts\activate

* macOS / Linux: source venv/bin/activate

Pomyślna aktywacja zostanie oznaczona prefiksem (venv) w wierszu poleceń.

• Zainstaluj bibliotekę LiteLLM:

```bash

pip install litellm

```

Teraz wszystkie komponenty są gotowe do pisania kodu.

Integracja LLM w Pythonie: Pierwsze zapytanie

Utwórz plik main.py w katalogu głównym projektu i dodaj następujący kod:

from litellm import completion
 
MODEL = "ollama_chat/qwen2.5:3b"
API_BASE = "http://localhost:11434"
 
 
def ask(question: str) -> str:
    response = completion(
        model=MODEL,
        messages=[
            {"role": "user", "content": question}
        ],
        api_base=API_BASE,
        request_timeout=120,
    )
    return response.choices[0].message.content
 
 
answer = ask("Cześć! Napisz jedno krótkie zdanie o Pythonie.")
print(answer)

Uruchom skrypt z aktywowanego wirtualnego środowiska:

python main.py

Jeśli w konsoli pojawi się sensowna odpowiedź od modelu, oznacza to, że pomyślnie zintegrowałeś lokalny LLM ze swoim kodem Python. To kluczowy moment, demonstrujący, jak abstrakcyjny model przekształca się w funkcjonalny komponent Twojej aplikacji.

Analiza kodu main.py

Przyjrzyjmy się głównym elementom tego minimalistycznego, ale funkcjonalnego skryptu:

• from litellm import completion: Importujemy główną funkcję completion z biblioteki LiteLLM, przeznaczoną do wysyłania zapytań do LLM.
• MODEL = "ollama_chat/qwen2.5:3b": Ta zmienna określa model, którego używamy. Prefiks ollama_chat/ informuje LiteLLM, że zapytanie powinno być skierowane do lokalnej usługi Ollama. Tutaj należy podać nazwę pobranego modelu (np. qwen2.5:1.5b).
• API_BASE = "http://localhost:11434": Wskazuje adres lokalnego serwera API Ollama. Domyślnie Ollama działa na porcie 11434.
• messages=[{"role": "user", "content": question}]: To fundamentalna struktura do interakcji z większością nowoczesnych API LLM. Zapytania są przekazywane w postaci listy wiadomości, gdzie każda wiadomość ma role (np. "user", "assistant", "system") i content (treść wiadomości). Nawet dla pojedynczego pytania używana jest ta struktura, co stanowi podstawę do przyszłej pracy z historią dialogu i kontekstem.
• request_timeout=120: Ustawia maksymalny czas oczekiwania na odpowiedź od modelu w sekundach. Lokalne modele mogą wymagać więcej czasu na pierwsze uruchomienie lub na przetwarzanie złożonych zapytań.
• response.choices[0].message.content: Z pełnego obiektu odpowiedzi zwróconego przez model wyodrębniamy bezpośrednio wygenerowany tekst. Obiekt response zawiera wiele innych przydatnych informacji, które będziemy mogli zbadać w kolejnych częściach.

Rozwiązywanie typowych problemów podczas uruchamiania

Podczas konfiguracji mogą pojawić się różne trudności. Oto najczęstsze z nich i sposoby ich rozwiązania:

• Problem 1: Connection refused lub Failed to connect

* Przyczyna: Usługa Ollama nie jest uruchomiona lub jest niedostępna.

* Rozwiązanie: Upewnij się, że Ollama jest aktywna. Sprawdź ikonę 🦙 w zasobniku systemowym (Windows/macOS) lub wykonaj ollama list w terminalu. Jeśli polecenie odpowiada, usługa działa.

• Problem 2: Model not found

* Przyczyna: Model wskazany w kodzie nie został pobrany lub jego nazwa nie zgadza się z zainstalowaną.

* Rozwiązanie: Wykonaj ollama list, aby zobaczyć listę dostępnych lokalnych modeli, i skoryguj nazwę modelu w zmiennej MODEL w main.py.

• Problem 3: Długa odpowiedź lub niska wydajność

* Przyczyna: Pierwsze uruchomienie modelu może być wolne z powodu ładowania do pamięci, lub model jest zbyt wymagający dla Twojego sprzętu.

* Rozwiązanie: Poczekaj dłużej. Zamknij aplikacje zużywające dużo zasobów. Spróbuj użyć lżejszej wersji modelu, np. qwen2.5:1.5b.

• Problem 4: ModuleNotFoundError: No module named 'litellm'

* Przyczyna: Skrypt został uruchomiony poza aktywowanym wirtualnym środowiskiem, w którym zainstalowano LiteLLM.

* Rozwiązanie: Upewnij się, że przed uruchomieniem skryptu aktywowałeś wirtualne środowisko (prefiks (venv) w terminalu).

• Problem 5: Problemy z kodowaniem w PowerShell (znaki-„krzaczki”)

* Przyczyna: Niezgodność kodowania terminala.

* Rozwiązanie: W PowerShell wykonaj $OutputEncoding = [System.Text.Encoding]::UTF8 przed uruchomieniem skryptu.

Co ważne

• Lokalne wdrożenie LLM z Ollama i LiteLLM pozwala uniknąć kosztów API i zależności od internetu, zapewniając pełną kontrolę nad procesem.
• Ollama służy jako środowisko uruchomieniowe (runtime) dla lokalnych modeli, a LiteLLM ujednolica API do interakcji z nimi z poziomu Pythona.
• Pierwszym krokiem jest instalacja Ollama i pobranie odpowiedniego modelu, takiego jak qwen2.5:3b.
• Skrypt Python używa litellm.completion do wysyłania zapytań, gdzie MODEL wskazuje na lokalny model poprzez ollama_chat/, a API_BASE — na adres Ollama.
• Zapytania do LLM są przekazywane w postaci listy wiadomości z rolami (role) i treścią (content), co stanowi podstawę do tworzenia systemów dialogowych.

Zakończenie i dalsze kroki

Na tym etapie pomyślnie zrealizowaliśmy podstawową integrację lokalnego LLM z aplikacją Python. Model przestał być abstrakcyjną technologią i stał się komponentem, którym można zarządzać, zdolnym odpowiadać na zapytania bezpośrednio z Twojego kodu. Ten ważny krok otwiera drzwi do dalszych eksperymentów i rozwoju bardziej złożonych aplikacji AI.

W następnej części przekształcimy ten minimalny przykład w pełnoprawny czat konsolowy, dodając pętlę komunikacji, możliwość wprowadzania zapytań przez użytkownika oraz podstawowe przygotowanie do zarządzania kontekstem dialogu. Pozwoli to przejść od jednorazowych pytań do interaktywnej interakcji z Twoim lokalnym LLM.

— Editorial Team