Skip to content

README-ru.md

Latest commit

 

History

History
450 lines (339 loc) · 28.2 KB

README-ru.md

File metadata and controls

450 lines (339 loc) · 28.2 KB
Raw

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

Docker AI Stack

Docker Compose AI Stack  Docker Pulls  Лицензия: MIT

Docker AI Stack: разверните полный self-hosted AI-стек одной командой

Включает Ollama, LiteLLM, AnythingLLM, Whisper, MCP Gateway, Embeddings, Docling и Kokoro — полностью сконфигурирован и готов к запуску с Docker Compose.

  • Без настройки: все сервисы автоматически конфигурируются при первом запуске
  • Безопасность: Ollama, LiteLLM и MCP Gateway автоматически генерируют API-ключи
  • Приватность: по умолчанию работает локально с опциональной поддержкой внешних провайдеров через LiteLLM
  • Опциональная авторизация: Whisper, WhisperLive, Kokoro, Embeddings и Docling работают без API-ключей по умолчанию (задайте ключи через env-файлы для публичных развёртываний)
  • Облегчённые стеки с меньшими требованиями к памяти (от ~4.5 ГБ)
  • GPU-ускорение через NVIDIA CUDA
  • Мультиархитектурность: linux/amd64, linux/arm64

Сообщество

  • 📬 Подписаться на обновления проектов (1–2 письма в месяц) — получить бесплатные руководства по развёртыванию AI и VPN (PDF, на английском)
  • 💬 Присоединяйтесь к сообществу r/selfhostedstack для обсуждений и демонстрации проектов
  • ⭐ Поставьте звезду репозиторию, если Docker AI Stack вам полезен

Docker AI Stack поддерживается автором Setup IPsec VPN (27k+ звёзд).

Включённые сервисы

Сервис Назначение Порт по умолчанию
Ollama (LLM) Запуск локальных LLM-моделей (llama3, qwen, mistral и др.) 11434
AnythingLLM Веб-чат — работает мгновенно без входа в систему 3001
LiteLLM AI-шлюз — маршрутизация запросов к Ollama, OpenAI, Anthropic и 100+ провайдерам 4000
Embeddings Преобразование текста в векторы для семантического поиска и RAG 8000
Whisper (STT) Транскрибация речи в текст 9000
WhisperLive (STT в реальном времени) Транскрибация речи в реальном времени через WebSocket 9090
Kokoro (TTS) Преобразование текста в естественную речь 8880
MCP Gateway Предоставление MCP-инструментов (файловая система, веб, GitHub, поиск, базы данных) AI-клиентам 3000
Docling Конвертирует документы (PDF, DOCX и др.) в структурированный текст/Markdown 5001

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

Требования:

  • Linux-сервер (локальный или облачный) с установленным Docker
  • Минимум 8 ГБ оперативной памяти (с небольшими моделями). Для крупных LLM-моделей (8B+) рекомендуется 16 ГБ и более.
  • Вы можете закомментировать ненужные сервисы для уменьшения потребления памяти.

Запуск полного стека:

# Клонируйте репозиторий для получения compose-файлов
git clone https://github.com/hwdsl2/docker-ai-stack
cd docker-ai-stack
docker compose up -d

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

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

Проверьте логи для подтверждения готовности всех сервисов:

docker compose logs

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

./stack-check.sh

Получение API-ключей:

# API-ключ Ollama
docker exec ollama ollama_manage --showkey

# API-ключ LiteLLM
docker exec litellm litellm_manage --showkey

# API-ключ MCP Gateway
docker exec mcp mcp_manage --showkey

Доступ к AnythingLLM (чат-интерфейс):

Откройте http://<server-ip>:3001 в браузере. AnythingLLM предварительно настроен для подключения к локальной языковой модели через LiteLLM — вход или настройка не требуются. Начните общаться сразу.

Примечание: При первом запуске AnythingLLM может потребоваться несколько минут для готовности (ожидание API-ключа LiteLLM). Проверяйте прогресс командой docker logs anythingllm.

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

