Artykuł Technologie

Ollama API - jak korzystać z lokalnego LLM przez REST

Autor: Piotr Broniewski 7 min czytania

Ollama przy starcie wystawia lokalny serwer REST pod http://localhost:11434. Główne endpointy to GET /api/tags (lista modeli), POST /api/generate (jednorazowa generacja) i POST /api/chat (rozmowa z historią). Odpytasz je curl, Pythonem albo dowolnym klientem HTTP, a pod /v1 działa warstwa zgodna z OpenAI.

W skrócie: jeśli umiesz wysłać request HTTP, umiesz sterować lokalnym modelem. Poniżej rozkładam każdy endpoint na działający snippet, pokazuję dostęp z Pythona i z bibliotek OpenAI, a na końcu zbieram dostęp zdalny oraz najczęstsze błędy. Konkret: to czysty REST, więc zadziała z każdego języka, który potrafi otworzyć połączenie.

Czym jest Ollama API i kiedy go użyć

Ollama to lokalny runtime modeli językowych - pobierasz model jednym poleceniem i uruchamiasz go na własnej maszynie. Pod maską: przy starcie Ollama nie tylko ładuje model, ale też podnosi serwer HTTP. To właśnie ten serwer udostępnia REST API, czyli interfejs między Twoim kodem a modelem. Bez API zostaje Ci tylko tryb interaktywny w terminalu (ollama run), który nadaje się do zabawy, ale nie do integracji. Jeśli dopiero zaczynasz, zacznij od wpisu czym jest Ollama i jak ją zainstalować, skrypty cron, kolejki zadań.

  • Przetwarzanie wsadowe - tysiąc dokumentów do streszczenia, klasyfikacja, ekstrakcja danych.
  • Podpięcie gotowego GUI - na przykład Open WebUI, które rozmawia z tym samym REST API

    odpowiedź zawiera pole "models" z listą zainstalowanych modeli i metadanymi

    print(r.json())

Jeśli dostaniesz pustą listę, to znaczy, że serwer działa, ale nie masz jeszcze żadnego modelu - pobierz go (ollama pull <model>). Dobór modelu pod Twój sprzęt opisuję w osobnym wpisie o modelach Ollamy. Ustaw stream na false, by dostać jedną kompletną odpowiedź zamiast strumienia fragmentów.

curl http://localhost:11434/api/generate -d '{
  "model": "llama3:70b",
  "prompt": "Wyjasnij w jednym zdaniu, czym jest REST API.",
  "stream": false
}'
import requests

payload = {
    "model": "llama3:70b",
    "prompt": "Wyjasnij w jednym zdaniu, czym jest REST API.",
    "stream": False,
}
r = requests.post("http://localhost:11434/api/generate", json=payload)
# wygenerowany tekst znajdziesz w polu "response"
print(r.json()["response"])

W praktyce: wygenerowany tekst siedzi w polu response, a obok dostajesz pola diagnostyczne, między innymi done, total_duration i eval_count (liczba wygenerowanych tokenów). Dodatkowe parametry modelu możesz zapisać na stałe w Modelfile, żeby nie powtarzać ich w każdym requeście.

POST /api/chat - rozmowa z historią

Tu zamiast pojedynczego prompt wysyłasz tablicę messages, gdzie każdy wpis ma rolę system, user lub assistant. To preferowany endpoint do chatbotów, bo przekazujesz w nim całą historię rozmowy, a model widzi kontekst.

curl http://localhost:11434/api/chat -d '{
  "model": "llama3:70b",
  "messages": [
    { "role": "system", "content": "Odpowiadasz krotko i po polsku." },
    { "role": "user", "content": "Podaj trzy zalety lokalnego LLM." }
  ],
  "stream": false
}'
import requests

payload = {
    "model": "llama3:70b",
    "messages": [
        {"role": "system", "content": "Odpowiadasz krotko i po polsku."},
        {"role": "user", "content": "Podaj trzy zalety lokalnego LLM."},
    ],
    "stream": False,
}
r = requests.post("http://localhost:11434/api/chat", json=payload)
# odpowiedź modelu jest w r.json()["message"]["content"]
print(r.json()["message"]["content"])

