PapaTramp/openclaude-LLM-local
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: split handbook into docs/ by topic, slim root README, add docs index

Browse Source 
Made-with: Cursor
This commit is contained in:
PTah
2026-04-21 15:37:43 +10:00
parent 25de357982
commit c589a216be
16 changed files with 713 additions and 524 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+25 -517
View File
@@ -1,532 +1,40 @@
# OpenClaude + Local LLM Handbook
Практическая документация по запуску `openclaude` на сервере, подключению локальных и облачных моделей, работе с MCP/RAG и планированию железа под разные бюджеты.
Репозиторий — **набор практических руководств** по запуску [OpenClaude](https://github.com/Gitlawb/openclaude) на своём железе, работе с **локальными и облачными** моделями, **MCP** и **RAG**, плюс пример минимального стека в `docs/rag-mcp-starter/`.
## 1) Что такое LLM и токены
Это **не** исходники OpenClaude: CLI ставится отдельно через npm (`@gitlawb/openclaude`). Сами гайды и скрипты вы клонируете отсюда.
- **LLM (Large Language Model)** - большая языковая модель, которая генерирует текст токен за токеном.
- **Токен** - кусок текста (слово, часть слова, знак, пробел), не всегда "целое слово".
- **Скорость 1-5 токенов/с** - скорость генерации ответа моделью (decode speed).
- Очень грубо: `5 ток/с` часто ощущается как `~15-25 символов/с`, но это зависит от языка и модели.
## Зачем этот репозиторий
## 2) Что такое MCP и зачем он нужен
- собрать **понятный путь от терминов до рабочего стенда** без пролистывания одного гигантского файла;
- держать **детали в `docs/`**, а в корне — только обзор и входные точки.
**MCP (Model Context Protocol)** - стандарт для подключения инструментов и источников данных к AI-агенту.
## С чего начать
Простая схема:
1. Коротко: **что это за проект vs CLI** → [docs/repository-and-cli.md](docs/repository-and-cli.md)
2. Полный указатель «**от простого к сложному**» → **[docs/README.md](docs/README.md)**
3. План по дням → [docs/START-HERE.md](docs/START-HERE.md)
4. Быстрый практический прогон (Ubuntu ~30 мин) → [docs/quickstart-30min.md](docs/quickstart-30min.md)
- Модель = "мозг"
- 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
git clone https://github.com/PTah/openclaude-LLM-local.git
cd openclaude-LLM-local
```
Дальше по шагам:
Если используете другой remote (fork), подставьте свой URL со страницы репозитория на GitHub.
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` в том же терминале.
| Тема | Документ |
|------|-----------|
| Термины (LLM, MCP, провайдеры) | [docs/concepts-and-terms.md](docs/concepts-and-terms.md) |
| Установка CLI, Ollama, профили | [docs/install-openclaude-cli.md](docs/install-openclaude-cli.md) |
| Локальные модели и `ollama` | [docs/local-llm-ollama.md](docs/local-llm-ollama.md) |
| RAG и MCP, чек-лист подключения | [docs/rag-mcp-stack.md](docs/rag-mcp-stack.md) |
| Пример стека (скрипты + compose) | [docs/rag-mcp-starter/](docs/rag-mcp-starter/) |
| GitHub / PAT / SSH | [docs/github-auth-remotes.md](docs/github-auth-remotes.md) |
| Железо под три бюджета | [docs/hardware-budgets.md](docs/hardware-budgets.md) |
### 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`
Остальные файлы перечислены в **[docs/README.md](docs/README.md)**.