Skip to content

README-ru.md

Latest commit

 

History

History
197 lines (139 loc) · 10.8 KB

README-ru.md

File metadata and controls

197 lines (139 loc) · 10.8 KB
Raw

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

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

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

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

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

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

Архитектура

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/>(текст → векторы)"]
Loading

Сервисы

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

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

git clone https://github.com/hwdsl2/docker-ai-stack
cd docker-ai-stack/stacks/code-assistant
docker compose up -d

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

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

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

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

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

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

Запуск без Docker Compose

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

docker network create ai-stack

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

# PostgreSQL (required by LiteLLM)
docker run -d --name litellm-db --restart always \
    --network ai-stack \
    -e POSTGRES_USER=litellm \
    -e POSTGRES_PASSWORD=litellm \
    -e POSTGRES_DB=litellm \
    -v litellm-db:/var/lib/postgresql \
    postgres:18

# 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@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

Проверка развёртывания

После запуска стека можно проверить, что все сервисы работают корректно:

# Выполните из корневой директории docker-ai-stack
../../stack-check.sh

Доступ к панели администратора LiteLLM:

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

Примечание: Для развёртываний с выходом в интернет настоятельно рекомендуется использовать обратный прокси для добавления HTTPS. В этом случае также измените "4000:4000/tcp" на "127.0.0.1:4000:4000/tcp" в docker-compose.yml, чтобы предотвратить прямой доступ к незашифрованному порту.

Попробуйте в Playground:

В панели администратора нажмите Playground в левом меню. Выберите локальную модель (например, ollama/llama3.2:3b) из выпадающего списка и начните общаться — это быстрый способ убедиться, что локальная языковая модель работает сквозным образом.

Настройка

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

Сервис Env-файл Репозиторий
Ollama ollama.env docker-ollama
LiteLLM litellm.env docker-litellm
MCP Gateway mcp.env docker-mcp-gateway
Embeddings embed.env docker-embeddings

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

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

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

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

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

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

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

docker compose pull
docker compose up -d

Ваши данные сохраняются в 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 уже задана, все сервисы подключаются автоматически.

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

# Получение API-ключей
LITELLM_KEY=$(docker exec litellm litellm_manage --getkey)
MCP_KEY=$(docker exec mcp mcp_manage --showkey | grep '^mcp-' | head -1)

# Используйте с 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" \
    -d '{"input": "function to handle authentication", "model": "text-embedding-ada-002"}' \
    | jq '.data[0].embedding[:5]'