Практика RAG · embeddings · диагностика До 12 минут

Диагностируем RAG-индекс по картам векторных представлений

Диагностируем RAG-индекс по картам векторных представлений
Temporary fallback cover; replace in editorial pass.

Карта embedding-пространства полезна не сама по себе. Она становится диагностическим инструментом только тогда, когда её выводы можно сопоставить с исходными расстояниями, соседями в индексе и структурой документов.

Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.

Что именно нужно доказать

Визуализация проекции векторов часто выглядит убедительно: документы образуют острова, похожие чанки оказываются рядом, а выбросы заметны почти сразу. Но двумерная карта может скрыть важную информацию. Проекция сжимает пространство, меняет расстояния и иногда создаёт видимые кластеры там, где в исходных векторах их нет.

Поэтому вопрос диагностики формулируется строже: помогает ли карта находить дефекты, которые подтверждаются измерениями в исходном пространстве? Для этого нужны три независимые проверки:

  • сколько исходных ближайших соседей сохранилось после проекции;
  • совпадают ли визуально близкие точки с настоящими cosine-neighbors;
  • связаны ли подозрительные области с конкретными границами чанков, метаданными или ошибками индекса.

Минимальная схема данных

Для воспроизводимой диагностики сохраните не только векторы. На каждую точку нужны идентификатор, идентификатор документа, порядковый номер чанка, текст или безопасный фрагмент текста, а также метаданные источника.

{
  "id": "doc-17:chunk-04",
  "document_id": "doc-17",
  "chunk_index": 4,
  "text": "...",
  "embedding": [0.012, -0.083, 0.441],
  "metadata": {
    "source": "handbook.md",
    "start": 1840,
    "end": 2360
  }
}

Если полные тексты нельзя выносить в диагностический артефакт, используйте хеш, короткий превью-фрагмент или ссылку на локальный идентификатор. Карта не должна случайно раскрывать содержимое закрытого корпуса.

Шаг 1. Зафиксируйте базовую выборку

Не начинайте с красивой картинки. Сначала зафиксируйте корпус, модель эмбеддингов, нормализацию, размерность, число точек и параметры индекса. Для сравнения двух версий индекса эти значения должны быть неизменными.

Пример безопасной проверки локального файла не меняет данные и не отправляет их наружу:

python - <<'PY'
import json
from pathlib import Path

path = Path("chunks.jsonl")
rows = [json.loads(line) for line in path.read_text().splitlines() if line.strip()]

assert rows, "Пустой набор"
dims = {len(row["embedding"]) for row in rows}
assert len(dims) == 1, f"Разные размерности: {dims}"

print("chunks:", len(rows))
print("dimensions:", dims.pop())
print("documents:", len({row["document_id"] for row in rows}))
PY

На этом этапе не делайте выводов о качестве. Цель — убедиться, что последующие измерения относятся к одному и тому же набору точек.

Шаг 2. Посчитайте исходных cosine-neighbors

Для каждого вектора найдите k ближайших соседей по cosine similarity. Если векторы нормализованы, косинусное сходство можно считать обычным скалярным произведением. Не смешивайте в одном сравнении cosine, евклидово расстояние и метрику, которую фактически использует production-индекс.

python - <<'PY'
import json
import numpy as np
from pathlib import Path

rows = [json.loads(line) for line in Path("chunks.jsonl").read_text().splitlines() if line.strip()]
X = np.asarray([row["embedding"] for row in rows], dtype=np.float32)

norms = np.linalg.norm(X, axis=1, keepdims=True)
X = X / np.maximum(norms, 1e-12)

similarity = X @ X.T
np.fill_diagonal(similarity, -np.inf)

k = 10
neighbors = np.argsort(-similarity, axis=1)[:, :k]

with Path("cosine-neighbors.jsonl").open("w") as output:
    for i, row in enumerate(rows):
        output.write(json.dumps({
            "id": row["id"],
            "neighbors": [
                {"id": rows[j]["id"], "score": float(similarity[i, j])}
                for j in neighbors[i]
            ]
        }, ensure_ascii=False) + "\n")
