198 lines
7.6 KiB
Markdown
198 lines
7.6 KiB
Markdown
# ollama-plagin-swap
|
||
|
||
Удалённый контроль swap для серверов Ollama, используемых через API OpenCode.
|
||
|
||
## Что устанавливается
|
||
|
||
- `src/ollama_swap_agent.py` и `src/ollama_swap_common.py`: Python-агент для macOS и Ubuntu.
|
||
- `examples/opencode/ollama-swap.js`: канонический клиентский плагин OpenCode без зависимостей.
|
||
- `examples/opencode/ollama-swap.ts`: необязательный TypeScript-плагин с пользовательскими инструментами и runtime-guard.
|
||
- Агент предоставляет `GET /health`, `GET /status` и `POST /restart`.
|
||
|
||
## Почему раньше дублировались плагины
|
||
|
||
OpenCode автоматически загружает все файлы плагинов из `.opencode/plugins/` проекта и из
|
||
`~/.config/opencode/plugins/`. Если один и тот же файл лежит в обоих местах, он загружается
|
||
дважды. Поэтому исходники перенесены в `examples/opencode/`, а устанавливается только один
|
||
глобальный файл.
|
||
|
||
## Установка клиента на текущий macOS
|
||
|
||
```sh
|
||
./scripts/install-client.sh
|
||
```
|
||
|
||
Устанавливаются файлы:
|
||
|
||
```text
|
||
~/.config/opencode/plugins/ollama-swap.js
|
||
~/.config/ollama-plagin-swap/clients.json
|
||
```
|
||
|
||
Отредактируйте `clients.json` и укажите URL и токен удалённого агента Ollama.
|
||
|
||
## Установка агента на сервере Ollama
|
||
|
||
Подключитесь по SSH к серверу `10.8.0.62` под пользователем с правами администратора/root. Пример:
|
||
|
||
```sh
|
||
ssh admin@10.8.0.62
|
||
```
|
||
|
||
### Сервер Ollama на macOS
|
||
|
||
Выполните на сервере Ollama:
|
||
|
||
```sh
|
||
mkdir -p ~/src/ollama-plagin-swap
|
||
# Сначала скопируйте файлы репозитория на сервер, затем:
|
||
cd ~/src/ollama-plagin-swap
|
||
./scripts/install-agent.sh
|
||
```
|
||
|
||
Установщик создаёт файлы:
|
||
|
||
```text
|
||
~/.local/share/ollama-plagin-swap/ollama_swap_agent.py
|
||
~/.local/share/ollama-plagin-swap/ollama_swap_common.py
|
||
~/.config/ollama-plagin-swap/config.json
|
||
~/Library/LaunchAgents/com.ollama.swap-agent.plist
|
||
```
|
||
|
||
Измените токен в `~/.config/ollama-plagin-swap/config.json`, затем перезапустите агент:
|
||
|
||
```sh
|
||
launchctl unload ~/Library/LaunchAgents/com.ollama.swap-agent.plist 2>/dev/null || true
|
||
launchctl load -w ~/Library/LaunchAgents/com.ollama.swap-agent.plist
|
||
```
|
||
|
||
Сам сервис Ollama агент перезапускает командами:
|
||
|
||
```sh
|
||
launchctl unload ~/Library/LaunchAgents/com.ollama.serve.plist 2>/dev/null
|
||
launchctl load -w ~/Library/LaunchAgents/com.ollama.serve.plist
|
||
```
|
||
|
||
### Сервер Ollama на Ubuntu
|
||
|
||
Выполните на сервере Ollama под root:
|
||
|
||
```sh
|
||
cd /opt/ollama-plagin-swap
|
||
sudo ./scripts/install-agent.sh
|
||
```
|
||
|
||
Установщик создаёт файлы:
|
||
|
||
```text
|
||
/opt/ollama-plagin-swap/ollama_swap_agent.py
|
||
/opt/ollama-plagin-swap/ollama_swap_common.py
|
||
/etc/ollama-plagin-swap/config.json
|
||
/etc/systemd/system/ollama-swap-agent.service
|
||
```
|
||
|
||
Измените `/etc/ollama-plagin-swap/config.json`, затем выполните:
|
||
|
||
```sh
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now ollama-swap-agent
|
||
```
|
||
|
||
При необходимости откройте доступ с клиентского IP:
|
||
|
||
```sh
|
||
sudo ufw allow from <ip-клиента-opencode> to any port 8731 proto tcp
|
||
```
|
||
|
||
Сам сервис Ollama агент перезапускает командой:
|
||
|
||
```sh
|
||
sudo systemctl restart ollama
|
||
```
|
||
|
||
## Генерация токена
|
||
|
||
Токен не выдаётся внешним сервисом: придумайте одинаковый секрет и впишите его и в серверный `config.json`, и в клиентский `clients.json`. Например:
|
||
|
||
```sh
|
||
openssl rand -hex 32
|
||
```
|
||
|
||
## Порог swap
|
||
|
||
По умолчанию агент сравнивает общий объём **используемого** swap с конкретным размером:
|
||
`swap_threshold_mb = 3048`. Процентный режим выключен (`swap_threshold_percent = null`).
|
||
|
||
Чтобы оставить прежнее процентное поведение, задайте, например:
|
||
```json
|
||
{
|
||
"swap_threshold_percent": 25,
|
||
"swap_threshold_mb": null
|
||
}
|
||
```
|
||
|
||
|
||
## Поведение агента
|
||
|
||
- Каждые `poll_interval_seconds` (по умолчанию 60) снимает метрики swap и состояние `/api/ps`.
|
||
- При превышении порога останавливает загруженные модели через `ollama stop` (`unload_models_before_restart`) и перезапускает сервис; если нужно, `restart_force_after_seconds` позволяет принудительный restart.
|
||
- `last_restart`, `restart_times` и навязчиво оставшийся `restart_in_progress` теперь корректно сохраняются и сбрасываются после нового запуска агента.
|
||
- После перезапуска ждёт `/api/tags` не более `restart_health_timeout_seconds`.
|
||
- Действует cooldown и лимит restart-ов в час для защиты от штормов.
|
||
- Логи и state хранятся в `~/.local/state/ollama-plagin-swap/`.
|
||
|
||
## Проверка агента на сервере
|
||
|
||
```sh
|
||
curl -sS -H "Authorization: Bearer <token>" http://10.8.0.62:8731/health
|
||
curl -sS -H "Authorization: Bearer <token>" http://10.8.0.62:8731/status
|
||
```
|
||
|
||
Ручной запрос на перезапуск:
|
||
|
||
```sh
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"reason":"manual","force":false}' \
|
||
http://10.8.0.62:8731/restart
|
||
```
|
||
|
||
## Перезагрузка сервера
|
||
|
||
После reboot Mac mini агент запустится автоматически при входе пользователя, потому что записан
|
||
в `~/Library/LaunchAgents` с `RunAtLoad=true`. Если автоматического входа нет, agent не стартует
|
||
до логина. Проверьте после перезагрузки:
|
||
|
||
```sh
|
||
launchctl list | grep com.ollama.swap-agent
|
||
curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:8731/health
|
||
```
|
||
|
||
## Проверка клиентского плагина OpenCode
|
||
|
||
OpenCode автоматически подключает глобальный plugin из
|
||
`~/.config/opencode/plugins/ollama-swap.js`. После запуска OpenCode проверьте логи/уведомления:
|
||
при `server.connected` клиент получит статус с удалённого агента и запустит периодический опрос.
|
||
|
||
## Неполадки LaunchAgent
|
||
|
||
Если лог показывает `unrecognized arguments: --config ...`, plist вызывает
|
||
`serve --config ...`. Переведите аргументы в порядок `--config <path> serve`:
|
||
|
||
```xml
|
||
<string>--config</string>
|
||
<string>/Users/andrew/.config/ollama-plagin-swap/config.json</string>
|
||
<string>serve</string>
|
||
```
|
||
|
||
После правки выполните `launchctl unload ... && launchctl load -w ...`.
|
||
|
||
## Локальные проверки перед установкой
|
||
|
||
```sh
|
||
/usr/bin/python3 -m py_compile src/*.py tests/*.py
|
||
/opt/homebrew/bin/pytest -q
|
||
node --check examples/opencode/ollama-swap.js
|
||
```
|