Ollama w Pythonie: jak uruchomić model lokalnie i wywołać go przez API

To pierwsza część cyklu o modelach lokalnych. Zakładam, że znasz podstawy z artykułu o API OpenAI w Pythonie: wiesz, czym są tokeny, okno kontekstu i response.usage. Tutaj zamieniamy chmurę na model, który działa u Ciebie na komputerze.

Po co uruchamiać model lokalnie?

Model lokalny nie jest „lepszą wersją” chmury. To inny kompromis:

Lokalny model ma sens, gdy przetwarzasz dane, których nie chcesz wysyłać na zewnątrz, gdy uczysz się i nie chcesz płacić za każde eksperymentalne zapytanie albo gdy chcesz sprawdzić, czy mniejszy model wystarczy do Twojego zadania.

Jak zainstalować Ollamę i pobrać model?

Ollamę pobierasz ze strony ollama.com (instalator na macOS i Windows, skrypt na Linuksa). Po instalacji w terminalu masz polecenie ollama. Model pobierasz jednym poleceniem:

ollama pull llama3.2
ollama list

ollama pull ściąga plik modelu (od kilkuset megabajtów do kilkudziesięciu gigabajtów), a ollama list pokazuje, co masz na dysku. Nazwa, którą tu widzisz, jest nazwą, której później użyjesz w kodzie. Wybierając model, kieruj się pamięcią: model o 11 mld parametrów w kwantyzacji Q4 zajmuje około 7 GB i potrzebuje podobnej ilości wolnej pamięci. Na komputerze z 16 GB RAM małe i średnie modele działają, ale duże już nie.

Sprawdź, czy serwer działa:

curl http://localhost:11434/api/version

Jeśli dostaniesz odpowiedź z numerem wersji, Ollama nasłuchuje na porcie 11434.

Jak wywołać model lokalny z Pythona?

Zainstaluj klienta: pip install openai. Potem użyj go tak samo jak w chmurze, zmieniając adres i klucz:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # wymagany przez bibliotekę, ignorowany przez Ollamę
)

response = client.chat.completions.create(
    model="llama3.2",  # dokładnie ta nazwa, którą pokazuje `ollama list`
    messages=[
        {"role": "system", "content": "Odpowiadasz po polsku, zwięźle."},
        {"role": "user", "content": "Wyjaśnij w dwóch zdaniach, czym jest token."},
    ],
)

print(response.choices[0].message.content)
print(response.usage.prompt_tokens, response.usage.completion_tokens)

Struktura odpowiedzi jest ta sama co w OpenAI, więc response.usage działa tak jak w poprzednim artykule. Pierwsze wywołanie trwa dłużej, bo Ollama ładuje model do pamięci. Kolejne są szybsze, dopóki model jest w pamięci (domyślnie kilka minut bezczynności).

Najważniejsza lekcja: cały kod aplikacji jest taki sam, zmieniają się tylko dwie wartości: adres serwera i nazwa modelu. W następnym artykule zamienimy je na ustawienia w pliku konfiguracyjnym.

Co zrobić, gdy dostanę błąd „model not found”?

Ollama zwraca ten błąd, gdy nazwa w model= nie istnieje na Twoim komputerze. Najczęstsze przyczyny:

• Model nie został pobrany. Uruchom ollama pull <nazwa>.
• Nazwa jest zapisana inaczej niż w ollama list. Skopiuj ją stamtąd, łącznie z tagiem po dwukropku, jeśli jest.
• Używasz nazwy modelu z chmury (np. gpt-4o-mini). Serwer lokalny jej nie zna.

Co zrobić, gdy kod nie może połączyć się z Ollamą?

Błąd połączenia (Connection refused, APIConnectionError) ma zwykle jedną z trzech przyczyn:

Trzeci przypadek to jedno z częstszych pytań programistów, którzy próbują włożyć wszystko do Dockera. W kontenerze localhost wskazuje na kontener, więc Ollama uruchomiona na komputerze jest dla niego niewidoczna. Można to obejść (adres hosta albo osobny kontener Ollamy), ale to dokłada konfigurację sieci. Dlatego w tym cyklu uruchamiamy wszystko jako zwykłe procesy na jednym komputerze, bez Docker Compose. Dzięki temu uczysz się samego mechanizmu, a nie sieci kontenerów. Do Dockera wrócisz, gdy aplikacja będzie działać.

Dlaczego model „ucina” długi tekst i odpowiada od środka?

To pułapka, której nie ma w chmurowych API. Ollama używa domyślnie niewielkiego okna kontekstu (w wersji, na której sprawdzałem, załadowany model miał kontekst 4096 tokenów), nawet jeśli sam model obsługuje znacznie więcej. Gdy wejście jest dłuższe, nie dostajesz błędu „maximum context length”, tylko po cichu ucięty początek tekstu i odpowiedź, która pomija część dokumentu.

Dlatego przy modelach lokalnych:

• sprawdzaj response.usage.prompt_tokens i porównuj z oczekiwaną długością tekstu,
• dziel dokumenty na fragmenty (jak w analizatorze dokumentów),
• jeśli potrzebujesz większego okna, zwiększ je w ustawieniach Ollamy (parametr num_ctx), pamiętając, że większy kontekst zużywa więcej pamięci.

Czy odpowiedzi lokalnego modelu są takie same jak z OpenAI?

Format odpowiedzi tak, treść nie. Mniejsze modele gorzej trzymają się instrukcji, częściej mylą język i słabiej radzą sobie z danymi w ustalonym formacie. Jeśli oczekujesz od modelu odpowiedzi w JSON, waliduj ją w Pydantic i zakładaj, że czasem trzeba ponowić zapytanie. Różnice w jakości i czasie zmierzymy na prawdziwym przykładzie w trzeciej części cyklu.

Co dalej?

Wiesz już, jak wywołać model lokalny. Problem w tym, że w kodzie zostały „na sztywno” adres, klucz i nazwa modelu. W drugiej części wstawimy między aplikację a modele bramkę LiteLLM i przełączanie lokalny/chmura ustawisz jedną zmianą w konfiguracji.

Jeśli uczysz się Pythona i chcesz, żeby ktoś doświadczony przejrzał Twoje projekty z AI, zobacz mentoring w ścieżce Python.