PY

Для большого корпуса полная матрица X @ X.T может быть слишком дорогой. Тогда используйте батчи или тот же approximate nearest neighbor-индекс, но отдельно сохраните его параметры и отличайте приближённый результат от точного эталона.

Шаг 3. Постройте карту, но не называйте её доказательством

Выберите метод проекции и зафиксируйте seed, если он поддерживается. Для диагностики полезно построить хотя бы две карты с разными параметрами или методами. Устойчивая закономерность, которая повторяется на нескольких проекциях, заслуживает проверки; одиночный визуальный эффект — только гипотеза.

В файл карты добавьте исходный идентификатор точки. Не заменяйте его порядковым номером строки: после фильтрации или пересортировки это приводит к неверному сопоставлению карты с индексом.

id,x,y,document_id,chunk_index
doc-17:chunk-04,-1.283,0.441,doc-17,4
doc-17:chunk-05,-1.190,0.398,doc-17,5

Цветом можно показать документ, тип источника или версию чанкинга. Однако не кодируйте слишком много признаков одновременно: карта должна помогать увидеть структуру, а не превращаться в легенду из десятков категорий.

Шаг 4. Измерьте сохранённых соседей

Главная проверка — пересечение множеств соседей до и после проекции. Для точки i обозначим исходных соседей как Ni, а соседей на карте — как Pi. Тогда:

recall_at_k(i) = |N_i ∩ P_i| / k

Среднее значение показывает общую сохранность локальной структуры, но медиана и нижние квантили важнее для поиска дефектов. Отдельно посчитайте метрику для разных типов чанков, документов и областей карты.

python - <<'PY'
import json
import numpy as np
from pathlib import Path

original = {
    row["id"]: {item["id"] for item in row["neighbors"]}
    for row in map(json.loads, Path("cosine-neighbors.jsonl").read_text().splitlines())
}

projected = {
    row["id"]: set(row["neighbors"])
    for row in map(json.loads, Path("projected-neighbors.jsonl").read_text().splitlines())
}

scores = []
for point_id, expected in original.items():
    actual = projected.get(point_id, set())
    scores.append(len(expected & actual) / max(len(expected), 1))

values = np.asarray(scores)
print("mean:", float(values.mean()))
print("median:", float(np.median(values)))
print("p10:", float(np.quantile(values, 0.10)))
print("below_0.30:", int((values < 0.30).sum()))
PY

Порог 0.30 в примере не является универсальным нормативом. Это рабочий фильтр для осмотра, который нужно заменить порогом, выбранным по вашему корпусу и задаче. Факт ухудшения подтверждается не порогом, а сравнением с базовой версией и ручной проверкой примеров.

Шаг 5. Проверьте визуально близкие точки в исходном пространстве

Обратная проверка ловит другую ошибку. Выберите пары, которые оказались рядом на карте, и пересчитайте их cosine similarity по исходным векторам. Если визуально близкая пара имеет низкое сходство, проекция создаёт ложное соседство.

Удобный отчёт содержит для каждой пары четыре поля: расстояние на карте, исходное cosine similarity, документ и отношение к границе чанка. Отсортируйте его по наибольшему расхождению между визуальной близостью и исходной близостью.

map_distance | cosine_similarity | left_id | right_id | same_document
0.041        | 0.982              | ...     | ...      | yes
0.052        | 0.214              | ...     | ...      | no

Первая строка похожа на подтверждённое соседство. Вторая — кандидат на ложный визуальный кластер. Но даже она не доказывает дефект индекса: возможно, карта просто потеряла одну из размерностей. Поэтому такие пары нужно проверять на нескольких проекциях и возвращать в retrieval-тест.

Шаг 6. Найдите дефекты границ чанков

