RAG Pipeline 3/N: Чанки – как резать текст, чтобы модель не получала мусор

ПЛОХАЯ НАРЕЗКА (по 1500 символов):

Файл nginx-guide.md:
┌──────────────────────────────────────────────────────────┐
│  ## Reverse Proxy                                         │
│  Для настройки reverse proxy используйте proxy_pass.      │
│  Основные параметры:                                      │
│  - proxy_set_header Host $host;                           │
│  - proxy_set_header X-Real-IP $remote_addr;               │
│  ...                                                      │
│  ## SSL/TLS                                               │  ← граница чанка
│  Для включения HTTPS добавьте в секцию server: ──────────►│    прошла посередине
│  ssl_certificate /etc/nginx/ssl/cert.pem;                 │    новой темы
│  ssl_certificate_key /etc/nginx/ssl/key.pem;              │
└──────────────────────────────────────────────────────────┘
Чанк 1: Reverse Proxy + начало SSL → вектор описывает "что-то про nginx"
Чанк 2: Остаток SSL без контекста → "cert.pem и key.pem" без объяснения зачем

ХОРОШАЯ НАРЕЗКА (по H2/H3):

Чанк 1: [## Reverse Proxy] — полная секция про proxy_pass
Чанк 2: [## SSL/TLS] — полная секция про сертификаты

def chunk_by_sections(content: str, file_path: str) -> list[dict]:
    """Режем markdown по H2/H3 заголовкам."""
    chunks = []
    lines = content.split('\n')
    current_section = file_path  # имя файла как fallback
    current_lines = []

    for line in lines:
        heading_match = re.match(r'^(#{2,3})\s+(.+)', line)
        if heading_match and current_lines:
            # Предыдущая секция завершена -- сохраняем
            text = '\n'.join(current_lines).strip()
            if text and len(text) >= 20:
                chunks.extend(_split_large_chunk(text, current_section))
            current_lines = [line]
            current_section = heading_match.group(2).strip()
        else:
            current_lines.append(line)

    # Последняя секция
    if current_lines:
        text = '\n'.join(current_lines).strip()
        if text and len(text) >= 20:
            chunks.extend(_split_large_chunk(text, current_section))

    return chunks

CHUNK_SIZE = 800   # символов
CHUNK_OVERLAP = 150  # символов

def _split_large_chunk(text: str, section: str) -> list[dict]:
    """Дорезка больших секций с overlap."""
    if len(text) <= CHUNK_SIZE:
        return [{'text': text, 'section': section}]

    pieces = []
    start = 0
    idx = 0
    while start < len(text):
        end = start + CHUNK_SIZE
        piece = text[start:end]
        pieces.append({
            'text': piece.strip(),
            'section': f"{section} (part {idx + 1})"
        })
        start = end - CHUNK_OVERLAP  # сдвиг с перекрытием
        idx += 1
    return pieces

Без overlap:
  Чанк 1: [───────────────────]
  Чанк 2:                      [───────────────────]
  Потеря:                      ↑ контекст разорван

С overlap 150:
  Чанк 1: [───────────────────]
  Чанк 2:              [───────────────────]
  Перекрытие:          ^^^^^^^^ 150 символов дублируются

English: "container"     → 1 token
Русский: "контейнер"     → ~9 tokens  (кириллица дробится на subword-фрагменты)
Русский: "проксирование" → ~11 tokens

CHUNK_SIZE = 800

def sanitize_for_embedding(text: str) -> str:
    """Чистим текст перед отправкой в модель."""
    if not text:
        return ""

    # 1. Unicode replacement characters (\ufffd)
    #    Появляются при чтении файлов с errors='replace'
    #    Невидимы глазу, но ломают Ollama
    text = text.replace('\ufffd', '')

    # 2. Управляющие символы (C0/C1)
    text = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]', '', text)

    # 3. Перекодировка: убираем невалидный UTF-8
    text = text.encode('utf-8', errors='ignore').decode('utf-8', errors='ignore')

    # 4. Длинные строки без пробелов (base64, хеши, URL)
    #    Обрезаем до 200 символов -- дальше бесполезно для поиска
    text = re.sub(r'\S{200,}', lambda m: m.group(0)[:200] + '...', text)

    # 5. Множественные пробелы и пустые строки
    text = re.sub(r'[ \t]{10,}', '  ', text)
    text = re.sub(r'\n{5,}', '\n\n\n', text)

    # 6. Обрезаем до CHUNK_SIZE
    text = text[:CHUNK_SIZE].strip()

    # 7. Quality gate: слишком короткий = мусор
    if len(text) < 20:
        return ""

    return text

payload = {
    'file_path': 'nora-sprint-status.md',     # откуда
    'section': 'v0.9.0 RELEASED (18.05.2026)', # какая секция
    'zone': 'warm',                             # hot/warm/cold
    'project': 'nora',                          # какой проект
    'mtime': 1747584000.0,                      # когда изменён
    'content_hash': 'a1b2c3d4...',              # md5 для change detection
    'text_preview': 'ARM64 binary + multi...',  # первые 500 символов
}

hot   = MEMORY.md         — главный файл, ядро контекста
warm  = memory/*.md       — активные файлы проектов
cold  = memory/_archive/  — завершённые проекты

PROJECT_PATTERNS = {
    'nora': r'^nora[-_]',
    'pusk': r'^pusk[-_]',
    'kmb': r'^(kmb[-_]|curriculum[-_]|kokon)',
    'jarvis': r'^(jarvis|JARVIS)',
    'infra': r'^(infrastructure|bastion|pve|vault)',
    # ...
}

content_hash = hashlib.md5(text.encode()).hexdigest()
if content_hash in existing_hashes:
    skipped_chunks += 1  # не переиндексируем
    continue

def get_embedding(text: str, retries: int = 2):
    """Embedding с progressive truncation."""
    text = sanitize_for_embedding(text)
    if len(text) < 10:
        return None

    # Пробуем полный текст, потом короче
    for text_len in [len(text), 600, 400]:
        prompt = text[:text_len]
        if len(prompt) < 20:
            return None
        for attempt in range(retries + 1):
            try:
                resp = requests.post(f"http://{OLLAMA_HOST}:{OLLAMA_PORT}/api/embeddings", json={
                    "model": "mxbai-embed-large",
                    "prompt": prompt
                }, timeout=75)
                if resp.status_code == 200:
                    return resp.json().get('embedding')
                elif resp.status_code == 500 and "context length" in resp.text:
                    break  # обрезаем и пробуем короче
            except Exception:
                if attempt < retries:
                    time.sleep(2 ** attempt)
        else:
            return None
    return None

#!/usr/bin/env python3
"""
chunk-markdown.py -- нарезка markdown-файлов для RAG pipeline.
Режет по H2/H3, дорезает с overlap, чистит мусор.

Запуск:
  python3 chunk-markdown.py /path/to/docs/
  python3 chunk-markdown.py /path/to/docs/ --stats
"""
import argparse
import re
import sys
from pathlib import Path

CHUNK_SIZE = 800
CHUNK_OVERLAP = 150
MIN_CHUNK_LEN = 20


def sanitize(text: str) -> str:
    """Чистим текст от мусора. Не обрезает по CHUNK_SIZE — этим занимается split_large."""
    if not text:
        return ""
    text = text.replace('\ufffd', '')
    text = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]', '', text)
    text = text.encode('utf-8', errors='ignore').decode('utf-8', errors='ignore')
    text = re.sub(r'\S{200,}', lambda m: m.group(0)[:200] + '...', text)
    text = re.sub(r'[ \t]{10,}', '  ', text)
    text = re.sub(r'\n{5,}', '\n\n\n', text)
    text = text.strip()
    if len(text) < MIN_CHUNK_LEN:
        return ""
    return text


def split_large(text: str, section: str) -> list[dict]:
    """Дорезка больших секций с overlap."""
    if len(text) <= CHUNK_SIZE:
        return [{'text': text, 'section': section, 'chars': len(text)}]
    pieces = []
    start = 0
    idx = 0
    while start < len(text):
        end = start + CHUNK_SIZE
        piece = text[start:end].strip()
        if piece:
            pieces.append({
                'text': piece,
                'section': f"{section} (part {idx + 1})",
                'chars': len(piece),
            })
        start = end - CHUNK_OVERLAP
        idx += 1
    return pieces


def chunk_file(filepath: Path) -> list[dict]:
    """Нарезка одного markdown-файла."""
    content = filepath.read_text(encoding='utf-8', errors='replace')
    chunks = []
    lines = content.split('\n')
    current_section = filepath.name
    current_lines = []

    for line in lines:
        heading = re.match(r'^(#{2,3})\s+(.+)', line)
        if heading and current_lines:
            text = sanitize('\n'.join(current_lines))
            if text:
                chunks.extend(split_large(text, current_section))
            current_lines = [line]
            current_section = heading.group(2).strip()
        else:
            current_lines.append(line)

    if current_lines:
        text = sanitize('\n'.join(current_lines))
        if text:
            chunks.extend(split_large(text, current_section))

    return chunks


def main():
    parser = argparse.ArgumentParser(description="Chunk markdown files for RAG")
    parser.add_argument("path", help="Directory with .md files")
    parser.add_argument("--stats", action="store_true", help="Show stats only")
    args = parser.parse_args()

    path = Path(args.path)
    if not path.is_dir():
        print(f"Not a directory: {path}", file=sys.stderr)
        sys.exit(1)

    total_files = 0
    total_chunks = 0
    total_chars = 0

    for md in sorted(path.rglob('*.md')):
        chunks = chunk_file(md)
        total_files += 1
        total_chunks += len(chunks)

        if args.stats:
            total_chars += sum(c['chars'] for c in chunks)
            continue

        for i, chunk in enumerate(chunks):
            print(f"--- {md.name} | {chunk['section']} | {chunk['chars']} chars ---")
            print(chunk['text'][:200])
            if chunk['chars'] > 200:
                print(f"  ... ({chunk['chars'] - 200} more chars)")
            print()

    if args.stats:
        avg = total_chars / total_chunks if total_chunks else 0
        print(f"Files:  {total_files}")
        print(f"Chunks: {total_chunks}")
        print(f"Avg:    {avg:.0f} chars/chunk")
        print(f"Total:  {total_chars:,} chars")


if __name__ == "__main__":
    main()

# Посмотреть нарезку
python3 chunk-markdown.py ~/docs/

# Только статистика
python3 chunk-markdown.py ~/docs/ --stats
# Files:  <N>
# Chunks: <N>
# Avg:    <N> chars/chunk
# Total:  <N> chars