Różnica wobec /api/generate w jednym zdaniu: generate zwraca tekst w polu response i jest jednym strzałem, chat zwraca obiekt message z rolą i treścią oraz prowadzi ciągniętą rozmowę.

Streaming - czytanie strumienia NDJSON

Gdy stream ma wartość true (to domyślne zachowanie), serwer zwraca odpowiedź w formacie NDJSON, czyli kolejne obiekty JSON oddzielone znakiem nowej linii. Każda linia to fragment generowanego tekstu. Sięgasz po to, gdy chcesz pokazywać odpowiedź na bieżąco, tak jak pisze ją model, zamiast czekać na całość.

import json
import requests

payload = {"model": "llama3:70b", "prompt": "Opowiedz dluga historie.", "stream": True}
with requests.post("http://localhost:11434/api/generate", json=payload, stream=True) as r:
    for line in r.iter_lines():
        if line:
            fragment = json.loads(line)
            # każda linia to osobny obiekt JSON - sklejasz pole "response" po kolei
            print(fragment.get("response", ""), end="")

Pro tip: jeśli odpowiedź "ucina się" albo widzisz błędy parsowania, prawie zawsze przyczyną jest traktowanie strumienia jak jednego JSON-a. Czytaj linia po linii, każdą parsuj osobno.

Inne endpointy - embeddingi, pobieranie, podgląd

Poza generacją przydają się trzy kolejne:

  • POST /api/embeddings - zamienia tekst na wektor liczb. To podstawa wyszukiwania semantycznego i architektury RAG, w której model odpowiada na bazie Twoich dokumentów.
  • POST /api/pull - pobiera model z rejestru na maszynę, odpowiednik ollama pull wywołany przez API.
  • POST /api/show - zwraca szczegóły konkretnego modelu, w tym dane z jego Modelfile.

Modele multimodalne, na przykład llava, który rozumie obrazy, odpytujesz tym samym mechanizmem, dokładając obraz w polu przewidzianym dla danych binarnych.

Tabela - główne endpointy w skrócie

Endpoint Metoda Do czego Kluczowe pola
/api/tags GET lista zainstalowanych modeli brak (zwraca pole models)
/api/generate POST jednorazowa generacja model, prompt, stream, options
/api/chat POST rozmowa z historią model, messages, stream
/api/embeddings POST wektory pod RAG model, tekst wejściowy
/api/pull POST pobranie modelu nazwa modelu
/api/show POST szczegóły modelu nazwa modelu

Dostęp z Pythona i kompatybilność OpenAI

Masz trzy drogi z poziomu kodu i każda ma swój sens.

Droga 1 - oficjalna biblioteka ollama. Najkrótsza ścieżka, jeśli piszesz w Pythonie i nie potrzebujesz nic poza Ollamą.

import ollama

odpowiedz = ollama.chat(
    model="llama3:70b",
    messages=[{"role": "user", "content": "Czym rozni sie chat od generate?"}],
)
# treść odpowiedzi jest w odpowiedz["message"]["content"]
print(odpowiedz["message"]["content"])

Instalujesz ją przez pip install ollama. Pod maską biblioteka woła ten sam REST, ale oszczędza Ci ręcznego budowania requestów i sama składa payload.

Droga 2 - czysty requests. Pokazałem ją wyżej przy endpointach. Wybierasz ją, gdy nie chcesz dodatkowej zależności albo gdy piszesz w innym języku - wtedy używasz jego klienta HTTP.

Droga 3 - warstwa zgodna z OpenAI pod /v1. Najważniejsze: tu rozwiewam mit "ollama api key". Lokalnie klucz API nie jest wymagany, bo Ollama nie ma wbudowanej autoryzacji. Warstwa /v1 przyjmuje jednak dowolny placeholder w polu api_key, bo biblioteki OpenAI wymagają, żeby to pole było wypełnione. Dzięki temu podpinasz istniejący kod napisany pod OpenAI, zmieniając tylko base_url.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # dowolny placeholder - lokalnie klucz nie jest sprawdzany
)
odpowiedz = client.chat.completions.create(
    model="llama3:70b",
    messages=[{"role": "user", "content": "Krotko: po co warstwa /v1?"}],
)
print(odpowiedz.choices[0].message.content)

