> 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="/files/f40998683b0aa62431eb81fa05a615038defc9d1" alt="知识库高级设置中的智能分段、分隔符、分段大小和重叠大小"><figcaption><p>正文正確但片段唔完整時，再調整分塊，並重新索引舊資料。</p></figcaption></figure>
{% endstep %}

{% step %}

### 4. 運行召回測試

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

<figure><img src="/files/65ce03c7ec8a7c321ec30cb89dc17f5b9a06494e" alt="召回测试中显示来源名称、相关度和命中片段的结果列表"><figcaption><p>先證明檢索層返回咗正確證據，再調整對話提示詞。</p></figcaption></figure>
{% endstep %}

{% step %}

### 5. 檢查對話或 Agent

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

## 問題應該反饋去邊度

<figure><img src="/files/7d2c5138b8f50f1c1d5c677ecaf2378c91106ecb" 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="/pages/4b9563c434830d8aac5df782c734b2ddcd8509f0">/pages/4b9563c434830d8aac5df782c734b2ddcd8509f0</a></td></tr><tr><td><strong>模型同檢索設定</strong></td><td>理解嵌入、重排、閾值同重建。</td><td><a href="/pages/80a36504e872dfe466466dc078aa9127440ec266">/pages/80a36504e872dfe466466dc078aa9127440ec266</a></td></tr><tr><td><strong>數據、私隱同維護</strong></td><td>確認備份同雲端服務邊界。</td><td><a href="/pages/c717d714b290fe2e0838ea72d335a09917e42a89">/pages/c717d714b290fe2e0838ea72d335a09917e42a89</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/zhong-wen-fan-ti/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.