Доступ к панели администратора 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) из выпадающего списка и начните общаться — это быстрый способ убедиться, что локальная языковая модель работает сквозным образом.

Остановка стека:

docker compose down

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.

Облегчённые стеки

Не нужен полный стек? Используйте преднастроенное подмножество из папки stacks/:

Стек Сервисы Память Сценарий использования
chat-ui Ollama + LiteLLM + AnythingLLM ~5 ГБ Веб-интерфейс для чата в стиле ChatGPT
voice-pipeline Whisper + Ollama + LiteLLM + Kokoro ~6 ГБ Речь в текст → LLM → текст в речь
voice-chat Whisper + Ollama + LiteLLM + Kokoro + AnythingLLM ~6.5 ГБ Чат-интерфейс с голосовым вводом/выводом
rag-pipeline Ollama + LiteLLM + Embeddings ~5 ГБ Семантический поиск + LLM Q&A
rag-pipeline-full Ollama + LiteLLM + Embeddings + Docling ~6 ГБ Разбор документов + семантический поиск + LLM Q&A
code-assistant Ollama + LiteLLM + MCP Gateway + Embeddings ~5 ГБ AI-разработка с инструментами + семантический поиск по коду
ai-tools Ollama + LiteLLM + MCP Gateway ~5 ГБ AI-ассистент для разработки с доступом к инструментам
chat-only Ollama + LiteLLM ~4.5 ГБ Минимальная локальная замена ChatGPT 
git clone https://github.com/hwdsl2/docker-ai-stack
cd docker-ai-stack/stacks/chat-ui  # или voice-pipeline, voice-chat, rag-pipeline, rag-pipeline-full, code-assistant, ai-tools, chat-only
docker compose up -d

Архитектура

graph LR
    A["🎤 Аудиовход"] -->|транскрибация| W["Whisper<br/>(речь в текст)"]
    D["📄 Документы"] -->|разбор| DC["Docling<br/>(документ → текст)"]
    DC -->|эмбеддинг| E["Embeddings<br/>(текст → векторы)"]
    E -->|хранение| VDB["Внешняя векторная база данных<br/>(Qdrant, Chroma)"]
    W -->|запрос| E
    VDB -->|контекст| L["LiteLLM<br/>(AI-шлюз)"]
    W -->|текст| L
    L -->|маршрутизация| O["Ollama<br/>(локальная LLM)"]
    L -->|ответ| T["Kokoro TTS<br/>(текст в речь)"]
    T --> B["🔊 Аудиовыход"]
    C["🤖 AI-клиент<br/>(Cline, Claude и др.)"] -->|MCP-инструменты| M["MCP Gateway<br/>(MCP-эндпоинт)"]
    C -->|чат| L
    L -->|MCP-протокол| M
    U["👤 Пользователь"] -->|чат| AN["AnythingLLM<br/>(чат-интерфейс)"]
    AN -->|запросы к LLM| L
    AN -->|MCP-инструменты| M
    U -->|использует| C
    U -->|говорит| A
    U -->|загружает| D
Loading

Примечания:

  • Порт Ollama (11434) и порт MCP Gateway (3000) доступны только внутри сети Docker и не открыты на хосте по умолчанию. Доступ к LLM осуществляется через LiteLLM на порту 4000.
  • Для снижения потребления памяти сервисы Kokoro (TTS), Docling (парсинг документов) и WhisperLive (распознавание речи в реальном времени) по умолчанию отключены. Чтобы включить их, раскомментируйте соответствующие сервисы в docker-compose.yml.

Запуск без 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

# 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 \
    -v litellm-shared:/var/lib/litellm-shared \
    hwdsl2/litellm-server

# 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

# Whisper (STT)
docker run -d --name whisper --restart always \
    --network ai-stack \
    -p 127.0.0.1:9000:9000 \
    -v whisper-data:/var/lib/whisper \
    hwdsl2/whisper-server

# WhisperLive (real-time STT)
docker run -d --name whisper-live --restart always \
    --network ai-stack \
    -p 127.0.0.1:9090:9090 \
    -v whisper-live-data:/var/lib/whisper-live \
    hwdsl2/whisper-live-server