Для RAG особенно важны не только кластеры документов, но и последовательность соседних чанков одного документа. Проверьте пары chunk_index = n и chunk_index = n + 1. Если они должны продолжать один смысловой фрагмент, но их векторы резко расходятся, причина может быть в границе чанка.

Ищите четыре характерных сигнала:

  • соседние по тексту чанки неожиданно удалены друг от друга;
  • один чанк стабильно тянется к документам другой темы;
  • в начале или конце чанков повторяются обрезанные предложения;
  • одинаковые заголовки создают отдельные ложные кластеры.

Разделите случаи на «граница внутри предложения», «граница между абзацами» и «граница между смысловыми блоками». Наличие первой категории — сильный повод проверить splitter. Но близость соседних чанков не всегда желательна: таблицы, списки и смена темы могут корректно разделять их.

Шаг 7. Сопоставьте карту с реальным индексом

Нельзя считать, что точный поиск по массиву векторов автоматически описывает production-поведение. Сравните для одной и той же контрольной выборки:

  • точных cosine-neighbors;
  • соседей, возвращённых ANN-индексом;
  • результаты после фильтров по метаданным;
  • итоговые чанки, которые получает генератор ответа.

Если точные соседи хорошие, а ANN возвращает другие точки, исследуйте параметры индекса и размер кандидатов. Если ANN совпадает с эталоном, но ответный retrieval теряет нужный чанк, ищите проблему в фильтрах, дедупликации, ограничении top_k или постобработке.

Как выглядит убедительный результат

Диагностика считается полезной, если она приводит к проверяемому действию. Хороший отчёт для каждой найденной области содержит:

  1. идентификаторы подозрительных чанков;
  2. их исходных ближайших соседей и значения cosine similarity;
  3. recall локальных соседей после проекции;
  4. границы текста и метаданные источника;
  5. гипотезу: splitter, модель, нормализация, ANN или фильтр;
  6. повторную проверку после изменения только одного фактора.

Например, карта показывает разрыв последовательных чанков, а исходное пространство подтверждает низкое сходство только у чанков, обрезанных посреди предложения. После изменения размера overlap повторная выборка уменьшает число таких разрывов, а retrieval-проверка возвращает нужный контекст чаще. Это уже диагностическая цепочка, а не интерпретация изображения.

Типовые ошибки

  • Считать кластеры фактом. Проекция — способ сформулировать гипотезу, не замена метрике.
  • Сравнивать разные корпуса. Изменение модели, нормализации или фильтров ломает прямое сравнение.
  • Терять идентификаторы. Сопоставление по позиции строки после сортировки даёт ложные выводы.
  • Проверять только среднее. Средняя сохранность соседей может скрывать провал на одном типе документов.
  • Смешивать точный и ANN-поиск. У них разные источники расхождений и разные параметры.
  • Публиковать сырой текст. Диагностический файл может содержать конфиденциальные данные.

Ограничения метода

Карта не восстанавливает исходную геометрию и не оценивает качество ответов сама по себе. Сохранённые соседи измеряют локальную структуру, но не полноту retrieval по пользовательским вопросам. Низкий recall на проекции может быть следствием агрессивного сжатия, а не дефекта индекса.

Поэтому итоговую проверку проводите на трёх уровнях: геометрия исходных embedding, поведение индекса и качество найденного контекста на заранее зафиксированной контрольной выборке. Не меняйте splitter и модель одновременно: иначе карта покажет разницу, но не объяснит её причину.

Короткий протокол

  1. Зафиксировать корпус, модель, нормализацию и параметры индекса.
  2. Посчитать исходных cosine-neighbors.
  3. Построить проекцию с сохранёнными идентификаторами.
  4. Измерить recall сохранённых соседей по точкам и группам.
  5. Проверить визуально близкие пары в исходном пространстве.
  6. Сопоставить выбросы с границами чанков.
  7. Сравнить точный поиск, ANN и retrieval с фильтрами.
  8. Повторить измерение после одного контролируемого изменения.

Дополнительные практические материалы собраны в разделе guides, а определения терминов — в глоссарии.