> 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/zhong-wen-fan-ti/knowledge-base/troubleshooting.md).

# 常見問題

遇到知識庫問題時，先判斷失敗發生喺導入、解析、分塊、召回定係回答層。一次只改一個變量，先至知道邊項調整真係有效。

{% hint style="info" %}
最快嘅定位方法係用同一個真實問題一路檢查：正文有冇答案、Chunk 係咪完整、召回係咪正確、回答係咪忠於來源。
{% endhint %}

## 5 步快速定位

{% stepper %}
{% step %}

### 1. 檢查資料狀態

資料應為【就緒】。如果長期處理中或者顯示錯誤，先睇錯誤資訊，並確認文件、處理器同模型服務可用。
{% endstep %}

{% step %}

### 2. 檢查解析正文

打開正文預覽，確認答案確實存在，掃描文字已經識別，雙欄同表格冇錯序。
{% endstep %}

{% step %}

### 3. 檢查 Chunks

確認問題需要嘅條件同結論位於可理解嘅片段中；唔好畀頁眉、頁腳同目錄佔滿結果。

<figure><img src="https://2742912793-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2FSuW1LQlcdqCWxhLJEEQe%2Fclipboard.png?alt=media&amp;token=6ea5de2d-e4a1-40e2-b31c-d9ca31779eed" alt="知识库高级设置中的智能分段、分隔符、分段大小和重叠大小"><figcaption><p>正文正確但片段唔完整時，再調整分塊，並重新索引舊資料。</p></figcaption></figure>
{% endstep %}

{% step %}

### 4. 運行召回測試

檢查來源名稱、相關度同片段內容。完全冇正確片段同正確片段排序靠後，係兩類唔同問題。

<figure><img src="https://2742912793-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2Fr2mSvzxjXSvwuT0gGIf6%2Fclipboard.png?alt=media&amp;token=87900ecb-c890-4894-9891-905a4caad74c" alt="召回测试中显示来源名称、相关度和命中片段的结果列表"><figcaption><p>先證明檢索層返咗正確證據，再調整對話提示詞。</p></figcaption></figure>
{% endstep %}

{% step %}

### 5. 檢查對話或 Agent

召回正確但回答錯誤時，確認已選擇或綁定知識庫，要求只依據來源回答，並把問題拆成更細嘅事實項。
{% endstep %}
{% endstepper %}

## 問題應該反饋到邊度

<figure><img src="https://2742912793-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2FT67uGAggILYAlBn5tJa9%2Fclipboard.png?alt=media&amp;token=8b08883c-8dc6-4295-9d56-1c4226b8fcdd" alt="按不知道如何操作、稳定复现、希望增加能力和不希望整理材料选择反馈路径的关系图"><figcaption><p>先完成最小排查；可穩定復現時附上脫敏步驟、錯誤同預期結果。</p></figcaption></figure>

{% hint style="danger" %}
截圖、日誌同示例資料入面唔好公開 API Key、內部文件內容、電郵或本地敏感路徑。
{% endhint %}

## 創建與導入

<details>

<summary>冇嵌入模型可以創建知識庫嗎？</summary>

可以。選擇【不使用】後仍然會使用 BM25 關鍵詞檢索。需要匹配唔同表達時再增加嵌入模型。

</details>

<details>

<summary>支持咩來源同文件格式？</summary>

來源包括文件、Cherry Studio 筆記、本地目錄同網頁連結。文件格式包括 PDF、DOCX、DOC、PPTX、XLSX、XLS、Markdown、TXT、CSV、HTML 同 EPUB。

</details>

<details>

<summary>一次可以添加幾多項？</summary>

一次互動式選擇最多 20 項。更多資料可以分批添加，或者使用目錄入口。

</details>

<details>

<summary>同名資料揀【全部保留】定【替換】？</summary>

更新制度、手冊或筆記快照時通常揀【替換】。只有真係需要並存嘅版本先揀【全部保留】，並喺名稱入面加入日期或版本。

</details>

<details>

<summary>資料一直停喺處理中點算？</summary>

檢查文件可唔可以打開、處理器同 OCR 係咪可用、模型服務係咪已配置。根據錯誤資訊判斷失敗喺讀取、解析定係嵌入階段。

</details>

## 解析與召回

<details>

<summary>掃描 PDF 點解冇文字？</summary>

掃描件需要 OCR。打開【設置】→【文檔處理】選擇可用 OCR，再重新索引文檔。複雜版式可以試專用文檔處理器。

</details>

<details>

<summary>修改 Chunk 設置後點解結果冇變化？</summary>

新設置唔會自動重做舊資料。對相關條目執行【重新索引】，再用同一問題復測。

</details>

<details>

<summary>召回測試完全冇結果點算？</summary>

依次檢查資料狀態、正文係咪包含答案、原文關鍵詞可唔可以命中、嵌入係咪完成、重排閾值係咪過高，以及 Top K 係咪過細。

</details>

<details>

<summary>來源正確但片段唔完整點算？</summary>

