Обзор GraphRAG

GraphRAG — режим retrieval-а для модуля Knowledge, дополняющий векторный поиск графом знаний, построенным из тех же чанков. Где plain RAG возвращает k чанков, ближайших к вопросу, GraphRAG дополнительно проходит по путям сущность-связь — это позволяет отвечать на вопросы, доказательства для которых разбросаны по нескольким документам.

Это не отдельный продукт. GraphRAG работает поверх той же таблицы KnowledgeChunk, что и Knowledge RAG; добавляются две таблицы — GraphNode и GraphEdge, наполняемые LLM-проходом при ingest-е.

Статус

При выключенном includeGraph эндпоинт ask ведёт себя ровно как Knowledge RAG. При включённом — vector retrieval смешивается с graph hop, и evidence-чанки склеиваются.

GraphRAG vs plain RAG

Правило: если ответ требует склеить факты из разных документов — GraphRAG стоит лишней стоимости ingest. Если ответ уже в одном — plain RAG быстрее, дешевле и точно так же точен.

Как строится при ingest

Драйвер — buildGraphFromChunks в packages/api/modules/knowledge/lib/graphrag.ts. Для каждого IngestionJob, после чанкинга и эмбеддинга:

1. Entity resolution. LLM-проход по чанку извлекает именованные сущности с canonical name и семантическим типом («Product», «Person», «API», «Concept»…). См. resolveEntitiesFromChunks в entity-resolution.ts.
2. Фильтр. Чанки с менее чем 2 сущностями отбрасываются — связь не сформировать.
3. Relation typing. Второй LLM-проход по тем же чанкам с уже разрешёнными сущностями извлекает направленные связи с confidence. См. extractRelationsFromChunks в relation-typing.ts.
4. Запись графа. Каждая сущность → upsertGraphNode (matched by (spaceId, canonicalName, nodeType)). Каждая связь → новый GraphEdge с evidenceChunkId, чтобы ответ мог цитировать оригинал.

Граф append-only при ingest — повторный ingest того же источника добавит новые evidence-edges, но не удалит старые. Per-source ребилд без re-embedding — roadmap.

Community detection

Когда edges накопятся, алгоритм Louvain кластеризует плотные окрестности в сообщества (listCommunities, getCommunity). Каждое сообщество — мягкий кластер связанных концептов, удобный для «какие темы в этом space» и для сужения GraphRAG retrieval-а до подграфа.

Сообщества пересчитывает scheduled job graphragCommunities. Реализация Louvain и LLM-naming — community-detection.ts.

Как идёт GraphRAG-запрос

const result = await orpc.knowledge.graphragExplain.call({
  spaceId: "ks_…",
  question: "Как wallet ledger обрабатывает promo balances?",
});

Путь запроса:

1. Anchor extraction. Вопрос эмбеддится, определяются top-k чанков. Сущности из них — anchor nodes.
2. Graph hop. От каждого anchor идём по исходящим и входящим edges с relationType, подходящим под intent вопроса. По умолчанию — 1 hop; 2 — opt-in.
3. Evidence gather. Для каждого пройденного edge evidenceChunkId резолвится в текст чанка.
4. Answer synthesis. Anchor-чанки + пройденные чанки → LLM. Ответ цитирует исходные документы.
5. Path output. В ответе — path: упорядоченный список (fromNode, relation, toNode). UI может отрисовать «почему этот ответ».

Shape — { answer, sources, chunks, path: GraphPath[] }. path — то, что отличает graphragExplain от ask.

Когда GraphRAG — не тот инструмент

• Маленькие spaces. < 20 документов — связей мало, граф ничего не добавит над plain retrieval.
• Сильно структурированный контент. Каждый документ самодостаточен — граф мало даёт.
• Шумный текст / OCR. LLM entity-resolution втягивает мусор. Plain RAG устойчивее.
• Cost-sensitive workflow. Ingest-time build = 2 лишних LLM-прохода на чанк. На масштабе чувствительно.

Форма стоимости при ingest

Ориентировочно на чанк:

embedding (всегда) + entity-resolution + relation-typing
   1×                  1×                  0.5–1× (только при ≥ 2 сущностях)

GraphRAG-ingest — 2–3× plain Knowledge ingest. Резерв соответственно; см. CREDIT_RATES.knowledge_graph_build.

При чувствительной стоимости — включайте GraphRAG только в тех spaces, куда реально приходят многодокументные вопросы. Per-space флаг — KnowledgeSpace.ragConfig.graphragEnabled; по умолчанию off.

Tenant isolation

Граф namespaced по knowledgeSpaceId. GraphNode.canonicalName уникален в пределах space; «OpenAI» в space A и в space B — разные строки. Cross-space traversal недопустим (Инвариант 5).

Связанные страницы

• GraphRAG entity model — GraphNode, GraphEdge, схема, evidence
• GraphRAG use cases — конкретные паттерны
• Обзор Knowledge RAG — нижележащий chunk + ask слой
• Knowledge evaluation — реально ли граф помогает на вашем eval-сете