RAG Setup
Create a knowledge base, link it to a Customize Model, and configure and validate the current Hybrid RAG flow.
Retrieval-Augmented Generation (RAG) searches linked knowledge bases for relevant chunks before a Customize Model answers, then adds the retrieved content to the context of that request. The model can use your documents without retraining the base model.
Linking a knowledge base grants the model permission to retrieve that data. It does not write the documents permanently into model weights. Document access, indexing state, and Customize Model settings remain separate.
Before you begin
Confirm that:
- A usable Customize Model already exists.
- You have use access to the target knowledge base.
- The knowledge base contains at least one Ready or Indexed document.
- Its creator or co-editors completed the required parser-model setup, and the expected chunks appear on the knowledge base Search page.
A file that is only queued for upload or has not finished parsing and indexing cannot appear in RAG results.
Build the RAG flow
Create a knowledge base
Choose a personal space or organization in the sidebar, open My knowledge base, and select New knowledge base. Enter a name, optional description, and any co-editors, then select Create.
Add documents and wait for indexing
Open the knowledge base and select Add new → Upload files, or choose Sync from S3. After choosing local files, select Start and wait until each required document is Ready or Indexed.
PDFs, Office files, text, tables, images, video, and audio use different parsing flows. See Upload and Manage Documents for formats, required models, and quota limits.
Test knowledge-base search first
Select Search in the upper-right corner of the knowledge base and test Hybrid Search with real questions. Verify the chunks, source documents, and scores before linking the knowledge base to a model.
Link the Customize Model
Open the Customize Model and go to Data → Knowledge base. Under Linked knowledge bases, select one or more knowledge bases you can access. Selection changes are saved automatically.
Configure retrieval behavior
Go to Behavior → Agent Loop and configure Top K, maximum iterations, minimum score, and whether Agentic RAG is enabled. These changes are also saved automatically.
Validate in Playground
Select Try in Playground and ask a question that requires the documents to answer. For example:
What does our refund policy say about digital products? Identify the source.Confirm that the response uses the correct documents, preserves important conditions, and includes enough source information to trace the answer.
Retrieval settings
| Setting | UI default | Range | Description |
|---|---|---|---|
| Enable Agentic RAG | Off | — | Runs an Agentic think-search and tool loop before producing the final answer |
| Top K results | 5 | 1–50 | Maximum chunks returned to the LLM at the end of each retrieval round |
| Max iterations | 3 | 1–10 | Maximum rounds available to the think-search or non-Agentic RAG flow |
| Min score | 0.18 | 0–1 | Filters results below this hybrid relevance score; leave blank for automatic behavior |
Top K results counts chunks, not documents or pages. One document can contribute several chunks, and results from all linked knowledge bases share the global Top K limit.
Linking knowledge bases versus enabling Agentic RAG
- Data → Knowledge base determines which knowledge bases the model can search.
- Behavior → Agent Loop → Enable Agentic RAG determines whether the Runtime uses Agentic planning, repeated think-search, and tool calls.
- Disabling Agentic RAG does not unlink knowledge bases. The Runtime can still perform non-Agentic RAG over linked content.
- With no linked knowledge base, knowledge-base retrieval is skipped even if Agentic RAG is enabled.
How Runtime retrieves content
Each linked knowledge base uses Hybrid Search:
- Dense vector search finds semantically similar chunks.
- BM25 finds chunks containing exact terms.
- Runtime blends semantic and lexical scores and applies Min score.
- Results from multiple knowledge bases are merged, deduplicated, sorted, and limited by the global Top K.
- The final chunks and their knowledge-base, document, page, image, and source-URI metadata are added to request context.
If vector retrieval is unavailable, or no result is found under conditions that allow fallback, Runtime can use page content as a fallback. Search warnings and the actual retrieval mode appear in RAG metadata.
Agentic and non-Agentic flows
With Enable Agentic RAG on, Runtime plans the next action, creates or updates retrieval keywords, searches knowledge bases, accumulates required evidence, and can use configured API, SQL, MCP, or skill tools. It produces the final answer after enough evidence is available or a stop condition is reached within Max iterations.
With Enable Agentic RAG off, linked knowledge bases still participate in RAG. Runtime searches with the original question and generated keywords, organizes results within the iteration budget, and adds retrieved context to the model request.
Test and diagnose
Test in three layers so you can locate the source of a problem:
- Knowledge base → Search: verify that Hybrid Search returns the expected chunks and test result limit and Min score.
- Customize Model → Playground: verify that the model correctly understands and combines retrieved content.
- Operate → Request Logs: inspect the actual request, RAG metadata, retrieval rounds, and source information.
Runtime retains document names, chunk IDs, pages, and source metadata, but it cannot guarantee that a model will print citations in its natural-language answer. If citations are required, explicitly request document names, page numbers, or source URIs in the System Prompt, then validate the format in Playground.
Multiple knowledge bases
A Customize Model can link multiple knowledge bases that it is allowed to use. Runtime searches each knowledge base in parallel and merges the global results. This is useful for:
- Maintaining policies, product documentation, technical manuals, and FAQs separately.
- Allowing different teams to manage their own knowledge bases while one model uses them together.
- Manually switching knowledge-base combinations to compare how different datasets affect answers.
More linked knowledge bases increase retrieval work and may introduce similar or duplicate content. There is no dedicated knowledge-base A/B testing button; change the linked set manually and compare answers to the same questions.