Files
ollama-plagin-swap/README.md
T

198 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```