Як я замінив OpenRouter на локальну Ollama в Spring Boot проекті

Я витрачав гроші на OpenRouter API щоразу, коли тестував генерацію казок у своєму Spring Boot проекті. Потім дізнався, що Ollama має OpenAI-сумісний API — і замінив зовнішній сервіс на локальну модель, змінивши лише 3 рядки конфігу.

Спойлер: Ollama працює локально, безкоштовно, без інтернету — і для розробки та тестування це ідеальна заміна будь-якого LLM API.

📚 Зміст статті

• 📌 Розділ 1. Чому я вирішив замінити OpenRouter
• 📌 Розділ 2. Що таке Ollama і як вона працює
• 📌 Розділ 3. Встановлення Ollama на macOS, Linux та Docker
• 📌 Розділ 4. Open WebUI — графічний інтерфейс для тестування
• 📌 Розділ 5. Інтеграція Ollama в Spring Boot проект
• 💼 Розділ 6. Порівняння OpenRouter vs Ollama
• 💼 Розділ 7. Яку модель обрати: Mistral vs Mistral-Nemo
• 💼 Розділ 8. Підводні камені та поради
• ❓ Часті питання (FAQ)
• ✅ Висновки

⸻

🎯 Розділ 1. Чому я вирішив замінити OpenRouter

Платити за кожен тестовий запит під час розробки — це як залишати таксі з увімкненим лічильником, поки ви зайшли в магазин.

Коли ви працюєте з LLM API в production — це виправдано. Але під час розробки ситуація інша: ви постійно змінюєте промпти, тестуєте різні формати відповідей, дебажите парсинг. Кожен такий запит — це реальні гроші, навіть якщо модель дешева.

Мої причини для переходу

• ✔️ Економія: тестові запити до OpenRouter коштували ~$0.000058 за штуку — мало, але за сотні запитів на день набігає
• ✔️ Швидкість ітерацій: локальна модель відповідає без мережевої затримки — цикл «змінив промпт → перевірив результат» стає миттєвим
• ✔️ Незалежність від інтернету: працюю з поїзда, кав'ярні, літака — Ollama працює офлайн
• ✔️ Приватність: дані дітей (імена, вік) не покидають мій комп'ютер під час тестування

Висновок розділу: Для розробки та тестування локальна модель — це не компроміс, а перевага. Production залишається на OpenRouter.

⸻

📌 Розділ 2. Що таке Ollama і як вона працює

Ollama — це як Docker, але для AI-моделей. Одна команда — і модель працює.

Замість того щоб налаштовувати Python-середовище, завантажувати ваги моделей вручну та розбиратись із залежностями — ви просто пишете ollama pull mistral і модель готова до роботи. Ollama бере на себе всю складність: квантизацію, оптимізацію під ваше залізо, управління пам'яттю.

Чому Ollama підходить для Spring Boot проектів

Ключова особливість Ollama — це OpenAI-сумісний ендпоінт /v1/chat/completions. Це означає, що будь-який код, який працює з OpenAI або OpenRouter API, може працювати з Ollama без зміни логіки — достатньо змінити URL.

Які моделі підтримує Ollama

• ✔️ Mistral (4.4 GB) — швидка, добре працює для генерації тексту
• ✔️ Mistral-Nemo (7 GB) — розумніша, краще тримає контекст і складні інструкції
• ✔️ Llama 3.1 (4.7–8 GB) — модель від Meta, сильна в reasoning
• ✔️ Gemma 2 (5.4 GB) — модель від Google, добре працює з багатомовним контентом
• ✔️ Phi-3 (2.2 GB) — компактна модель від Microsoft для слабшого залізa

Висновок розділу: Ollama робить локальний AI доступним для будь-якого розробника — без DevOps навичок і з мінімальними вимогами до заліза.

📌 Розділ 3. Встановлення Ollama на macOS, Linux та Docker

Від нуля до працюючої локальної AI-моделі — 2 хвилини і 3 команди.

macOS (Homebrew) — рекомендований спосіб

# Встановлення
brew install ollama
# Запуск сервісу (працюватиме у фоні)
brew services start ollama
# Завантаження моделі (~4.4 GB)
ollama pull mistral
# Перевірка
ollama list

Після цього Ollama слухає на http://localhost:11434 і готова приймати запити.

Linux

# Встановлення одним скриптом
curl -fsSL https://ollama.com/install.sh | sh
# Завантаження моделі
ollama pull mistral
# Перевірка що сервіс працює
curl http://localhost:11434/api/tags

Docker — універсальний варіант

# Запуск Ollama в контейнері
docker run -d -p 11434:11434 --name ollama ollama/ollama
# Завантаження моделі всередину контейнера
docker exec ollama ollama pull mistral

Перевірка: тестовий запит

Після встановлення будь-яким способом перевірте працездатність:

