Prime Agent и Ollama 2026: исправление сбоев

Симптом: Ollama отвечает отдельно, но Prime Agent не показывает модель, выдаёт ошибку API или останавливает кодовую задачу.
Быстрое решение: не переустанавливайте всё сразу — пройдите пять уровней по порядку: сервис Ollama, сетевой адрес, models.json, совместимость API и возможности модели.

Официальный репозиторий Prime Agent описывает среду для кодовых и длительных автономных задач, включая фоновые сессии и повторное подключение. Поэтому ситуация «модель возвращает текст» ещё не доказывает, что связка готова к программной работе.

Последнее обновление: 11 августа 2026 года. Параметры Prime Agent сверены с текущей официальной документацией models.md, а команды для Ollama — с её официальными материалами по API, OpenAI-совместимому интерфейсу и диагностике.

Эта инструкция нужна вам, если Prime Agent не показывает установленную модель Ollama, если запросы завершаются ошибкой, если инструменты не вызываются или если длинная задача останавливается на середине. Она также подходит платформенным командам, которые собираются запускать Prime Agent и Ollama на разных машинах.

Карта пяти уровней

Не переходите к следующему уровню, пока предыдущий не подтверждён минимальным тестом. Такая последовательность сокращает область поиска: если /api/tags не отвечает, исправлять compat в models.json пока бессмысленно.

Шаг 1. Сервис Ollama и модель

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

curl -s http://localhost:11434/api/tags

В ответе должен прийти JSON со списком моделей. Название из поля name или соответствующего элемента списка нужно использовать без самовольной замены тега. Например, qwen2.5-coder:7b и qwen2.5-coder — не обязательно одно и то же имя для конфигурации.

Проверьте, что конкретная модель отвечает отдельно от Prime Agent:

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [
      {"role": "user", "content": "Ответьте одним словом: готово"}
    ],
    "stream": false
  }'

Ожидаемый результат — JSON с содержимым ответа, а не ошибка соединения, отсутствие модели или бесконечное ожидание. Официальный API Ollama использует идентификатор модели в запросе и поддерживает отключение потоковой выдачи через stream: false.

Проверьте журнал Ollama. На macOS обычно используется:

cat ~/.ollama/logs/server.log

Для Linux с systemd:

journalctl -u ollama --no-pager --follow --pager-end

В контейнере смотрите вывод через:

docker logs <container-name>

Эти расположения приведены в официальной инструкции Ollama по диагностике.

Шаг 2. Адрес доступа и смысл localhost

Для локального сценария, когда Prime Agent и Ollama работают на одном компьютере, используется адрес:

http://localhost:11434/v1

Именно суффикс /v1 важен для OpenAI-совместимого интерфейса. В baseUrl не добавляйте /chat/completions: Prime Agent сам формирует маршрут API.

Проверьте совместимый список моделей:

curl -s http://localhost:11434/v1/models \
  -H "Authorization: Bearer ollama"

В локальной конфигурации ключ может быть произвольным: Prime Agent требует поле apiKey, а Ollama его не проверяет как полноценный внешний сервис. Это не означает, что в открытом файле нужно хранить настоящий секрет.

Порядок подключения и поддерживаемые маршруты сверяйте с официальной документацией Ollama по OpenAI-совместимости.

В удалённом сценарии проверяйте /v1/models из той же среды, где запущен Prime Agent, а не только из браузера на ноутбуке. Если запрос с сервера Prime Agent не проходит, проблема находится в маршрутизации, bind-адресе, сетевом экране или туннеле.

Не объявляйте удалённый доступ исправным по одному успешному запросу с вашей рабочей станции. Нужен ответ именно от узла Prime Agent, иначе вы проверяете другой сетевой маршрут.

Если Ollama слушает только 127.0.0.1, внешний узел не сможет подключиться к API даже при открытом порте. Если вы меняете адрес прослушивания, одновременно пересмотрите правила межсетевого экрана и способ защиты API. Не публикуйте локальный интерфейс в интернет без ограничения доступа.

Шаг 3. models.json и повторная загрузка

Prime Agent ищет пользовательские модели в:

~/.prime/agent/models.json

Минимальная конфигурация для Ollama выглядит так:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "<MODEL_ID>"
        }
      ]
    }
  }
}

Официальная документация Prime Agent по моделям требует, чтобы id совпадал с идентификатором, передаваемым API. Поля name, reasoning, input, contextWindow, maxTokens и cost описывают модель и поведение Prime Agent, но не заменяют реальное имя модели в Ollama.

