PTah
533 lines
18 KiB
Markdown
533 lines
18 KiB
Markdown
# OpenClaude + Local LLM Handbook
|
||
|
||
Практическая документация по запуску `openclaude` на сервере, подключению локальных и облачных моделей, работе с MCP/RAG и планированию железа под разные бюджеты.
|
||
|
||
## 1) Что такое LLM и токены
|
||
|
||
- **LLM (Large Language Model)** - большая языковая модель, которая генерирует текст токен за токеном.
|
||
- **Токен** - кусок текста (слово, часть слова, знак, пробел), не всегда "целое слово".
|
||
- **Скорость 1-5 токенов/с** - скорость генерации ответа моделью (decode speed).
|
||
- Очень грубо: `5 ток/с` часто ощущается как `~15-25 символов/с`, но это зависит от языка и модели.
|
||
|
||
## 2) Что такое MCP и зачем он нужен
|
||
|
||
**MCP (Model Context Protocol)** - стандарт для подключения инструментов и источников данных к AI-агенту.
|
||
|
||
Простая схема:
|
||
|
||
- Модель = "мозг"
|
||
- MCP-сервер = "шлюз к инструментам"
|
||
- MCP-инструменты = конкретные действия (`search_docs`, `run_sql`, `create_ticket` и т.д.)
|
||
|
||
Польза MCP:
|
||
|
||
- Подключение к актуальным данным (документы, БД, API)
|
||
- Контролируемое выполнение действий через схемы входа/выхода
|
||
- Повторяемая интеграция для локальных и облачных сценариев
|
||
|
||
## 3) Основные сценарии работы OpenClaude
|
||
|
||
`openclaude` поддерживает разные провайдеры, включая:
|
||
|
||
- OpenAI-compatible API
|
||
- Ollama (локально)
|
||
- DeepSeek (через OpenAI-compatible endpoint)
|
||
- Gemini, GitHub Models, Codex и др.
|
||
|
||
## 4) Быстрый запуск OpenClaude
|
||
|
||
### 4.0 Предварительные требования
|
||
|
||
Для любого сценария нужны **Node.js 18+** и **npm** (идут вместе с официальной сборкой Node).
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
node -v
|
||
npm -v
|
||
```
|
||
|
||
Дальше по шагам:
|
||
|
||
1. установить **OpenClaude CLI** (раздел **4.1**);
|
||
2. для **локальных** моделей через Ollama — установить и запустить **Ollama** (раздел **4.2**), затем профиль из **4.3**;
|
||
3. для облака (OpenAI / DeepSeek) достаточно ключей API — см. **4.4** и **4.5**.
|
||
|
||
Если при запуске OpenClaude появится предупреждение вроде `ripgrep not found`, установите **ripgrep** (`rg`) и проверьте `rg --version` в том же терминале.
|
||
|
||
### 4.1 Установка OpenClaude
|
||
|
||
```bash
|
||
npm install -g @gitlawb/openclaude
|
||
openclaude --version
|
||
```
|
||
|
||
### 4.2 Установка и запуск Ollama (для локального профиля)
|
||
|
||
Сайт проекта: [https://ollama.com](https://ollama.com)
|
||
|
||
**Linux** (типовой скрипт установки):
|
||
|
||
```bash
|
||
curl -fsSL https://ollama.com/install.sh | sh
|
||
```
|
||
|
||
После установки сервис часто уже включён (`systemctl status ollama`). При необходимости: `sudo systemctl enable --now ollama`.
|
||
|
||
**macOS** (Homebrew):
|
||
|
||
```bash
|
||
brew install --cask ollama
|
||
```
|
||
|
||
**Windows**: установщик с [страницы загрузки](https://ollama.com/download) или:
|
||
|
||
```powershell
|
||
winget install Ollama.Ollama
|
||
```
|
||
|
||
Проверка CLI:
|
||
|
||
```bash
|
||
ollama --version
|
||
```
|
||
|
||
Убедитесь, что API доступен на `http://127.0.0.1:11434` (на Windows приложение после установки обычно уже поднимает сервер; при сомнении запустите `ollama serve` в отдельном окне терминала).
|
||
|
||
Скачайте хотя бы одну модель для работы с OpenClaude (пример ниже совпадает с профилем в **4.3**):
|
||
|
||
```bash
|
||
ollama pull qwen2.5-coder:7b
|
||
```
|
||
|
||
Быстрая проверка генерации:
|
||
|
||
```bash
|
||
ollama run qwen2.5-coder:7b
|
||
```
|
||
|
||
### 4.3 Локальный Ollama-профиль (бесплатно)
|
||
|
||
macOS / Linux:
|
||
|
||
```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
|
||
```
|
||
|
||
Windows PowerShell:
|
||
|
||
```powershell
|
||
$env:CLAUDE_CODE_USE_OPENAI="1"
|
||
$env:OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
|
||
$env:OPENAI_MODEL="qwen2.5-coder:7b"
|
||
|
||
openclaude
|
||
```
|
||
|
||
Альтернатива без ручных переменных (если установлен Ollama и доступна команда `ollama launch`):
|
||
|
||
```bash
|
||
ollama launch openclaude --model qwen2.5-coder:7b
|
||
```
|
||
|
||
### 4.4 OpenAI-профиль
|
||
|
||
macOS / Linux:
|
||
|
||
```bash
|
||
export CLAUDE_CODE_USE_OPENAI=1
|
||
export OPENAI_API_KEY=sk-...
|
||
export OPENAI_MODEL=gpt-4o
|
||
openclaude
|
||
```
|
||
|
||
Windows PowerShell:
|
||
|
||
```powershell
|
||
$env:CLAUDE_CODE_USE_OPENAI="1"
|
||
$env:OPENAI_API_KEY="sk-..."
|
||
$env:OPENAI_MODEL="gpt-4o"
|
||
|
||
openclaude
|
||
```
|
||
|
||
### 4.5 DeepSeek-профиль
|
||
|
||
macOS / Linux:
|
||
|
||
```bash
|
||
export CLAUDE_CODE_USE_OPENAI=1
|
||
export OPENAI_BASE_URL=https://api.deepseek.com/v1
|
||
export OPENAI_API_KEY=sk-...
|
||
export OPENAI_MODEL=deepseek-chat
|
||
openclaude
|
||
```
|
||
|
||
Windows PowerShell:
|
||
|
||
```powershell
|
||
$env:CLAUDE_CODE_USE_OPENAI="1"
|
||
$env:OPENAI_BASE_URL="https://api.deepseek.com/v1"
|
||
$env:OPENAI_API_KEY="sk-..."
|
||
$env:OPENAI_MODEL="deepseek-chat"
|
||
|
||
openclaude
|
||
```
|
||
|
||
## 5) Локальные бесплатные модели: где брать и что ставить
|
||
|
||
### Где брать
|
||
|
||
- Проще всего через `Ollama`: [https://ollama.com/library](https://ollama.com/library)
|
||
|
||
### Рекомендуемый старт
|
||
|
||
- `qwen2.5-coder:7b` - хороший баланс для кода
|
||
- `qwen2.5:3b` - если сервер слабый
|
||
- `llama3.1:8b` - универсальный сильный baseline
|
||
- `deepseek-r1:8b` - reasoning-ориентированный вариант
|
||
|
||
### Команды
|
||
|
||
```bash
|
||
ollama pull qwen2.5-coder:7b
|
||
ollama pull qwen2.5:3b
|
||
ollama pull llama3.1:8b
|
||
ollama pull deepseek-r1:8b
|
||
ollama list
|
||
```
|
||
|
||
## 6) Важный вопрос: локальные модели "дообучаются сами"?
|
||
|
||
Короткий ответ: **нет**.
|
||
|
||
- Обычная работа в чате не дообучает модель автоматически.
|
||
- Качество повышают обычно так:
|
||
- обновляют модель/тег (`ollama pull ...`)
|
||
- улучшают системные промпты
|
||
- подключают RAG (документы + retrieval)
|
||
- Полноценный finetune/LoRA - отдельный ML-процесс.
|
||
|
||
## 7) Профили и переключение через direnv
|
||
|
||
### 7.1 Профили
|
||
|
||
Создать:
|
||
|
||
```bash
|
||
mkdir -p ~/.config/openclaude/profiles
|
||
```
|
||
|
||
`~/.config/openclaude/profiles/local.env`
|
||
|
||
```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
|
||
unset OPENAI_API_KEY
|
||
```
|
||
|
||
`~/.config/openclaude/profiles/openai.env`
|
||
|
||
```bash
|
||
export CLAUDE_CODE_USE_OPENAI=1
|
||
export OPENAI_BASE_URL=https://api.openai.com/v1
|
||
export OPENAI_API_KEY=sk-REPLACE_ME
|
||
export OPENAI_MODEL=gpt-4o
|
||
```
|
||
|
||
`~/.config/openclaude/profiles/deepseek.env`
|
||
|
||
```bash
|
||
export CLAUDE_CODE_USE_OPENAI=1
|
||
export OPENAI_BASE_URL=https://api.deepseek.com/v1
|
||
export OPENAI_API_KEY=sk-REPLACE_ME
|
||
export OPENAI_MODEL=deepseek-chat
|
||
```
|
||
|
||
Права:
|
||
|
||
```bash
|
||
chmod 600 ~/.config/openclaude/profiles/*.env
|
||
```
|
||
|
||
### 7.2 Установка direnv
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install -y direnv
|
||
```
|
||
|
||
Для bash:
|
||
|
||
```bash
|
||
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
```
|
||
|
||
Для zsh:
|
||
|
||
```bash
|
||
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
|
||
source ~/.zshrc
|
||
```
|
||
|
||
### 7.3 Автопрофиль на папку проекта
|
||
|
||
В корне проекта:
|
||
|
||
```bash
|
||
cat > .envrc <<'EOF'
|
||
source_env ~/.config/openclaude/profiles/local.env
|
||
EOF
|
||
direnv allow
|
||
```
|
||
|
||
На **Windows** нативный `direnv` используют реже; задайте переменные в текущей сессии PowerShell через `$env:ИМЯ="значение"`, добавьте их в профиль PowerShell, либо работайте в **WSL** и следуйте Linux-инструкциям выше.
|
||
|
||
## 8) Минимальный RAG стек (локально)
|
||
|
||
### Что такое RAG
|
||
|
||
**RAG (Retrieval-Augmented Generation)** — подход, при котором модель отвечает не только из «общих» весов, а **сначала находит релевантные фрагменты в ваших данных** (документы, база знаний, код), подмешивает их в контекст и уже тогда формулирует ответ.
|
||
|
||
### Из чего состоит RAG-стек
|
||
|
||
1. **Документы** — `md` / `pdf` / `txt`, wiki, выгрузки и т.д.
|
||
2. **Chunking** — разбиение текста на фрагменты фиксированного размера с перекрытием.
|
||
3. **Embeddings** — векторное представление каждого фрагмента.
|
||
4. **Vector DB** — хранение векторов и поиск ближайших соседей по запросу.
|
||
5. **Retriever** — например MCP-инструмент `search_docs`: достаёт релевантный контекст по вопросу пользователя.
|
||
6. **LLM** — генерирует ответ с учётом найденного контекста (и при желании с явными ссылками на источники).
|
||
|
||
Плюсы такого контура:
|
||
|
||
- ответы опираются на **ваши** материалы;
|
||
- обычно **меньше голых галлюцинаций** по фактам из документации;
|
||
- проще **проверять происхождение** ответа (по найденным чанкам и источникам).
|
||
|
||
### Минимальная локальная конфигурация (этот репозиторий)
|
||
|
||
Рекомендуемая база:
|
||
|
||
- Embeddings: `nomic-embed-text` (через Ollama)
|
||
- Vector DB: Qdrant
|
||
- Retrieval tool: MCP `search_docs`
|
||
|
||
Готовый пример скриптов и compose: `docs/rag-mcp-starter/`.
|
||
|
||
Минимальная схема:
|
||
|
||
1. Сложить документы (`md/txt/pdf`)
|
||
2. Разбить на чанки (`chunk_size ~1000`, overlap `~120`)
|
||
3. Сделать embeddings
|
||
4. Записать в Qdrant
|
||
5. Поднять MCP-инструмент `search_docs`
|
||
6. Вызывать его из OpenClaude
|
||
|
||
## 9) Быстрый чек-лист, если MCP "не виден"
|
||
|
||
1. MCP-сервер стартует вручную:
|
||
|
||
```bash
|
||
python mcp_server.py
|
||
```
|
||
|
||
2. Импорты и зависимости установлены:
|
||
|
||
```bash
|
||
python -c "import fastmcp, qdrant_client, requests; print('ok')"
|
||
```
|
||
|
||
3. Пути в `~/.claude/settings.json` корректны (`command`, `args`)
|
||
4. Qdrant доступен: `curl http://127.0.0.1:6333/collections`
|
||
5. Ollama доступен: `curl http://127.0.0.1:11434/api/tags`
|
||
|
||
## 10) План закупки железа под 3 бюджета
|
||
|
||
Ориентиры даны для Linux-сервера и локального запуска LLM (Ollama/OpenAI-compatible).
|
||
|
||
### Бюджет A: Минимальный (CPU-only)
|
||
|
||
**Для кого:** старт, RAG, базовые задачи, без требований к высокой скорости.
|
||
|
||
- CPU: 8-12 vCPU (современные ядра)
|
||
- RAM: 32 GB (минимум 16 GB, но хуже)
|
||
- Disk: NVMe 512 GB
|
||
- GPU: нет
|
||
|
||
Ожидания:
|
||
|
||
- модели 3B-7B с умеренной скоростью
|
||
- ориентир decode: примерно `1-6 ток/с` (зависит от модели и квантизации)
|
||
|
||
Рекомендованные модели:
|
||
|
||
- `qwen2.5:3b`
|
||
- `qwen2.5-coder:7b` (если хватает RAM/терпения)
|
||
|
||
### Бюджет B: Комфортный (1x GPU среднего класса)
|
||
|
||
**Для кого:** ежедневная работа 1-3 пользователей, код + RAG в комфортном режиме.
|
||
|
||
- CPU: 8-16 vCPU
|
||
- RAM: 32-64 GB
|
||
- GPU: 1x NVIDIA 12-16 GB VRAM (например, RTX 3060 12GB / 4070 Ti Super 16GB)
|
||
- Disk: NVMe 1 TB
|
||
|
||
Ожидания:
|
||
|
||
- стабильная работа 7B/8B, лучше latency и throughput
|
||
- ориентир decode: примерно `10-35 ток/с`
|
||
|
||
Рекомендованные модели:
|
||
|
||
- `qwen2.5-coder:7b`
|
||
- `llama3.1:8b`
|
||
- `deepseek-r1:8b`
|
||
|
||
### Бюджет C: Производительный (1-2 GPU высокого класса)
|
||
|
||
**Для кого:** команда, многозадачность, более тяжелые модели и высокая отзывчивость.
|
||
|
||
- CPU: 16+ vCPU
|
||
- RAM: 64-128 GB
|
||
- GPU:
|
||
- вариант 1: 1x NVIDIA 24 GB VRAM (RTX 4090 / L40-class по бюджету)
|
||
- вариант 2: 2x GPU по 16-24 GB для масштабирования
|
||
- Disk: NVMe 2 TB
|
||
|
||
Ожидания:
|
||
|
||
- уверенная работа 14B+ (квантизованные), параллельные запросы
|
||
- ориентир decode: `25-80+ ток/с` в зависимости от модели/батча
|
||
|
||
Рекомендованные модели:
|
||
|
||
- 14B-класс инструкт/кодовые варианты
|
||
- mix моделей: одна "быстрая дешевая", одна "качественная тяжелая"
|
||
|
||
### Что критично кроме железа
|
||
|
||
- стабильная версия драйверов CUDA (если NVIDIA)
|
||
- быстрый NVMe (модели занимают много места)
|
||
- мониторинг температуры/памяти/IO
|
||
- резерв свободного диска под новые веса
|
||
|
||
## 11) Практика обновления и обслуживания моделей
|
||
|
||
- Смотреть установленные:
|
||
|
||
```bash
|
||
ollama list
|
||
```
|
||
|
||
- Обновлять нужные:
|
||
|
||
```bash
|
||
ollama pull qwen2.5-coder:7b
|
||
```
|
||
|
||
- Удалять старые:
|
||
|
||
```bash
|
||
ollama rm <model:tag>
|
||
```
|
||
|
||
- Проверять занятое место:
|
||
|
||
```bash
|
||
sudo du -h --max-depth=2 /usr/share/ollama /var/lib/ollama 2>/dev/null | sort -h | tail -n 30
|
||
```
|
||
|
||
## 12) Подключение к GitHub и PAT (без постоянных запросов пароля)
|
||
|
||
### 12.1 Рекомендуемый путь через GitHub CLI
|
||
|
||
```bash
|
||
gh auth login
|
||
gh auth status
|
||
```
|
||
|
||
Это самый удобный вариант для GitHub: авторизация один раз и нормальная работа `git pull/push` и `gh`.
|
||
|
||
Если **`gh repo view`** или API в другой среде (CI, удалённый агент) возвращают ошибку про отсутствие репозитория, хотя у вас локально всё ок — см. пояснение в `docs/openclaude-with-repositories.md` (раздел «Частые ошибки», подраздел про GitHub CLI).
|
||
|
||
### 12.2 Через PAT по HTTPS
|
||
|
||
1. Создать Personal Access Token на GitHub (минимальные нужные scopes).
|
||
2. Проверить, что remote в HTTPS:
|
||
|
||
```bash
|
||
git remote -v
|
||
git remote set-url origin https://github.com/OWNER/REPO.git
|
||
```
|
||
|
||
3. Включить credential helper, чтобы не вводить PAT каждый раз:
|
||
|
||
```bash
|
||
git config --global credential.helper store
|
||
```
|
||
|
||
4. Выполнить `git pull` или `git push` и один раз ввести логин + PAT.
|
||
|
||
### 12.3 Через SSH (альтернатива PAT)
|
||
|
||
```bash
|
||
ssh-keygen -t ed25519 -C "you@example.com"
|
||
# Добавьте публичный ключ в GitHub account settings
|
||
git remote set-url origin git@github.com:OWNER/REPO.git
|
||
```
|
||
|
||
SSH обычно удобнее для постоянной работы с приватными репозиториями.
|
||
|
||
## 13) Частые проблемы и быстрые фиксы
|
||
|
||
### 13.1 Скрипт запуска падает с `#!/usr/bin/env: No such file or directory`
|
||
|
||
Причина: BOM в начале файла.
|
||
|
||
Фикс:
|
||
|
||
```bash
|
||
sed -i '1s/^\xEF\xBB\xBF//' script.sh
|
||
chmod +x script.sh
|
||
```
|
||
|
||
### 13.2 Почему после выбора зеркала apt все еще ходит в `ru.archive.ubuntu.com`
|
||
|
||
Обычно источники лежат в `*.sources` (deb822), а не только в `sources.list`.
|
||
Нужно менять и `URIs:` в deb822-блоках.
|
||
|
||
---
|
||
|
||
## Roadmap продолжения
|
||
|
||
Когда вернемся к теме, логично идти так:
|
||
|
||
1. Проверка текущего сервера (CPU/RAM/GPU/NVMe)
|
||
2. Выбор стартового профиля (`local`/`openai`/`deepseek`)
|
||
3. Поднятие `openclaude` + smoke test
|
||
4. Запуск минимального RAG с Qdrant
|
||
5. Добавление MCP-инструментов под ваши рабочие данные
|
||
6. Оптимизация скорости и стоимости (routing между моделями)
|
||
|
||
## Дополнительные материалы в репозитории
|
||
|
||
- Быстрый гайд: `docs/quickstart-30min.md`
|
||
- Точка входа: `docs/START-HERE.md`
|
||
- Готовый starter: `docs/rag-mcp-starter/`
|
||
- Работа с GitHub/GitLab/Gitea: `docs/openclaude-with-repositories.md`
|
||
- Подробно про SSH к GitHub: `docs/github-ssh-setup-and-troubleshooting.md`
|
||
- Примеры cron-автоматизации: `docs/cron-examples.md`
|
||
- Автоустановка cron: `scripts/install-cron.sh`
|
||
- Каталог моделей: `docs/model-catalog.md`
|
||
- Выбор runtime: `docs/runtime-choice.md`
|
||
- Локальный Cursor-like стек: `docs/cursor-like-stack.md`
|
||
- Честные ожидания: `docs/expectations.md`
|
||
- Шаблон benchmark: `docs/bench-template.md`
|
||
- Локальная генерация изображений: `docs/image-generation-local.md`
|