curl http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mistral",
"messages": [{"role": "user", "content": "Привіт! Розкажи коротку казку"}]
}'

Якщо у відповіді є JSON з полем choices — все працює.

Керування сервісом на macOS

# Зупинити
brew services stop ollama
# Запустити
brew services start ollama
# Перевірити статус
brew services info ollama

Висновок: Встановлення Ollama простіше ніж налаштування більшості Java-фреймворків. Три команди — і локальний AI готовий.

📌 Розділ 4. Open WebUI — графічний інтерфейс для тестування

Тестувати промпти через curl — можна. Через красивий чат-інтерфейс — приємніше і продуктивніше.

Перед тим як підключати Ollama до Spring Boot, варто перевірити як модель відповідає на ваші промпти. Open WebUI дає зручний інтерфейс для цього — з історією чатів, вибором моделей та налаштуванням параметрів.

Запуск Open WebUI через Docker

docker run -d -p 3000:8080 \
--add-host=host.docker.internal:host-gateway \
--name open-webui \
ghcr.io/open-webui/open-webui:main

Параметр --add-host=host.docker.internal:host-gateway дозволяє контейнеру звертатись до Ollama, яка працює на хост-машині. Після запуску відкрийте http://localhost:3000 — і ви отримаєте повноцінний чат з AI.

Що можна робити в Open WebUI

• ✔️ Тестувати різні моделі та порівнювати відповіді
• ✔️ Відлагоджувати промпти для генерації казок перед інтеграцією
• ✔️ Перевіряти якість українського тексту різних моделей
• ✔️ Налаштовувати temperature, max_tokens та інші параметри

Керування контейнером

# Зупинити
docker stop open-webui
# Запустити знову
docker start open-webui

Open WebUI — необов'язковий, але дуже зручний інструмент. Допомагає відточити промпти до того, як писати код.

📌 Розділ 5. Інтеграція Ollama в Spring Boot проект

Найкраща міграція — та, де ви не переписуєте код, а лише міняєте конфігурацію.

Як виглядала архітектура з OpenRouter

Spring Boot → HTTPS → openrouter.ai/api/v1/chat/completions → Відповідь

Як стала з Ollama

Spring Boot → HTTP → localhost:11434/v1/chat/completions → Відповідь

Формат запитів і відповідей ідентичний. Міняється тільки адреса.

Крок 1: Додаємо конфігурований URL в application.properties

Було (тільки API-ключ і модель):

app.openrouter.api-key=${OPENROUTER_API_KEY:sk-or-v1-ваш-ключ}
app.openrouter.model=${OPENROUTER_MODEL:mistralai/mistral-7b-instruct}

Стало (додали base-url):