Konkret: jeśli masz aplikację gotową pod ChatGPT, droga 3 pozwala przełączyć ją na lokalny model bez przepisywania logiki. To wygodny most między światem chmurowym a self-hostingiem. Gdy jednorazowo potrzebujesz mocy większej niż Twoja maszyna, ten sam kod skierujesz na chmurowego dostawcę udostępniającego API zgodne z OpenAI - warstwa /v1 sprawia, że to tylko kwestia zmiany base_url.

Zdalny dostęp i OLLAMA_HOST

Domyślnie serwer nasłuchuje wyłącznie na 127.0.0.1, czyli jest widoczny tylko z tej samej maszyny. To bezpieczny stan startowy. Aby odpytać API z innego komputera, ustaw zmienną OLLAMA_HOST tak, by serwer słuchał na adresie dostępnym w sieci.

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Wtedy adres API z innej maszyny ma postać http://ADRES_SERWERA:11434, gdzie ADRES_SERWERA to IP komputera z Ollamą. Drugą przydatną zmienną jest OLLAMA_ORIGINS, którą kontrolujesz, z jakich źródeł (CORS) przeglądarka może wołać API - przyda się przy aplikacjach webowych.

Najważniejsze i bez owijania: Ollama nie ma wbudowanej autoryzacji. Wystawienie gołego portu 11434 do internetu oznacza, że każdy, kto zna Twój adres, może korzystać z modelu i obciążać Twój sprzęt. Tak się tego nie robi.

Jak udostępnić bezpiecznie:

  • Reverse proxy z uwierzytelnianiem - postaw nginx albo Caddy przed Ollamą i dołóż basic auth lub własny token. Ruch z zewnątrz trafia najpierw do proxy, które sprawdza hasło.
  • Tunel zamiast otwartego portu - VPN albo tunel SSH sprawiają, że port nie jest publiczny, a i tak dosięgniesz go zdalnie.
  • Kontener - jeśli wolisz izolację, sprawdź uruchomienie Ollamy w Dockerze.

Częste błędy i pułapki

Większość problemów z Ollama API to nie awarie, lecz drobiazgi w adresie, porcie albo brakującym modelu. Oto tabela: przyczyna, a obok rozwiązanie.

Objaw Najczęstsza przyczyna Rozwiązanie
404 page not found na /api/generate literówka w ścieżce, zły port, brak pobranego modelu lub stara wersja Ollamy sprawdź adres, wykonaj curl http://localhost:11434/api/tags, pobierz model (ollama pull), zaktualizuj Ollamę
connection refused serwer nie wystartował upewnij się, że Ollama działa (ollama serve); pomoże instrukcja instalacji Ollamy i dobierz mniejszy model w modelach Ollamy. Druga to czystyrequestsna endpoint REST, na przykładPOST http://localhost:11434/api/chatz payloadem JSON. Biblioteka jest krótsza,requests` daje pełną kontrolę i nie dokłada zależności do projektu.

Dlaczego dostaję 404 na /api/generate?

Najczęstsze przyczyny to literówka w ścieżce, zły port, brak pobranego modelu albo stara wersja Ollamy. Zacznij od curl http://localhost:11434/api/tags - jeśli zwróci listę, serwer i port są dobre, więc sprawdź dokładną ścieżkę endpointu i nazwę modelu. Jeśli modelu brakuje, pobierz go poleceniem ollama pull.

Jak wyświetlić listę zainstalowanych modeli przez API?

Wykonaj GET /api/tags, czyli najprościej curl http://localhost:11434/api/tags. Endpoint zwraca pole models z listą modeli zainstalowanych na maszynie wraz z ich metadanymi. To zarazem najszybszy sposób, by potwierdzić, że serwer API w ogóle działa - jeśli odpowiada, masz pewność, że port i adres są poprawne.

Podsumowanie i dalsze kroki

W skrócie: Ollama API to lokalny serwer REST pod http://localhost:11434, którego trzy filary to GET /api/tags, POST /api/generate i POST /api/chat. Odpytujesz go curl, biblioteką ollama, czystym requests albo - przez /v1 - kodem napisanym pod OpenAI. Klucz API lokalnie nie jest potrzebny.

Co dalej, zależnie od tego, dokąd zmierzasz: