Lokální LLM v Pythonu: Rychlý start s Ollama a LiteLLM

Lokální LLM v Pythonu: Rychlý průvodce s Ollama a LiteLLM pro vývojáře

Mnoho vývojářů, kteří začínají svou cestu do světa velkých jazykových modelů (LLM), naráží na překážky: nutnost registrace v cloudových službách, správa API klíčů a neustálé náklady na tokeny. Tento přístup, ačkoliv funkční, není vždy optimální pro první experimenty a lokální vývoj. Tento článek nabízí efektivní alternativu: nasazení a integraci LLM přímo na vašem počítači. Krok za krokem nastavíme lokální prostředí s využitím Ollamy pro spouštění modelů a LiteLLM pro jejich integraci do Python aplikací, čímž ukážeme, jak získat první smysluplnou odpověď od vaší vlastní LLM bez závislosti na externích službách.

Výhody lokálního LLM vývoje

Lokální nasazení LLM má řadu nesporných výhod, zejména pro učení a prototypování. Zaprvé, zcela eliminuje potřebu API klíčů a s nimi spojených finančních nákladů, což umožňuje provádět neomezené množství experimentů. Zadruhé, odpadá závislost na internetovém připojení pro každý požadavek, což je kriticky důležité pro offline vývoj nebo práci v podmínkách nestabilní sítě. Zatřetí, tento přístup činí proces interakce s LLM maximálně transparentním: vidíte, jak váš Python kód komunikuje s LiteLLM, který zase předává požadavek Ollamě, a ta – lokálnímu modelu. Není to 'kouzlo AI', ale jasně sledovatelná programová logika, což výrazně zjednodušuje ladění a pochopení architektury. Pro vývojáře, kteří se snaží hluboce porozumět mechanice integrace LLM, je lokální přístup ideálním výchozím bodem.

Ollama a LiteLLM: Klíčové komponenty architektury

Než se pustíme do instalace, je důležité rozlišit funkce dvou hlavních nástrojů, které budeme používat: Ollama a LiteLLM.

Ollama — je výkonný nástroj pro lokální spouštění velkých jazykových modelů. Funguje jako server, který spravuje stahování, ukládání a provádění LLM na vašem počítači a poskytuje jednotné API pro přístup k nim. V podstatě je Ollama runtime pro lokální LLM, umožňující snadnou práci s různými modely, jako jsou Llama, Mistral, Qwen a další.
LiteLLM — je lehká Python knihovna, navržená pro sjednocení API požadavků na různé poskytovatele LLM. Její klíčovou vlastností je poskytování jednotného rozhraní pro interakci jak s cloudovými službami (OpenAI, Anthropic, Google Gemini), tak s lokálními řešeními, jako je Ollama. To znamená, že kód napsaný pro lokální model prostřednictvím LiteLLM lze snadno adaptovat pro práci s cloudovými poskytovateli s minimálními změnami.

Tímto způsobem Ollama 'spustí' lokální model, LiteLLM zajistí standardizovaný způsob přístupu k němu z Pythonu a váš kód kolem toho vytvoří plnohodnotnou aplikaci.

Instalace Ollamy a stažení lokálního modelu

Pro zahájení práce s lokální LLM je nutné provést několik po sobě jdoucích kroků.

Instalace Ollamy

Nejprve si stáhněte a nainstalujte Ollamu z oficiálních stránek (ollama.com) pro váš operační systém (Windows, macOS, Linux). Po instalaci ověřte správnost instalace spuštěním příkazu v terminálu:

ollama --version

Úspěšný výstup čísla verze potvrdí připravenost Ollamy k práci. Na Windows se ujistěte, že ikona Ollamy (🦙) je přítomna v systémové liště, což indikuje aktivní službu na pozadí.

Stažení lokální LLM

Ollama sama o sobě není model, ale pouze platforma pro jejich spouštění. Nyní je nutné stáhnout konkrétní velký jazykový model. Pro naše účely se skvěle hodí qwen2.5:3b — kompaktní, ale dostatečně výkonný model, který dobře funguje na většině notebooků a podporuje češtinu. Spusťte stahování přes terminál:

ollama run qwen2.5:3b

Při prvním spuštění se zahájí stahování modelu, který bude uložen lokálně. Po dokončení stahování se dostanete do interaktivního chatu Ollamy. Ověřte funkčnost modelu dotazem v češtině, například: Ahoj! Řekni mi ve dvou větách, co je to Python. Pokud model odpoví, znamená to, že hlavní překážka byla překonána. Pro ukončení chatu použijte /bye.

Poznámka: Pokud výkon qwen2.5:3b není dostatečný pro vaše zařízení, zkuste lehčí verzi: ollama run qwen2.5:1.5b. Logika Python kódu zůstane nezměněna.

Příprava Python prostředí

Pro izolaci závislostí projektu se doporučuje použít virtuální prostředí.

Vytvořte složku projektu a přejděte do ní:

```bash

mkdir llm-chat

cd llm-chat

```

Inicializujte virtuální prostředí:

```bash

python -m venv venv

```

Aktivujte jej.

* Windows: venv\Scripts\activate

* macOS / Linux: source venv/bin/activate

Úspěšná aktivace bude označena předponou (venv) v příkazovém řádku.

Nainstalujte knihovnu LiteLLM:

