Dify knowledge base tutorial: chunking, indexing and retrieval

What a knowledge base does

A model only knows what it learned in training. A knowledge base gives an app your own content, such as a help center, internal policies or a product catalog. When a question arrives, Dify finds the most relevant passages and passes them to the model with the question, so the answer draws on your content. That is retrieval-augmented generation, built from scratch in the RAG tutorial.

Dify Cloud offers two kinds. In a classic knowledge base you decide how content is chunked, indexed and searched. An agent knowledge base, in beta, organizes and indexes everything on its own. The self-hosted docs describe only the classic kind, so most of this lesson covers it, and the last section covers the agent kind.

Create a knowledge base and upload files

A classic knowledge base comes down to three decisions: how files are chunked, how chunks are indexed and how results are searched. The upload comes first. On a self-hosted install the upload limits are environment settings: UPLOAD_FILE_BATCH_LIMIT for files per upload and UPLOAD_FILE_SIZE_LIMIT for file size.

Images get a little extra care. Small images, under 2 MB in JPG, PNG or GIF format, become attachments of their chunks when they sit inside Word and Excel files. The same happens when any file links them with Markdown image syntax. They come back alongside their chunks at retrieval time.

1. Click Knowledge > Create > Create a ready-to-use knowledge base.
2. Select Import from file as the data source and upload your files.
3. Pick the chunk mode and its settings, then click Preview to see how the content will be split.
4. Choose the index method and the retrieval settings, covered in the sections below.

The data source can't be changed once the knowledge base is created. The chunk mode can't change either, though the delimiter and the maximum chunk length can be adjusted at any time.

Chunk settings

Chunking splits each document into smaller segments called chunks. When someone asks a question, Dify searches the chunks and gives the relevant ones to the model as context, because reading whole documents for every query would be slow. The chunking lesson covers the strategies in general.

Two settings apply in every mode. The delimiter is where text is split, such as a double line break for paragraphs. The maximum chunk length, in characters, forces a split in text that runs over it. Delimiters are removed during chunking, so with A as the delimiter, CBACD becomes CB and CD. The docs advise a character that does not appear in your content.

General mode adds chunk overlap, so the end of one chunk reopens the next. With an overlap of 50 characters, the end of one chunk is repeated at the start of the next. In Parent-child mode the parent chunk is either a Paragraph or the Full Doc, and Full Doc processes only the first 10,000 tokens.

Before splitting, you can replace runs of spaces, newlines and tabs, and remove all URLs and email addresses. Full Doc mode ignores the second option. Summary Auto-Gen writes a summary for every chunk and indexes the summaries too, so a summary that matches a question brings its chunk back with it.

Index method and search settings

High Quality indexing uses an embedding model to turn each chunk into a vector, so a search can match meaning and not only exact words. The embeddings lesson explains the idea. Economical indexing keeps 10 keywords per chunk, spends no tokens and retrieves less accurately, using an inverted index, the keyword lookup structure that web search engines use. It supports only Top K. An Economical knowledge base can be upgraded to High Quality in its settings. A High Quality one can't switch back.

High Quality offers three search methods: vector search, full-text search and hybrid search. Hybrid runs both and reorders the results. In hybrid mode, Weight Settings need no rerank model. A semantic value of 1 uses vector search only, a keyword value of 1 uses keyword search only, and values between mix them. The docs suggest keyword weight when users know the exact terms, and semantic weight when the content lacks those terms or the queries cross languages.

A rerank model is off by default. When on, a third-party model re-sorts the chunks the search returned. Add its API key under Integrations > Model Provider first, because it spends the rerank model's tokens. Top K is how many chunks come back, and Score Threshold is the minimum similarity a chunk needs. The docs say both take effect in the rerank phase, so switch a rerank model on to apply them. Changing the embedding model later re-embeds every chunk.

Q&A mode, described in the self-hosted docs, writes question-and-answer pairs for each segment, so a user's question is matched against questions rather than paragraphs. The docs point it at FAQ-style documents.

Test retrieval before an app uses it

In a knowledge base, click the Retrieval Testing icon in the left sidebar. Type questions the way your users would and see which chunks come back. If you want numbers rather than a look, evaluating RAG shows how to score such results. Settings you change on that page are temporary and apply only to the current test session, so set the ones you keep in the knowledge base's own settings.

The Records section logs every retrieval: the questions you tested and the requests from linked apps, in test runs or in production. Test retrievals and regular retrievals use the same API endpoint.

Use it in a chatflow

A Chatflow reaches a knowledge base through the Knowledge Retrieval node. The User Input node collects the question, and Knowledge Retrieval searches the selected knowledge bases. It outputs a result list of chunks. The LLM node answers from the question and those chunks, and the Answer node returns the reply. The LLM node page gives this prompt for the context.