睇 Chunks，確認條件同結論係咪被切開。適當增大 Chunk 或重疊，或者將結構混亂嘅源資料整理成清晰筆記後重新索引。

</details>

<details>

<summary>正確結果排得太後點算？</summary>

先刪除重複同過期資料，再考慮嵌入模型。候選大致正確但順序唔穩時，可以增加重排並重新調節閾值。

</details>

<details>

<summary>Top K 應該設幾多？</summary>

可以由 6 開始，用固定問題比較漏召回、噪聲同耗時。Top K 可喺 1～50 之間調整，唔好將調大當成通用修復。

</details>

## 對話與 Agent

<details>

<summary>對話入面嘅知識庫入口不可用點算？</summary>

選擇支持工具調用嘅模型，並移除當前消息附件。仲要確認至少有一個知識庫包含就緒資料。

</details>

<details>

<summary>回答冇顯示來源點算？</summary>

確認輸入區真係有選中知識庫，再將相同問題放入召回測試。召回冇正確片段時先修復知識庫。

</details>

<details>

<summary>召回正確，回答仍然唔準點算？</summary>

要求模型只依據引用回答，將任務拆成更細嘅事實項，並人工核對重要結論。此時問題通常喺提示詞、模型或者上下文組織。

</details>

<details>

<summary>Agent 點解睇唔到知識庫？</summary>

打開【編輯智能體】→【知識庫】，將目標庫綁定到當前 Agent，並喺【內置工具】中啟用【知識庫搜索】。

</details>

<details>

<summary>知識庫管理會改變資料嗎？</summary>

會。【知識庫管理】支持添加、刪除或刷新文檔。只讀任務唔好啟用；寫操作前檢查目標、影響同回退方式。

</details>

## 模型、數據與備份

<details>

<summary>更換嵌入模型點解要求重建？</summary>

唔同嵌入模型生成嘅向量唔可以直接混用。先確認新模型可用並保留完整備份，再重建已有向量索引。

</details>

<details>

<summary>重排同相似度閾值係咩關係？</summary>

重排會對候選片段重新打分，閾值會過濾重排後嘅低分結果。未配置重排時，知識庫設置入面唔會顯示相似度閾值。

</details>

<details>

<summary>本地嵌入模型下載後就完全離線咩？</summary>

唔一定。解析、OCR、重排同聊天都必須全部使用本地能力，先至係完全離線流程。

</details>

<details>

<summary>修改原文件或網頁會自動更新嗎？</summary>

唔會。文件、筆記同網頁會按導入時內容建立資料。重新添加同名資料並選擇【替換】，再完成召回測試。

</details>

<details>

<summary>精簡備份包含知識庫文件嗎？</summary>

唔包含完整知識庫數據文件。遷移或刪除前使用完整備份，並喺恢復後驗證資料與召回。

</details>

## 配置說明：診斷基線

| 項目    | 推薦起點          | 只喺咩情況下調整            |
| ----- | ------------- | ------------------- |
| Top K | 6             | 正確片段被截走或者噪聲太多       |
| 相似度閾值 | 配置重排後由 0.0 開始 | 低分噪聲好明顯，而且正確片段仍然有餘量 |
| Chunk | 保留預設智能分段      | 條件同結論被切開或者片段太長      |
| 嵌入模型  | BM25 不足時再增加   | 口語問法、同義表達無法穩定命中     |
| 重排模型  | 候選正確但順序唔穩時增加  | 唔用嚟修復解析錯誤或者缺失正文     |

## 用戶案例

小林發現「住宿費標準」喺聊天入面回答錯誤。佢先用相同問題做召回測試，見到正確來源根本冇出現；打開正文後發現雙欄 PDF 已經錯序。更換處理器並重新索引後，召回正確，聊天回答亦都恢復正常。

呢個過程只改咗解析器一個變量，所以可以確認根因，而唔係靠同時調大 Top K、Chunk 同閾值碰運氣。

{% hint style="warning" %}
如果仍然無法解決，請記錄應用版本、操作系統、處理器、嵌入與重排模型、完整錯誤、脫敏最小樣本、召回結果同預期來源。
{% endhint %}

## 繼續閱讀

<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>文件解析與 OCR</strong></td><td>解決掃描、錯序同表格丟失。</td><td><a href="/docs/zhong-wen-fan-ti/knowledge-base/document-preprocessing.md">文件解析同 OCR</a></td></tr><tr><td><strong>模型同檢索設定</strong></td><td>理解嵌入、重排、閾值同重建。</td><td><a href="/docs/zhong-wen-fan-ti/knowledge-base/emb-models-info.md">模型同檢索設定</a></td></tr><tr><td><strong>數據、私隱同維護</strong></td><td>確認備份與雲端服務邊界。</td><td><a href="/docs/zhong-wen-fan-ti/knowledge-base/data.md">數據、私隱同維護</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 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/zhong-wen-fan-ti/knowledge-base/troubleshooting.md?ask=<question>&goal=<user_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.