# AnythingLLM (чат-интерфейс)
docker run -d --name anythingllm --restart always \
    --network ai-stack \
    -p 3001:3001 \
    -e STORAGE_DIR=/app/server/storage \
    -e LLM_PROVIDER=generic-openai \
    -e GENERIC_OPEN_AI_BASE_PATH=http://litellm:4000/v1 \
    -e GENERIC_OPEN_AI_MODEL_PREF=ollama/llama3.2:3b \
    -e GENERIC_OPEN_AI_MODEL_TOKEN_LIMIT=131072 \
    -e EMBEDDING_ENGINE=native \
    -e DISABLE_TELEMETRY=true \
    -v anythingllm-data:/app/server/storage \
    -v litellm-shared:/var/lib/litellm-shared:ro \
    -v "$(pwd)/chat-ui-bootstrap.sh:/usr/local/bin/chat-ui-bootstrap.sh:ro" \
    --entrypoint /bin/bash \
    mintplexlabs/anythingllm \
    /usr/local/bin/chat-ui-bootstrap.sh

# Kokoro (TTS)
docker run -d --name kokoro --restart always \
    --network ai-stack \
    -p 127.0.0.1:8880:8880 \
    -v kokoro-data:/var/lib/kokoro \
    hwdsl2/kokoro-server

# Docling (разбор документов)
docker run -d --name docling --restart always \
    --network ai-stack \
    -p 127.0.0.1:5001:5001 \
    -v docling-data:/var/lib/docling \
    hwdsl2/docling-server

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

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

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

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

В compose-файлах этого репозитория LiteLLM и MCP Gateway подключаются автоматически — ручная настройка ключей не требуется.

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

  • Ollama генерирует API-ключ при первом запуске и копирует его в общий том
  • MCP Gateway делает то же самое
  • LiteLLM считывает оба ключа из общих томов при запуске

Переменные LITELLM_MCP_URL=http://mcp:3000/mcp и LITELLM_OLLAMA_BASE_URL=http://ollama:11434 уже заданы в compose-файлах, поэтому все сервисы подключаются автоматически одной командой docker compose up -d.

После подключения AI-клиенты, обращающиеся к LiteLLM, смогут использовать MCP-инструменты (файловая система, web-fetch, GitHub и др.) напрямую через прокси LiteLLM.

Пример голосового конвейера

Транскрибируйте голосовой вопрос, получите ответ от локальной LLM через Ollama и преобразуйте его в речь:

Примечание: Kokoro (TTS) отключён по умолчанию. Чтобы использовать этот пример, сначала раскомментируйте сервис kokoro в файле docker-compose.yml, затем выполните docker compose up -d.

Совет: Нужен образец аудиофайла? Скачайте этот образец английской речи (WAV, лицензия MIT) из репозитория Azure Samples:

curl -L -o sample_speech.wav \
    "https://github.com/Azure-Samples/cognitive-services-speech-sdk/raw/master/sampledata/audiofiles/katiesteve.wav"
LITELLM_KEY=$(docker exec litellm litellm_manage --getkey)

# Шаг 1: Транскрибация аудио в текст (Whisper)
TEXT=$(curl -s http://localhost:9000/v1/audio/transcriptions \
    -F file=@sample_speech.wav -F model=whisper-1 | jq -r .text)

# Шаг 2: Отправка текста в Ollama через LiteLLM и получение ответа
RESPONSE=$(curl -s http://localhost:4000/v1/chat/completions \
    -H "Authorization: Bearer $LITELLM_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"ollama/llama3.2:3b\",\"messages\":[{\"role\":\"user\",\"content\":\"$TEXT\"}]}" \
    | jq -r '.choices[0].message.content')

# Шаг 3: Преобразование ответа в речь (Kokoro TTS)
curl -s http://localhost:8880/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"tts-1\",\"input\":\"$RESPONSE\",\"voice\":\"af_heart\"}" \
    --output response.mp3

Пример RAG-конвейера

Создание эмбеддингов документов для семантического поиска, извлечение контекста и ответы на вопросы с помощью локальной модели Ollama:

