PapaTramp/openclaude-LLM-local
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
17 Commits 1 Branch 0 Tags
ab4e83b04242f35decefacff1f3a2a8d5cf594d4
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

OpenClaude + Local LLM Handbook

Практическая документация по запуску openclaude на сервере, подключению локальных и облачных моделей, работе с MCP/RAG и планированию железа под разные бюджеты.

1) Что такое LLM и токены

  • LLM (Large Language Model) - большая языковая модель, которая генерирует текст токен за токеном.
  • Токен - кусок текста (слово, часть слова, знак, пробел), не всегда "целое слово".
  • Скорость 1-5 токенов/с - скорость генерации ответа моделью (decode speed).
  • Очень грубо: 5 ток/с часто ощущается как ~15-25 символов/с, но это зависит от языка и модели.

2) Что такое MCP и зачем он нужен

MCP (Model Context Protocol) - стандарт для подключения инструментов и источников данных к AI-агенту.

Простая схема:

  • Модель = "мозг"
  • MCP-сервер = "шлюз к инструментам"
  • MCP-инструменты = конкретные действия (search_docs, run_sql, create_ticket и т.д.)

Польза MCP:

  • Подключение к актуальным данным (документы, БД, API)
  • Контролируемое выполнение действий через схемы входа/выхода
  • Повторяемая интеграция для локальных и облачных сценариев

3) Основные сценарии работы OpenClaude

openclaude поддерживает разные провайдеры, включая:

  • OpenAI-compatible API
  • Ollama (локально)
  • DeepSeek (через OpenAI-compatible endpoint)
  • Gemini, GitHub Models, Codex и др.

4) Быстрый запуск OpenClaude

4.1 Установка

npm install -g @gitlawb/openclaude

4.2 Локальный Ollama-профиль (бесплатно)

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b
openclaude

4.3 OpenAI-профиль

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o
openclaude

4.4 DeepSeek-профиль

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=https://api.deepseek.com/v1
export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=deepseek-chat
openclaude

5) Локальные бесплатные модели: где брать и что ставить

Где брать

Рекомендуемый старт

  • qwen2.5-coder:7b - хороший баланс для кода
  • qwen2.5:3b - если сервер слабый
  • llama3.1:8b - универсальный сильный baseline
  • deepseek-r1:8b - reasoning-ориентированный вариант

Команды

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 Профили

Создать:

mkdir -p ~/.config/openclaude/profiles

~/.config/openclaude/profiles/local.env

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

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

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

Права:

chmod 600 ~/.config/openclaude/profiles/*.env

7.2 Установка direnv

sudo apt update
sudo apt install -y direnv

Для bash:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

Для zsh:

echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

7.3 Автопрофиль на папку проекта

В корне проекта:

cat > .envrc <<'EOF'
source_env ~/.config/openclaude/profiles/local.env
EOF
direnv allow

8) Минимальный RAG стек (локально)

Рекомендуемая база:

  • Embeddings: nomic-embed-text (через Ollama)
  • Vector DB: Qdrant
  • Retrieval tool: MCP search_docs

Минимальная схема:

  1. Сложить документы (md/txt/pdf)
  2. Разбить на чанки (chunk_size ~1000, overlap ~120)
  3. Сделать embeddings
  4. Записать в Qdrant
  5. Поднять MCP-инструмент search_docs
  6. Вызывать его из OpenClaude

9) Быстрый чек-лист, если MCP "не виден"

  1. MCP-сервер стартует вручную:
python mcp_server.py
  1. Импорты и зависимости установлены:
python -c "import fastmcp, qdrant_client, requests; print('ok')"
  1. Пути в ~/.claude/settings.json корректны (command, args)
  2. Qdrant доступен: curl http://127.0.0.1:6333/collections
  3. 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) Практика обновления и обслуживания моделей

  • Смотреть установленные:
ollama list
  • Обновлять нужные:
ollama pull qwen2.5-coder:7b
  • Удалять старые:
ollama rm <model:tag>
  • Проверять занятое место:
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

gh auth login
gh auth status

Это самый удобный вариант для GitHub: авторизация один раз и нормальная работа git pull/push и gh.

12.2 Через PAT по HTTPS

  1. Создать Personal Access Token на GitHub (минимальные нужные scopes).
  2. Проверить, что remote в HTTPS:
git remote -v
git remote set-url origin https://github.com/OWNER/REPO.git
  1. Включить credential helper, чтобы не вводить PAT каждый раз:
git config --global credential.helper store
  1. Выполнить git pull или git push и один раз ввести логин + PAT.

12.3 Через SSH (альтернатива PAT)

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 в начале файла.

Фикс:

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
Reference in New Issue View Git Blame Copy Permalink
S
Description
No description provided
Readme 106 KiB
Languages
Shell 100%