ollama-llm: подключение к SpeShu.AI через OpenAI-совместимый адрес

Ollama — локальный runtime для LLM: он поднимает HTTP-сервер, раздаёт скачанные веса и отдаёт генерацию. Практически весь код, который вы пишете поверх Ollama, ходит в его OpenAI-совместимый слой — тот же самый протокол, что и у SpeShu.AI. Поэтому перенести такой код на облако сводится к двум значениям: адрес сервера и ключ. Модели, железо и локальный сервер больше не нужны.

От SpeShu.AI ollama-llm получает ровно две вещи: base_url = "https://speshu.ai/api/v1" и API-ключ. Больше ничего настраивать не нужно — ни allowlist моделей, ни параметров провайдера, ни плагинов. Любой клиент, умеющий говорить с OpenAI-совместимым адресом, подключается одним аргументом.

Совместимость у ollama-llm двухуровневая, и путать уровни — источник почти всех проблем на этой странице. Слой /v1 (OpenAI-совместимый) у Ollama есть, и именно он работает с SpeShu.AI. Родной протокол (POST /api/chat, POST /api/generate, GET /api/tags, POST /api/embed) — это совсем другой API, и на /api/v1 SpeShu.AI его не отдаёт: запрос уйдёт и вернёт 404. Если ваш код уходит в ollama.Client(host=...) — перепишите его на OpenAI-клиент, см. раздел «Конфигурация».

Установка

Установите пакеты

OpenAI-совместимый слой — это обычный OpenAI-клиент:

pip install openai requests

Родной клиент Ollama (pip install ollama, from ollama import Client) в код генерации не входит — он нужен только для варианта с локальными эмбеддингами из раздела «Эмбеддинги».

Задайте ключ

export SPESHU_API_KEY="sk-ваш-ключ"

Ключ создаётся на speshu.ai/profile и показывается один раз. Подробности — в разделе Аутентификация.

Возьмите идентификатор модели из каталога

Идентификатор текстовой модели не зашивайте в код: состав каталога меняется, и зашитый в код идентификатор падает с 404 model_not_found. Возьмите его из GET /api/v1/models:

cURL

export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  | jq -r '.data[0].id')
echo "$SPESHU_MODEL"

В коде ниже это переменная окружения SPESHU_MODEL. Формат ответа — в разделе Каталог моделей.

Конфигурация

Схема подключения зеркальна привычной для Ollama. Локально это OpenAI(base_url="http://localhost:11434/v1", api_key="ollama"), где api_key — заглушка, которую локальный сервер не проверяет. Через SpeShu.AI меняются два значения — base_url и api_key, и заглушка превращается в настоящий ключ:

Python

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://speshu.ai/api/v1",
    api_key=os.environ["SPESHU_API_KEY"],
)

MODEL = os.environ["SPESHU_MODEL"]  # из GET /api/v1/models

Слэша в конце адреса быть не должно. https://speshu.ai/api/v1/ — вариант хуже неправильного: часть клиентов склеивает его с путём и получает //chat/completions. И суффикс /v1 обязателен: без него клиент соберёт /api/chat/completions и вернёт 404, хотя ключ рабочий.

Если вы добавляли Ollama через обёртку LangChain, поменяйте обёртку, а не адрес. langchain_ollama.ChatOllama говорит с Ollama через его родной клиент, поэтому base_url там не переключает протокол — такая конфигурация уйдёт в /api/chat и вернёт 404. OpenAI-совместимый адрес SpeShu.AI принимает langchain_openai.ChatOpenAI с теми же двумя параметрами:

Python

import os

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model=os.environ["SPESHU_MODEL"],
    base_url="https://speshu.ai/api/v1",
    api_key=os.environ["SPESHU_API_KEY"],
    temperature=0,
)

Первый рабочий пример

Тот же вызов, что и локально, — с блоком system и печатью списания.

Python

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://speshu.ai/api/v1",
    api_key=os.environ["SPESHU_API_KEY"],
)
MODEL = os.environ["SPESHU_MODEL"]

response = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Отвечай по-русски, кратко."},
        {"role": "user", "content": "Что такое контекстное окно модели?"},
    ],
)

print(response.choices[0].message.content)
print("списано:", response.usage.cost.total_cost, "₽")

usage.cost.total_cost — сумма в рублях, списанная с кошелька. У Ollama такого поля нет: там расход считает сам сервер и наружу не отдаёт. Разбор — в гайде Учёт средств.

Эмбеддинги

Эндпоинта эмбеддингов у SpeShu.AI нет: POST /api/v1/embeddings не существует, и запрос к нему вернёт 404. Это ограничение не обходится настройкой. Два честных варианта:(а) Рекомендуемый. Эмбеддинги считает локальный Ollama, генерацию — SpeShu.AI. Это как раз сильная сторона ollama-llm: POST /api/embed у него есть, работает локально и ничего не стоит. В коде ниже это два независимых конфига, и смена любого из них не затрагивает другой.(б) Без эмбеддингов вовсе. Локальный стек остаётся источником контекста, а отбор фрагментов делаете вы сами — по метаданным, по имени файла, по дате. Это обычный чат с документами, и он целиком работает на одном ключе SpeShu.AI.

Вариант (а): два клиента в одном процессе.

Python

import os

from ollama import Client
from openai import OpenAI

# --- генерация: SpeShu.AI ---
speshu = OpenAI(
    base_url="https://speshu.ai/api/v1",
    api_key=os.environ["SPESHU_API_KEY"],
)
MODEL = os.environ["SPESHU_MODEL"]

# --- эмбеддинги: локальный Ollama, к SpeShu.AI отношения не имеет ---
ollama = Client(host=os.environ.get("OLLAMA_HOST", "http://localhost:11434"))
EMBEDDING_MODEL = os.environ["OLLAMA_EMBEDDING_MODEL"]


