docs: split handbook into docs/ by topic, slim root README, add docs index
Made-with: Cursor
This commit is contained in:
PTah
+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