API Ollama на Python, затем хостинг-эндпоинт

Настройка клиента Python

Сначала установите сам Ollama, запустите его и загрузите модель из терминала: ollama pull llama3. Сервер слушает на http://localhost:11434. Затем установите пакет Python в виртуальной среде:

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

Пакет ollama общается с собственными маршрутами Ollama под /api. Пакет openai предназначен для второй части этого руководства, где целью является хостинг-эндпоинт. Если вы предпочитаете визуальный инструмент перед написанием кода, см. заметки о использовании Ollama с графическим интерфейсом.

Проверьте установку, запустив ollama list в терминале. Если ваша модель отображается там, Python её найдет. Если позже возникнет ошибка подключения, сервер, вероятно, не запущен.

Ваш первый вызов чата

Это основы Python API Ollama в одном фрагменте: системное сообщение, сообщение пользователя и два параметра.

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"])

Ответ — это объект, похожий на словарь; текст находится в message.content. В options вы можете установить параметры генерации. temperature управляет случайностью, а num_ctx задает длину контекста для этого вызова. Ollama по умолчанию использует довольно маленький контекст, если вы его не увеличите, что удивляет людей, которые вставляют длинные документы и получают ответы, игнорирующие начало.

Для многоходового диалога храните список сообщений и добавляйте каждый ответ самостоятельно. Ollama, как и большинство API чата, не сохраняет состояние между вызовами.

Потоковые ответы

Без потоковой передачи вы ждете полного ответа. С stream=True функция возвращает генератор, и вы печатаете части по мере их поступления:

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)

Каждая часть содержит небольшой message.content. Последняя часть имеет done, установленный в true, и включает время и количество токенов. Для веб-приложений передавайте эти фрагменты в браузер через серверные события или веб-сокет.

Ошибки, которые вы действительно увидите

Два сценария ошибок покрывают большинство проблем новичков.

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?")

Ошибка 404 от ResponseError означает, что имя модели не совпадает с тем, что вы скачали. Имена включают теги, поэтому llama3 и llama3:70b — это разные модели. Ошибка подключения означает, что сервер не запущен или вы находитесь внутри контейнера, где localhost указывает на контейнер, а не на хост. В этом случае передайте клиент с правильным хостом: ollama.Client(host="http://host.docker.internal:11434").

Другие шаблоны собраны в распространенных ошибках API Ollama.

Та же программа, хостинг-эндпоинт

Локальные модели ограничены вашей памятью и скоростью. Когда скрипт должен работать на сервере, обрабатывать множество параллельных задач или использовать большое контекстное окно, хостинг-эндпоинт проще. Трюк заключается в том, чтобы писать программу на основе SDK OpenAI и рассматривать базовый URL, ключ и модель как конфигурацию:

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.")

Для локального Ollama установите LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (принимается любая непустая строка) и LLM_MODEL=llama3. Для хостингового API используйте значения по умолчанию выше, ваш реальный ключ и модель uncensored. Ничего другого в коде не меняется.

Получите ключ на странице API-ключей. Новые аккаунты могут получить пробный баланс $0,50 в один клик, без оплаты, действительный в течение 7 дней. Модель представляет собой одну модель с открытыми весами от независимого провайдера, настроенную на ответы без отказов по контенту для законного использования взрослыми. Это только текст, и это не официальный API какой-либо крупной лаборатории.

Запуск множества промптов параллельно

Локальная модель на одной машине обычно обрабатывает один запрос за раз, поэтому циклы являются последовательными. Хостинг-эндпоинт позволяет параллельные запросы, что делает пакетную работу намного быстрее. Держите количество воркеров ниже лимита вашего ключа: 8 параллельных запросов для полного ключа, 2 для пробного ключа.

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)

Шесть воркеров оставляют запас ниже лимита 8. Если воркер получает 429, SDK OpenAI по умолчанию повторяет попытку несколько раз, но добавьте собственную задержку для длительных запусков. Также помните, что каждый потоковый запрос удерживает свой слот до конца потока, поэтому не смешивайте длинный потоковый чат и большой пакет на одном пробном ключе.

Различия, которые нужно учесть

• Нет локальных параметров. num_ctx и keep_alive не имеют смысла на хостинговой стороне. Контекстное окно составляет 100 000 токенов, промпт и ответ вместе.
• Лимиты запросов. Полный ключ позволяет 8 параллельных запросов и 300 запросов в минуту; пробный ключ позволяет 2 и 60. После этого вы получаете 429 с rate_limited или concurrency. Повторите попытку после паузы; при временной перегрузке ответ содержит Retry-After: 5.
• Стоимость. Ввод стоит $0,15 за 1M токенов, а вывод — $0,50 за 1M. Скрипт, отправляющий 2000 промптов по 600 входных и 400 выходных токенов, потратит 2000 x (600 x $0,15 + 400 x $0,50) / 1M = 2000 x $0,00029 = $0,58.
• Биллинг. Предоплаченный баланс, от $20 до $500, оплачивается криптовалютой (USDT на TRC20 или USDC на Base). Неудачные или отклоненные запросы не оплачиваются.

Для сравнения эндпоинтов прочитайте нашу заметку о ценах API или документацию.

Дополнительные руководства

• Ollama API против OpenAI API: Эндпоинты и код
• Как использовать Ollama с графическим интерфейсом (и хостинговым резервным вариантом)