Ассистент разработки

September 14, 2026 · View on GitHub

English | 简体中文 | 繁體中文 | Русский

Ассистент разработки

Локальная LLM с доступом к MCP-инструментам и семантическим поиском по коду для AI-ассистентов разработки (Cline, Claude, Cursor и др.).

Сервисы: Ollama (LLM) + LiteLLM (шлюз) + MCP Gateway + Embeddings

Память: ~5 ГБ RAM (с моделью 3B)

Платформы: linux/amd64, linux/arm64

📘 Kindle Countdown Deal: $0.99/£0.99 (только в США и Великобритании). The Self-Hosted AI Builder’s Guide — практическое руководство по развертыванию, защите и эксплуатации полного приватного AI-стека.

Архитектура

graph LR
    U["👤 Пользователь"] -->|использует| C["🤖 AI-клиент<br/>(Cline, Claude и др.)"]
    C -->|MCP-инструменты| M["MCP Gateway<br/>(MCP-эндпоинт)"]
    C -->|чат| L["LiteLLM<br/>(AI-шлюз)"]
    L -->|маршрутизация| O["Ollama<br/>(локальная LLM)"]
    L -->|MCP-протокол| M
    C -->|эмбеддинги| E["Embeddings<br/>(текст → векторы)"]

Сервисы

СервисНазначениеПорт по умолчанию
Ollama (LLM)Запускает локальные LLM-модели (llama3, qwen, mistral и др.)11434
LiteLLMAI-шлюз с панелью администратора — маршрутизирует запросы к Ollama и 100+ провайдерам4000
MCP GatewayПредоставляет MCP-инструменты (файловая система, fetch, GitHub, поиск, БД) AI-клиентам3000
EmbeddingsПреобразует текст в векторы для семантического поиска и RAG8000

Примечание: Лёгкие подстеки используют общие стандартные имена контейнеров, порты и имена Docker volumes. С compose-файлами по умолчанию запускайте только один вариант подстека за раз; перед переключением на другой вариант остановите текущий.

Доступ по умолчанию:

  • LiteLLM опубликован на порту хоста 4000.
  • Embeddings по умолчанию привязан к 127.0.0.1:8000.
  • MCP Gateway по умолчанию внутренний; раскомментируйте его port mapping только если MCP-клиенту на хосте нужен прямой доступ.
  • Ollama доступен только внутри Docker-сети; для доступа с хоста или из браузера используйте LiteLLM.

Быстрый старт

Требования:

  • Linux-сервер (локальный или облачный) с установленным Docker
  • Достаточно ОЗУ для этого подстека и выбранной модели (см. оценку памяти выше)
  • Для крупных LLM-моделей (8B+) рекомендуется 16 ГБ ОЗУ или больше
git clone https://github.com/hwdsl2/self-hosted-ai-stack
cd self-hosted-ai-stack/stacks/code-assistant
docker compose up -d

Загрузка модели (обязательно перед отправкой LLM-запросов):

docker exec ollama ollama_manage --pull llama3.2:3b

Запустите проверку работоспособности, чтобы убедиться, что сервисы работают:

# Из каталога этого подстека:
../../stack-check.sh

# Или из корня репозитория:
# ./stack-check.sh

Совет: При первом запуске сервисам может потребоваться несколько минут для инициализации. Если какие-либо проверки не пройдены, подождите и запустите ../../stack-check.sh снова. Используйте docker compose logs для проверки прогресса.

Получите master key LiteLLM (используется для входа в Admin UI и для прямых LLM API-запросов):

docker exec litellm litellm_manage --showkey

Откройте Admin UI LiteLLM:

Откройте http://<server-ip>:4000/ui в браузере. Войдите с именем пользователя admin и master key LiteLLM в качестве пароля. UI предоставляет управление виртуальными ключами, учёт расходов и настройку моделей.

Совет: В Admin UI нажмите Playground в левом меню. Выберите локальную модель (например, ollama-chat/llama3.2:3b) из списка и начните чат — это быстрый способ проверить локальную LLM end-to-end.

Остановить подстек:

# Остановить и удалить контейнеры (данные сохраняются в Docker volumes)
docker compose down

GPU-ускорение (NVIDIA CUDA)

Для GPU-ускорения NVIDIA используйте CUDA compose-файл:

docker compose -f docker-compose.cuda.yml up -d

Совет: Чтобы не добавлять -f docker-compose.cuda.yml к каждой последующей команде docker compose (down, pull, logs и т. д.), задайте её один раз для текущей сессии shell:

export COMPOSE_FILE=docker-compose.cuda.yml

Затем выполняйте обычные команды docker compose как всегда. Чтобы сделать это постоянным, добавьте COMPOSE_FILE=docker-compose.cuda.yml в файл .env в этом каталоге. Выполните unset COMPOSE_FILE, чтобы вернуться к конфигурации CPU.

Требования: GPU NVIDIA, драйвер NVIDIA 575.57.08+ (Linux) или 576.57+ (Windows), и NVIDIA Container Toolkit, установленный на хосте. CUDA-образы поддерживают только linux/amd64.

Запуск без Docker Compose

Если вы предпочитаете использовать команды docker run напрямую, сначала создайте общую сеть для связи между сервисами:

docker network create ai-stack

Затем запустите каждый сервис в общей сети:

Примечание: При ручном использовании docker run дождитесь готовности каждой зависимости перед запуском сервисов, которые её используют (например, дождитесь PostgreSQL и других зависимостей, например Ollama или MCP, перед запуском LiteLLM; если используется AnythingLLM, дождитесь готовности LiteLLM перед его запуском). В примерах ниже создаётся одна переменная пароля PostgreSQL и повторно используется для Postgres и LiteLLM.

