On this page
Build and query a knowledge graph¶
Prepare and build a graph¶
Use a managed storage binding on pgvector, Qdrant or Weaviate. ContextBase builds the graph from canonical chunks, so the source documents must be indexed in the space. The graph itself is stored in the platform’s PostgreSQL database.
Configure a language model. Start with the
graphragpreset or add thegraphretriever to your pipeline. For a graph-only retriever useidentityfusion. If you keep another retriever as well, select a fusion such asrrf. The preset uses ordinary grounded generation.Request a build with
POST /api/v1/spaces/{space_id}/graph/rebuildfrom a caller authorized to configure the space.202 Acceptedmeans the work is queued. With neither a graph retriever nor a previous graph, the API returns409. PollGET /api/v1/spaces/{space_id}/graph/status.When state is
built, try a question about one known entity and inspect the links to its sources. Record how it compares with passage search before increasing the corpus or changing settings.
The build extracts entities and relationships from chunks, groups related entities into communities and links them to source passages. It can call the model once per extracted chunk, plus additional calls for summaries and difficult entity matches. Start with a small, representative corpus, especially with a metered model. Source or build-setting changes can make a graph stale. Check status and rebuild. If only the entity-vector representation changed, the rebuild can re-embed existing entities.
Choose local or global use¶
Local. The
graphretriever follows named entities and returns linked passages with graph context. Use it with the ordinaryllmgenerator for questions such as “Which teams maintain line 4 and where are their responsibilities specified?”Global. The
graph_globalgenerator uses community summaries. Use it for a question such as “What kinds of maintenance risks recur across our manuals?” It needs agraphretriever in the pipeline.
Build settings and source changes can make an existing graph stale. Review its status, then request a rebuild. A change limited to the entity-vector representation can be served by re-embedding existing entities instead of prompting the model about every chunk again.
Build settings¶
Set these on the graph retriever:
entity_typesdefaults toperson,organization,location,event,conceptandwork. Focus this list on the types of entities your questions link together.extraction_share=1.0reads all eligible chunks with the model. Lower it to sample the most central fragments by dense-vector similarity. The platform can link unextracted chunks by the entities they name, but their text contributes no new entities or relationships.build_model,build_api_baseandbuild_temperaturecan override the space’s model for extraction, community summaries and model-assisted entity resolution.build_concurrencylimits concurrent calls. If unset, it uses the installation ceiling.clustering_resolution=1.0controls grouping, withclustering_seed=0by default.unlinked_group_size=32groups entities with no relationships at the coarse level.community_summary_source="at_build"writes summaries during the build.on_demanddefers the work until they are needed. Compare build cost and question latency for your workload.entity_resolution_normalizeandentity_resolution_match_spellingsdefault to true. The spelling threshold isentity_resolution_threshold=0.85.entity_resolution_match_vectorsandentity_resolution_ask_modeldefault to false. If you enable vector matching, the default threshold isentity_resolution_vector_threshold=0.95.
Local retrieval settings¶
The entity matcher defaults to entity_search_mode="words", with
vectors or both available. For vector matching, choose
entity_vector_text="name" (default) or name_and_description.
A graph must have entity vectors built for the selected representation.
A vector match must meet entity_search_threshold=0.75.
entity_search_requires_description defaults to true.
entity_top_k controls how many entities contribute their context.
When unset, it follows the retrieval depth. The result count still
counts passages.
The switches include_source_fragments, include_entity_context
and include_community_summaries are on by default.
community_summary_levels="base" is the default, with
base_and_coarse available. context_budget caps the assembled
context in characters and otherwise follows retrieval depth.
fragment_context_share=0.5 and community_context_share=0.1
reserve room for passages and summaries. Their sum must be below 1
to leave room for entities and relationships.
Generate a global answer (graph_global)¶
After building the graph, set the generator to graph_global.
This generator drafts partial answers from community summaries, rates
their usefulness and synthesizes the survivors. It uses graph summaries
as grounding. Consult source passages as well when checking a specific
claim.
Use entry="level" (default) to start at the coarsest available level,
or set level to choose the starting level. The generator can descend
into finer communities in either case. Use entry="retrieval" to read
the base communities of matched entities. It stays at the base level and
requires a path without query transforms. If entity matching finds
nothing, it returns no overview answer for that question.
{
"node": "graph_global",
"params": {"entry": "level", "map_top_k": 8, "map_budget": 32}
}
map_top_k=8limits the best partial answers selected from the entire walk for the final synthesis.min_score=1(0–100) is the minimum contribution score.map_budget=64is checked between levels inentry="level". It prevents further descent once reached. The generator always finishes the current level, so the actual count of evaluated summaries can exceed it. Inentry="retrieval"the same value is a hard cap on readings of the matched communities, strongest matches first. One reading can be a full summary or a part of a large community.map_concurrencylimits simultaneous model calls for one question and defaults to the installation ceiling.model,api_baseandtemperaturecan override generation settings. If summaries are written on demand,community_summary_budget=16on the retriever is the per-level summary budget for a global walk.
Requests with metadata_filter receive 409 on this generation path.
To use document filters in the same space, call /search for passages
from the retrieval pipeline. See Generate answers and inspect their sources for supported configurations.
Inspect status and compare results¶
absent: check that the pipeline includes a graph retriever and request a build.building: wait for the worker.stale: inspectoutdated_settings,predating_settingsandbuild_settings_knownbefore rebuilding. Comparebuilt_atwithextracted_atto see whether the corpus was read again.builtwith missing entities: checkskipped_fragments(failed extractions) andunextracted_fragments(outside extraction coverage). The second count can be expected whenextraction_shareis less than 1.Many isolated entities: inspect
extracted_entities,resolved_entities,base_communitiesandmean_community_size. Try more appropriate entity types or resolution settings on a small sample before a larger rebuild.Missing citations: review
relations_without_sourcesanddropped_sources. Recut documents can replace the chunks that a graph had linked to. A graph description and its source passage are different pieces of evidence.
Compare local results on a fixed set of entity questions and global answers on overview questions. Record source coverage, representative errors, runtime and model cost beside any quality score. Keep a plain-retrieval baseline. See Evaluate retrieval and answers.