> 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/advanced-basic/trace.md).

# 調用鏈使用教程

## 功能介紹

調用鏈（Trace）係一個基於 [OpenTelemetry](https://opentelemetry.io/docs/languages/js/) 實現嘅可觀測工具。佢通過喺端側自動採集、儲存同處理數據，將一次對話背後嘅完整執行過程可視化，用嚟查看每個處理環節（例如模型調用、知識庫檢索、MCP 工具調用或者網絡搜索）嘅耗時、輸入輸出同 token 使用情況，為定位問題、優化效果提供量化評估依據。

每次新對話請求會生成一條 trace 數據。一條 trace 由多個 span 組成，每個 span 對應 Cherry Studio 嘅一個處理環節，例如模型調用、知識庫檢索、MCP 工具調用或者網絡搜索。Trace 視窗會以樹狀結構展示呢啲 span，你可以逐層展開查看詳情。

<figure><img src="/files/d5d0daf31f41b83ff1bd808bd82869cee311912b" alt=""><figcaption><p>調用鏈整體效果</p></figcaption></figure>

## 開啟 Trace

Trace 預設隱藏，需要先開啟開發者模式：

1. 打開 `設定 → 常規設定`
2. 搵到 **開發者模式**
3. 開啟 **啟用開發者模式**

<figure><img src="/files/481049dc909c5fdb601808e219339308fa2206b6" alt=""><figcaption><p>喺常規設定中開啟開發者模式</p></figcaption></figure>

{% hint style="info" %}
開啟之後，之前已經產生嘅會話唔會補生成 Trace；只有之後新嘅問答先會記錄調用鏈。
{% endhint %}

Trace 數據儲存在本地應用數據目錄中。通常唔需要手動處理，如需徹底清理，可進入 `設定 → 數據設定 → 數據目錄`，使用 **清除快取**，或者打開數據目錄後刪除 trace 相關快取。

常見數據目錄：

* **macOS**：`~/Library/Application Support/CherryStudio`
* **Windows**：`%APPDATA%\CherryStudio`
* **Linux**：`~/.config/CherryStudio`

<figure><img src="/files/9cbda34461fb3a2f18f6a5e1614bbf225ce01e94" alt=""><figcaption><p>數據目錄同快取清理入口</p></figcaption></figure>

## 場景介紹

### 全鏈路查看

喺 Cherry Studio 對話框中撳調用鏈按鈕，即可打開今次對話嘅完整鏈路。無論對話過程中調用了模型、網絡搜索、知識庫定係 MCP，都可以喺調用鏈視窗中查看到對應節點。

<figure><img src="/files/179199a31f9417217200bca9544d0fd0ba11d247" alt=""><figcaption><p>對話消息旁嘅調用鏈入口</p></figcaption></figure>

<figure><img src="/files/1ef1a257acf8ef338b0d50338f79b7403afbe031" alt=""><figcaption><p>調用鏈樹狀視圖</p></figcaption></figure>

### 查看模型調用

撳模型調用節點，可以查看今次模型請求嘅耗時、token 使用量、輸入同輸出。

<figure><img src="/files/0c3dfaa99dd9a0a9fcfd2a3b3455250559ad60e5" alt=""><figcaption><p>選擇模型調用節點</p></figcaption></figure>

<figure><img src="/files/73306edb46caadcc56d41675bc2aa36950828eb5" alt=""><figcaption><p>模型調用輸入</p></figcaption></figure>

<figure><img src="/files/52547481e6c456b9571b870df793ad6ab1e77d92" alt=""><figcaption><p>模型調用輸出</p></figcaption></figure>

### 查看網絡搜索

撳網絡搜索節點，可以查看搜索請求嘅問題、返回結果，以及之後傳畀模型嘅上下文。

<figure><img src="/files/0d3556649b72dc4116e6e618ad3808f45c271af9" alt=""><figcaption><p>選擇網絡搜索節點</p></figcaption></figure>

<figure><img src="/files/4df47e0e4a52b2fd4733294f85071eb37218aa74" alt=""><figcaption><p>網絡搜索輸入</p></figcaption></figure>

<figure><img src="/files/c2ae30590b7edc3a1efcc21b0031ad98336cf2a1" alt=""><figcaption><p>網絡搜索返回結果</p></figcaption></figure>

### 查看知識庫檢索

撳知識庫節點，可以查看檢索問題、命中嘅內容，以及知識庫返回畀模型嘅上下文。

<figure><img src="/files/b9cbe03eeae3d0bd1784cc2d8a1c0b85fc35e704" alt=""><figcaption><p>知識庫節點詳情</p></figcaption></figure>

### 查看 MCP 調用

撳 MCP 節點，可以查看 MCP Server tool 嘅輸入參數、返回值同耗時，方便排查工具調用係咪符合預期。

<figure><img src="/files/df47b2600bf445a7897f4de8f9474034c4498223" alt=""><figcaption><p>MCP 調用詳情</p></figcaption></figure>

<figure><img src="/files/3753918cc4b6fc4f0a797ab73893b46fa788eecc" alt=""><figcaption><p>MCP 返回結果</p></figcaption></figure>

## 問題同建議

如果調用鏈數據顯示異常，或者你希望補充更多可觀測能力，參考 [反饋同建議](/docs/zhong-wen-fan-ti/question-contact/suggestions.md) 中提供嘅官方渠道。反饋時建議附上 Trace 截圖、所用模型、係咪啟用了知識庫 / MCP / 網絡搜索，以及能夠重現嘅提問內容。

***

### 💡 獲取幫助同提交反饋

如果您喺配置或使用過程中遇到任何疑問、Bug 或有功能改進建議，請參考 [反饋同建議](/docs/zhong-wen-fan-ti/question-contact/suggestions.md) 入面提供嘅官方渠道。


---

# 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/advanced-basic/trace.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.