```bash

pip install litellm


Nyní jsou všechny komponenty připraveny k psaní kódu.

## Integrace LLM v Pythonu: První požadavek
Vytvořte soubor `main.py` v kořenovém adresáři projektu a přidejte následující kód:

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("Ahoj! Napiš jednu krátkou větu o Pythonu.")

print(answer)


Spusťte skript z aktivovaného virtuálního prostředí:

python main.py


Pokud se v konzoli objeví smysluplná odpověď od modelu, znamená to, že jste úspěšně integrovali lokální LLM do svého Python kódu. Toto je klíčový moment, který demonstruje, jak se abstraktní model mění ve funkční komponentu vaší aplikace.

### Rozbor kódu `main.py`
Pojďme se podívat na hlavní prvky tohoto minimalistického, ale funkčního skriptu:

*   `from litellm import completion`: Importujeme hlavní funkci `completion` z knihovny LiteLLM, určenou pro odesílání požadavků na LLM.
*   `MODEL = "ollama_chat/qwen2.5:3b"`: Tato proměnná definuje model, který používáme. Předpona `ollama_chat/` říká LiteLLM, že požadavek má být směřován na lokální službu Ollama. Zde musíte uvést název modelu, který jste stáhli (například `qwen2.5:1.5b`).
*   `API_BASE = "http://localhost:11434"`: Určuje adresu lokálního API serveru Ollama. Ve výchozím nastavení Ollama běží na portu `11434`.
*   `messages=[{"role": "user", "content": question}]`: Toto je základní struktura pro interakci s většinou moderních LLM API. Požadavky se předávají jako seznam zpráv, kde každá zpráva má `role` (například "user", "assistant", "system") a `content` (text zprávy). I pro jediný dotaz se používá tato struktura, což pokládá základ pro budoucí práci s historií dialogu a kontextem.
*   `request_timeout=120`: Nastavuje maximální dobu čekání na odpověď od modelu v sekundách. Lokální modely mohou vyžadovat více času na první spuštění nebo na zpracování složitých požadavků.
*   `response.choices[0].message.content`: Z celého objektu odpovědi, vráceného modelem, extrahujeme přímo vygenerovaný text. Objekt `response` obsahuje mnoho dalších užitečných informací, které budeme moci prozkoumat v dalších částech.

## Řešení typických problémů při spuštění
Během nastavení se mohou objevit různé komplikace. Zde jsou ty nejčastější a způsoby jejich řešení:

*   **Problém 1: `Connection refused` nebo `Failed to connect`**
    *   **Příčina:** Služba Ollama není spuštěna nebo je nedostupná.
    *   **Řešení:** Ujistěte se, že je Ollama aktivní. Zkontrolujte ikonu 🦙 v systémové liště (Windows/macOS) nebo spusťte `ollama list` v terminálu. Pokud příkaz odpoví, služba funguje.
*   **Problém 2: `Model not found`**
    *   **Příčina:** Model uvedený v kódu není stažen nebo se jeho název neshoduje s nainstalovaným.
    *   **Řešení:** Spusťte `ollama list`, abyste viděli seznam dostupných lokálních modelů, a upravte název modelu v proměnné `MODEL` v `main.py`.
*   **Problém 3: Dlouhá odpověď nebo nízký výkon**
    *   **Příčina:** První spuštění modelu může být pomalé kvůli načítání do paměti, nebo je model příliš náročný pro vaše zařízení.
    *   **Řešení:** Počkejte déle. Zavřete aplikace náročné na zdroje. Zkuste použít lehčí verzi modelu, například `qwen2.5:1.5b`.
*   **Problém 4: `ModuleNotFoundError: No module named 'litellm'`**
    *   **Příčina:** Skript byl spuštěn mimo aktivované virtuální prostředí, kde je LiteLLM nainstalován.
    *   **Řešení:** Ujistěte se, že jste před spuštěním skriptu aktivovali virtuální prostředí (předpona `(venv)` v terminálu).
*   **Problém 5: Problémy s kódováním v PowerShellu (symboly-„krakonoši“)**
    *   **Příčina:** Neshoda kódování terminálu.
    *   **Řešení:** V PowerShellu spusťte `$OutputEncoding = [System.Text.Encoding]::UTF8` před spuštěním skriptu.

## Co je důležité
*   Lokální nasazení LLM s Ollamou a LiteLLM umožňuje vyhnout se nákladům na API a závislosti na internetu, čímž poskytuje plnou kontrolu nad procesem.
*   Ollama slouží jako runtime pro lokální modely a LiteLLM sjednocuje API pro interakci s nimi z Pythonu.
*   Prvním krokem je instalace Ollamy a stažení vhodného modelu, jako je `qwen2.5:3b`.
*   Python skript používá `litellm.completion` pro odesílání požadavků, kde `MODEL` odkazuje na lokální model přes `ollama_chat/` a `API_BASE` na adresu Ollamy.
*   Požadavky na LLM se předávají ve formě seznamu zpráv s rolemi (`role`) a obsahem (`content`), což je základ pro vytváření dialogových systémů.

## Závěr a další kroky
V této fázi jsme úspěšně implementovali základní integraci lokální LLM do Python aplikace. Model přestal být abstraktní technologií a stal se ovladatelnou komponentou, schopnou odpovídat na dotazy přímo z vašeho kódu. Tento důležitý krok otevírá dveře pro další experimenty a vývoj složitějších AI aplikací.

V další části tento minimální příklad transformujeme do plnohodnotného konzolového chatu, přidáme cyklus komunikace, možnost zadávání dotazů uživatelem a základní přípravu pro správu kontextu dialogu. To umožní přejít od jednorázových otázek k interaktivní interakci s vaší lokální LLM.

— Editorial Team