LITELLM_POSTGRES_PASSWORD=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32)

# PostgreSQL with pgvector (required by LiteLLM; pgvector enables vector storage for RAG)
docker run -d --name litellm-db --restart always \
    --network ai-stack \
    -e POSTGRES_USER=litellm \
    -e POSTGRES_PASSWORD="$LITELLM_POSTGRES_PASSWORD" \
    -e POSTGRES_DB=litellm \
    -v litellm-db:/var/lib/postgresql \
    pgvector/pgvector:pg18-trixie

# Ollama (LLM)
docker run -d --name ollama --restart always \
    --network ai-stack \
    -v ollama-data:/var/lib/ollama \
    -v ollama-shared:/var/lib/ollama-shared \
    hwdsl2/ollama-server

# MCP Gateway
docker run -d --name mcp --restart always \
    --network ai-stack \
    -v mcp-data:/var/lib/mcp \
    -v mcp-shared:/var/lib/mcp-shared \
    hwdsl2/mcp-gateway

# Embeddings
docker run -d --name embeddings --restart always \
    --network ai-stack \
    -p 127.0.0.1:8000:8000 \
    -v embeddings-data:/var/lib/embeddings \
    hwdsl2/embeddings-server

# LiteLLM (AI-шлюз)
docker run -d --name litellm --restart always \
    --network ai-stack \
    -p 4000:4000 \
    -e LITELLM_OLLAMA_BASE_URL=http://ollama:11434 \
    -e LITELLM_MCP_URL=http://mcp:3000/mcp \
    -e LITELLM_DATABASE_URL="postgresql://litellm:${LITELLM_POSTGRES_PASSWORD}@litellm-db:5432/litellm" \
    -v litellm-data:/etc/litellm \
    -v ollama-shared:/var/lib/ollama-shared:ro \
    -v mcp-shared:/var/lib/mcp-shared:ro \
    hwdsl2/litellm-server

Примечание: Общая сеть позволяет сервисам обращаться друг к другу по имени контейнера (например, LiteLLM подключается к Ollama через http://ollama:11434).

Загрузка модели (обязательно перед отправкой LLM-запросов):

docker exec ollama ollama_manage --pull llama3.2:3b

Счётчики использования

Этот стек участвует в анонимном агрегированном подсчёте загрузок GitHub release assets проекта. Запустите с AI_STACK_DISABLE_USAGE_COUNTS=1 docker compose up -d, чтобы отключить их; подробнее см. Счётчики использования.

Настройка

Каждый сервис можно настроить с помощью опционального env-файла. Скопируйте пример env-файла из соответствующего репозитория, отредактируйте его и раскомментируйте монтирование тома в docker-compose.yml:

СервисEnv-файлРепозиторий
Ollamaollama.envdocker-ollama
LiteLLMlitellm.envdocker-litellm
MCP Gatewaymcp.envdocker-mcp-gateway
Embeddingsembed.envdocker-embeddings

Подробные параметры настройки, справочник API и управление моделями описаны в документации каждого сервиса.

Развёртывание с доступом из интернета

По умолчанию все сервисы слушают по незашифрованному HTTP. Для развёртываний с доступом из интернета установите обратный прокси (например, Caddy, Nginx или Traefik) перед стеком для обеспечения HTTPS. Каждый репозиторий сервиса содержит подробное руководство по обратному прокси с примерами для Caddy и nginx.

Резервное копирование и восстановление

Инструкции по резервному копированию и восстановлению см. в руководстве Резервное копирование и восстановление.

Обновление образов

Обновление всех сервисов до последних версий:

git pull
docker compose pull
docker compose up -d
../../stack-check.sh

После перезапуска подстека выполните ../../stack-check.sh, чтобы проверить сервисы и настройку сгенерированных учётных данных.

git pull обновляет этот репозиторий, включая compose-файлы или вспомогательные скрипты, используемые этим подстеком; docker compose pull обновляет образы сервисов.

Ваши данные сохраняются в Docker-томах. Всегда делайте резервную копию перед обновлением.

Подключение MCP Gateway к LiteLLM

LiteLLM и MCP Gateway автоматически подключены при использовании compose-файла или команд docker run выше — ручная настройка ключей не требуется.

API-ключи автоматически передаются между сервисами через общие тома Docker:

  • MCP Gateway генерирует API-ключ при первом запуске и копирует его в том mcp-shared
  • LiteLLM читает ключ MCP из общего тома при запуске

Переменная окружения LITELLM_MCP_URL=http://mcp:3000/mcp уже задана, все сервисы подключаются автоматически.

Использование

Примечание: В примерах ниже используется jq для форматирования JSON-ответов. Установите его, если он ещё не доступен.

LiteLLM автоматически подключается к MCP Gateway внутри Docker. Чтобы AI-клиент на хосте напрямую использовал http://localhost:3000/mcp, раскомментируйте проброс порта 3000:3000/tcp для сервиса mcp в docker-compose.yml и перезапустите сервис.

# Получение API-ключей
LITELLM_KEY=$(docker exec litellm litellm_manage --getkey)
MCP_KEY=$(docker exec mcp mcp_manage --getkey)
EMBED_KEY=$(docker exec embeddings embed_manage --getkey)

# Используйте с AI-клиентом (например, Cline в VS Code):
# LLM-эндпоинт: http://localhost:4000 (с LITELLM_KEY)
# MCP-эндпоинт: http://localhost:3000/mcp (с MCP_KEY)

# Генерация эмбеддингов для семантического поиска по коду
curl -s http://localhost:8000/v1/embeddings \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $EMBED_KEY" \
    -d '{"input": "function to handle authentication", "model": "text-embedding-ada-002"}' \
    | jq '.data[0].embedding[:5]'