Проверьте файл до запуска:

python3 -m json.tool ~/.prime/agent/models.json

Если команда возвращает ошибку, сначала исправьте JSON: лишнюю запятую, неправильные кавычки, комментарии или незакрытую скобку. Затем сравните значение id с фактическим результатом:

ollama list

После исправления откройте меню /model заново. Файл перечитывается при открытии выбора модели, поэтому полная переустановка не нужна для каждой правки.

Разделяйте три разных симптома:

1. Модель не установлена. В ollama list отсутствует нужный ID.
2. Конфигурация не загружена. Модель есть в Ollama, но не появляется в /model.
3. Имя не совпадает. Запись видна, но запрос получает ошибку о неизвестной модели.

Не меняйте одновременно путь, имя провайдера, baseUrl и параметры совместимости. Иначе после успешного теста вы не будете знать, какой именно шаг устранил проблему.

Шаг 4. Совместимость OpenAI API

Когда модель видна, но запрос отклоняется, смотрите на конкретное поле ошибки. Ollama поддерживает часть OpenAI-совместимого API, включая Chat Completions, потоковую выдачу, JSON-режим и инструменты, однако поддержку каждого параметра нужно проверять по текущей документации.

Prime Agent отдельно описывает две настройки:

{
  "compat": {
    "supportsDeveloperRole": false,
    "supportsReasoningEffort": false
  }
}

supportsDeveloperRole нужен, если сервер не принимает роль developer. supportsReasoningEffort отключает отправку параметра управления рассуждением, если конкретный интерфейс или модель его не принимает. Эти параметры можно задать на уровне провайдера или переопределить для отдельной модели.

Пример конфигурации:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "<MODEL_ID>",
          "reasoning": false
        }
      ]
    }
  }
}

Минимальный запрос к совместимому API:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [
      {"role": "user", "content": "Ответьте: API работает"}
    ],
    "stream": false
  }'

Разбирайте ответ по такой последовательности:

• 404 обычно требует проверки маршрута и суффикса /v1;
• ошибка неизвестной модели указывает на id;
• ошибка роли указывает на supportsDeveloperRole;
• ошибка поля рассуждения — на supportsReasoningEffort;
• ошибка потока или статистики требует отдельного теста без потоковой выдачи и без дополнительных полей.

После каждого изменения повторяйте только один запрос. Не отключайте все возможности сразу: иначе базовый тест пройдёт, но Prime Agent потеряет нужную функцию для последующей работы.

Шаг 5. Кодовые задачи и возможности модели

Типичная ошибка диагностики выглядит так: модель отвечает на «объясните этот файл», но не может устойчиво пройти задачу «прочитайте файл, измените функцию и запустите тест». В первом случае проверяется генерация текста. Во втором — следование инструкции, вызов инструментов, сохранение состояния, корректное формирование аргументов и реакция на результат команды.

Проведите последовательную проверку в отдельном тестовом репозитории:

1. Прочитать небольшой файл.
2. Изменить одну строку.
3. Выполнить безопасную тестовую команду.
4. Прочитать результат команды.
5. Исправить небольшую ошибку по выводу теста.

Ожидаемый результат — не красивое объяснение, а фактически изменённый файл, выполненная команда и честный отчёт об ошибке, если модель не справилась. Права инструментов должны соответствовать рабочему каталогу, а тестовую директорию лучше отделить от проекта с важными данными.

Если ошибка стабильно воспроизводится на маленьком тесте, не называйте её подтверждённым дефектом Prime Agent или Ollama. Возможны ограничения конкретной модели, шаблона сообщений или формата инструментов. В этом случае практичнее выбрать другую модель, уменьшить число действий или разделить задачу на этапы.

Шаг 6. Зависание, обрывы потока и нехватка ресурсов

Если базовый диалог работает, а длинная задача останавливается, фиксируйте временную последовательность:

T0 — Prime Agent отправил запрос.
T1 — Ollama начала загрузку модели.
T2 — появились первые токены или ответ задержался.
T3 — вырос контекст или запустилась подзадача.
T4 — поток оборвался, процесс получил ошибку или ресурс закончился.

Сверяйте три источника:

1. состояние Prime Agent через доступные команды состояния;
2. журнал Ollama;
3. системные показатели памяти, загрузки процессора, диска и сети.

Параметр keep_alive в Ollama может влиять на время удержания модели в памяти, а при слишком большом числе запросов сервер может вернуть 503, сообщая о перегрузке. Эти причины нужно отличать от сетевого разрыва и от слишком длинного контекста. Дополнительные варианты диагностики приведены в официальном разделе Ollama с ответами на частые вопросы.

