Единый роутер LLM-запросов и MCP-набор инструментов с устойчивой очередью, автодискавери устройств и телеметрией в Telegram.
- Локальные задачи через Ollama (
ollama.generate,ollama.embed). - Облачные провайдеры: OpenAI, OpenRouter.
- Единый job lifecycle: submit -> claim -> heartbeat -> complete/fail.
- Автодискавери устройств через Tailscale mesh.
- Multi-port probe (
OLLAMA_PORTS) — несколько Ollama инстансов на одном хосте. - Compose profiles:
ollama(single),ollama-multi(3 инстанса).
- Postgres-очередь с
FOR UPDATE SKIP LOCKED. - Lease-механика: задачи возвращаются в очередь после таймаута воркера.
- Состояние переживает перезапуск контейнеров.
llmmcpотдаёт MCP/HTTP bridge к core.llmtelemetryпубликует статус/прогресс в Telegram.- Поддержан route через
telegram-mcpи direct fallback.
- Полный набор K8s манифестов с Kustomize.
- Ollama Deployment с nodeSelector для привязки к нодам.
- Готов к развёртыванию на K3s кластере.
┌──────────────────────┐ ┌──────────────────────┐
│ Clients / MCP Hosts │─────▶│ llmmcp (Node.js) │
│ │ │ :3333 │
└──────────────────────┘ └──────────┬───────────┘
│ gRPC/HTTP
┌───────▼───────────┐
│ llmcore (Go API) │
│ :8080 / :9090 │
└───────┬───────────┘
│
┌────────────────────▼────────────────────┐
│ llmdb (PostgreSQL) │
│ jobs, devices, models, telemetry state │
└──────────────────────────────────────────┘
▲ ▲
│ │
┌──────┴──────┐ ┌─────┴─────────┐
│ llmworker │ │ llmtelemetry │
│ execution │ │ tg updates │
└─────────────┘ └───────────────┘
| Компонент | Порт | Назначение |
|---|---|---|
llmcore |
8080 |
HTTP API для job-операций |
llmcore |
9090 |
внутренний gRPC transport |
llmmcp |
3333 |
MCP/HTTP bridge |
llmdb |
5435 |
очередь и состояние |
cd llm-mcp
cp .env.example .env
docker compose -f compose.yml --env-file .env up -d --buildПроверка:
curl -fsS http://127.0.0.1:8080/health || true
curl -fsS http://127.0.0.1:3333/health || truePOST /v1/jobs— постановка задачи.GET /v1/jobs/{id}— статус.GET /v1/jobs/{id}/stream— SSE статус/прогресс.POST /v1/workers/register|claim|complete|fail|heartbeat— протокол worker.
POST /v1/embeddings— синхронный embedding proxy.
Роутинг: модели с / в имени (например, qwen/qwen3-embedding-8b) маршрутизируются
на облачный API (OpenRouter, OpenAI, etc.), остальные — на лучший доступный Ollama через
SelectOllamaDevice с circuit breaker и retry.
# Локальный Ollama
curl -X POST http://localhost:8080/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "nomic-embed-text", "input": "Hello world"}'
# Облачный (OpenRouter)
curl -X POST http://localhost:8080/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "qwen/qwen3-embedding-8b", "input": "Hello world", "dimensions": 1024}'Поддержка Matryoshka: параметр dimensions передаётся в cloud API для серверного truncation,
с клиентским fallback через env CLOUD_EMBED_DIMENSIONS.
POST /v1/chat/completions— синхронный/streaming chat completion proxy.
Роутинг аналогичен embeddings: модели с / → OpenRouter, без / → Ollama.
Поддержка stream: true (SSE). Ollama NDJSON автоматически конвертируется в OpenAI SSE формат.
# Sync
curl -X POST http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "google/gemini-2.5-flash-lite", "messages": [{"role": "user", "content": "Hello"}]}'
# Streaming
curl -N http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "google/gemini-2.5-flash-lite", "messages": [{"role": "user", "content": "Count 1-5"}], "stream": true}'GET /v1/costs/balance— баланс OpenRouter, расходы за день/неделю/месяц, top модели.GET /v1/costs/summary— детальная сводка расходов.GET /v1/models/stats— статистика по моделям (запросы, токены, расходы, feedback).POST /v1/feedback— оценка качества ответа ({"model": "...", "rating": "good|bad"}).
POST /v1/knowledge/ingest— запись знаний в LightRAG или mem0.target: "lightrag"— глубокие знания (entity extraction, граф). Минимум 100 символов.target: "mem0"— короткие факты/предпочтения. Минимум 10 символов.
POST /v1/discovery/run— ручной запуск discovery.GET /v1/dashboard— текущее состояние устройств и моделей.GET /metrics— Prometheus метрики (embedding/chat requests, latency, tokens, cost, devices).
PORT_DB_LLM=5435,PORT_HTTP_LLMCORE=8080,PORT_GRPC_LLMCORE=9090,PORT_MCP_LLM=3333.OLLAMA_BASE_URL,OLLAMA_MODEL,OLLAMA_EMBED_MODEL.OLLAMA_EXTRA_ENDPOINTS— дополнительные Ollama endpoints через запятую (например, K8s сервисы).OPENAI_API_KEY,OPENROUTER_API_KEY,OPENROUTER_BASE_URL(по умолчаниюhttps://openrouter.ai/api/v1).CLOUD_EMBED_DIMENSIONS— fallback dimensions для Matryoshka truncation облачных моделей.TELEGRAM_USE_MCP,TELEGRAM_MCP_BASE_URL,TELEGRAM_MCP_BOT_ID,TELEGRAM_MCP_CHAT_ID.TELEGRAM_MCP_FALLBACK_DIRECT=1для отказоустойчивого маршрута телеметрии.- Если
TELEGRAM_MCP_BASE_URLне задан, используетсяhttp://tgapi:8000; на 1 релиз включён legacy retry кhttp://telegram-api:8000.
doc/README.md— полный справочник по core/worker/mcp/telemetry.doc/integration_channel_mcp.md— интеграция сchannel-mcp.proto/llm.proto— внутренний gRPC контракт.
llm-mcp/
├── core/ # Go API/router/queue/discovery
├── worker/ # Python execution adapters
├── telemetry/ # Telegram telemetry sender
├── mcp/ # MCP adapter (Node.js)
├── planner/ # Фоновые процессы (sync, cleanup, benchmarks)
├── db/init/ # SQL init + миграции
├── k8s/ # Kubernetes манифесты
├── proto/ # gRPC contracts
├── scripts/ # Утилиты (sync моделей, probe)
├── config/ # Курированные конфиги
└── compose.yml
- Версия хранится в
VERSIONв форматеYYYY.MM.x. - Все изменения описываются в
CHANGELOG.md. - Секреты и токены не попадают в git; используется только
.env.example. - Перед merge обязательны
docker compose configи минимальный smoke по health/API.