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 + 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 ```bash
node -v git clone https://github.com/PTah/openclaude-LLM-local.git
npm -v 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 Остальные файлы перечислены в **[docs/README.md](docs/README.md)**.
```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
+100
View File
@@ -0,0 +1,100 @@
# Документация: навигация от простого к сложному
Этот каталог — основной вход: кратко **о чём репозиторий**, затем **термины**, далее **установка OpenClaude**, **локальные модели**, **RAG/MCP**, **эксплуатация**, **Git**, **железо и продвинутые темы**.
---
## 0. Что это за проект и где брать CLI
| Документ | О чём |
|----------|--------|
| [repository-and-cli.md](repository-and-cli.md) | Чем этот handbook отличается от OpenClaude CLI; как клонировать репозиторий; откуда ставится `@gitlawb/openclaude` |
---
## 1. Термины и контекст
| Документ | О чём |
|----------|--------|
| [concepts-and-terms.md](concepts-and-terms.md) | LLM, токены, MCP, типовые провайдеры |
---
## 2. Установка и конфигурация OpenClaude
| Документ | О чём |
|----------|--------|
| [install-openclaude-cli.md](install-openclaude-cli.md) | Node/npm, установка CLI, Ollama по ОС, переменные окружения и профили (локально / OpenAI / DeepSeek), PowerShell |
| [configure-profiles-direnv.md](configure-profiles-direnv.md) | Файлы профилей в `~/.config/openclaude/profiles`, direnv, Windows vs WSL |
---
## 3. Локальные LLM (Ollama)
| Документ | О чём |
|----------|--------|
| [local-llm-ollama.md](local-llm-ollama.md) | Каталог моделей, рекомендации «с чего начать», миф про «самообучение», обслуживание (`pull`/`rm`/место) |
| [model-catalog.md](model-catalog.md) | Расширенный обзор семейств моделей |
---
## 4. RAG, MCP, стек из этого репозитория
| Документ | О чём |
|----------|--------|
| [rag-mcp-stack.md](rag-mcp-stack.md) | Что такое RAG, из чего состоит стек, минимальная связка с Qdrant + MCP, чек-лист если MCP не виден |
| [rag-mcp-starter/](rag-mcp-starter/) | Docker Compose, `index.py`, `mcp_server.py`, скрипты установки и обслуживания |
---
## 5. Быстрый старт по времени и ролям
| Документ | О чём |
|----------|--------|
| [START-HERE.md](START-HERE.md) | План на 1 / 3 / 7 дней |
| [quickstart-30min.md](quickstart-30min.md) | Пошагово «с нуля» на Ubuntu (~30 минут) |
| [expectations.md](expectations.md) | Облако vs локально: честные ожидания |
| [runtime-choice.md](runtime-choice.md) | Выбор рантайма и окружения |
---
## 6. Эксплуатация и автоматизация
| Документ | О чём |
|----------|--------|
| [cron-examples.md](cron-examples.md) | Примеры cron для моделей и стека |
| `../scripts/install-cron.sh` | Установка типовых cron-задач из репозитория |
---
## 7. Git, GitHub, репозитории кода
| Документ | О чём |
|----------|--------|
| [github-auth-remotes.md](github-auth-remotes.md) | `gh auth`, PAT, HTTPS, SSH |
| [github-ssh-setup-and-troubleshooting.md](github-ssh-setup-and-troubleshooting.md) | SSH к GitHub подробно и типовые ошибки |
| [openclaude-with-repositories.md](openclaude-with-repositories.md) | Поток с кодом, MCP вокруг Git-платформ, проблемы `gh` в CI/облаке |
---
## 8. Железо, бенчмарки, дополнительные сценарии
| Документ | О чём |
|----------|--------|
| [hardware-budgets.md](hardware-budgets.md) | Три бюджета железа под локальные LLM |
| [bench-template.md](bench-template.md) | Шаблон benchmark своих задач |
| [cursor-like-stack.md](cursor-like-stack.md) | Локальный стек в духе IDE |
| [image-generation-local.md](image-generation-local.md) | Локальная генерация изображений |
| [linux-server-fixes.md](linux-server-fixes.md) | BOM в shell-скриптах, зеркала apt |
---
## 9. Куда двигаться после базы
| Документ | О чём |
|----------|--------|
| [roadmap-next-steps.md](roadmap-next-steps.md) | Следующие шаги после минимального контура |
---
Вся структура предполагает линейное чтение сверху вниз; для «только поднять стенд за вечер» достаточно цепочки **repository-and-cli** → **install-openclaude-cli** → **quickstart-30min** → **rag-mcp-starter**.
docs/START-HERE.md
+6 -5
View File
@@ -1,15 +1,16 @@
# START HERE # START HERE
Рекомендуемый порядок внедрения OpenClaude + local LLM. Рекомендуемый порядок внедрения OpenClaude + local LLM. Полная карта всех гайдов (от простого к сложному): [README.md](README.md) в каталоге `docs/`.
## План на 1 день (минимальный рабочий контур) ## План на 1 день (минимальный рабочий контур)
1. Прочитать: `docs/quickstart-30min.md` 1. Определиться, где handbook и где CLI: `docs/repository-and-cli.md`
2. Поднять минимальный стек: 2. Прочитать: `docs/quickstart-30min.md`
3. Поднять минимальный стек:
- `docs/rag-mcp-starter/install-minimal.sh` - `docs/rag-mcp-starter/install-minimal.sh`
3. Проверить готовность: 4. Проверить готовность:
- `docs/rag-mcp-starter/healthcheck.sh --mode minimal` - `docs/rag-mcp-starter/healthcheck.sh --mode minimal`
4. Зафиксировать рабочий профиль модели: 5. Зафиксировать рабочий профиль модели:
- обычно `qwen2.5-coder:7b` - обычно `qwen2.5-coder:7b`
- для слабого сервера `qwen2.5:3b` - для слабого сервера `qwen2.5:3b`
docs/concepts-and-terms.md
+37
View File
@@ -0,0 +1,37 @@
# Термины: LLM, токены, MCP и сценарии OpenClaude
Коротко — что есть что, прежде чем переходить к установке и железу.
## LLM и токены
- **LLM (Large Language Model)** — большая языковая модель, которая генерирует текст токен за токеном.
- **Токен** — кусок текста (слово, часть слова, знак, пробел), не всегда «целое слово».
- **Скорость (например 1–5 токенов/с)** — скорость генерации ответа моделью (decode speed).
- Очень грубо: `5 ток/с` часто ощущается как `~15–25 символов/с`, но это зависит от языка и модели.
## MCP
**MCP (Model Context Protocol)** — стандарт для подключения инструментов и источников данных к AI-агенту.
Простая схема:
- Модель = «мозг»
- MCP-сервер = «шлюз к инструментам»
- MCP-инструменты = конкретные действия (`search_docs`, `run_sql`, `create_ticket` и т.д.)
Польза MCP:
- подключение к актуальным данным (документы, БД, API);
- контролируемое выполнение действий через схемы входа/выхода;
- повторяемая интеграция для локальных и облачных сценариев.
## Сценарии работы OpenClaude
`openclaude` поддерживает разные провайдеры, в том числе:
- OpenAI-compatible API
- Ollama (локально)
- DeepSeek (через OpenAI-compatible endpoint)
- Gemini, GitHub Models, Codex и др.
Дальше: [установка CLI и зависимостей](install-openclaude-cli.md) → [профили и переменные окружения](configure-profiles-direnv.md).
docs/configure-profiles-direnv.md
+80
View File
@@ -0,0 +1,80 @@
# Профили OpenClaude и direnv
Как хранить отдельные файлы окружения для локального / OpenAI / DeepSeek и подключать их при входе в каталог проекта.
## 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
```
## 2. Установка direnv (Linux)
```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
```
## 3. Автопрофиль на папку проекта
В корне проекта:
```bash
cat > .envrc <<'EOF'
source_env ~/.config/openclaude/profiles/local.env
EOF
direnv allow
```
На **Windows** нативный `direnv` используют реже; задайте переменные в текущей сессии PowerShell через `$env:ИМЯ="значение"`, добавьте их в профиль PowerShell, либо работайте в **WSL** и следуйте Linux-инструкциям выше.
В OpenClaude также можно пользоваться встроенной настройкой провайдеров (`/provider` в CLI) — см. документацию upstream [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude).
docs/github-auth-remotes.md
+50
View File
@@ -0,0 +1,50 @@
# Git: GitHub, PAT, `gh` и remotes
Практичные способы не вводить пароль на каждом `git push` и нормально работать с `gh`.
## 1. Рекомендуемый путь через GitHub CLI
```bash
gh auth login
gh auth status
```
Удобно для GitHub: одна авторизация и нормальная работа `git pull`/`git push` и `gh`.
Если **`gh repo view`** или API в другой среде (CI, удалённый агент) возвращают ошибку про отсутствие репозитория, хотя у вас локально всё ок — см. [openclaude-with-repositories.md](openclaude-with-repositories.md) (раздел «Частые ошибки», подраздел про GitHub CLI).
## 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.
## 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 обычно удобнее для постоянной работы с приватными репозиториями.
## 4. Подробности и типовые проблемы SSH
- [github-ssh-setup-and-troubleshooting.md](github-ssh-setup-and-troubleshooting.md)
## 5. OpenClaude и репозитории (потоки разработки, RAG с кода)
- [openclaude-with-repositories.md](openclaude-with-repositories.md)
docs/hardware-budgets.md
+70
View File
@@ -0,0 +1,70 @@
# Планирование железа под локальные LLM (3 бюджета)
Ориентиры для Linux-сервера и локального запуска LLM (Ollama / OpenAI-compatible). Подробнее про ожидания к качеству: [expectations.md](expectations.md), выбор рантайма: [runtime-choice.md](runtime-choice.md).
## Бюджет 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: Комфортный (1× GPU среднего класса)
**Для кого:** ежедневная работа 1–3 пользователей, код + RAG в комфортном режиме.
- CPU: 8–16 vCPU
- RAM: 32–64 GB
- GPU: 1× 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: 1× NVIDIA 24 GB VRAM (RTX 4090 / L40-class по бюджету)
- вариант 2: 2× GPU по 16–24 GB для масштабирования
- Disk: NVMe 2 TB
Ожидания:
- уверенная работа 14B+ (квантизованные), параллельные запросы
- ориентир decode: `25–80+ ток/с` в зависимости от модели/батча
Рекомендованные модели:
- 14B-класс инструкт/кодовые варианты
- mix моделей: одна «быстрая дешёвая», одна «качественная тяжёлая»
## Что критично кроме железа
- стабильная версия драйверов CUDA (если NVIDIA);
- быстрый NVMe (модели занимают много места);
- мониторинг температуры/памяти/IO;
- резерв свободного диска под новые веса.
docs/install-openclaude-cli.md
+148
View File
@@ -0,0 +1,148 @@
# Установка OpenClaude: предусловия, Ollama, профили провайдеров
Пошагово: Node/npm → CLI → (для локальных моделей) Ollama → переменные окружения для выбранного провайдера.
## 0. Предусловия
Нужны **Node.js 18+** и **npm** (входят в официальную установку Node).
Проверка:
```bash
node -v
npm -v
```
Дальше:
1. установить **OpenClaude CLI** (ниже);
2. для **локальных** моделей через Ollama — установить и запустить **Ollama**, затем локальный профиль;
3. для облака (OpenAI / DeepSeek) достаточно ключей API — см. профили ниже.
Если при запуске OpenClaude появится предупреждение вроде `ripgrep not found`, установите **ripgrep** (`rg`) и проверьте `rg --version` в том же терминале.
## 1. Установка OpenClaude
```bash
npm install -g @gitlawb/openclaude
openclaude --version
```
## 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 (пример ниже совпадает с локальным профилем):
```bash
ollama pull qwen2.5-coder:7b
```
Быстрая проверка генерации:
```bash
ollama run qwen2.5-coder:7b
```
Подробнее про выбор и обслуживание моделей: [local-llm-ollama.md](local-llm-ollama.md).
## 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. 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
```
## 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
```
Дальше: закрепить профили на диске и автоподстановку в проектах — [configure-profiles-direnv.md](configure-profiles-direnv.md).
docs/linux-server-fixes.md
+18
View File
@@ -0,0 +1,18 @@
# Мелкие фиксы на Linux-сервере (BOM, apt-зеркала)
## Скрипт падает с `#!/usr/bin/env: No such file or directory`
Причина: **BOM** (маркер UTF-8) в начале файла.
Фикс:
```bash
sed -i '1s/^\xEF\xBB\xBF//' script.sh
chmod +x script.sh
```
## После смены зеркала apt всё ещё ходит в `ru.archive.ubuntu.com`
Обычно источники лежат в **`*.sources`** (формат deb822), а не только в `sources.list`.
Нужно править **`URIs:`** в соответствующих deb822-блоках под выбранное зеркало.
docs/local-llm-ollama.md
+65
View File
@@ -0,0 +1,65 @@
# Локальные модели через Ollama: где брать, что ставить, обслуживание
## Где брать модели
Проще всего через каталог Ollama: [https://ollama.com/library](https://ollama.com/library)
Расширенные таблицы и заметки по семействам: [model-catalog.md](model-catalog.md)
## Рекомендуемый старт
- `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
```
Установка самого Ollama по ОС — в [install-openclaude-cli.md](install-openclaude-cli.md#2-установка-и-запуск-ollama-для-локального-профиля).
## «Модель дообучается сама» от работы в чате?
Короткий ответ: **нет**.
- Обычная работа в чате не дообучает модель автоматически.
- Качество обычно улучшают так:
- обновляют модель/тег (`ollama pull ...`);
- улучшают системные промпты;
- подключают RAG (документы + retrieval).
- Полноценный finetune/LoRA — отдельный ML-процесс.
## Обновление и обслуживание
Смотреть установленные:
```bash
ollama list
```
Обновлять нужные:
```bash
ollama pull qwen2.5-coder:7b
```
Удалять старые:
```bash
ollama rm <model:tag>
```
Проверять занятое место (Linux):
```bash
sudo du -h --max-depth=2 /usr/share/ollama /var/lib/ollama 2>/dev/null | sort -h | tail -n 30
```
Дальше: как подключать документы и MCP — [rag-mcp-stack.md](rag-mcp-stack.md).
docs/model-catalog.md
+2
View File
@@ -2,6 +2,8 @@
Практический каталог моделей для code-задач в локальном и гибридном сценарии. Практический каталог моделей для code-задач в локальном и гибридном сценарии.
Базовые команды `ollama pull` и обслуживание: [local-llm-ollama.md](local-llm-ollama.md).
> Важно: "лучшая модель" зависит от языка проекта, длины контекста, формата задач и вашего железа. > Важно: "лучшая модель" зависит от языка проекта, длины контекста, формата задач и вашего железа.
## 1) Рекомендуемые семейства ## 1) Рекомендуемые семейства
docs/quickstart-30min.md
+2 -2
View File
@@ -2,7 +2,7 @@
Короткий маршрут "с нуля до рабочего стенда" на Ubuntu. Короткий маршрут "с нуля до рабочего стенда" на Ubuntu.
Если вы на **Windows**, установите Ollama и Node.js локально, затем для запуска OpenClaude на локальной модели используйте блоки **Windows PowerShell** в `README.md` (раздел «4) Быстрый запуск OpenClaude»: предусловия **4.0**, установка CLI **4.1**, установка Ollama **4.2**, профиль **4.3**). Полный стек ниже (Docker, bash-скрипты, пути `~/...`) удобнее повторять в **WSL2** или на Linux-сервере с тем же репозиторием. Если вы на **Windows**, установите Ollama и Node.js локально, затем для запуска OpenClaude на локальной модели следуйте `docs/install-openclaude-cli.md` (блоки **PowerShell** и порядок шагов там же). Полный стек ниже (Docker, bash-скрипты, пути `~/...`) удобнее повторять в **WSL2** или на Linux-сервере с тем же репозиторием.
## 0) Что получится ## 0) Что получится
@@ -21,7 +21,7 @@ sudo systemctl start docker
## 2) Установка Ollama ## 2) Установка Ollama
Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `README.md`, раздел **4.2**. Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `docs/install-openclaude-cli.md` (раздел про установку Ollama).
```bash ```bash
curl -fsSL https://ollama.com/install.sh | sh curl -fsSL https://ollama.com/install.sh | sh
docs/rag-mcp-stack.md
+62
View File
@@ -0,0 +1,62 @@
# RAG, минимальный стек и отладка MCP
## Что такое 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: каталог [rag-mcp-starter/](rag-mcp-starter/).
Минимальная схема:
1. Сложить документы (`md`/`txt`/`pdf`).
2. Разбить на чанки (`chunk_size ~1000`, overlap `~120`).
3. Сделать embeddings.
4. Записать в Qdrant.
5. Поднять MCP-инструмент `search_docs`.
6. Вызывать его из OpenClaude.
Быстрый сценарий «с нуля за 30 минут» на Ubuntu: [quickstart-30min.md](quickstart-30min.md).
Интеграция с Git и индексация репозитория как базы знаний: [openclaude-with-repositories.md](openclaude-with-repositories.md).
## Чек-лист, если MCP «не виден»
1. MCP-сервер стартует вручную из каталога starter:
```bash
cd docs/rag-mcp-starter
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`
docs/rag-mcp-starter/README.md
+4
View File
@@ -149,3 +149,7 @@ chmod +x upgrade.sh
- `RAG_DOCS_DIR` (default `./docs`) - `RAG_DOCS_DIR` (default `./docs`)
- `CHUNK_SIZE` (default `1000`) - `CHUNK_SIZE` (default `1000`)
- `CHUNK_OVERLAP` (default `120`) - `CHUNK_OVERLAP` (default `120`)
## См. также
- Обзор RAG и связка с OpenClaude: [../rag-mcp-stack.md](../rag-mcp-stack.md)
docs/repository-and-cli.md
+32
View File
@@ -0,0 +1,32 @@
# Этот репозиторий и установка OpenClaude CLI
## Что лежит в этом репозитории
Проект **openclaude-LLM-local** — это **справочник по эксплуатации**: тексты в `docs/`, пример минимального RAG в `docs/rag-mcp-starter/`, вспомогательные скрипты в `scripts/`.
Это **не** исходный код приложения OpenClaude и **не** форк движка моделей.
## Как получить эти материалы у себя
Клонирование (подставьте свой fork или upstream URL из страницы репозитория на GitHub):
```bash
git clone https://github.com/PTah/openclaude-LLM-local.git
cd openclaude-LLM-local
```
Дальше читайте навигацию в [README.md](README.md) (каталог `docs/`) или краткий план в [START-HERE.md](START-HERE.md).
## Откуда ставится сам OpenClaude
CLI распространяется как **npm-пакет** upstream-проекта:
```bash
npm install -g @gitlawb/openclaude
```
Исходники и релизы CLI: репозиторий [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude) на GitHub.
Итого: **документацию и примеры** вы тянете из этого handbook-репозитория; **бинарник/CLI OpenClaude** ставите через `npm` из `@gitlawb/openclaude`.
Следующий шаг по порядку «от простого к сложному»: [install-openclaude-cli.md](install-openclaude-cli.md).
docs/roadmap-next-steps.md
+12
View File
@@ -0,0 +1,12 @@
# Что делать дальше (дорожная карта)
Если уже есть базовый локальный контур OpenClaude + выбранная модель, логичный следующий порядок:
1. Зафиксировать текущие характеристики сервера (CPU/RAM/GPU/NVMe).
2. Выбрать стартовый профиль (`local` / OpenAI / DeepSeek) и закрепить его в [configure-profiles-direnv.md](configure-profiles-direnv.md).
3. Поднять `openclaude` и сделать короткий smoke test на типовой задаче.
4. Запустить минимальный RAG с Qdrant по [rag-mcp-stack.md](rag-mcp-stack.md) и каталогу [rag-mcp-starter/](rag-mcp-starter/).
5. Добавить MCP-инструменты под ваши рабочие данные.
6. Оптимизировать скорость и стоимость (routing между моделями, гибрид с облаком — см. [expectations.md](expectations.md)).
Фазированный план по дням: [START-HERE.md](START-HERE.md).