> 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).

# 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.

{% hint style="info" %}
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.
{% endhint %}

## 5 quick troubleshooting steps

{% 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 really exists, that scanned text has been recognized, and that two-column layouts and tables are not out of order.
{% endstep %}

{% step %}

### 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.

<figure><img src="/files/0359b26559db3bea6e323bf599d74c081ad91c93" alt="知识库高级设置中的智能分段、分隔符、分段大小和重叠大小"><figcaption><p>If the text is correct but the chunks are incomplete, adjust the chunking settings and reindex the old documents.</p></figcaption></figure>
{% endstep %}

{% step %}

### 4. Run a retrieval test

Check the source name, relevance, and chunk content. Having no correct chunks at all and having correct chunks ranked too low are two different problems.

<figure><img src="/files/c6f3bfaf5deb56fb89e9a46bf9e60343a52ba0e2" alt="召回测试中显示来源名称、相关度和命中片段的结果列表"><figcaption><p>First prove that the retrieval layer returns the correct evidence, then adjust the prompt for the conversation.</p></figcaption></figure>
{% 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 answers to rely only on the source, and break the question into smaller factual items.
{% endstep %}
{% endstepper %}

## Where should the issue be reported?

<figure><img src="/files/1f45275b203c7f5ea09c49487ede4dadd4ee6214" alt="按不知道如何操作、稳定复现、希望增加能力和不希望整理材料选择反馈路径的关系图"><figcaption><p>First complete the minimum troubleshooting steps; when the issue can be reproduced reliably, attach anonymized steps, the error, and the expected result.</p></figcaption></figure>

{% 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

<details>

<summary>Can I create a knowledge base without an embedding model?</summary>

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.

</details>

<details>

<summary>What sources and file formats are supported?</summary>

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.

</details>

<details>

<summary>How many items can be added at once?</summary>

Up to 20 items can be selected interactively at one time. More documents can be added in batches, or through the directory entry.

</details>

<details>

<summary>For documents with the same name, should I choose [Keep all] or [Replace]?</summary>

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.

</details>

<details>

<summary>What should I do if a document stays stuck on processing?</summary>

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.

</details>

## Parsing and retrieval

<details>

<summary>Why does a scanned PDF have no text?</summary>

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.

</details>

<details>

<summary>Why do the results not change after modifying the chunk settings?</summary>

New settings do not automatically reprocess old documents. Run \[Reindex] on the relevant entries, then retest with the same question.

</details>

<details>

<summary>What should I do if a retrieval test returns no results at all?</summary>

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.

</details>

<details>

<summary>What if the source is correct but the chunks are incomplete?</summary>

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.

</details>

<details>

<summary>What if the correct results are ranked too low?</summary>

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.

</details>

<details>

<summary>What should Top K be set to?</summary>

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.

</details>

## Conversation and Agent

<details>

<summary>What should I do if the knowledge base entry in the conversation is unavailable?</summary>

Choose a model that supports tool calls and remove the current message attachment. Also confirm that at least one knowledge base contains ready documents.

</details>

<details>

<summary>What should I do if the answer does not show sources?</summary>

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.

</details>

<details>

<summary>What should I do if retrieval is correct but the answer is still inaccurate?</summary>

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.

</details>

<details>

<summary>Why can't the Agent see the knowledge base?</summary>

Open \[Edit Agent] → \[Knowledge Base], bind the target knowledge base to the current Agent, and enable \[Knowledge Base Search] in \[Built-in Tools].

</details>

<details>

<summary>Will knowledge base management change the documents?</summary>

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.

</details>

## Models, data, and backups

<details>

<summary>Why does changing the embedding model require rebuilding?</summary>

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.

</details>

<details>

<summary>What is the relationship between reranking and the similarity threshold?</summary>

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.

</details>

<details>

<summary>After downloading a local embedding model, is everything completely offline?</summary>

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

</details>

<details>

<summary>Will modifying the original file or webpage update it automatically?</summary>

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.

</details>

<details>

<summary>Does a slim backup include knowledge base files?</summary>

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.

</details>

## Configuration notes: diagnostic baseline

| Item                 | Recommended starting point                                              | Only adjust when                                                     |
| -------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- |
| 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.

{% hint style="warning" %}
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.
{% endhint %}

## Continue reading

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Document parsing and OCR</strong></td><td>Solve scanning, misordered text, and missing tables.</td><td><a href="/pages/7d495aecf9165aca96855bc0d74b3e925728dedc">/pages/7d495aecf9165aca96855bc0d74b3e925728dedc</a></td></tr><tr><td><strong>Model and retrieval settings</strong></td><td>Understand embedding, reranking, thresholds, and rebuilding.</td><td><a href="/pages/244bae136e1bc54a35816d43dc1b6b0e3b8c7e3e">/pages/244bae136e1bc54a35816d43dc1b6b0e3b8c7e3e</a></td></tr><tr><td><strong>Data, privacy, and maintenance</strong></td><td>Confirm the boundaries of backups and cloud services.</td><td><a href="/pages/79d7d1d4aa8046a5b156be2497b3f18795dd88a8">/pages/79d7d1d4aa8046a5b156be2497b3f18795dd88a8</a></td></tr></tbody></table>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/docs/en-us/knowledge-base/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.