Посібник з усунення неполадок Ollama API

Розуміння структури кінцевої точки API ollama

The ollama endpoint дотримується суворого RESTful шаблону, який відображає структуру API OpenAI. Ви взаємодієте з ним, надсилаючи POST запити до /v1/chat/completions та запитування доступних моделей через GET /v1/models. Ця стандартизація дозволяє вам міняти базові моделі без переписування коду клієнта.

Багато розробників припускають, що кінцева точка підтримує вбудовування (embeddings) або генерацію зображень за замовчуванням. Вона не підтримує. Наш хостинговий сервіс, наприклад, обслуговує лише текстові завершення з однією uncensored-моделлю. Завжди перевіряйте GET /v1/models відповідь, щоб точно дізнатися, які можливості доступні. Якщо ви бачите список моделей, перевірте їхні ідентифікатори перед надсиланням запитів.

При використанні локального екземпляра кінцева точка зазвичай працює на http://localhost:11434. Для хмарних постачальників ви використовуватимете користувацький базовий URL. Переконайтеся, що ваш HTTP-клієнт правильно обробляє заголовки, особливо Content-Type: application/json. Відсутній заголовок часто призводить до тихих збоїв, які виглядають як помилки моделі.

Структурні елементи ключа:

• model: Рядковий ідентифікатор конкретної LLM.
• messages: Масив об'єктів контенту на основі ролей.
• stream: Булевий прапорець, що вмикає Server-Sent Events (SSE).

Чому ваші запити до API ollama можуть не працювати

API calls usually fail due to incorrect base URLs, expired keys, or malformed JSON payloads. The most common error is a 401 Unauthorized response, which means your API key is missing or invalid. Another frequent issue is a 404 Not Found, indicating the endpoint does not support the requested path or model ID.

Уважно перевірте тіло запиту. Якщо ви надсилаєте параметр, який кінцева точка не підтримує, наприклад modalities для моделі лише з текстом, сервер може відхилити запит. Наш сервіс, наприклад, не підтримує вхідні зображення. Відправка їх призводить до миттєвої помилки.

Тайм-аути мережі також викликають збої. Якщо ваша локальна інстанція Olloma простаює, вона може вивантажувати модель з VRAM. Перший запит після холодного запуску може зайняти кілька секунд. Встановіть щедрий тайм-аут у вашому HTTP-клієнті, щоб уникнути передчасних відключень.

Поширені коди помилок:

• 400: Bad Request (неправильний JSON або недійсні параметри).
• 401: Неповноважний (недійсний або відсутній API-ключ).
• 429: Занадто багато запитів (перевищено ліміт швидкості).
• 500: Internal Server Error (помилка завантаження моделі).

Правильне налаштування необмежених моделей ollama

Нецензуровані моделі часто потребують специфічних параметрів для поведінки, як очікується. Основна різниця полягає в system prompt. Ви повинні явно вказати моделі обходити стандартні обмеження. Без сильного системного промпту модель може повернутися до стандартних поведінок безпеки.

Наша точка доступу використовує ідентифікатор моделі uncensored. Ви надсилаєте запити до цього ідентифікатора, а сервер обробляє вибір базової моделі. Це абстрагує складність керування версіями моделей. Вам не потрібно знати, чи є базова архітектура на основі Llama чи Mistral.

Налаштуйте temperature параметр для контролю креативності. Значення 0.7 є хорошою стартовою точкою для збалансованих відповідей. Вищі значення збільшують випадковість, що корисно для творчого письма, але може знизити фактичну точність. Нижчі значення роблять вивід більш детермінованим.

Поради щодо конфігурації:

• Використовувати top_p поруч із temperature для кращого контролю.
• Встановити stop послідовності для запобігання нескінченним циклам.
• Завжди включайте system повідомлення для визначення ролі.

Обробка потокової передачі та лімітів токенів

Потокові відповіді повертають дані фрагментами через події, надслані сервером (SSE). Кожен фрагмент містить часткове завершення. Ви повинні зібрати ці фрагменти, щоб отримати повну відповідь. Наш сервіс включає статистику використання токенів у останньому фрагменті, що дозволяє відстежувати витрати в реальному часі.

Ліміти токенів критичні для довгих розмов. Наш ендпоінт підтримує контекстне вікно 100,000 токенів, об'єднуючи як промпт, так і завершення. Однак максимальний вивід на один запит становить 16,000 токенів. Якщо ви не встановили max_tokens, за замовчуванням — 2048 токенів. Це може призвести до несподіваного обрізання довгих відповідей.

Під час потокової передачі (streaming) обробляйте мережеві перериви коректно. Якщо з'єднання перерветься, ви зможете відновити процес з останнього отриманого фрагмента, якщо сервер це підтримує. Інакше вам може знадобитися повторна спроба всього запиту. Завжди моніторьте usage field у фінальному чанку, щоб уникнути несподіваних платежів.

Найкращі практики потокової передачі:

• Правильно розбирайте події SSE, ігноруючи порожній рядки.
• Накопичуйте фрагменти в пам’яті або буфері.
• Перевірте usage об'єкт у останньому блоці для підрахунку токенів.

Помилки білінгу та Арифметика токенів

Помилки в оплаті часто виникають через непорозуміння того, як рахуються токени. Токени нараховуються як за вхідні дані (промпт), так і за вихідні дані (завершення). Наші тарифи становлять $0.15 за 1M вхідних токенів та $0.50 за 1M вихідних токенів. Помилки та відмови є безкоштовними, що знижує витрати на налагодження.

Токенізатори не завжди відображають 1:1 з символами. Одне слово може бути кількома токенами. Якщо ви оцінюєте витрати на основі кількості символів, ви можете недооцінити рахунок. Використовуйте надійну бібліотеку токенізаторів у вашому клієнті, щоб отримати точні підрахунки перед надсиланням запитів.

Кредит не має строку дії. Якщо ви поповнюєте баланс криптовалютою, кошти залишаються доступними, доки ви їх не використаєте. Це зручно для довгострокових проектів. Однак майте на увазі, що кожен запит споживає токени з вашого балансу. Якщо баланс низький, наступні запити можуть не виконатися.

Поради щодо оплати:

• Відстежуйте використання токенів у кожній відповіді.
• Налаштуйте сповіщення про низькі порогові значення балансу.
• Використовувати max_tokens для обмеження потенційних витрат.

Проблеми безпеки та сканування портів

Локальні ендпоінти Ollama часто відкриті для мережі за замовчуванням. Це робить їх вразливими до сканерів портів, які шукають безкоштовні обчислення. Якщо ви відкриєте порт 11434 без автентифікації, будь-хто зможе використовувати ваші GPU-ресурси. Це може призвести до високих рахунків за електроенергію та уповільнення продуктивності.

Захистіть свою кінцеву точку, змінивши порт за замовчуванням або використовуючи зворотний проксі з автентифікацією. Наш хостинговий сервіс забезпечує безпеку за вас, тому вам не потрібно турбуватися про відкриття портів. Вам потрібно лише зберігати свій API-ключ у таємниці.

Для локальних налаштувань використовуйте брандмаєр для обмеження доступу до довірених IP-адрес. Ви також можете увімкнути аутентифікацію на основі токенів у файлі конфігурації Ollama. Це запобігає несанкціонованим запитам від користувачів.

Кроки безпеки:

• Змініть порт за замовчуванням, якщо відкриваєте доступ до інтернету.
• Використовуйте зворотний проксі з HTTPS та автентифікацією.
• Відстежуйте мережевий трафік на предмет незвичної активності.

Локальне проти Хмарного використання API ollama

Локальне використання дає вам повний контроль над конфіденційністю даних та вибором моделей. Ви можете запускати кілька моделей одночасно та миттєво перемикатися між ними. Однак ви несете відповідальність за технічне обслуговування обладнання, оновлення та безпеку. Хмарне використання перекладає ці обов'язки на постачальника.

Наш хмарний сервіс пропонує uncensored модель, оптимізовану для генерації необмеженого контенту. Ви отримуєте миттєвий доступ без завантаження великих файлів моделей. Компроміс полягає в тому, що ваші дані проходять через наші сервери. Для чутливих даних локальне рішення може бути кращим.

Хмарні послуги часто мають вищу затримку через мережеві кругові подорожі. Локальні екземпляри мають майже нульову затримку, якщо GPU достатньо швидкий. Однак локальні екземпляри вимагають значного обсягу VRAM. Якщо ваш GPU вичерпує пам’ять, модель може перемикатися на CPU, що різко сповільнює відповіді.

Порівняння:

• Локальне: Конфіденційність, контроль, залежність від апаратного забезпечення.
• Хмарний: Зручність, масштабованість, передача даних.

Поширені помилки на стороні клієнта

Розробники часто забувають обробляти ліміти швидкості. Наш сервіс дозволяє 300 запитів на хвилину на кожен ключ. Якщо ви перевищите цей ліміт, ви отримаєте помилку 429. Реалізуйте експоненційне сповільнення (exponential backoff) у вашому клієнті, щоб коректно обробляти ці помилки.

Інша помилка — не встановлення stream параметр правильно. Якщо ви очікуєте потокову передачу, але не встановлюєте stream: true, ви чекатимете на всю відповідь, перш ніж отримати будь-які дані. Це може сповільнити роботу вашого додатка.

Помилки режиму JSON також поширені. Якщо ви встановите response_format: {type: "json_object"}, модель повинна повертати дійсний JSON. Якщо вона цього не робить, ваш парсер видасть помилку. Додайте обробку помилок для перехоплення та повторної спроби парсингу JSON.

Чек-лист:

• Реалізуйте обробку лімітів швидкості.
• Встановити stream: true для оновлень у реальному часі.
• Перевірте вивід JSON при використанні режиму JSON.