forked from templates/template-go-orm
fedos
8e74e53b3d
Go-сервис-прокси между Codex CLI и Ollama. Добавляет Bearer-авторизацию, LLM-маршрутизатор (deepseek классифицирует запросы: code/doc/general), поддержку OpenAI Responses API для Codex CLI, стриминг SSE, кеш модели. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
110 lines
5.1 KiB
Markdown
110 lines
5.1 KiB
Markdown
# 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 # Подробная архитектура
|
||
```
|
||
|
||
## Ключевые команды
|
||
|
||
```bash
|
||
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 (для тестирования)
|
||
|
||
```bash
|
||
ollama pull gemma:1b # Router LLM + документы + общее
|
||
ollama pull qwen2.5-coder:1.5b # Целевая модель для кода
|
||
```
|
||
|
||
## Тестирование через curl
|
||
|
||
```bash
|
||
# Здоровье сервиса
|
||
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` файл
|