LITELLM_KEY=$(docker exec litellm litellm_manage --getkey)

# Шаг 1: Создание эмбеддинга фрагмента документа и сохранение вектора в векторной БД
curl -s http://localhost:8000/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{"input": "Docker simplifies deployment by packaging apps in containers.", "model": "text-embedding-ada-002"}' \
    | jq '.data[0].embedding'
# → Сохраните возвращённый вектор вместе с исходным текстом в Qdrant, Chroma, pgvector и т.д.

# Шаг 2: При запросе создайте эмбеддинг вопроса, извлеките наиболее релевантные фрагменты
#          из векторной БД, затем отправьте вопрос и контекст в Ollama через LiteLLM.
curl -s http://localhost:4000/v1/chat/completions \
    -H "Authorization: Bearer $LITELLM_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "ollama/llama3.2:3b",
      "messages": [
        {"role": "system", "content": "Answer using only the provided context."},
        {"role": "user", "content": "What does Docker do?\n\nContext: Docker simplifies deployment by packaging apps in containers."}
      ]
    }' \
    | jq -r '.choices[0].message.content'

Пример MCP-инструментов

Используйте MCP Gateway для предоставления AI-ассистенту доступа к файлам, вебу и GitHub:

MCP_KEY=$(docker exec mcp mcp_manage --showkey | grep '^mcp-' | head -1)

# Используйте MCP-эндпоинт с AI-клиентом (например, Cline в VS Code)
# URL MCP-сервера: http://localhost:3000/mcp
# Заголовок Authorization: Bearer <api_key>

# Или протестируйте MCP-эндпоинт напрямую
curl -s http://localhost:3000/mcp \
    -X POST \
    -H "Authorization: Bearer $MCP_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Настройка

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

Сервис Env-файл Репозиторий
Ollama ollama.env docker-ollama
LiteLLM litellm.env docker-litellm
Embeddings embed.env docker-embeddings
Whisper whisper.env docker-whisper
WhisperLive whisper-live.env docker-whisper-live
Kokoro kokoro.env docker-kokoro
MCP Gateway mcp.env docker-mcp-gateway
Docling docling.env docker-docling

AnythingLLM настраивается через веб-интерфейс по адресу http://<IP-сервера>:3001. Вы можете изменить провайдера LLM, модель, движок эмбеддингов и другие параметры в разделе Settings. Подробнее см. документацию AnythingLLM.

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

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

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

При открытии сервисов в интернет установите API-ключи для сервисов с опциональной авторизацией (Whisper, WhisperLive, Kokoro, Embeddings, Docling) через соответствующие env-файлы.

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

Ваши API-ключи, модели и конфигурация хранятся в Docker-томах. Создайте резервную копию перед обновлением или внесением изменений:

# Экспорт API-ключей (при работающих контейнерах)
docker exec ollama ollama_manage --showkey
docker exec litellm litellm_manage --showkey
docker exec mcp mcp_manage --showkey

# Резервное копирование всех томов (сначала остановите сервисы)
docker compose down
mkdir -p backups
for vol in ollama-data litellm-data litellm-db embeddings-data whisper-data whisper-live-data kokoro-data mcp-data docling-data anythingllm-data; do
  docker volume inspect "$vol" >/dev/null 2>&1 && \
    docker run --rm -v "${vol}:/source:ro" -v "$(pwd)/backups:/backup" \
      alpine tar czf "/backup/${vol}.tar.gz" -C /source .
done

Примечание: Тома ollama-shared, mcp-shared и litellm-shared являются временными томами для передачи ключей и не требуют резервного копирования.

Инструкции по восстановлению, миграции на новый сервер и полный контрольный список перед обновлением см. в руководстве Резервное копирование и восстановление.

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

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

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

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

Лицензия

Copyright (C) 2026 Lin Song
Данный проект лицензирован на условиях лицензии MIT.

Данный проект представляет собой независимую Docker-конфигурацию и не аффилирован с Ollama, Berri AI (LiteLLM), Hugging Face, hexgrad (Kokoro), OpenAI, SYSTRAN или MCPHub, не одобрен и не спонсирован ими.