GraphRAG — сущности, сообщества и утверждения

Лёгкий GraphRAG поверх текста ваших собственных документов — без выделенной графовой базы данных или офлайн-сервиса кластеризации. Это спутник ассистентов: ассистент подмешивает в ответы соседей сущности и отчёты сообществ, когда это уместно, а операции этой страницы — то, чем эти графы строятся и как их можно опросить напрямую.

Каждой операции нужен полный ключ, и, кроме простых чтений и удалений, она оплачивается из кошелька кредитов (см. кредиты). listGraphEntities — единственное чтение графа, доступное напрямую поисковому ключу (см. ключи и области доступа).

Извлечение сущностей и связей

generateGraphEntities — POST /collections/{collectionName}/graph/entities/generate — читает text_fields у каждого из document_ids (до 50), просит модель назвать упомянутые сущности и связи между ними и записывает их:

await client.graph.generateGraphEntities({
  collectionName: "products",
  body: { document_ids: ["42", "43"], text_fields: ["description", "specs"] },
});

Сущность с уже известным точным name получает этот документ в свой source_doc_ids вместо дублирующей строки. Новое имя, не совпавшее точно, всё равно сопоставляется семантически с существующими сущностями коллекции того же type по близости эмбеддингов — «De Walt», достаточно похожий на «DeWalt», сворачивается в алиас, а не становится второй сущностью. Вместе с сущностями сохраняются и структурированные фактические утверждения («claims») — о возможностях, сертификации, совместимости, цене — всё, что подтверждает текст.

status утверждения (confirmed, suspected, disputed, unverified) отражает, насколько уверен исходный текст, а не уверенность модели в том, что она правильно его прочитала.

Этот шаг запускается вручную и инкрементально по замыслу, а не по расписанию — извлечение дорогая часть, поэтому само по себе ничего не выполняется. Запускайте его снова по мере индексации новых документов или чтобы охватить больше каталога.

Группировка сущностей в сообщества

generateGraphCommunities — POST /collections/{collectionName}/graph/communities/generate — группирует связанные сущности (обычные компоненты связности, не Лейден) в иерархию: уровень 0 — самая мелкая группировка, каждый следующий уровень — более грубое объединение предыдущего, до max_levels. Для каждой группы не меньше min_size сущностей на каждом уровне модель пишет короткий заголовок и summary, эмбеддится для семантического поиска:

await client.graph.generateGraphCommunities({
  collectionName: "products",
  body: { min_size: 3, max_levels: 3 },
});

Запускайте снова после того, как generateGraphEntities добавит достаточно сущностей, чтобы изменить форму графа, — запуск заменяет существующие отчёты коллекции. listGraphCommunities (GET /collections/{collectionName}/graph/communities) выводит их, сначала недавние; deleteGraphCommunity (DELETE /graph/communities/{communityId}) удаляет один.

Широкие вопросы через Global Search

globalSearchGraph — POST /collections/{collectionName}/graph/global-search — это map-reduce GraphRAG: каждый отчёт сообщества на уровне level (по умолчанию — самый грубый из сгенерированных, для наименьшего числа самых широких отчётов) получает один вызов модели с вопросом, какие пункты он предлагает в ответ на question, каждый с оценкой релевантности 0–100 (шаг «map», выполняется параллельно, не больше max_communities отчётов — при их избытке на уровне выбираются самые похожие на question по эмбеддингу). Каждый пункт выше порога релевантности идёт в один финальный вызов «reduce», который синтезирует ответ:

const result = await client.graph.globalSearchGraph({
  collectionName: "products",
  body: { question: "Какие дрели у нас есть и чем они отличаются?", max_communities: 10 },
});
// result.answer, result.communities_considered, result.sources

Используйте его для вопросов «как это всё связано», слишком широких для контекста одного документа.

Конкретные вопросы через DRIFT

driftSearchGraph — POST /collections/{collectionName}/graph/drift-search — сначала запускает праймер Global Search по отчётам уровня level (max_communities штук), чтобы получить промежуточный ответ и уточняющие вопросы, на которые отчёты сами по себе не отвечают. Каждый из первых max_follow_ups уточняющих вопросов затем получает свой Local Search — сущности, ближайшие к нему по эмбеддингу, их соседей на один переход и утверждения о них, — а финальный вызов синтезирует праймер с локальным ответом на каждый уточняющий вопрос:

const result = await client.graph.driftSearchGraph({
  collectionName: "products",
  body: { question: "Какая дрель лучше для бетона и что ещё нужно?", max_follow_ups: 3 },
});
// result.answer, result.primer_answer, result.follow_ups

Используйте DRIFT вместо Global Search, когда у вопроса конкретный узкий ответ (рекомендация одного товара), который широкие отчёты сообществ сами по себе не покрывают; Global Search — когда вопрос действительно про весь каталог.

Стоимость

Извлечение и поиск каждый раз запускают один или несколько вызовов модели и списываются с кошелька кредитов: извлечение сущностей и утверждений — за обработанный документ, отчёты сообществ — за сообщество, Global Search — за каждый отчёт на шаге map плюс один reduce, DRIFT — за праймер, за каждый отвеченный уточняющий вопрос и один reduce. См. кредиты.