Для первичного разделения причин используйте такую схему:

• модель долго загружается перед первым ответом — проверяйте загрузку и доступную память;
• первые ответы быстрые, затем задержка растёт — проверяйте контекст и размер истории;
• ошибка появляется при параллельных подзадачах — временно уменьшите число одновременных запросов;
• Ollama возвращает 503 — смотрите нагрузку и очередь запросов;
• терминал отключился, а сессия исчезла — проверяйте фоновый режим и возможность повторного подключения.

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

Шаг 7. Удалённая среда и устойчивый запуск

Для удалённой схемы сначала определите, где находится каждый компонент:

Не проверяйте только SSH-подключение. SSH может быть доступен, а API Ollama — слушать только 127.0.0.1 на другой машине. Аналогично, обратный туннель может пропускать один порт, но не тот маршрут, который записан в baseUrl.

Перед запуском реальной работы сделайте тест с ограниченным временем и сохраните:

• версию Prime Agent;
• версию Ollama;
• точный ID модели;
• сокращённый models.json без секретов;
• адрес API без закрытых токенов;
• путь к журналам;
• команду запуска;
• момент и условие сбоя.

Это превращает «иногда зависает» в воспроизводимую границу: например, после запуска инструмента, при росте контекста или только после отключения терминала.

Минимальная приёмка после исправления

Не заменяйте пять тестов одной большой задачей. Приёмку лучше проводить как временную шкалу:

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

Для первичной проверки фонового состояния используйте команды Prime Agent:

prime-agent status
prime-agent agents
prime-agent attach <agent>
prime-agent doctor

Команды помогают проверить активные процессы, сессии и повторное подключение. Если конкретная команда отсутствует в установленной версии, ориентируйтесь на справку вашей версии:

prime-agent --help

Частые вопросы

Почему Prime Agent не видит Ollama?

Проверьте модель через ollama list, затем выполните python3 -m json.tool ~/.prime/agent/models.json. После этого сравните id с фактическим именем модели и повторно откройте /model. Если Ollama отвечает, но запись отсутствует, ищите ошибку пути, JSON или структуры providers, а не проблему сетевого соединения.

Как заполнить baseUrl?

На одном компьютере используйте http://localhost:11434/v1. В контейнере, на удалённой машине или через туннель адрес должен быть доступен именно из процесса Prime Agent. Проверьте его запросом к /v1/models; браузер или локальный терминал на другой машине не подтверждают правильность маршрута.

Почему разговор работает, а кодовая задача нет?

Диалог проверяет генерацию текста, но кодовая задача добавляет инструменты, права доступа, рабочий каталог, обработку stdout и повторные действия. Разделите проверку на чтение, малое изменение и тестовую команду. Если модель не проходит малый сценарий, замените модель или сократите задачу вместо маскировки ошибки дополнительными инструкциями.

Почему поток обрывается на длинной задаче?

Проверьте журнал Ollama, рост контекста, загрузку модели, число параллельных подзадач и системные ресурсы. Отдельно исключите 503, остановку процесса и разрыв терминала. Успешный короткий ответ не доказывает устойчивость многошаговой сессии.

Как выбрать удалённую среду?

Если Prime Agent и Ollama должны работать непрерывно, выбирайте среду, где процесс переживает отключение терминала, сеть между узлами предсказуема, а ресурсы не забираются соседними задачами. Для краткого эксперимента достаточно локального запуска. Для повторяемого долгого прогона сравните собственный компьютер с отдельным Mac-сервером и арендованной средой.

После пятислойной проверки становится видно, что именно ломается: конфигурация, сеть, API, модель или окружение. Если причина в нестабильном хосте, нехватке ресурсов или невозможности продолжить сессию после разрыва терминала, бесконечное редактирование models.json проблему не решит. Локальный запуск удобен для коротких экспериментов, но зависит от свободной памяти, состояния рабочего компьютера и домашней сети. Отдельная машина требует предварительной настройки и постоянного обслуживания.

Если вам нужен более устойчивый вариант для длительных запусков, сравните аренду Mac mini для удалённой разработки или аренду Mac mini в США на восточном побережье с текущей схемой. Это особенно важно, когда задачи Prime Agent должны продолжаться после отключения терминала, а локальный компьютер периодически освобождает память, уходит в сон или теряет сетевое соединение.

Частые вопросы