docs: split handbook into docs/ by topic, slim root README, add docs index
Made-with: Cursor
This commit is contained in:
PTah
@@ -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)**.
|
||||
|
||||
+100
@@ -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**.
|
||||
+6
-5
@@ -1,15 +1,16 @@
|
||||
# START HERE
|
||||
|
||||
Рекомендуемый порядок внедрения OpenClaude + local LLM.
|
||||
Рекомендуемый порядок внедрения OpenClaude + local LLM. Полная карта всех гайдов (от простого к сложному): [README.md](README.md) в каталоге `docs/`.
|
||||
|
||||
## План на 1 день (минимальный рабочий контур)
|
||||
|
||||
1. Прочитать: `docs/quickstart-30min.md`
|
||||
2. Поднять минимальный стек:
|
||||
1. Определиться, где handbook и где CLI: `docs/repository-and-cli.md`
|
||||
2. Прочитать: `docs/quickstart-30min.md`
|
||||
3. Поднять минимальный стек:
|
||||
- `docs/rag-mcp-starter/install-minimal.sh`
|
||||
3. Проверить готовность:
|
||||
4. Проверить готовность:
|
||||
- `docs/rag-mcp-starter/healthcheck.sh --mode minimal`
|
||||
4. Зафиксировать рабочий профиль модели:
|
||||
5. Зафиксировать рабочий профиль модели:
|
||||
- обычно `qwen2.5-coder:7b`
|
||||
- для слабого сервера `qwen2.5:3b`
|
||||
|
||||
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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)
|
||||
@@ -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;
|
||||
- резерв свободного диска под новые веса.
|
||||
@@ -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).
|
||||
@@ -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-блоках под выбранное зеркало.
|
||||
@@ -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).
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
Практический каталог моделей для code-задач в локальном и гибридном сценарии.
|
||||
|
||||
Базовые команды `ollama pull` и обслуживание: [local-llm-ollama.md](local-llm-ollama.md).
|
||||
|
||||
> Важно: "лучшая модель" зависит от языка проекта, длины контекста, формата задач и вашего железа.
|
||||
|
||||
## 1) Рекомендуемые семейства
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Короткий маршрут "с нуля до рабочего стенда" на 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) Что получится
|
||||
|
||||
@@ -21,7 +21,7 @@ sudo systemctl start docker
|
||||
|
||||
## 2) Установка Ollama
|
||||
|
||||
Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `README.md`, раздел **4.2**.
|
||||
Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `docs/install-openclaude-cli.md` (раздел про установку Ollama).
|
||||
|
||||
```bash
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
|
||||
@@ -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`
|
||||
@@ -149,3 +149,7 @@ chmod +x upgrade.sh
|
||||
- `RAG_DOCS_DIR` (default `./docs`)
|
||||
- `CHUNK_SIZE` (default `1000`)
|
||||
- `CHUNK_OVERLAP` (default `120`)
|
||||
|
||||
## См. также
|
||||
|
||||
- Обзор RAG и связка с OpenClaude: [../rag-mcp-stack.md](../rag-mcp-stack.md)
|
||||
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user