A Chatbot app has a simpler route. Open Context, click Add and pick a knowledge base, set the Retrieval Setting, turn on Citation and Attribution under Add Features, try it in Debug and Preview, then publish. With several knowledge bases linked, Dify searches all of them at once and a rerank step picks the best chunks. Weighted Score needs no extra model, but only works when every knowledge base uses High Quality indexing and the same embedding model.

Answer using only this context:
{{knowledge_retrieval.result}}

Question: {{user_question}}

1. Create a ready-to-use knowledge base and upload your file, as in the sections above.
2. In Studio, create a Chatflow and add a Knowledge Retrieval node after User Input.
3. In the node, set Query Text to the variable that holds the user's message. The docs' example is userinput.query. Add your knowledge base and open Retrieval Setting to choose the rerank setting, Top K and Score Threshold.
4. In the LLM node, connect the Knowledge Retrieval output to the context input and use the prompt above, replacing {{user_question}} with the user's message variable.
5. Add an Answer node that returns the LLM's reply. Dify tracks citations on its own, so users see where the information came from.
6. Click Preview and ask one question your document answers and one it does not.

The agent knowledge base on Cloud

The agent kind has no chunk mode or index method to choose. A reasoning model reads and organizes each document, an embedding model makes it searchable, and you pick the content, a retrieval depth and how many chunks come back. Its content can sync from a website, online documents or a drive on a schedule from 1 hour to 30 days, or by hand. The Cloud docs say a new project should start here.

Chatbot, legacy Agent and Text Generator apps can't search an agent knowledge base, and it can't be turned back into a classic one. Its pages sit in the Cloud docs only.

To test one, run questions on its Retrieval Test page. When a run returns the right chunks, keep it as a golden question, and after any change to a setting or model, run an evaluation under Quality to confirm that all golden questions still pass. When a chunk is missing or ranks too low, mark it as a bad case. Change one setting at a time and retest.

Common mistakes

• Treating the chunk mode as a default to fix later. It can't be changed after creation, though the delimiter and maximum length can.
• Picking High Quality and expecting to move back to Economical to save tokens. The docs allow only the other direction.
• Using a delimiter that appears in your text. The delimiter itself is removed during chunking, so every place it occurs becomes a cut and that character is gone from your chunks.
• Raising Top K or Score Threshold and seeing no change. Both apply in the rerank phase, so a rerank model has to be on.
• Switching rerank on and finding it does nothing, because no key was ever added for that model.
• Choosing Weighted Score across knowledge bases that use different embedding models or an Economical index. Dify shows an error or hides the option. The fix is a rerank model or one shared setup.
• Linking an agent knowledge base to a Chatbot app, which can't search it.

Try it yourself

• Upload one document and click Preview in General mode, then in Parent-child mode. Compare the chunks.
• Ask the same question on the Retrieval Testing page with Vector Search and then Hybrid Search. See which chunks change.
• Raise the Score Threshold until a question that worked returns nothing, then lower it again.

Next

Lesson 4 builds an agent app that calls tools, then publishes it as a web app, an API and an embed, and reads its logs. A knowledge base can be one of that agent's tools.

Frequently asked questions

Sources

1. Dify Docs (GitHub): Upload Local Files (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/create-knowledge/import-text-data/readme.mdx
2. Dify Docs (GitHub): Configure the Chunk Settings (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/create-knowledge/chunking-and-cleaning-text.mdx
3. Dify Docs (GitHub): Index Method and Retrieval Settings (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/create-knowledge/setting-indexing-methods.mdx
4. Dify Docs (GitHub): Test Knowledge Retrieval (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/test-retrieval.mdx
5. Dify Docs (GitHub): Manage Knowledge Settings (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/manage-knowledge/introduction.mdx
6. Dify Docs (GitHub): Integrate Knowledge within Apps (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/integrate-knowledge-within-application.mdx
7. Dify Docs (GitHub): Knowledge Retrieval node (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/knowledge-retrieval.mdx
8. Dify Docs (GitHub): LLM node (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/llm.mdx
9. Dify Cloud Docs (GitHub): Knowledge (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge/overview.mdx
10. Dify Cloud Docs (GitHub): Agent Knowledge Base (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/overview.mdx
11. Dify Cloud Docs (GitHub): Create an Agent Knowledge Base (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/create-knowledge-base.mdx
12. Dify Cloud Docs (GitHub): Retrieval Settings (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/retrieval-settings.mdx
13. Dify Cloud Docs (GitHub): Test and Tune Retrieval (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/test-and-tune.mdx
14. Dify Cloud Docs (GitHub): Connect to Apps, Agents, and Code (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/use-knowledge-in-apps.mdx