Ollama API w Pythonie, a następnie endpoint hostowany

Skonfiguruj klienta Pythona

Najpierw zainstaluj samą Ollamę, uruchom ją i pobierz model z terminala: ollama pull llama3. Serwer nasłuchuje na http://localhost:11434. Następnie zainstaluj pakiet Pythona w środowisku wirtualnym:

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

Pakiet ollama komunikuje się z natywnymi ścieżkami Ollamy pod /api. Pakiet openai jest przeznaczony na drugą część tego samouczka, gdzie celem jest endpoint hostowany. Jeśli wolisz narzędzie graficzne przed kodowaniem, zobacz uwagi na temat używania Ollamy z GUI.

Sprawdź instalację, uruchamiając ollama list w terminalu. Jeśli Twój model tam widnieje, Python go znajdzie. Jeśli później otrzymasz błąd połączenia, serwer prawdopodobnie nie działa.

Twoje pierwsze wywołanie czatu

To są podstawy ollama api python w jednym fragmencie: wiadomość systemowa, wiadomość użytkownika i dwie opcje.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

Odpowiedź to obiekt przypominający słownik; tekst znajduje się w message.content. W options możesz ustawić parametry generowania. temperature kontroluje losowość, a num_ctx ustawia długość okna kontekstu dla tego zapytania. Domyślnie Ollama używa stosunkowo małego okna kontekstu, chyba że je zwiększysz, co zaskakuje osoby wklejające długie dokumenty i otrzymujące odpowiedzi ignorujące początek.

W przypadku czatu wieloetapowego utrzymaj listę wiadomości i dołączaj każdą odpowiedź samodzielnie. Ollama, podobnie jak większość API czatowych, jest bezstanowa między wywołaniami.

Odpowiedzi strumieniowe

Bez strumieniowania czekasz na pełną odpowiedź. Przy stream=True funkcja zwraca generator, a Ty wypisujesz fragmenty, gdy przychodzą:

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

Każda część zawiera małą message.content. Ostatnia część ma done ustawione na true i zawiera czasy oraz liczbę tokenów. W aplikacjach webowych przekaż te fragmenty do przeglądarki za pomocą zdarzeń wysłanych przez serwer lub websocket.

Błędy, które faktycznie zobaczysz

Dwie awarie obejmują większość problemów początkujących.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

Błąd 404 z ResponseError oznacza, że nazwa modelu nie pasuje do pobranego. Nazwy zawierają tagi, więc llama3 i llama3:70b to różne modele. Błąd połączenia oznacza, że serwer nie działa, albo jesteś wewnątrz kontenera, gdzie localhost wskazuje na kontener, a nie host. W takim przypadku przekaż klienta z odpowiednim hostem: ollama.Client(host="http://host.docker.internal:11434").

Więcej wzorców znajdziesz w częstych błędach w API Ollama.

Ten sam program, endpoint hostowany

Modele lokalne są ograniczone przez Twoją pamięć i szybkość. Gdy skrypt musi działać na serwerze, obsługiwać wiele zadań równoległych lub używać większego okna kontekstu, endpoint hostowany jest łatwiejszy. Sekret polega na napisaniu programu pod SDK OpenAI i traktowaniu base URL, klucza i modelu jako konfiguracji:

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

Dla lokalnej Ollamy ustaw LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (akceptowany jest dowolny nie pusty ciąg) i LLM_MODEL=llama3. Dla API hostowanego użyj powyższych domyślnych wartości, swojego prawdziwego klucza i modelu uncensored. Nic innego w kodzie się nie zmienia.

Pobierz klucz na stronie klucza API. Nowe konta mogą jednorazowo aktywować kredyt próbny $0,50 bez podawania danych płatniczych, ważny przez 7 dni. Model to jeden model o otwartych wagach od niezależnego dostawcy, dostrojony do odpowiadania bez odmów treści dla legalnego użytku dorosłych. Obsługuje tylko tekst i nie jest oficjalnym API żadnego dużego laboratorium.

Uruchamianie wielu promptów równolegle

Lokalny model na jednej maszynie zazwyczaj obsługuje jedno zapytanie na raz, więc pętle są sekwencyjne. Endpoint hostowany pozwala na równoległe zapytania, co znacznie przyspiesza pracę wsadową. Utrzymaj liczbę workerów poniżej limitu Twojego klucza: 8 równoległych zapytań dla pełnego klucza, 2 dla klucza próbnego.

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

Sześciu workerów zostawia zapas poniżej limitu 8. Jeśli worker otrzyma 429, SDK OpenAI domyślnie próbuje ponownie kilka razy, ale dodaj własny backoff dla długich uruchomień. Pamiętaj też, że każde strumieniowane zapytanie trzyma swój slot do końca strumieniowania, więc nie mieszaj długiego czatu strumieniowego z dużą paczką na tym samym kluczu próbnym.

Różnice do zaplanowania

• Brak opcji tylko lokalnych. num_ctx i keep_alive nie mają znaczenia po stronie hostowanej. Okno kontekstu wynosi 100 000 tokenów, razem z promptem i completion.
• Limity zapytań. Pełny klucz pozwala na 8 równoległych zapytań i 300 zapytań na minutę; klucz próbny pozwala na 2 i 60. Po przekroczeniu limitu otrzymasz błąd 429 z rate_limited lub concurrency. Spróbuj ponownie po krótkiej przerwie; w przypadku tymczasowego przeciążenia odpowiedź zawiera nagłówek Retry-After: 5.
• Koszt. Input to $0,15 za 1M tokenów, a output to $0,50 za 1M. Skrypt wysyłający 2 000 promptów po 600 tokenów input i 400 tokenów output wyda 2 000 x (600 x $0,15 + 400 x $0,50) / 1M = 2 000 x $0,00029 = $0,58.
• Rozliczenie. Przedpłacony kredyt, od $20 do $500, płatny kryptowalutami (USDT na TRC20 lub USDC na Base). Nieudane lub odrzucone zapytania nie są rozliczane.

Aby porównać endpointy, przeczytaj naszą notę o cenach API lub dokumentację.

Więcej przewodników

• API Ollama vs API OpenAI: endpointy i kod
• Jak używać Ollama z GUI (i rezerwowym rozwiązaniem hostowanym)