FAQ
When you encounter knowledge base issues, first determine whether the failure occurs at the import, parsing, chunking, retrieval, or answering stage. Change only one variable at a time so you can tell which adjustment actually works.
The fastest way to locate the issue is to run the same real question through the whole check: whether the answer exists in the text, whether the chunk is complete, whether retrieval is correct, and whether the answer stays faithful to the source.
5 quick troubleshooting steps
3. Check the chunks
Confirm that the conditions and conclusions needed for the question are in understandable chunks; do not let headers, footers, and tables of contents dominate the results.
Where should the issue be reported?
Do not expose API keys, internal file contents, email addresses, or local sensitive paths in screenshots, logs, or sample documents.
Creation and import
Can I create a knowledge base without an embedding model?
Yes. After selecting [Do not use], BM25 keyword retrieval will still be used. Add an embedding model later if you need to match different expressions.
What sources and file formats are supported?
Sources include files, Cherry Studio notes, local directories, and web links. Supported file formats include PDF, DOCX, DOC, PPTX, XLSX, XLS, Markdown, TXT, CSV, HTML, and EPUB.
How many items can be added at once?
Up to 20 items can be selected interactively at one time. More documents can be added in batches, or through the directory entry.
For documents with the same name, should I choose [Keep all] or [Replace]?
When updating policies, manuals, or note snapshots, [Replace] is usually the right choice. Choose [Keep all] only when multiple versions must truly coexist, and add a date or version number to the name.
What should I do if a document stays stuck on processing?
Check whether the file can be opened, whether the processor and OCR are available, and whether the model service is configured. Use the error message to determine whether the failure happened during reading, parsing, or embedding.
Parsing and retrieval
Why does a scanned PDF have no text?
Scanned files require OCR. Open [Settings] → [Document Processing], choose an available OCR, and then reindex the document. For complex layouts, try a dedicated document processor.
Why do the results not change after modifying the chunk settings?
New settings do not automatically reprocess old documents. Run [Reindex] on the relevant entries, then retest with the same question.
What should I do if a retrieval test returns no results at all?
Check the document status, whether the text contains the answer, whether the original keywords can be matched, whether embedding is complete, whether the reranking threshold is too high, and whether Top K is too small.
What if the source is correct but the chunks are incomplete?
Check the chunks to see whether the conditions and conclusions were split apart. Increase the chunk size or overlap appropriately, or reorganize poorly structured source documents into clear notes and then reindex.
What if the correct results are ranked too low?
First remove duplicates and outdated documents, then consider the embedding model. If the candidates are roughly correct but the order is unstable, you can add reranking and readjust the threshold.
What should Top K be set to?
You can start with 6 and compare missed retrieval, noise, and latency using fixed questions. Top K can be adjusted between 1 and 50; do not treat increasing it as a universal fix.
Conversation and Agent
What should I do if the knowledge base entry in the conversation is unavailable?
Choose a model that supports tool calls and remove the current message attachment. Also confirm that at least one knowledge base contains ready documents.
What should I do if the answer does not show sources?
Confirm that a knowledge base is actually selected in the input area, then put the same question into the retrieval test. If retrieval does not return the correct chunks, fix the knowledge base first.
What should I do if retrieval is correct but the answer is still inaccurate?
Require the model to answer only based on citations, break the task into smaller factual items, and manually verify important conclusions. At this point, the problem is usually in the prompt, the model, or the context organization.
Why can't the Agent see the knowledge base?
Open [Edit Agent] → [Knowledge Base], bind the target knowledge base to the current Agent, and enable [Knowledge Base Search] in [Built-in Tools].
Will knowledge base management change the documents?
Yes. [Knowledge Base Management] supports adding, deleting, or refreshing documents. Do not enable it for read-only tasks; check the target, impact, and rollback method before writing.
Models, data, and backups
Why does changing the embedding model require rebuilding?
Vectors generated by different embedding models cannot be mixed directly. First confirm that the new model is available and keep a complete backup, then rebuild the existing vector index.
What is the relationship between reranking and the similarity threshold?
Reranking rescoring the candidate chunks, and the threshold filters low-scoring results after reranking. If reranking is not configured, the similarity threshold will not appear in the knowledge base settings.
After downloading a local embedding model, is everything completely offline?
Not necessarily. Parsing, OCR, reranking, and chat must all also use local capabilities for the process to be completely offline.
Will modifying the original file or webpage update it automatically?
No. Files, notes, and web pages are turned into documents based on the content at the time of import. Add the document with the same name again and choose [Replace], then run the retrieval test again.
Does a slim backup include knowledge base files?
It does not include the full knowledge base data files. Use a full backup before migrating or deleting, and verify the documents and retrieval after restoring.
Configuration notes: diagnostic baseline
Top K
6
Correct chunks are cut off or there is too much noise
Similarity threshold
Start from 0.0 after configuring reranking
Low-scoring noise is obvious, and the correct chunks still have room
Chunk
Keep the default intelligent segmentation
Conditions and conclusions are split apart, or the chunk is too long
Embedding model
Increase it only when BM25 is insufficient
Colloquial queries and synonyms cannot be matched reliably
Reranking model
Increase it when the candidates are correct but the ranking is unstable
Not used to fix parsing errors or missing text
User case
Xiaolin found that the answer about the "accommodation fee standard" was wrong in chat. He first ran a retrieval test with the same question and saw that the correct source did not appear at all; after opening the text, he found that the two-column PDF was out of order. After switching the processor and reindexing, retrieval became correct and the chat answer was restored as well.
This process changed only one variable, the parser, so it confirmed the root cause instead of relying on randomly increasing Top K, chunk size, and threshold at the same time.
If the problem still cannot be solved, record the app version, operating system, processor, embedding and reranking models, full error, anonymized minimal sample, retrieval results, and expected source.
Continue reading
Last updated
Was this helpful?