def embed(texts: list[str]) -> list[list[float]]:
    response = ollama.embed(model=EMBEDDING_MODEL, input=texts)
    return response["embeddings"]

Метод Client.embed и поле embeddings в ответе появились в ollama 0.3.x; в более ранних версиях был embeddings(model=..., prompt=...) с одиночной строкой. Проверьте версию, если поднимаете окружение с нуля.

Продвинутые сценарии

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

stream=True на chat.completions.create — единственный способ обойти потолок запроса в 300 секунд: поток идёт до 15 минут. На OpenAI-совместимом слое приходит обычный SSE с data:-кадрами, поэтому клиент разбирает его сам, без участия Ollama:

Python

stream = client.chat.completions.create(
    model=MODEL,
    stream=True,
    messages=[{"role": "user", "content": "Напиши три абзаца про океан."}],
)

for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
print()

Разбор кадров, маркер [DONE] и кадр со списанием — в разделе Потоковая передача.

Вызов функций

tools и tool_choice уходят без изменений: схема инструмента та же. Один нюанс миграции — локально вы могли полагаться на то, что конкретная open-weight модель всегда поддерживает вызовы инструментов; в каталоге SpeShu.AI моделей много, и поддержка неодинаковая.

Python

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Текущая погода в городе. Используй, когда спрашивают о погоде.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "Какая сейчас погода в Москве?"}],
    tools=TOOLS,
)
print(response.choices[0].message.tool_calls)

Полный цикл вызова — в разделе Вызов функций.

Структурированный вывод

response_format с JSON Schema переезжает как есть. Локально строгий режим часто приходилось обходить парсингом текста — здесь этого не нужно.

Python

import json

response = client.chat.completions.create(
    model=MODEL,
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "answer",
            "schema": {
                "type": "object",
                "properties": {
                    "answer": {"type": "string"},
                    "sources": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["answer", "sources"],
            },
        },
    },
    messages=[{"role": "user", "content": "Дай краткий ответ и список источников."}],
)

print(json.loads(response.choices[0].message.content))

Поддержка json_schema зависит от модели — не все её принимают. Разбор и запасные варианты — в разделе Структурированный вывод.

Генерация изображений

У Ollama нет эндпоинта генерации изображений, поэтому в его API этот сценарий не появится. Медиа-задачи на SpeShu.AI создаются отдельным эндпоинтом и от вашего LLM-клиента не зависят: Создание задачи.

cURL

export MEDIA_MODEL=$(curl -s https://speshu.ai/api/v1/media/models \
  | jq -r '.data[0].id')

curl -s https://speshu.ai/api/v1/async/media/tasks \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model": "'"$MEDIA_MODEL"'", "input": {"prompt": "Кот в смокинге, студийный свет"}}'

Оплата списывается при создании задачи, а не при успешном результате: повтор с тем же Idempotency-Key вернёт исходную задачу, с новым — создаст новую и спишет снова.

Частые проблемы

404 на первом же запросе

Проверьте адрес: должно быть https://speshu.ai/api/v1 — с /api в середине и /v1 на конце. Без суффикса /v1 клиент собирает путь /api/chat/completions и получает 404, хотя ключ при этом рабочий.

Адрес задан с лишним слэшем в конце

https://speshu.ai/api/v1/ — вариант хуже неправильного: часть клиентов склеивает его с путём и получает //chat/completions. Не пишите слэш в конце.

Остался ollama.Client(host=...)

Родной протокол Ollama — /api/chat, /api/generate, /api/tags — на SpeShu.AI не отдаётся, и ответ всегда 404, независимо от ключа. Замените клиент на OpenAI-совместимый с base_url, как в разделе «Конфигурация».

Вместо своего ключа уходит заглушка ollama

Это остаток от локального сервера: в коде осталось api_key="ollama". У SpeShu.AI ключ проверяется — подставьте os.environ["SPESHU_API_KEY"] и убедитесь, что в переменной полное значение с префиксом sk-, без кавычек и переносов строк.

404 model_not_found

Идентификатор зашит в код и разошёлся с каталогом — состав меняется, и зашитое значение устаревает молча. Возьмите его заново из GET /api/v1/models и держите в SPESHU_MODEL.

404 при попытке включить поток

Отдельного эндпоинта для потока нет: это параметр stream=True на chat.completions.create. Формат кадров и разбор — в разделе Потоковая передача.

Полная таблица кодов и три формата ошибок API — на странице Ошибки, таймауты и квоты — в разделе Лимиты.

Что дальше

Начало работы

Ключ, баланс и первый запрос целиком

Модели и цены

Как выбрать модель под задачу

Вызов функций

Полный цикл вызова инструмента

Медиаввод

Ссылки, base64 и хранилище

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

ollama-llm: подключение к SpeShu.AI через OpenAI-совместимый адрес

Установка

Конфигурация

Первый рабочий пример

Эмбеддинги

Продвинутые сценарии

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

Вызов функций

Структурированный вывод

Генерация изображений

Частые проблемы

Что дальше

Начало работы

Модели и цены

Вызов функций

Медиаввод

​Установка

​Конфигурация

​Первый рабочий пример

​Эмбеддинги

​Продвинутые сценарии

​Потоковый ответ

​Вызов функций

​Структурированный вывод

​Генерация изображений

​Частые проблемы

​Что дальше

Начало работы

Модели и цены

Вызов функций

Медиаввод

Установка

Конфигурация

Первый рабочий пример

Эмбеддинги

Продвинутые сценарии

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

Вызов функций

Структурированный вывод

Генерация изображений

Частые проблемы

Что дальше