ollama-proxy/AGENTS.md

AGENTS.md — ollama-proxy

Контекст

ollama-proxy — Go-прокси для Ollama Cloud (https://ollama.com). Балансирует запросы по нескольким API-ключам с round-robin и failover на 429/5xx. Слушает 127.0.0.1:11435, экспонирует нативный Ollama API (/api/*) и OpenAI-совместимый (/v1/*) passthrough. Деплой — systemd unit ollama-proxy.service. Используется opencode через кастомный провайдер ocp.

Стек

• Go 1.22 (используется log/slog, net/http, net/http/httputil)
• Единственная внешняя зависимость: golang.org/x/term (prompt без echo в accounts add)
• Go 1.18 из apt НЕ подходит — нужен ~/.local/go/bin/go (Go 1.22.10). Перед сборкой: export PATH="$HOME/.local/go/bin:$PATH"
• Сборка: make build → ./ollama-proxy
• Тесты: go test ./... (43 теста, включая integration-тесты с httptest)
• Линт: go vet ./..., gofmt -l .

Структура

main.go                        — точка входа, делегирует в cli.Run
internal/config/
  accounts.go                  — Account, AccountsFile, JSON load/save (chmod 0600, atomic)
  server.go                    — ServerConfig (addr, base_url, cooldown, retries, log_level)
internal/log/logger.go         — slog JSON logger с configurable level
internal/proxy/
  balancer.go                  — round-robin + per-account cooldown (RWMutex)
  handler.go                   — HTTP handler: reverse-proxy, Authorization подмена, SSE flush
  retry.go                     — документация стриминг-инварианта
internal/cli/
  root.go                      — dispatch подкоманд (serve / accounts / version)
  accounts.go                  — add / list / remove / set-base-url
  serve.go                     — запуск HTTP-сервера с signal handling
systemd/ollama-proxy.service   — systemd unit

Конфигурация

• Аккаунты: ~/.config/ollama-proxy/accounts.json (XDG_CONFIG_HOME, chmod 0600, atomic write)
• Флаги serve: --addr, --base-url, --cooldown, --retries, --log-level
• Env vars: OLLAMA_PROXY_ADDR, OLLAMA_PROXY_BASE_URL, OLLAMA_PROXY_COOLDOWN, OLLAMA_PROXY_RETRIES, OLLAMA_PROXY_LOG_LEVEL

Типичные задачи

• Добавить аккаунт: ollama-proxy accounts add --name <alias> (промпт) или ... add <key> --name <alias>
• Перезапустить после правки аккаунтов: sudo systemctl restart ollama-proxy (прокси читает accounts.json при старте; runtime-обновления не поддерживаются)
• Посмотреть логи: journalctl -u ollama-proxy -f — JSON-структурированные (account, account_id, path, status, latency_ms, stream)
• Проверить, что прокси жив: curl http://127.0.0.1:11435/api/version → должен вернуть JSON от ollama.com
• Проверить список моделей: curl http://127.0.0.1:11435/v1/models | jq '.data | length' (~35 моделей)
• Запустить opencode с пулом: openlama (обёртка в ~/.local/bin/openlama, выставляет NO_PROXY и запускает opencode)
• Обновить список моделей в opencode-конфиге: curl -sS http://127.0.0.1:11435/v1/models | jq -r '.data[].id' → обновить models блок в ~/.config/opencode/opencode.json

Интеграция с opencode

Два отдельных конфига: opencode видит только marg/fireworks, openlama видит только ocp.

• ~/.config/opencode/opencode.json — глобальный конфиг с marg + fireworks (без ocp)
• ~/.config/opencode/openlama.json — отдельный конфиг с ocp + "enabled_providers": ["ocp"]. Содержит те же instructions/mcp/plugins/agent что глобальный, но только провайдер ocp.
• ~/.local/bin/openlama — обёртка, выставляет OPENCODE_CONFIG=~/.config/opencode/openlama.json + NO_PROXY=127.0.0.1,localhost,::1 + exec opencode "$@"

openlama.json (ключевая часть):

{
  "enabled_providers": ["ocp"],
  "provider": {
    "ocp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama Cloud (pool)",
      "options": {
        "baseURL": "http://127.0.0.1:11435/v1",
        "apiKey": "proxy"
      },
      "models": {
        "gpt-oss:20b": { "name": "gpt-oss:20b" },
        "...": { "name": "..." }
      }
    }
  }
}

OPENCODE_CONFIG мерджится с глобальным конфигом, но enabled_providers: ["ocp"] перекрывает глобальный — marg/fireworks скрыты.

Модель не сделана дефолтной — выбирается через /models в TUI.

ВАЖНО: NO_PROXY. Если в окружении установлен HTTP_PROXY/HTTPS_PROXY (например http://127.0.0.1:2080), opencode (Bun runtime) направит запросы к прокси через HTTP-прокси → 502 Bad Gateway. Нужно явно исключить localhost:

# В ~/.config/environment.d/no-proxy-local.conf (systemd/desktop sessions):
NO_PROXY=127.0.0.1,localhost,::1
no_proxy=127.0.0.1,localhost,::1

Или запускать opencode с NO_PROXY=127.0.0.1,localhost opencode ....

Модели в конфиге: opencode НЕ умеет динамически резолвить модели через /v1/models для @ai-sdk/openai-compatible — models: {} даёт ProviderModelNotFoundError. Нужно явно перечислить модели. Обновить список: curl -sS http://127.0.0.1:11435/v1/models | jq -r '.data[].id' → вставить в models блок.

WARN

• Никогда не запускай прокси на 0.0.0.0 без auth — он не имеет аутентификации, любой может использовать твои ключи
• accounts.json содержит ключи в plaintext — файл chmod 0600, не коммить в git
• После правки accounts.json нужен sudo systemctl restart ollama-proxy (прокси не перечитывает файл в рантайме)
• Если локальная ollama запущена на 11434 — это НЕ конфликтует (прокси на 11435), но OLLAMA_HOST=127.0.0.1:11435 нужно явно указывать
• Стриминг-инвариант: после первого flush-а 2xx ответа переключение аккаунта НЕ происходит. Mid-stream ошибки → truncated response клиенту. Это by design (нельзя дублировать вывод)
• 5xx НЕ вызывает cooldown аккаунта (только 429). 5xx → failover на следующий аккаунт, но без penalty

План отката

• sudo systemctl stop ollama-proxy && sudo systemctl disable ollama-proxy
• sudo rm /usr/local/bin/ollama-proxy /etc/systemd/system/ollama-proxy.service && sudo systemctl daemon-reload
• Убрать блок ocp из ~/.config/opencode/opencode.json