app.openrouter.api-key=${OPENROUTER_API_KEY:not-needed}
app.openrouter.model=${OPENROUTER_MODEL:mistral}
app.openrouter.base-url=${OPENROUTER_BASE_URL:http://localhost:11434/v1/chat/completions}

Крок 2: Робимо URL конфігурованим у клієнтському класі

Додаємо нове поле з анотацією @Value:

@Value("${app.openrouter.base-url:https://openrouter.ai/api/v1/chat/completions}")
private String apiBaseUrl;

Замінюємо хардкод у методі generateResponse:

// Було:
String apiUrl = "https://openrouter.ai/api/v1/chat/completions";
// Стало:
String apiUrl = apiBaseUrl;

Оновлюємо лог для зрозумілості:

// Було:
log.info("Запит до OpenRouter API, модель: {}", model);
// Стало:
log.info("Запит до LLM API ({}), модель: {}", apiBaseUrl, model);

Крок 3: Перемикання між середовищами

Локальна розробка (application.properties за замовчуванням):

app.openrouter.api-key=not-needed
app.openrouter.model=mistral
app.openrouter.base-url=http://localhost:11434/v1/chat/completions

Production на Railway (environment variables):

OPENROUTER_API_KEY=sk-or-v1-ваш-реальний-ключ
OPENROUTER_MODEL=mistralai/mistral-7b-instruct
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1/chat/completions

Жодних if/else, жодних профілів — конфігурація вирішує все.

Висновок розділу: Вся міграція — це 3 рядки в properties + 1 рядок у Java-класі. Код не змінюється, бізнес-логіка залишається тією самою.

💼 Розділ 6. Порівняння: OpenRouter vs Ollama

Це не конкуренти — це інструменти для різних етапів розробки.

Ідеальна стратегія — Ollama для розробки, OpenRouter (або інший API) для production. Один код, різні конфіги.

💼 Розділ 7. Яку модель обрати: Mistral vs Mistral-Nemo

Починайте з меншої моделі. Переходьте на більшу тільки якщо бачите проблеми з якістю.

Як встановити обидві моделі

# Легка модель (вже встановлена)
ollama pull mistral
# Розумніша модель
ollama pull mistral-nemo
# Перевірити що є
ollama list

Перемикання — один рядок у конфігу:

# Легка
app.openrouter.model=mistral
# Розумніша
app.openrouter.model=mistral-nemo

Обидві моделі зберігаються на диску. Ollama підвантажує в пам'ять тільки ту, яка використовується.

Висновок: У середовищі розробки та локального тестування оптимально стартувати з Mistral як базової моделі з мінімальними ресурсними вимогами.

У разі недостатньої якості генерації або потреби у кращому розумінні інструкцій, перехід на Mistral-Nemo здійснюється без змін у бізнес-логіці — достатньо оновити назву моделі в конфігурації або команді запуску.

💼 Розділ 8. Підводні камені та поради

Локальна модель — не срібна куля. Знати обмеження — означає уникнути розчарувань.

1. Cold start — перший запит повільний

Коли Ollama отримує перший запит після запуску або після довгої паузи, вона завантажує модель у RAM. Це може зайняти 5-15 секунд. Наступні запити — швидкі (0.5-2 секунди).

Рішення: Зробіть «прогрівальний» запит при старті Spring Boot додатку або просто враховуйте цю затримку.

2. Якість українського тексту

Локальні моделі розміром 7B параметрів генерують українську гірше ніж GPT-4 або Claude. Для тестування логіки додатку це нормально, але фінальні тексти для користувачів краще генерувати через потужніші хмарні моделі.

Рішення: Використовуйте Ollama для перевірки flow (генерація → парсинг → збереження → відображення), а не для оцінки фінальної якості тексту.

3. Ollama повинна бути запущена

Якщо Ollama не працює, Spring Boot отримає connection refused. Переконайтесь що сервіс активний перед запуском додатку.

# Перевірка
brew services info ollama
# Якщо зупинена
brew services start ollama

4. Споживання ресурсів

В idle-режимі Ollama майже не споживає ресурси. Але під час генерації модель займає 4-10 GB RAM і навантажує CPU/GPU. На MacBook з 8 GB RAM може бути тісно з Mistral-Nemo.

Рішення: Використовуйте mistral (4.4 GB) на машинах з 8 GB RAM, mistral-nemo — на 16 GB+.

5. Різниця в форматі відповідей

Хоча API сумісний, локальні моделі можуть повертати текст у трохи іншому стилі — наприклад, з markdown-форматуванням або іншою структурою. Тестуйте парсинг відповідей ретельно.

Висновок: Всі підводні камені вирішуються — головне знати про них заздалегідь і не очікувати від 7B-моделі якості GPT-4.

❓ Часті питання (FAQ)

Чи можна використовувати Ollama в production?

Технічно — так, я можу розгорнути Ollama у production-середовищі.

Але для проєктів із великим навантаженням я цього не рекомендую.

Ollama обслуговує запити послідовно та фактично обмежена ресурсами одного сервера (CPU/GPU, RAM).

Для production-рішень із масштабуванням я обираю хмарні API (OpenRouter, OpenAI)

або розгортаю vLLM / TGI з балансуванням навантаження, автоскейлінгом та контролем продуктивності.

Скільки місця на диску займають моделі?

Mistral — ~4.4 GB, Mistral-Nemo — ~7 GB. Моделі зберігаються у ~/.ollama/models/. Видалити непотрібну модель можна командою ollama rm назва-моделі.

Чи працює Ollama на Windows?

Так, Ollama підтримує Windows 10+ (64-bit). Завантажте інсталятор з ollama.com/download або використовуйте Docker. На Windows із GPU NVIDIA працює особливо швидко завдяки CUDA.

Чи можна запускати кілька моделей одночасно?

Ollama автоматично вивантажує попередню модель і завантажує нову при зміні. Одночасно в пам'яті — одна модель. Для паралельної роботи кількох моделей потрібен достатній обсяг RAM.

Як оновити Ollama?

На macOS: brew upgrade ollama. Моделі зберігаються окремо і не потребують повторного завантаження після оновлення.

✅ Висновки

• 🔹 Ollama дозволяє запустити повноцінну LLM локально за 2 хвилини
• 🔹 Завдяки OpenAI-сумісному API, перемикання Spring Boot проекту з OpenRouter на Ollama — це зміна 3 рядків у конфігурації
• 🔹 Ідеальна стратегія: Ollama для розробки та тестування, хмарний API для production
• 🔹 Починайте з моделі Mistral (4.4 GB), переходьте на Mistral-Nemo тільки якщо потрібна вища якість
• 🔹 Код залишається незмінним — конфігурація визначає середовище

Головна думка:

Найкраща архітектура — та, де перемикання між локальною та хмарною AI-моделлю не вимагає зміни жодного рядка коду. Три параметри в конфігу — і ваш Spring Boot проект працює з будь-яким LLM-провайдером.