PTah
241 lines
7.9 KiB
Markdown
241 lines
7.9 KiB
Markdown
# OpenClaude + Local LLM: Quickstart 30 min
|
|
|
|
Короткий маршрут "с нуля до рабочего стенда" на Ubuntu.
|
|
|
|
Если вы на **Windows**, установите Ollama и Node.js локально, затем для запуска OpenClaude на локальной модели следуйте `docs/install-openclaude-cli.md` (блоки **PowerShell** и порядок шагов там же). Полный стек ниже (Docker, bash-скрипты, пути `~/...`) удобнее повторять в **WSL2** или на Linux-сервере с тем же репозиторием.
|
|
|
|
## 0) Что получится
|
|
|
|
- локальный LLM через Ollama
|
|
- `openclaude` в CLI
|
|
- локальный RAG-поиск через MCP (`search_docs`)
|
|
|
|
## 1) Установка зависимостей
|
|
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install -y curl git docker.io docker-compose-plugin python3 python3-venv python3-pip direnv
|
|
sudo systemctl enable docker
|
|
sudo systemctl start docker
|
|
```
|
|
|
|
Если на Ubuntu 24.04 вы видите ошибку `Unable to locate package docker-compose-plugin`, подключите официальный Docker APT-репозиторий и установите пакеты оттуда:
|
|
|
|
```bash
|
|
sudo rm -f /etc/apt/sources.list.d/docker.list
|
|
sudo rm -f /etc/apt/keyrings/docker.gpg
|
|
sudo apt update
|
|
sudo apt install -y ca-certificates curl gnupg
|
|
|
|
sudo install -m 0755 -d /etc/apt/keyrings
|
|
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
|
|
sudo chmod a+r /etc/apt/keyrings/docker.gpg
|
|
|
|
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
|
|
|
sudo apt update
|
|
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
|
docker compose version
|
|
```
|
|
|
|
## 2) Установка Ollama
|
|
|
|
Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `docs/install-openclaude-cli.md` (раздел про установку Ollama).
|
|
|
|
```bash
|
|
curl -fsSL https://ollama.com/install.sh | sh
|
|
sudo systemctl enable ollama
|
|
sudo systemctl start ollama
|
|
curl -s http://127.0.0.1:11434/api/tags
|
|
```
|
|
|
|
## 3) Установка OpenClaude
|
|
|
|
```bash
|
|
npm install -g @gitlawb/openclaude
|
|
```
|
|
|
|
Для очень слабого сервера можно использовать минимальный установщик:
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
chmod +x install-minimal.sh
|
|
./install-minimal.sh --model qwen2.5:3b
|
|
```
|
|
|
|
## 4) (Опционально) Хранить модели Ollama на втором диске
|
|
|
|
Если системный диск маленький, заранее перенесите путь хранения моделей (например, на `/mnt/data`).
|
|
|
|
```bash
|
|
sudo mkdir -p /mnt/data/ollama-models
|
|
sudo chown -R ollama:ollama /mnt/data/ollama-models
|
|
|
|
sudo mkdir -p /etc/systemd/system/ollama.service.d
|
|
sudo tee /etc/systemd/system/ollama.service.d/override.conf > /dev/null <<'EOF'
|
|
[Service]
|
|
Environment="OLLAMA_MODELS=/mnt/data/ollama-models"
|
|
EOF
|
|
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl restart ollama
|
|
systemctl show ollama -p Environment
|
|
```
|
|
|
|
После этого новые `ollama pull ...` будут сохраняться в `OLLAMA_MODELS`.
|
|
|
|
## 5) (Опционально) Перенести Docker data-root на второй диск
|
|
|
|
Если вы поднимаете Qdrant/контейнеры и хотите экономить системный диск, перенесите хранилище Docker (образы, volumes, слой контейнеров) на `/mnt/data/docker`.
|
|
|
|
```bash
|
|
docker info | grep "Docker Root Dir"
|
|
|
|
sudo systemctl stop docker
|
|
sudo systemctl stop docker.socket
|
|
|
|
sudo mkdir -p /mnt/data/docker
|
|
sudo chown root:root /mnt/data/docker
|
|
sudo chmod 711 /mnt/data/docker
|
|
|
|
sudo rsync -aHAXx --numeric-ids /var/lib/docker/ /mnt/data/docker/
|
|
|
|
sudo mkdir -p /etc/docker
|
|
sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
|
|
{
|
|
"data-root": "/mnt/data/docker"
|
|
}
|
|
EOF
|
|
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl start docker
|
|
docker info | grep "Docker Root Dir"
|
|
```
|
|
|
|
Ожидаемый результат: `Docker Root Dir: /mnt/data/docker`.
|
|
|
|
## 6) Скачать стартовые модели
|
|
|
|
```bash
|
|
ollama pull qwen2.5-coder:7b
|
|
ollama pull nomic-embed-text
|
|
ollama pull llava:7b
|
|
ollama pull minicpm-v
|
|
ollama pull qwen2.5vl
|
|
```
|
|
|
|
`llava` / `minicpm-v` / `qwen2.5vl` полезны для анализа картинок и OCR-сценариев (vision), а не для генерации изображений "с нуля". Для image generation смотрите `docs/free-graphical-models.md`.
|
|
|
|
## 7) Поднять Qdrant
|
|
|
|
**Qdrant** — это векторная база данных. В этом проекте она хранит embeddings (векторы) фрагментов ваших документов и быстро ищет наиболее похожие фрагменты по запросу пользователя.
|
|
|
|
Зачем он нужен в нашем контуре:
|
|
|
|
- `index.py` превращает текст документов в embeddings и записывает их в Qdrant;
|
|
- `mcp_server.py` при вызове `search_docs` ищет релевантные чанки в Qdrant;
|
|
- OpenClaude получает найденный контекст и отвечает уже на основе ваших данных (RAG), а не только на "общих знаниях" модели.
|
|
|
|
Без Qdrant связка RAG в текущем starter-стеке работать не будет.
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
docker compose up -d
|
|
curl -s http://127.0.0.1:6333/collections
|
|
```
|
|
|
|
## 8) Подготовить Python окружение
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install --upgrade pip
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## 9) Проиндексировать документы
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
mkdir -p docs
|
|
# Добавьте в docs/ файлы .md .txt .pdf
|
|
python index.py
|
|
```
|
|
|
|
## 10) Запустить MCP сервер
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
source .venv/bin/activate
|
|
python mcp_server.py
|
|
```
|
|
|
|
## 11) Подключить MCP в OpenClaude
|
|
|
|
Добавьте в `~/.claude/settings.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"local-rag": {
|
|
"command": "/home/USER/openclaude-LLM-local/docs/rag-mcp-starter/.venv/bin/python",
|
|
"args": ["/home/USER/openclaude-LLM-local/docs/rag-mcp-starter/mcp_server.py"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Замените `USER` на вашего пользователя.
|
|
|
|
## 12) Запуск OpenClaude на локальной модели
|
|
|
|
```bash
|
|
export CLAUDE_CODE_USE_OPENAI=1
|
|
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
|
|
export OPENAI_MODEL=qwen2.5-coder:7b
|
|
openclaude
|
|
```
|
|
|
|
Проверка в чате: попросите агента использовать `search_docs` по вашему запросу.
|
|
|
|
## 13) Проверка готовности стенда
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
chmod +x healthcheck.sh
|
|
./healthcheck.sh --mode full
|
|
```
|
|
|
|
## 14) Быстрый статус в одном экране
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
chmod +x status.sh
|
|
./status.sh
|
|
```
|
|
|
|
## 15) Бэкап перед обновлениями
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
chmod +x backup.sh
|
|
./backup.sh
|
|
```
|
|
|
|
## 16) Восстановление из бэкапа
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
chmod +x restore.sh
|
|
./restore.sh --from /path/to/backup_YYYYMMDD_HHMMSS
|
|
```
|
|
|
|
## 17) Безопасное обновление стенда
|
|
|
|
```bash
|
|
cd ~/openclaude-LLM-local/docs/rag-mcp-starter
|
|
chmod +x upgrade.sh
|
|
./upgrade.sh
|
|
```
|