> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/en-us/knowledge-base/troubleshooting.md). # Frequently Asked Questions When you encounter a knowledge base issue, first determine whether the failure occurred at the import, parsing, chunking, retrieval, or answer stage. Changing only one variable at a time is the only way to know which adjustment truly works. {% hint style="info" %} The fastest way to pinpoint the issue is to run the same real question through every check: does the body contain the answer, are the Chunks complete, is retrieval correct, and is the answer faithful to the source. {% endhint %} ## 5 Quick Steps to Pinpoint the Issue {% stepper %} {% step %} ### 1. Check the document status The document should be \[Ready]. If it has been processing for a long time or shows an error, first check the error message and confirm that the file, processor, and model service are available. {% endstep %} {% step %} ### 2. Check the parsed text Open the text preview and confirm that the answer is actually present, that scanned text has been recognized, and that two-column layouts and tables are not out of order. {% endstep %} {% step %} ### 3. Check Chunks Confirm that the conditions and conclusion needed for the question are in understandable chunks; do not let headers, footers, and the table of contents take up all the results.

知识库高级设置中的智能分段、分隔符、分段大小和重叠大小 — If the text is correct but the chunks are incomplete, adjust chunking and reindex the old documents.

{% endstep %} {% step %} ### 4. Run a retrieval test Check the source name, relevance, and chunk content. Having no correct chunks at all and having the correct chunks ranked too low are two different problems.

召回测试中显示来源名称、相关度和命中片段的结果列表 — First prove that the retrieval layer returns the right evidence, then adjust the chat prompt.

{% endstep %} {% step %} ### 5. Check the conversation or Agent If retrieval is correct but the answer is wrong, confirm that the knowledge base has been selected or bound, require the answer to be based only on the sources, and break the question into smaller factual items. {% endstep %} {% endstepper %} ## Where should the issue be reported

按不知道如何操作、稳定复现、希望增加能力和不希望整理材料选择反馈路径的关系图 — Finish the minimum troubleshooting first; when it can be reproduced reliably, include sanitized steps, the error, and the expected result.

{% hint style="danger" %} Do not expose API keys, internal file contents, email addresses, or local sensitive paths in screenshots, logs, or sample documents. {% endhint %} ## Creation and import

Can I create a knowledge base without an embedding model?

Yes. After choosing \[Do Not Use], BM25 keyword search will still be used. Add an embedding model later when you need to match different wording.

What sources and file formats are supported?

Sources include files, Cherry Studio notes, local directories, and web links. 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 once. More documents can be added in batches, or through the directory entry.

For items with the same name, choose [Keep All] or [Replace]?

When updating policies, manuals, or note snapshots, \[Replace] is usually the better choice. Choose \[Keep All] only when versions truly need to coexist, and add a date or version to the name.

What should I do if the 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 is in reading, parsing, or embedding.

## Parsing and retrieval

Why does a scanned PDF have no text?

Scanned documents require OCR. Open \[Settings] → \[Document Processing], choose an available OCR, and then reindex the document. For complex layouts, try a dedicated document processor.

Why didn't the results change after I modified the Chunk settings?

The new settings do not automatically redo old documents. Run \[Reindex] on the relevant items, then retest with the same question.

What should I do if the retrieval test returns no results at all?

Check, in order, 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 chunk is incomplete?

Check the Chunks and confirm whether the conditions and conclusion were split apart. Increase the chunk size or overlap appropriately, or organize structurally messy source material into clear notes and then reindex.

What if the correct results are ranked too low?

First remove duplicate and outdated documents, then consider the embedding model. If the candidates are roughly correct but the order is unstable, you can increase reranking and readjust the threshold.

What should Top K be set to?

You can start with 6 and use fixed questions to compare missed retrievals, noise, and latency. 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 a conversation is unavailable?

Choose a model that supports tool calling, and remove attachments from the current message. Also confirm that at least one knowledge base contains ready documents.

What should I do if the answer does not show sources?

Confirm that the knowledge base is indeed selected in the input area, then put the same question into the retrieval test. If retrieval has no correct chunks, fix the knowledge base first.

What should I do if retrieval is correct but the answer is still inaccurate?

Ask the model to answer only based on the cited sources, break the task into smaller factual items, and manually verify important conclusions. At this point, the problem usually lies in the prompt, model, or context organization.

Why can't the Agent see the knowledge base?

Open \[Edit Agent] → \[Knowledge Base], bind the target base to the current Agent, and enable \[Knowledge Base Search] under \[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; before write operations, check the target, impact, and rollback method.

## 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 full backup, then rebuild the existing vector index.

What is the relationship between reranking and the similarity threshold?

Reranking re-scores the candidate chunks, and the threshold filters out low-scoring results after reranking. If reranking is not configured, the similarity threshold will not be shown in the knowledge base settings.

After downloading a local embedding model, is it completely offline?

Not necessarily. Parsing, OCR, reranking, and chat must all use local capabilities too for the workflow to be completely offline.

Will changes to the original file or webpage update automatically?

No. Files, notes, and webpages are turned into documents based on the content at import time. Add the document with the same name again and choose \[Replace], then run the retrieval test.

Does a lightweight backup include knowledge base files?

It does not include the full knowledge base data files. Use a full backup before migration or deletion, and verify the documents and retrieval after restoring.

## Configuration guide: diagnostic baseline | Item | Recommended starting point | Only adjust when | | -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ | | Top K | 6 | The correct chunk is cut off or there is too much noise | | Similarity threshold | After configuring reranking, start from 0.0 | Low-scoring noise is obvious, and the correct chunk still has room | | Chunk | Keep the default smart segmentation | The conditions and conclusion are split apart, or the chunk is too long | | Embedding model | Increase only when BM25 is insufficient | Colloquial wording and synonymous expressions cannot be matched reliably | | Reranking model | Increase when the candidates are correct but the order is unstable | Not used to fix parsing errors or missing text | ## User case Xiaolin discovered that the question about the 'accommodation fee standard' was being answered incorrectly 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 had been out of order. After changing the processor and reindexing, retrieval became correct and the chat answer returned to normal. This process changed only one variable—the parser—so it was possible to confirm the root cause instead of blindly increasing Top K, Chunk size, and thresholds all at once. {% hint style="warning" %} If it still cannot be resolved, record the app version, operating system, processor, embedding and reranking models, the full error, a sanitized minimal sample, the retrieval results, and the expected source. {% endhint %} ## Continue reading


Document parsing and OCR	Solve scanning issues, misordered text, and table loss.	Document Parsing and OCR
Model and retrieval settings	Understand embeddings, reranking, thresholds, and rebuilding.	Model and Retrieval Settings
Data, privacy, and maintenance	Confirm backup and cloud service boundaries.	Data, Privacy, and Maintenance

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cherryai.com.cn/docs/en-us/knowledge-base/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.