Local_Perplexity/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Ollama Proxy — Go-сервис, выступающий прокси между Codex CLI и локальной Ollama. Добавляет авторизацию-заглушку и LLM-маршрутизатор: маленькая модель (gemma:1b) классифицирует входящий запрос и перенаправляет его к нужной целевой модели (qwen2.5-coder для кода, gemma для текста).

Без БД, без Docker на текущем этапе. Чистый Go, stateless.

Архитектура

Codex CLI → Ollama Proxy (:11435) → Ollama (:11434)
                  │
            Token check (AUTH_TOKEN из .env)
            Router LLM: gemma:1b → code / document / general
                  │
     qwen2.5-coder:1.5b | gemma:1b | gemma:1b

Поток запроса:

1. Codex CLI отправляет запрос с model: "auto" на прокси
2. Middleware проверяет Authorization: Bearer <AUTH_TOKEN>
3. Router: если модель не указана явно → gemma:1b классифицирует последнее user-сообщение
4. Прокси подменяет поле model в запросе и проксирует в реальную Ollama
5. Стриминг-ответ (NDJSON) возвращается в Codex CLI построчно

Маршрутизация срабатывает только один раз (при первом запросе с model: "auto"). Последующие запросы в той же сессии Codex CLI отправляет уже с конкретным именем модели — прокси пропускает роутер и проксирует напрямую.

Структура проекта

cmd/server/main.go              # Точка входа — загрузка конфига, запуск HTTP-сервера
internal/
  config/config.go              # Конфигурация из env-переменных
  model/
    ollama.go                   # Типы Ollama API (Chat, Generate, Tags, Message)
  handler/
    middleware.go               # Проверка AUTH_TOKEN (Bearer token)
    proxy.go                    # HTTP-хендлеры: /api/chat, /api/generate, /api/tags
  service/
    ollama_client.go            # HTTP-клиент к Ollama (streaming + синхронный)
    router.go                   # LLM-маршрутизатор через gemma:1b
  router/
    router.go                   # chi-роутер, регистрация маршрутов
go.mod / go.sum                 # Зависимости
Makefile                        # Команды сборки и запуска
.env                            # Локальные переменные окружения (не в git)
docs/
  architecture.md               # Подробная архитектура

Ключевые команды

make build    # go build -o ollama-proxy ./cmd/server
make run      # go run ./cmd/server (читает .env)
make test     # go test ./...

Переменные окружения (.env)

Переменная	Описание	По умолчанию
PROXY_PORT	Порт прокси	11435
AUTH_TOKEN	Токен авторизации (заглушка)	— (обязательна)
OLLAMA_URL	URL реальной Ollama	http://localhost:11434
ROUTER_MODEL	Модель-классификатор	gemma:1b
CODE_MODEL	Модель для кода	qwen2.5-coder:1.5b
DOC_MODEL	Модель для документов	gemma:1b
GENERAL_MODEL	Общая модель	gemma:1b

Модели Ollama (для тестирования)

ollama pull gemma:1b             # Router LLM + документы + общее
ollama pull qwen2.5-coder:1.5b  # Целевая модель для кода

Тестирование через curl

# Здоровье сервиса
curl http://localhost:11435/health

# Без токена → 401
curl -X POST http://localhost:11435/api/chat -d '{}'

# С токеном, auto-маршрутизация (code)
curl http://localhost:11435/api/chat \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -d '{"model":"auto","messages":[{"role":"user","content":"напиши функцию на Go"}]}'

# С токеном, явная модель (без маршрутизации)
curl http://localhost:11435/api/chat \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -d '{"model":"gemma:1b","messages":[{"role":"user","content":"привет"}]}'

# Список моделей
curl http://localhost:11435/api/tags \
  -H "Authorization: Bearer <AUTH_TOKEN>"

Конвенции

• Комментарии в коде — на русском
• Переносы строк LF (.gitattributes)
• Версионирование: bumpversion, VERSION файл