Skip to main content

Tune the knowledge engine

The Settings tab of Knowledge Management configures the knowledge engine behind every knowledge source: how documents are parsed and split, which embedding model turns them into vectors, how retrieval ranks results, and what curators may do with document metadata. A change applies to every source and takes effect without a restart.

Who can use it: the Admin role or the Knowledge Admin grant, in Control Room under Knowledge. A Super Admin's changes are saved platform-wide; another administrator's changes apply to your organisation only.

Prerequisites​

  • An embedding model in the AI Gateway's Embedding tier. The Model field lists those models; without any, you can type a model ID.
  • For GPU parsing, an NGC API key on the Credentials tab of Platform Settings and GPU capacity.

How settings are layered​

Defaults come from the environment. Overrides are stored at two levels, platform-wide and per organisation, and merged on every request. A field marked Override was customised at your level: Reset removes the override, and Reset section clears every override in a section. Inherited marks a platform-wide value you cannot reset here; Unsaved marks an edit not yet saved, with Undo change (the circular arrow) beside it.

Presets: stage a set of edits for review: Accuracy (larger chunks, the semantic strategy, more rerank candidates, HyDE on), Speed (small chunks, token splitting, fewer candidates, query routing, no HyDE) and Balanced (the environment defaults). Applying one asks you to confirm, then shows the changes as unsaved edits.

Search settings... filters fields, the strip of section names jumps to a section, and Advanced (N settings) reveals the rarely changed fields; the fields of HyDE, Entity graph and Document metadata are disabled while the section's first toggle is off.

The Settings tab of Knowledge Management: the Search settings box, the Presets Accuracy, Speed and Balanced, Export and Import, the section strip Embedding Model, Chunking, Retrieval, HyDE, Parsing, Entity graph, Document metadata, Permissions and Uploads, the How it works toggle, and the Embedding Model section with Model, Dimensions, Batch Size, Concurrent Batches, Normalize Vectors and Advanced (4 settings).The Settings tab of Knowledge Management: the Search settings box, the Presets Accuracy, Speed and Balanced, Export and Import, the section strip Embedding Model, Chunking, Retrieval, HyDE, Parsing, Entity graph, Document metadata, Permissions and Uploads, the How it works toggle, and the Embedding Model section with Model, Dimensions, Batch Size, Concurrent Batches, Normalize Vectors and Advanced (4 settings).
The Settings tab opens on the Embedding Model section. The strip under the presets jumps to any of the nine sections; every field shows a hint and, where a change costs something, an Impact line.

The nine sections​

SectionWhat it controlsWhat you decide
Embedding ModelThe model, its dimensions, batch size, concurrency and vector normalisation.Which model; changing it later re-embeds everything.
ChunkingChunk size and overlap, token or semantic splitting, headings and tables.Chunk size and overlap.
RetrievalResults returned, search timeout, reranking and its thresholds, dense weight, query routing.Whether reranking is on.
HyDEEmbedding a generated hypothetical answer instead of the raw question.Extra recall against added latency and one more model call per query.
ParsingCPU or GPU document parsing and image OCR through a vision model.The parsing mode.
Entity graphEntity extraction at ingest that boosts or injects related passages at query time.Whether ingest may take twice as long.
Document metadataShowing, curating and filtering by extracted metadata, and the Metadata fields registry.Whether curators may correct metadata.
PermissionsPermission cache lifetimes and the pre-filter threshold.Fresher access checks against more load.
UploadsThe largest file and request accepted by direct upload.The caps for your organisation.

Decide on day one​

  1. Choose the embedding model

    Model lists the gateway's embedding models with their dimensions and provider. Picking one fills Dimensions, Batch Size, Chunk Size and Chunk Overlap from the model's profile, shown under Auto-configured for the model. Changing the model later warns that every existing source becomes stale and needs a full re-embedding.

  2. Set chunk size and overlap

    Chunk Size (64 to 4,096 tokens) trades context per result against precision: doubling it roughly halves the chunk count. Chunk Overlap (0 to 512 tokens) keeps context across chunk boundaries at the cost of more chunks. Strategy is token_based or semantic, Respect Headings never splits across a heading, and Table Strategy keeps a table whole or splits it by row.

    The Chunking section: its description How documents are split into chunks before embedding, then Chunk Size and Chunk Overlap each with a hint, an Impact line, a token input and its range, Strategy with the options token_based and semantic, and Respect Headings with its toggle.The Chunking section: its description How documents are split into chunks before embedding, then Chunk Size and Chunk Overlap each with a hint, an Impact line, a token input and its range, Strategy with the options token_based and semantic, and Respect Headings with its toggle.
    Chunking decides how documents are split before embedding. Chunk Size and Chunk Overlap are the two values to decide on day one; their Impact lines say what doubling either one costs.
  3. Decide on reranking

    Enable Reranking is on by default and calls the AI Gateway's reranking tier on every search. While no model is assigned to that tier, turn it off: results then come back in similarity order, gated by the Similarity Threshold instead of the Rerank Threshold.

  4. Pick the parsing mode

    Parsing Mode is unstructured (CPU, the default) or nvidia (GPU, several times faster on PDFs and images, and it needs the NGC API key and GPU capacity). Image OCR (vision) is off by default and needs a vision-capable model in the gateway. Set Image OCR Model (under Advanced) to a registered vision model's exact ID: nothing validates it, and an untagged gpt-4o-mini is only the default.

  5. Decide on metadata curation

    Enable metadata features shows extracted metadata on the Documents tab. Allow curation lets curators correct values, which are stored separately and survive a re-sync. Auto-declare found keys makes the keys documents carry filterable, and Narrow by the question (off by default) searches matching documents first. Under Metadata fields, Define a metadata field adds a custom field with a key, label and type.

Save and review​

  • A section with edits shows Save changes, which opens Review changes listing each field's old and new value; Confirm & Save applies them. When the embedding model or its dimensions change, the review warns This change requires re-embedding ALL knowledge sources and the button reads I understand - Save & re-embed.
  • With edits in several sections, a bar counts the unsaved changes with Discard and Save all; Save all asks you to confirm, or warns that a re-embed is required.
  • After a model change, sources not yet re-embedded are excluded from search and marked Stale on the Sources tab, whose banner offers Re-embed all.

Export and import​

Export downloads the current settings as a JSON file. Import opens Import Settings: paste a previously exported file or Choose File, Review Changes lists what would change, and Confirm & Import overwrites the matching sections.

Verify​

The saved fields show Override, the section header counts its overrides, and a toast confirms the section was saved or All settings saved. Run a query on Search & Test to see the effect.

Troubleshooting​

  • knowledge-engine not reachable.: the engine is down. Ask your administrator to check the service and reload.
  • knowledge-engine is busy.: the request timed out, often during a large sync. Reload in a moment.
  • Fix validation errors before saving: a number is outside its range or not a number.
  • No active embedding models found in AI Gateway. Add models to the Embedding tier in AI Gateway, or type a model ID manually.: the gateway has no embedding model yet.
  • No embedding model configured. on the Sources tab, with Connect Source disabled: save a Model here first.

Describes the platform as of .

Was this page helpful?