Add OpenClaude local LLM deployment handbook.
Made-with: Cursor
This commit is contained in:
Andrey Lutsenko
@@ -0,0 +1,354 @@
|
||||
# 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.1 Установка
|
||||
|
||||
```bash
|
||||
npm install -g @gitlawb/openclaude
|
||||
```
|
||||
|
||||
### 4.2 Локальный Ollama-профиль (бесплатно)
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 4.3 OpenAI-профиль
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_OPENAI=1
|
||||
export OPENAI_API_KEY=sk-...
|
||||
export OPENAI_MODEL=gpt-4o
|
||||
openclaude
|
||||
```
|
||||
|
||||
### 4.4 DeepSeek-профиль
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## 8) Минимальный RAG стек (локально)
|
||||
|
||||
Рекомендуемая база:
|
||||
|
||||
- Embeddings: `nomic-embed-text` (через Ollama)
|
||||
- Vector DB: Qdrant
|
||||
- Retrieval tool: MCP `search_docs`
|
||||
|
||||
Минимальная схема:
|
||||
|
||||
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
|
||||
|
||||
Рекомендуемый вариант:
|
||||
|
||||
```bash
|
||||
gh auth login
|
||||
gh auth status
|
||||
```
|
||||
|
||||
Для HTTPS git credentials сохранять через credential helper (или использовать 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 между моделями)
|
||||
Reference in New Issue
Block a user