На этой странице

Построение и использование графа знаний

Подготовьте и постройте граф

  1. Выберите управляемое хранилище на pgvector, Qdrant или Weaviate. ContextBase строит граф из канонических чанков, поэтому проиндексируйте исходные документы в пространстве. Сам граф хранится в PostgreSQL платформы.

  2. Настройте языковую модель. Возьмите шаблон graphrag или добавьте ретривер graph в конвейер. Если он единственный, задайте объединение identity. Если есть ещё ретривер, используйте объединение вроде rrf. В шаблоне стоит генератор ответов по фрагментам.

  3. Запросите сборку через POST /api/v1/spaces/{space_id}/graph/rebuild с правом настройки пространства. Код 202 Accepted означает, что работа поставлена в очередь. API возвращает 409, если в пайплайне нет ретривера графа и граф ранее не строился. Проверяйте состояние через GET /api/v1/spaces/{space_id}/graph/status.

  4. Когда состояние станет built, задайте вопрос об известной сущности и посмотрите, к каким источникам ведут результаты. Сравните с поиском по фрагментам, прежде чем увеличить объём корпуса или поменять настройки.

При сборке модель извлекает из чанков сущности и связи. ContextBase объединяет сущности в сообщества и привязывает их к исходным фрагментам. На каждый извлекаемый фрагмент может уйти вызов модели, а на сводки и разбор спорных совпадений нужны дополнительные вызовы. Начните с небольшого типового корпуса, особенно при оплате за запросы. При изменении документов или настроек проверьте состояние и перестройте граф. Если изменилось только представление векторов сущностей, достаточно пересчитать их из уже построенного графа.

Запрос сборки · Реализация сборки

Выберите локальный или глобальный режим

  • Локальный. Ретривер graph находит упомянутые сущности и возвращает связанные фрагменты с контекстом графа. Вместе с обычным генератором llm это подходит для вопросов вроде «Какие команды обслуживают линию 4 и где указаны их обязанности?»

  • Глобальный. Генератор graph_global использует сводки сообществ. Задайте ему вопрос об основных темах, например «Какие риски при обслуживании чаще всего упоминаются в инструкциях?» Для генератора нужен ретривер graph в конвейере.

Настройки построения

Настройте эти параметры в ретривере graph:

  • В entity_types по умолчанию входят person, organization, location, event, concept и work. Оставьте типы сущностей, связи между которыми нужны для ваших вопросов.

  • При extraction_share=1.0 модель обрабатывает все доступные фрагменты. Уменьшите долю, чтобы обработать наиболее центральные фрагменты по сходству плотных векторов. Остальные фрагменты можно связать по упоминаниям сущностей. Новых сущностей и связей они не добавляют.

  • build_model, build_api_base и build_temperature уточняют параметры модели для извлечения, сводок и разрешения неоднозначностей. build_concurrency ограничивает число одновременных вызовов. Если параметр не задан, действует лимит установки.

  • clustering_resolution=1.0 задаёт детализацию группировки, а clustering_seed=0 — начальное значение для воспроизведения разбиения. unlinked_group_size=32 задаёт размер группы несвязанных сущностей на грубом уровне.

  • При community_summary_source="at_build" сводки пишутся во время сборки. Режим on_demand переносит эту работу на момент запроса. Сравните стоимость сборки и задержку ответа.

  • entity_resolution_normalize и entity_resolution_match_spellings включены по умолчанию. Порог сходства написаний — entity_resolution_threshold=0.85. entity_resolution_match_vectors и entity_resolution_ask_model выключены по умолчанию. Для сопоставления по векторам порог по умолчанию — entity_resolution_vector_threshold=0.95.

Настройки локального поиска

По умолчанию сущности ищутся по словам (entity_search_mode="words"). Доступны также vectors и both. При поиске по векторам укажите entity_vector_text="name" (по умолчанию) или name_and_description. Для выбранного представления в графе должны быть соответствующие векторы. Векторное совпадение должно достигнуть порога entity_search_threshold=0.75. entity_search_requires_description по умолчанию включён. entity_top_k ограничивает число сущностей, дающих контекст. Если параметр не задан, действует глубина поиска. Размер итоговой выдачи по-прежнему считается во фрагментах.

Флаги include_source_fragments, include_entity_context и include_community_summaries по умолчанию включены. community_summary_levels="base" — стандартный режим, также доступен base_and_coarse. Параметр context_budget ограничивает объём собранного контекста в символах. Если предел не задан, он зависит от глубины поиска. fragment_context_share=0.5 и community_context_share=0.1 выделяют место фрагментам и сводкам. Сумма долей меньше 1, чтобы оставалось место для сущностей и связей.

Глобальный ответ по графу (graph_global)

После построения графа установите генератор graph_global. Он составляет частичные ответы по сводкам сообществ, оценивает пользу каждого и объединяет отобранные ответы. Контекст берётся из графа. Проверяя отдельное утверждение, сверяйтесь также с исходными фрагментами.

Режим entry="level" по умолчанию начинает с самого общего доступного уровня. Параметр level позволяет выбрать начальный уровень. В обоих случаях генератор может спускаться к более мелким сообществам. Режим entry="retrieval" читает базовые сообщества найденных сущностей и остаётся на базовом уровне. Для него нужен конвейер без преобразований запроса. Если сущности не найдены, обзорный ответ не формируется.

{
  "node": "graph_global",
  "params": {"entry": "level", "map_top_k": 8, "map_budget": 32}
}
  • map_top_k=8 ограничивает число лучших частичных ответов, которые попадут в итоговый синтез после всего обхода. min_score=1 (от 0 до 100) задаёт минимальную оценку для отбора.

  • При entry="level" бюджет map_budget=64 проверяется между уровнями. После достижения бюджета генератор прекращает спуск. Начатый уровень он обрабатывает целиком, поэтому число оценённых сводок может превысить бюджет. При entry="retrieval" тот же параметр строго ограничивает число чтений найденных сообществ, начиная с самых релевантных. За одно чтение считается сводка или фрагмент крупного сообщества.

  • map_concurrency ограничивает число одновременных вызовов модели для одного вопроса. По умолчанию действует лимит установки. Поля model, api_base и temperature уточняют настройки генерации. При построении сводок по запросу community_summary_budget=16 на ретривере задаёт бюджет сводок на уровень глобального обхода.

Запрос с metadata_filter на этом пути генерации получает 409. Чтобы отобрать документы по метаданным в том же пространстве, вызовите /search. Поддерживаемые настройки описаны в Генерация ответа и просмотр источников.

Настройки графа · Глобальный генератор

Состояние и проверка результатов

  • absent: убедитесь, что выбран ретривер графа, и запустите сборку. building: дождитесь завершения работы исполнителя.

  • stale: посмотрите outdated_settings, predating_settings и build_settings_known перед перестроением. Поля built_at и extracted_at помогут понять, перечитывался ли корпус.

  • built, но сущности не находятся: изучите skipped_fragments (сбои извлечения) и unextracted_fragments (вне извлечения). Второй результат возможен при extraction_share меньше 1.

  • Много изолированных сущностей: изучите extracted_entities, resolved_entities, base_communities и mean_community_size. Попробуйте другие типы сущностей или настройки разрешения на выборке перед следующей большой сборкой.

  • Нет ссылок на источники: проверьте relations_without_sources и dropped_sources. При повторном разбиении документа его старые чанки могут замениться, поэтому граф теряет ссылки на них. Описание из графа и исходный фрагмент нужно различать при проверке.

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

Реализация статуса графа

ContextBase0.1.0

Поиск в документации