docs: refresh translations for recent English changes (#3379)
This commit is contained in:
Max
GitHub
parent
d8b638304e
commit
c5d7d0b6d0
6 changed files with 3149 additions and 1047 deletions
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
translation:
|
||||
sections: [e33d441f12d50535, 7099694c603e0f5f, c1df4cf9673433e6, c9cd294541422e6e, 6cec073617bfd037, efa92b8f99e908c8, 6a22a29e27fb4601]
|
||||
sections: [7be05607887e6853, e7375894888d9750, c36f73fc7e3af13b, 2fec2d7e129e62fe, 809b0e0a7c27295a, b4395a04d2a5d906, 1a436007f5f54779, c6b2078ed1e63ba5]
|
||||
tool: 1
|
||||
---
|
||||
# 處理錯誤 {#handling-errors}
|
||||
|
||||
工具失敗的方式有兩種，而 SDK 對待它們的方式截然不同。
|
||||
工具失敗的方式有三種，而 SDK 對待每一種的方式都不同。
|
||||
|
||||
引發一般的例外，看到的是**模型**。引發 `MCPError`，看到的是**協定**。
|
||||
引發 `ToolError`，**模型**會看到你的訊息。引發 `MCPError`，看到的是**協定**。引發其他任何東西就是崩潰：模型只知道呼叫失敗了，而 traceback 進了你的記錄。
|
||||
|
||||
這一頁談的是怎麼選。
|
||||
|
||||
|
|
@ -15,11 +15,11 @@ translation:
|
|||
|
||||
拿一個查東西的工具來說，讓查詢落空：
|
||||
|
||||
```python title="server.py" hl_lines="11-12"
|
||||
```python title="server.py" hl_lines="2 12-13"
|
||||
--8<-- "docs_src/handling_errors/tutorial001.py"
|
||||
```
|
||||
|
||||
這兩行跟 MCP 一點關係也沒有。`get_author` 引發的是普通的 `ValueError`，任何 Python 函式都會這麼做。
|
||||
`ToolError` 來自 `mcp.server.mcpserver.exceptions`，是工具告訴模型出了問題的方式。
|
||||
|
||||
用一個不在目錄裡的書名呼叫它，看看結果：
|
||||
|
||||
|
|
@ -30,19 +30,21 @@ result.structured_content # None
|
|||
```
|
||||
|
||||
* 請求**成功**了。有結果；呼叫端沒有引發任何東西。
|
||||
* `is_error` 是 `True`，而例外的訊息（前面加上工具名稱）就在 `content` 裡，正是模型讀取的地方。
|
||||
* `is_error` 是 `True`，而你的訊息（前面加上工具名稱）就在 `content` 裡，正是模型讀取的地方。
|
||||
* `structured_content` 是 `None`。失敗的呼叫沒有回傳值可以結構化。
|
||||
|
||||
這是**工具錯誤**，也是工具引發**任何**例外時的預設行為。而且幾乎總是你想要的。
|
||||
這是**工具錯誤**，而且幾乎總是你想要的。
|
||||
|
||||
呼叫工具的是模型，引數也是它選的。所以工具錯誤就是對話中的一個回合：模型讀到「No book titled 'Nothing' in the catalog.」，發現自己猜錯了書名，就換個更好的再呼叫一次。只寫了一個 `raise`，就得到一個會自我修正的 agent。
|
||||
|
||||
在伺服器上，一個 `ToolError` 就是記錄裡的一行 `INFO`，沒有 traceback。這是你預料中的事，所以沒什麼好追查的。
|
||||
|
||||
!!! tip
|
||||
永遠不要從工具 `return` 錯誤訊息。回傳的字串 `is_error=False`，所以在模型（以及每個用戶端 UI）看來，工具是成功的，那個字串就是答案。要用 `raise`。那個旗標才是訊號。
|
||||
|
||||
## 模型無法修正的錯誤 {#an-error-the-model-cannot-fix}
|
||||
|
||||
現在把 `ValueError` 換成 `MCPError`。
|
||||
現在把 `ToolError` 換成 `MCPError`。
|
||||
|
||||
```python title="server.py" hl_lines="1 3 14"
|
||||
--8<-- "docs_src/handling_errors/tutorial002.py"
|
||||
|
|
@ -74,16 +76,35 @@ result.structured_content # None
|
|||
|
||||
兩條路徑回答的是兩個不同的問題。
|
||||
|
||||
* **引發任何例外**，用於**執行**上的失敗：工具想做的事沒做成。呼叫是模型選的，所以模型應該看到後果，並有機會補救。拼錯的書名、逾時的上游 API、不存在的資料列：都是工具錯誤。
|
||||
* **引發 `ToolError`**，用於**執行**上的失敗：工具想做的事沒做成。呼叫是模型選的，所以模型應該看到後果，並有機會補救。拼錯的書名、逾時的上游 API、不存在的資料列：都是工具錯誤。
|
||||
* **引發 `MCPError`**，用於**請求本身**就該被拒絕的情況：用戶端缺少工具所依賴的能力、伺服器處於無法服務任何人的狀態、呼叫端跳過了必要的步驟。模型再怎麼重試也修不好這些，所以把訊息交給它毫無益處。
|
||||
|
||||
一個問題就能決定：**更聰明的模型能避開這個錯誤嗎？**能 -> 一般的例外。不能 -> `MCPError`。
|
||||
一個問題就能決定：**更聰明的模型能避開這個錯誤嗎？**能 -> `ToolError`。不能 -> `MCPError`。
|
||||
|
||||
照這個標準，第二版的 `get_author` 選錯了：換個更好的書名就能解決，所以模型理應看到訊息。放在那裡是為了示範機制，不是建議這麼做。
|
||||
|
||||
!!! info
|
||||
`MCPError` 位於 `from mcp import MCPError`，接受 `code`、`message` 和選用的 `data` 承載。放進去什麼，用戶端就收到什麼：SDK 會把引發的 `MCPError` 原封不動地轉送，不會加以清理。
|
||||
|
||||
## 其他任何例外 {#any-other-exception}
|
||||
|
||||
現在把檢查拿掉，讓字典查詢自己失敗：
|
||||
|
||||
```python title="server.py" hl_lines="11"
|
||||
--8<-- "docs_src/handling_errors/tutorial004.py"
|
||||
```
|
||||
|
||||
`CATALOG[title]` 引發 `KeyError`。這不在你的計畫之內，所以 SDK 把它當成崩潰：
|
||||
|
||||
```python
|
||||
result.is_error # True
|
||||
result.content # [TextContent(text="Error executing tool get_author")]
|
||||
```
|
||||
|
||||
呼叫仍然回傳 `is_error=True`，所以模型知道它失敗了，可以繼續往下走。它拿不到的是例外的文字：你程式碼裡的 `KeyError`，或是隔了三層函式庫的驅動程式丟出的一堆 SQL，都可能描述了伺服器的內部細節，所以永遠不會離開伺服器。
|
||||
|
||||
拿到它的是你。伺服器以 `ERROR` 層級記錄這次崩潰，附上完整的 traceback，訊息是 `Tool 'get_author' raised an unexpected exception`。因此，設在 `WARNING` 的正式環境記錄在每個 `ToolError` 經過時都保持安靜，一旦真的有東西壞了才會出聲。
|
||||
|
||||
## 不存在的資源 {#a-resource-that-doesnt-exist}
|
||||
|
||||
資源也畫了同一條線，並為常見情況提供了一個具名的例外。
|
||||
|
|
@ -104,7 +125,7 @@ result.structured_content # None
|
|||
}
|
||||
```
|
||||
|
||||
注意這裡沒有 `is_error=True` 那種半成品結果。資源讀取要嘛回傳內容，要嘛失敗：資源只有協定這條路。範本以及資源的其他一切都在 **[資源](resources.md)**。
|
||||
注意這裡沒有 `is_error=True` 那種半成品結果。資源讀取要嘛回傳內容，要嘛失敗：資源只有協定這條路。`ResourceError` 是同樣的東西，用在不是「找不到」的失敗上（`-32603`，附上你的訊息），兩者在記錄裡都是一行 `INFO`。除了 `MCPError` 以外的任何其他例外都是崩潰：用戶端收到只寫出 URI 的 `-32603`，traceback 則以 `ERROR` 層級進你的記錄。範本以及資源的其他一切都在 **[資源](resources.md)**。
|
||||
|
||||
## 永遠不用引發的錯誤 {#errors-you-never-raise}
|
||||
|
||||
|
|
@ -115,16 +136,17 @@ result.structured_content # None
|
|||
這表示有一整類 `raise` 陳述式不用寫：不要重新驗證自己的型別提示。
|
||||
|
||||
!!! info
|
||||
這一頁的一切都是**用戶端**看到的東西，而寫測試用的記憶體內 `Client` 看到的完全一樣。就算是 `raise_exceptions=True` 也不會把工具錯誤變回 traceback：等到那個旗標能起作用時，你的例外早已是 `is_error=True` 的結果。對結果做斷言。**[測試](../get-started/testing.md)** 說明了這個模式。
|
||||
這一頁**用戶端**看到的一切，寫測試用的記憶體內 `Client` 也都看得到。就算是 `raise_exceptions=True` 也不會把失敗工具的例外交回給呼叫端：等到那個旗標能起作用時，你的例外早已是 `is_error=True` 的結果。對結果做斷言。如果需要崩潰的 traceback，它在伺服器的記錄裡，pytest 的 `caplog` 能捕捉到。**[測試](../get-started/testing.md)** 說明了這個模式。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 在工具裡引發**任何例外** -> 呼叫回傳 `is_error=True`，訊息在 `content` 裡。模型讀到後可以重試。這是預設行為。
|
||||
* 在工具裡引發 **`ToolError`** -> 呼叫回傳 `is_error=True`，你的訊息在 `content` 裡。模型讀到後可以重試。
|
||||
* 引發 **`MCPError`** -> 呼叫本身以 JSON-RPC 錯誤失敗。模型什麼都看不到；由主機處理。`code`、`message` 和 `data` 完整保留。
|
||||
* 決定性的問題：「更聰明的模型能避開這個錯誤嗎？」能 -> 例外。不能 -> `MCPError`。
|
||||
* 決定性的問題：「更聰明的模型能避開這個錯誤嗎？」能 -> `ToolError`。不能 -> `MCPError`。
|
||||
* 任何**其他例外**都是崩潰 -> `is_error=True`，模型只看到 `Error executing tool <name>`，而你得到一筆附上 traceback 的 `ERROR` 記錄。
|
||||
* 資源處理函式引發的 `ResourceNotFoundError` -> 協定的 `-32602`，URI 在 `data` 裡。
|
||||
* 錯誤的引數會在函式執行前依 schema 被拒絕；這些不用 `raise`。
|
||||
* `from mcp import MCPError`；錯誤碼常數來自 `mcp.types`。
|
||||
* 匯入：`from mcp import MCPError`、`from mcp.server.mcpserver.exceptions import ToolError, ResourceError, ResourceNotFoundError`，以及來自 `mcp.types` 的錯誤碼常數。
|
||||
|
||||
錯誤處理完畢。這就是伺服器**公開**的全部內容。每個處理函式在執行時能讀到什麼、又能反過來對用戶端做什麼，是下一節的主題：**[在處理函式內部](../handlers/index.md)**。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [496394d24d221bf1, 4ceb4591180dc6c3, 0fd63e4682d02e0c, 969ede0bd3686a16, 043f526230dd243d, 6ee3e9bcfd24047a]
|
||||
sections: [496394d24d221bf1, 4ceb4591180dc6c3, 0fd63e4682d02e0c, 969ede0bd3686a16, 864137b5e9c61e91, 043f526230dd243d, db1ef91db7d6b3f3]
|
||||
tool: 1
|
||||
---
|
||||
# 媒體 {#media}
|
||||
|
|
@ -81,6 +81,24 @@ result.structured_content # None
|
|||
!!! check
|
||||
用 `data=` 時沒有檔名，也就沒有東西可以猜。忘了 `format=`，SDK 就會退回預設值：圖片是 `image/png`，音訊是 `audio/wav`。這樣用 MP3 位元組建立 `Audio`，用戶端會被告知 `mime_type="audio/wav"`，然後老老實實地解碼失敗。傳 `data=` 的時候，就一起傳 `format=`。
|
||||
|
||||
## 內嵌資源 {#embedding-a-resource}
|
||||
|
||||
工具也可以回傳一份文件：一些文字或位元組，連同它所在的 URI 和 MIME 型別。這就是 **`EmbeddedResource`**，另一種內容區塊。它跟普通的 `str` 不同，會告訴用戶端這段內容是什麼，讓用戶端可以把它顯示成附件，或認出這是它已經知道的資源。
|
||||
|
||||
```python title="server.py" hl_lines="7 14 16-18"
|
||||
--8<-- "docs_src/media/tutorial005.py"
|
||||
```
|
||||
|
||||
* `brand://guidelines` 是一個普通的資源（**[資源](resources.md)** 有完整介紹）。模型要求時，工具會交出同一份文件；直接呼叫 `guidelines()`，真實來源就只有一個。
|
||||
* `EmbeddedResource` 和 `TextResourceContents` 來自 `mcp.types`。這裡沒有像圖片那樣的輔助工具：建立的區塊會原封不動放進結果，也沒有 `structured_content`。
|
||||
* 使用資源註冊時的 URI，用戶端才能知道附件和 `brand://guidelines` 是同一份文件。任何 URI 都合法，不論有沒有註冊。
|
||||
|
||||
```python
|
||||
result.content # [EmbeddedResource(type="resource", resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text="# Brand guidelines\n\n..."))]
|
||||
```
|
||||
|
||||
二進位內容就用 `BlobResourceContents(uri=..., mime_type=..., blob=...)` 取代 `TextResourceContents`，把位元組經 base64 編碼後放進 `blob`。如果只想送出一個指標，讓用戶端之後再用 `resources/read` 讀取，就改回傳 `ResourceLink(name=..., uri=...)`；它也是一種內容區塊。
|
||||
|
||||
## 圖示 {#icons}
|
||||
|
||||
`Icon` 是中繼資料，不是內容。它不帶圖片本身，而是用一個 URI 指向圖片；用戶端可以去抓取並顯示在伺服器名稱、工具、資源或提示詞旁邊。
|
||||
|
|
@ -110,6 +128,7 @@ client.server_info.icons # [Icon(src="https://example.com/brand-kit.png", mime_
|
|||
|
||||
* 從工具回傳 `Image` 或 `Audio`，用戶端就會收到一個 `ImageContent`／`AudioContent` 區塊：位元組經 base64 編碼，附上 MIME 型別。
|
||||
* 可以用 `path=` 建立並讓副檔名決定 MIME 型別，或用記憶體內的 `data=` 加上明確的 `format=`。
|
||||
* 回傳 `EmbeddedResource` 可以把一份文件（文字或 base64 blob，附上 URI 和 MIME 型別）放進結果；只想送出指標的話，回傳 `ResourceLink`。
|
||||
* 媒體結果沒有 `structured_content`，也沒有輸出 schema。
|
||||
* `Icon` 是個指標：一個 `src` URI，加上選用的 `mime_type`、`sizes` 和 `theme`。
|
||||
* `icons=[...]` 在伺服器、工具、資源和提示詞上都能用，用戶端會在對應的物件上找到它們。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, ffe823cb0fedd488, f33651add1b59094]
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, d30d3c20168b88b2, f5ef38dad59d6f76, 6e38a699ba57fbdf, 2b984a3bf37a0ddd]
|
||||
tool: 1
|
||||
---
|
||||
# 提示詞 {#prompts}
|
||||
|
|
@ -137,7 +137,52 @@ uv run mcp dev server.py
|
|||
```
|
||||
|
||||
!!! info
|
||||
如果讀過 **[工具](tools.md)**，這一頁的內容你都已經會了。同樣的裝飾器、同樣以 docstring 當描述、同樣的 `Annotated`/`Field`。唯一不同的是由誰觸發（使用者），以及結果去哪裡（進入對話）。
|
||||
如果讀過 **[工具](tools.md)**，到這裡為止的內容你都已經會了。同樣的裝飾器、同樣以 docstring 當描述、同樣的 `Annotated`/`Field`。唯一不同的是由誰觸發（使用者），以及結果去哪裡（進入對話）。
|
||||
|
||||
## 不只是文字 {#more-than-text}
|
||||
|
||||
`UserMessage` 和 `AssistantMessage` 凡是接受 `str` 的地方，也都接受內容區塊，或 `Image`／`Audio` 輔助類別。提示詞裡常見兩種情況：附上一份文件，以及附上一張圖片。
|
||||
|
||||
### 嵌入檔案 {#embedding-a-file}
|
||||
|
||||
```python title="server.py" hl_lines="5 12 21 23"
|
||||
--8<-- "docs_src/prompts/tutorial004.py"
|
||||
```
|
||||
|
||||
* 風格指南是位於 `style://python` 的資源（**[資源](resources.md)** 會介紹），從 `server.py` 旁邊的 `style-guide.md` 讀取。放任何一個 Markdown 檔案在那裡都可以。
|
||||
* `EmbeddedResource(resource=TextResourceContents(...))`（兩者都來自 `mcp.types`）把檔案連同 URI 和 MIME 類型當成第一則訊息帶上；引用它的請求以純文字接在後面。
|
||||
* 用嵌入而不是把指南貼進 f-string，用戶端就能把它顯示成附件，之後還能重新打開 `style://python`，而模型收到的是原封不動的檔案。二進位檔案則改用 `BlobResourceContents` 搭配 base64 的 `blob`。
|
||||
|
||||
算繪之後，第一則訊息的 `content` 是一個 `resource` 區塊：
|
||||
|
||||
```json
|
||||
{"type": "resource", "resource": {"uri": "style://python", "mimeType": "text/markdown", "text": "* Prefer early returns.\n..."}}
|
||||
```
|
||||
|
||||
### 附上圖片 {#attaching-an-image}
|
||||
|
||||
```python title="server.py" hl_lines="4 15"
|
||||
--8<-- "docs_src/prompts/tutorial005.py"
|
||||
```
|
||||
|
||||
* `Image` 是 **[圖片、音訊與圖示](media.md)** 裡的輔助類別。提示詞算繪時，`UserMessage` 會把它轉成 `ImageContent` 區塊（檔案以 base64 編碼，MIME 類型從 `.png` 推測）；`Audio` 也以同樣方式變成 `AudioContent`。
|
||||
* 在 `server.py` 旁邊放任何一張名為 `architecture.png` 的 PNG。提示詞引數是字串，所以圖片一定來自伺服器；`component` 只提供文字。
|
||||
|
||||
```json
|
||||
{"type": "image", "data": "iVBORw0KGgoAAAANSUhEUg...", "mimeType": "image/png"}
|
||||
```
|
||||
|
||||
## 執行時變更清單 {#changing-the-list-at-runtime}
|
||||
|
||||
用戶端連著的時候也可以新增提示詞，例如讓使用者把一段指示存成自己的選單項目。先註冊提示詞，再發通知：
|
||||
|
||||
```python title="server.py" hl_lines="5 23-27"
|
||||
--8<-- "docs_src/prompts/tutorial006.py"
|
||||
```
|
||||
|
||||
* `mcp.add_prompt(Prompt.from_function(fn, name=..., description=...))` 註冊函式的效果和 `@mcp.prompt()` 完全一樣，`mcp.remove_prompt(name)` 則是反過來。`add_prompt` 遇到同名的既有項目會保留而不覆寫，所以這個工具會先移除舊的，讓儲存變成取代。`prompts/list` 會立即反映變更。
|
||||
* `await ctx.notify_prompts_changed()` 把 `notifications/prompts/list_changed` 送給每個在 `subscriptions/listen` 串流上監聽的 `2026-07-28` 用戶端（**[訂閱](../handlers/subscriptions.md)**）。呼叫端是 2026 之前的用戶端時，`await ctx.session.send_prompt_list_changed()` 會把通知送給它（**[服務舊版用戶端](../run/legacy-clients.md)**）。兩個都呼叫；沒有人可通知時，各自什麼都不做。
|
||||
* 收到通知的用戶端會再呼叫一次 `prompts/list`。在 Python 的 `Client` 裡寫成 `async with client.listen(prompts_list_changed=True) as sub:`，會產出 `PromptsListChanged` 事件。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
|
|
@ -147,5 +192,7 @@ uv run mcp dev server.py
|
|||
* 回傳 `str` 會變成一則使用者訊息。回傳 `UserMessage`／`AssistantMessage` 的清單，可以替多輪對話起頭。
|
||||
* `title=` 和 `Field(description=...)` 是用戶端放在 UI 上的內容。
|
||||
* 缺少必填引數會讓整個請求失敗，沒有個別提示詞的錯誤結果。
|
||||
* 把 `EmbeddedResource` 或 `Image` 包進 `UserMessage`，就能附上文件或圖片。
|
||||
* 執行時用 `mcp.add_prompt(...)`／`mcp.remove_prompt(...)` 新增或移除提示詞，接著 `await ctx.notify_prompts_changed()` 和 `await ctx.session.send_prompt_list_changed()`。
|
||||
|
||||
伺服器端替提示詞（或資源範本）引數做自動完成，請見 **[自動完成](completions.md)**。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [a838d57f003aed44, 857d03886a0137ed, 42d9efcb9f542867, 2290ff08435b5573, e866c192e11d1c14, 6cdbad079f7b47f0, d4b607372fb28b51, 18dbf726ac45e0b7, c6f7d2a148aa49f4, c851964bb3301907, d715db6f8dccc9cc, ef86634aa70498a7]
|
||||
sections: [a838d57f003aed44, 857d03886a0137ed, 42d9efcb9f542867, 2290ff08435b5573, 91be9b73602abcf1, 6cdbad079f7b47f0, d4b607372fb28b51, 18dbf726ac45e0b7, c7eff2a5698225fa, c851964bb3301907, 8f296f1f09e4c400, d715db6f8dccc9cc, a0c344a48450dbe4]
|
||||
tool: 1
|
||||
---
|
||||
# 結構化輸出 {#structured-output}
|
||||
|
|
@ -103,7 +103,7 @@ result.structured_content # {"temperature": 16.2, "humidity": 0.83, "conditions
|
|||
--8<-- "docs_src/structured_output/tutorial003.py"
|
||||
```
|
||||
|
||||
`TypedDict` 在執行時就是普通的 `dict`，所以建立並回傳的就是它。schema、驗證和 `structured_content` 都跟 `BaseModel` 版本一模一樣（少了描述，因為 `TypedDict` 沒有地方放）。
|
||||
`TypedDict` 在執行時就是普通的 `dict`，所以建立並回傳的就是它。schema、驗證和 `structured_content` 都遵循跟 `BaseModel` 版本一樣的規則：加上類別 docstring 或 `Annotated[..., Field(description=...)]`，它們就成為描述；dict 裡沒放進去的 `NotRequired` 鍵，也不會出現在 `structured_content` 裡。
|
||||
|
||||
## dataclass {#a-dataclass}
|
||||
|
||||
|
|
@ -185,16 +185,16 @@ result.structured_content # {"London": 16.2, "Reykjavik": 4.4}
|
|||
註記承諾的是 `WeatherData`，但上游回應不再送 `humidity` 了。
|
||||
|
||||
!!! check
|
||||
呼叫 `get_weather`，它不會默默把一個半空的物件交給用戶端。呼叫會失敗，錯誤的頭幾行就點名了那個欄位：
|
||||
呼叫 `get_weather`，它不會默默把一個半空的物件交給用戶端。呼叫會失敗：用戶端收到 `is_error=True` 和 `Error executing tool get_weather`，所以模型知道呼叫失敗了，而不是信心滿滿地讀一份根本不存在的天氣。欄位名稱是留給你看的，在伺服器記錄裡以 `ERROR` 層級出現：
|
||||
|
||||
```text
|
||||
Error executing tool get_weather: 1 validation error for WeatherData
|
||||
Tool 'get_weather' raised an unexpected exception
|
||||
...
|
||||
pydantic_core._pydantic_core.ValidationError: 1 validation error for WeatherData
|
||||
humidity
|
||||
Field required [type=missing, input_value={'temperature': 16.2, 'conditions': 'Overcast'}, input_type=dict]
|
||||
```
|
||||
|
||||
這段文字會以 `is_error=True` 的工具結果回傳，所以模型知道呼叫失敗了，而不是信心滿滿地讀一份根本不存在的天氣。
|
||||
|
||||
順帶一提，從 `-> WeatherData` 的工具回傳普通的 `dict` 沒問題，`json.loads` 產生的正是這個。驗證看的是值，不是 Python 型別。
|
||||
|
||||
## 選擇退出 {#opting-out}
|
||||
|
|
@ -209,6 +209,10 @@ result.structured_content # {"London": 16.2, "Reykjavik": 4.4}
|
|||
|
||||
反過來，`structured_output=True` 會把自動偵測變成硬性要求：回傳型別產生不出 schema 的工具，會在匯入時引發例外，而不是退回文字。
|
||||
|
||||
## 內容區塊與媒體 {#content-blocks-and-media}
|
||||
|
||||
內容區塊和媒體（`TextContent`、`EmbeddedResource`、`Image`、`Audio` 這一類，不論是單獨出現、作為 `list`、`tuple` 或 `Sequence` 的元素，還是作為 union 的分支）會自動幫你退出：它們是給模型讀的，所以自動偵測不會從中推導出 schema（`Image` 和 `Audio` 在 **[圖片、音訊與圖示](media.md)** 說明）。對內容區塊類別，`structured_output=True` 仍然會強制產生一個 schema。
|
||||
|
||||
## 沒有型別提示的類別 {#a-class-without-type-hints}
|
||||
|
||||
有一種情況會在沒有要求的前提下變成非結構化：回傳一個**本體上沒有任何註記**的類別。
|
||||
|
|
@ -237,6 +241,6 @@ result.structured_content # {"London": 16.2, "Reykjavik": 4.4}
|
|||
* 純量、串列、tuple 和 union 會包進 `{"result": ...}`。模型、`TypedDict`、dataclass、帶註記的類別和 `dict[str, ...]` 本來就是物件，維持原樣。
|
||||
* 每個結果都帶有 `content`（文字，給模型）**和** `structured_content`（資料，給應用程式）。
|
||||
* 回傳的東西會拿 schema 驗證。不符合就是工具錯誤，不會是一份壞掉的結果。
|
||||
* `structured_output=False` 讓工具退出。沒有型別提示的類別會默默退出，要留意。
|
||||
* `structured_output=False` 讓工具退出。內容區塊、`Image` 和 `Audio` 預設就退出；沒有型別提示的類別會默默退出，要留意。
|
||||
|
||||
工具能回覆的一切，現在都掌握在你手上了。接下來是第二個基本元件：**[資源](resources.md)**。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [e4cc390d56573409, 8566e2b68594e9ad, 2c97b9f888398951, 048e5471dfa71aea, 3076b1e16ad95950, edbedf2a16e71311, 3d8ef8da89fa87c1, f6c0e02e6ea5a363]
|
||||
sections: [e4cc390d56573409, f30cf8103a6e918c, 2c97b9f888398951, 048e5471dfa71aea, 3076b1e16ad95950, edbedf2a16e71311, 3d8ef8da89fa87c1, f6c0e02e6ea5a363]
|
||||
tool: 1
|
||||
---
|
||||
# 工具 {#tools}
|
||||
|
|
@ -39,6 +39,8 @@ SDK 從這些型別提示產生一份 JSON Schema，並在 `tools/list` 時送
|
|||
|
||||
兩個引數都在 `required` 裡，因為都沒有預設值。等一下就會修正這點。（`title` 鍵是 Pydantic 產生的附帶產物；屬性、它們的型別和 `required` 才是契約。）
|
||||
|
||||
也沒有 `$schema` 鍵：MCP 把沒有這個鍵的 schema 當作 **JSON Schema 2020-12**，而這正是 Pydantic 產生的格式，所以在你到 **[低階 Server](../advanced/low-level-server.md#the-dialect-is-json-schema-2020-12)** 上親手寫 schema 之前，沒有什麼需要選的。
|
||||
|
||||
!!! tip
|
||||
這裡的型別提示不是說明文件，而是**契約**。如果用戶端送來 `"limit": "ten"`，SDK 會在函式執行之前就拒絕它。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [4a7033e1ed8ad602, 55dcbfff0c6271bf, 101ef9d14bf4ec46, 4b6c4a845438abc7, f98b46bafbee4acd]
|
||||
sections: [4a7033e1ed8ad602, 55dcbfff0c6271bf, 317f4256a650cab6, 4b6c4a845438abc7, f98b46bafbee4acd]
|
||||
tool: 1
|
||||
---
|
||||
# URI 範本與路徑安全 {#uri-templates-and-path-safety}
|
||||
|
|
@ -98,7 +98,7 @@ translation:
|
|||
|
||||
內建檢查擋得住常見情況，但無從得知你的沙箱邊界。存取檔案系統時，用 `safe_join` 解析路徑，並確認它仍在基底目錄之內：
|
||||
|
||||
```python title="server.py" hl_lines="4 14"
|
||||
```python title="server.py" hl_lines="5 15"
|
||||
--8<-- "docs_src/uri_templates/tutorial002.py"
|
||||
```
|
||||
|
||||
|
|
@ -127,7 +127,7 @@ translation:
|
|||
這些檢查只是啟發式的前置過濾；存取檔案系統時，`safe_join` 仍然是真正的隔離邊界。
|
||||
|
||||
!!! tip
|
||||
如果處理函式無法完成請求（檔案不存在、id 不認識），就引發例外。SDK 會把它轉成錯誤回應。協定錯誤和工具錯誤的差別請見 **[處理錯誤](handling-errors.md)**。
|
||||
如果處理函式無法完成請求（檔案不存在、id 不認識），就像上面的 `read_manual` 那樣引發 `ResourceNotFoundError`。用戶端會收到 `-32602`，附上你的訊息和 URI。非預期的例外則會變成通用的 `-32603`。請見 **[處理錯誤](handling-errors.md#a-resource-that-doesnt-exist)**。
|
||||
|
||||
## 低階 Server 上的資源 {#resources-on-the-low-level-server}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue