# «От чёрного ящика к инженерии»

Практическая книга о том, как понимать, проектировать и контролировать LLM-системы.

Здесь собран не набор «магических промптов», а инженерный взгляд на современные большие языковые модели: от токенизации, attention и MLP-памяти до агентных контуров, tool use, RAG, верификации и AI-friendly разработки.

Актуальный контекст книги: апрель 2026 года.

## Как создавалась книга

Книга написана полностью с помощью оркестрации Claude Opus 4.6, с точечной валидацией ключевых фрагментов и формулировок через GPT 5.4 High.

## Для кого эта книга

- для software-инженеров, которые встраивают LLM в продукты, backend-сервисы и интерфейсы;
- для ML-инженеров, которые работают с inference, fine-tuning, RAG и quality-контролем;
- для техлидов и архитекторов, которые принимают решения о внедрении LLM в production;
- для разработчиков, которые хотят перейти от интуитивного промптинга к предсказуемой инженерии.

## Что внутри

Книга разбита на 26 глав и идёт от механики модели к архитектуре систем:

- **Главы 1–5:** фундамент — токены, embeddings, attention, MLP, галлюцинации, каузальное декодирование, длинный контекст;
- **Главы 6–9:** протоколирование — промпт как контракт, XML-разметка, многогипотезность, декомпозиция задач;
- **Главы 10–13:** архитектура — агент vs чат, инструменты, RAG, антигаллюцинационный контур, верификация;
- **Главы 14–15:** качество и безопасность — evals (golden sets, LLM-as-Judge, regression gates), безопасность (prompt injection, jailbreaks, red-teaming, guardrails);
- **Главы 16–17:** код и наблюдаемость — AI-friendly код, LDD, observability (OpenTelemetry, SLO, incident response);
- **Главы 18–20:** продвинутые темы — мультимодальные системы, дообучение и post-training, паттерны проектирования;
- **Главы 21–22:** serving и runtime — inference pipeline, KV-кэш, PagedAttention, quantization, durable orchestration, жизненный цикл агента;
- **Глава 23:** внедрение — минимальный контур, метрики, постепенная интеграция;
- **Глава 24:** ландшафт 2026 — гибридные архитектуры, reasoning-модели, MoE, SSM/Mamba, экономика inference;
- **Глава 25:** резюме и первоисточники.

Каждая глава завершается практическим выводом и списком источников.

## Как читать

- Если тема новая, начинайте последовательно с `book/00_introduction.md` и дальше по главам.
- Если нужен справочник по конкретной теме, можно читать выборочно: главы самодостаточны и связаны навигацией.
- Если интересует прикладная работа, после фундамента переходите к `book/10_agent_not_chat.md`, `book/11_tools.md`, `book/12_rag.md`, `book/13_anti_hallucination_loop.md`.
- Если интересует внедрение в команду и кодовую базу, откройте `book/16_code_architecture.md` и `book/23_getting_started.md`.
- Если интересует оценка качества и безопасность, смотрите `book/14_llm_system_quality_evaluation.md` и `book/15_llm_system_security.md`.

## Что вы получите

- ментальные модели того, как LLM реально работают;
- практические паттерны для промптов, agent loop, tool use и верификации;
- анти-паттерны, которые ломают production-системы;
- чек-листы для внедрения, отладки и масштабирования;
- подборку первичных статей, спецификаций и репозиториев по каждой теме.

## Структура репозитория

- `book/` — основной текст книги по главам;
- `BlackboxBook.pdf` — готовая PDF-сборка;
- `scripts/build_book_pdf.py` — скрипт локальной сборки PDF;
- `build_pdf.command` — удобный запуск стандартной PDF-сборки на macOS;
- `build_pdf_ebook.command` — удобный запуск ebook/Kindle-сборки на macOS;
- `build_pdf_phone.command` — удобный запуск phone-сборки для узкого экрана на macOS;
- `.github/agents/` — агенты GitHub Copilot для редактуры, фактчекинга, консистентности и оркестрации;
- `.github/instructions/` и `.github/prompts/` — инструкции и prompt-шаблоны для работы с книгой.

## С чего начать

- Читать PDF: `BlackboxBook.pdf`
- Читать по главам: `book/00_introduction.md`

## Локальная сборка PDF

Если вы читаете книгу из репозитория и хотите пересобрать PDF локально:

```bash
python3 scripts/build_book_pdf.py --source book --output BlackboxBook.pdf
```

Понадобятся `pandoc` и один из PDF-движков: `tectonic`, `xelatex` или `lualatex`.

`./build_pdf.command` собирает стандартный `BlackboxBook.pdf` в формате A4.

`./build_pdf_ebook.command` собирает `BlackboxBook_ebook.pdf` в формате `6in x 8in` с уменьшенными полями для чтения на Kindle с 7" экраном, автоматически переносит длинные строки в fenced code blocks и немного уменьшает шрифт в коде.

`./build_pdf_phone.command` собирает `BlackboxBook_phone.pdf` в формате `4.1in x 9.1in` с узкой текстовой колонкой и уменьшенными полями для чтения на экране смартфона без зума; длинные строки в fenced code blocks переносятся автоматически.

## О подходе книги

Главная идея проста: LLM нельзя надёжно использовать как магию. Ими нужно управлять как инженерной системой — через понимание механики, явные протоколы, внешние инструменты, верификацию и наблюдаемость.

Именно этому посвящена книга.