docs: refresh translations for recent English changes (#3379)
This commit is contained in:
Max
GitHub
parent
d8b638304e
commit
c5d7d0b6d0
2 changed files with 3149 additions and 1047 deletions
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [ebef1e7a0df854f4, a4c687d3d627d516, 8e79141fc2985342, b345dd05b9c3c7ab, 80ce41579825a6fa, 5f0fa90494de8f65, 83d10514eaa62fa5, 9190555aa39a5d28, 84a4c9d8bf14dddb, 927d71cf40b58c30]
|
||||
sections: [ebef1e7a0df854f4, 8355cfaf1f76c9d5, 8e79141fc2985342, 46bdb07c7537e8a5, 80ce41579825a6fa, 5f0fa90494de8f65, 83d10514eaa62fa5, 9190555aa39a5d28, 84a4c9d8bf14dddb, 927d71cf40b58c30]
|
||||
tool: 1
|
||||
---
|
||||
# 用戶端 {#the-client}
|
||||
|
|
@ -27,9 +27,10 @@ Python 程式要和 MCP 伺服器對話，靠的就是 **`Client`**。
|
|||
|
||||
* `MCPServer`（或低階的 `Server`）實例：在**同一個處理程序內**連線。
|
||||
* URL 字串（`Client("http://localhost:8000/mcp")`）：Streamable HTTP，也就是正式環境的路徑。
|
||||
* 一個**傳輸**：任何可以 `async with ... as (read, write)` 的東西，例如包住子處理程序的 `stdio_client(...)`。
|
||||
* `StdioServerParameters`：要當作**子處理程序**啟動的命令，透過它的 stdin 和 stdout 溝通。
|
||||
* 一個**傳輸**：任何可以 `async with ... as (read, write)` 的東西，例如用 `streamable_http_client(url, http_client=...)` 包住你自己的 HTTP 用戶端。
|
||||
|
||||
這一頁其餘的內容在這三種情況下完全相同。標頭、子處理程序、逾時，以及 `Transport` 協定另外有專屬的頁面：**[用戶端傳輸方式](transports.md)**。
|
||||
這一頁其餘的內容在這四種情況下完全相同。標頭、子處理程序、逾時，以及 `Transport` 協定另外有專屬的頁面：**[用戶端傳輸方式](transports.md)**。
|
||||
|
||||
### 連線後的用戶端上有什麼 {#whats-on-a-connected-client}
|
||||
|
||||
|
|
@ -82,7 +83,7 @@ tool.description # 'Search the catalog by title or author.'
|
|||
|
||||
`call_tool(name, arguments)` 會執行工具，並回傳一個 `CallToolResult`。
|
||||
|
||||
```python title="client.py" hl_lines="26-33"
|
||||
```python title="client.py" hl_lines="27-34"
|
||||
--8<-- "docs_src/client/tutorial003.py"
|
||||
```
|
||||
|
||||
|
|
@ -113,7 +114,7 @@ result.is_error # False
|
|||
會引發例外的工具，在用戶端這邊**不會**引發例外。它會以一個普通的結果回來，帶著 `is_error=True`。
|
||||
|
||||
!!! check
|
||||
向 `lookup_book` 要 `"Solaris"`（目錄裡沒有的書名），函式會引發 `ValueError`。呼叫仍然正常回傳：
|
||||
向 `lookup_book` 要 `"Solaris"`（目錄裡沒有的書名），函式會引發 `ToolError`。呼叫仍然正常回傳：
|
||||
|
||||
```python
|
||||
result.is_error # True
|
||||
|
|
@ -121,7 +122,7 @@ result.is_error # False
|
|||
result.structured_content # None
|
||||
```
|
||||
|
||||
例外的訊息落在 `content` 裡，**模型**可以讀到它並再試一次。這是刻意的設計：工具錯誤是對話的一部分，不是當機。在信任 `structured_content` 之前，一定要先看 `is_error`。
|
||||
`ToolError` 的訊息落在 `content` 裡，**模型**可以讀到它並再試一次。這是刻意的設計：工具錯誤是對話的一部分，不是當機。（假如工具是因為其他例外而當掉，`content` 就只會寫 `Error executing tool lookup_book`。）在信任 `structured_content` 之前，一定要先看 `is_error`。
|
||||
|
||||
!!! warning
|
||||
`is_error=True` 涵蓋的不只是你自己的 `raise`。要一個伺服器根本沒有的工具（`call_tool("does_not_exist", {})`），也不會引發任何例外。你會拿回同樣的形狀：`is_error=True`，`content` 裡是 `Unknown tool: does_not_exist`。只有在伺服器回的是 JSON-RPC **錯誤**而不是結果時，`Client` 的方法才會引發 `MCPError`；伺服器什麼時候產生哪一種，請見 **[處理錯誤](../servers/handling-errors.md)**。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [9cac816674181eb0, 0700f337babcd4dd, 2bde0dd58cdf00f5, ff7401df479af877, 3d0832f39b0d7059, d4bf7e4479637768, 05e20c0a798860e7]
|
||||
sections: [9cac816674181eb0, 0700f337babcd4dd, 2bde0dd58cdf00f5, 40b4916d82eaf1d4, 3d0832f39b0d7059, dfa4446556badef0, 5bd93be2ab2ecb9c]
|
||||
tool: 1
|
||||
---
|
||||
# 用戶端傳輸方式 {#client-transports}
|
||||
|
|
@ -76,15 +76,15 @@ translation:
|
|||
|
||||
**stdio** 伺服器是一個子處理程序。用戶端啟動它，把 JSON-RPC 寫進它的 stdin，再從它的 stdout 讀取 JSON-RPC。桌面版 MCP 主機（host）就是這樣在你的機器上執行伺服器的：主機**就是**這段程式碼加上一個 UI，而 **[連接到真正的主機](../get-started/real-host.md)** 則是從主機那一側、以設定檔的形式看同一個關係。
|
||||
|
||||
用 `StdioServerParameters` 描述這個處理程序，用 `stdio_client` 把它變成傳輸，再把**那個**交給 `Client`：
|
||||
用 `StdioServerParameters` 描述這個處理程序，再把它交給 `Client`：
|
||||
|
||||
```python title="client.py" hl_lines="4-8 12"
|
||||
```python title="client.py" hl_lines="3-7 11"
|
||||
--8<-- "docs_src/client_transports/tutorial004.py"
|
||||
```
|
||||
|
||||
`Client` 不接受單獨的參數物件。`StdioServerParameters` 是設定；`stdio_client(server)` 才是知道怎麼依據它啟動處理程序的傳輸。一定要包起來。
|
||||
進入區塊時會啟動處理程序。離開區塊時，子處理程序也會一併關閉：關掉 stdin、等待、拖太久就強制終止。你永遠不需要自己清理。
|
||||
|
||||
離開 `async with` 區塊時，子處理程序也會一併關閉：關掉 stdin、等待、拖太久就強制終止。你永遠不需要自己清理。
|
||||
子處理程序的 stderr 會接到你的 stderr。想送到別的地方，就自己用 `stdio_client`（來自 `mcp`）建立傳輸，改傳入那個：`Client(stdio_client(server, errlog=log_file))`。
|
||||
|
||||
!!! warning
|
||||
子處理程序**不會**繼承你的環境。它拿到的是一份精簡的允許清單（POSIX 上是 `HOME`、`LOGNAME`、`PATH`、`SHELL`、`TERM` 和 `USER`），這樣敏感的東西才不會洩漏到一個可能不是你寫的處理程序裡。
|
||||
|
|
@ -99,16 +99,16 @@ translation:
|
|||
|
||||
對 `Client` 來說，上面這些全都是同一種東西。
|
||||
|
||||
**傳輸**是任何會產出一對 `(read, write)` 訊息串流的非同步 context manager：正式地說，就是 `mcp.client` 裡的 `Transport` 協定。`Client` 依型別解析它的引數：伺服器物件就在處理程序內連線，`str` 會變成 `streamable_http_client(url)`，其他任何東西則直接當成傳輸進入。最後這條規則就是為什麼 `stdio_client(...)`、`streamable_http_client(...)` 和 `sse_client(...)` 都能放進同一個位置，也是為什麼你可以自己寫一個。
|
||||
**傳輸**是任何會產出一對 `(read, write)` 訊息串流的非同步 context manager：正式地說，就是 `mcp.client` 裡的 `Transport` 協定。`Client` 依型別解析它的引數：伺服器物件就在處理程序內連線，`str` 會變成 `streamable_http_client(url)`，`StdioServerParameters` 會變成 `stdio_client(params)`，其他任何東西則直接當成傳輸進入。最後這條規則就是為什麼 `stdio_client(...)`、`streamable_http_client(...)` 和 `sse_client(...)` 都能放進同一個位置，也是為什麼你可以自己寫一個。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* `Client(mcp)`（伺服器物件）在記憶體內連線。用在測試和嵌入。
|
||||
* `Client("http://.../mcp")`（URL）透過 Streamable HTTP 連線，也就是正式環境用的傳輸方式。
|
||||
* 標頭、驗證、proxy 和逾時都放在你傳給 `streamable_http_client(url, http_client=...)` 的 `httpx2.AsyncClient` 上。沒有 `headers=` 這個關鍵字引數。
|
||||
* stdio 是 `Client(stdio_client(StdioServerParameters(...)))`，絕對不是單獨的參數物件。
|
||||
* stdio 是 `Client(StdioServerParameters(...))`。只有要把子處理程序的 stderr 導到別處時，才需要自己用 `stdio_client(...)` 包起來。
|
||||
* 子處理程序拿到的是允許清單上的環境，不是你的環境；`env=` 會往上加。
|
||||
* 傳輸就是任何可以 `async with x as (read, write)` 的東西。只要不是伺服器物件或 URL，`Client` 就會直接交給那個協定處理。
|
||||
* 傳輸就是任何可以 `async with x as (read, write)` 的東西。只要不是伺服器物件、URL 或 `StdioServerParameters`，`Client` 就會直接交給那個協定處理。
|
||||
* 建立 `Client` 是選定傳輸方式。`async with` 才是開啟它。
|
||||
|
||||
傳輸開啟之後，兩邊得對協定版本達成一致。平常根本不需要去想這件事；真的需要的時候，請看 **[協定版本](../protocol-versions.md)**。
|
||||
|
|
|
|||
Loading…
Reference in a new issue