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
|
||||
---
|
||||
# Hataları ele alma {#handling-errors}
|
||||
|
||||
Bir araç iki şekilde başarısız olabilir ve SDK bu ikisini çok farklı ele alır.
|
||||
Bir araç üç şekilde başarısız olabilir ve SDK her birini farklı ele alır.
|
||||
|
||||
Sıradan bir istisna fırlatırsanız bunu **model** görür. `MCPError` fırlatırsanız bunu **protokol** görür.
|
||||
`ToolError` fırlatırsanız mesajınızı **model** görür. `MCPError` fırlatırsanız bunu **protokol** görür. Başka herhangi bir şey fırlatırsanız bu bir çökmedir: model yalnızca çağrının başarısız olduğunu öğrenir, traceback ise log'unuza düşer.
|
||||
|
||||
Bu sayfa, hangisini seçeceğinizle ilgili.
|
||||
|
||||
|
|
@ -15,11 +15,11 @@ Bu sayfa, hangisini seçeceğinizle ilgili.
|
|||
|
||||
Bir şeyi arayıp bulan bir araç düşünün; arama sonuçsuz kalsın:
|
||||
|
||||
```python title="server.py" hl_lines="11-12"
|
||||
```python title="server.py" hl_lines="2 12-13"
|
||||
--8<-- "docs_src/handling_errors/tutorial001.py"
|
||||
```
|
||||
|
||||
Bu iki satırda MCP'ye özgü hiçbir şey yok. `get_author`, herhangi bir Python fonksiyonunun yapacağı gibi düz bir `ValueError` fırlatır.
|
||||
`mcp.server.mcpserver.exceptions` içindeki `ToolError`, bir aracın modele bir şeylerin ters gittiğini söyleme yoludur.
|
||||
|
||||
Katalogda olmayan bir başlıkla çağırın ve sonuca bakın:
|
||||
|
||||
|
|
@ -30,13 +30,15 @@ result.structured_content # None
|
|||
```
|
||||
|
||||
* İstek **başarılı oldu**. Ortada bir sonuç var; çağıran tarafta hiçbir şey fırlatılmadı.
|
||||
* `is_error` değeri `True`; istisnanızın mesajı (başına araç adı eklenmiş olarak) `content`'te, tam da modelin okuduğu yerde.
|
||||
* `is_error` değeri `True`; mesajınız (başına araç adı eklenmiş olarak) `content`'te, tam da modelin okuduğu yerde.
|
||||
* `structured_content` değeri `None`. Başarısız bir çağrının yapılandırılacak bir dönüş değeri yoktur.
|
||||
|
||||
Bu bir **araç hatasıdır** ve aracınızın fırlattığı *her* istisna için varsayılan davranış budur. Neredeyse her zaman istediğiniz şey de budur.
|
||||
Bu bir **araç hatasıdır** ve neredeyse her zaman istediğiniz şey de budur.
|
||||
|
||||
Aracınızı çağıran modeldir. Argümanları o seçti. Bu yüzden araç hatası, konuşmada bir tur demektir: model *"No book titled 'Nothing' in the catalog."* mesajını okur, başlığı yanlış tahmin ettiğini anlar ve daha iyi bir başlıkla tekrar çağırır. Tek bir `raise` yazdınız ve kendi kendini düzelten bir ajan elde ettiniz.
|
||||
|
||||
Sunucuda bir `ToolError`, log'da tek bir `INFO` satırıdır; traceback yoktur. Bunu zaten bekliyordunuz, bu yüzden araştırılacak bir şey yok.
|
||||
|
||||
!!! tip
|
||||
Bir araçtan hata mesajını asla `return` ile döndürmeyin. Döndürülen bir dizenin `is_error=False`
|
||||
değeri vardır; bu yüzden modele (ve her istemci arayüzüne) araç çalışmış ve yanıt o dizeymiş gibi görünür.
|
||||
|
|
@ -44,7 +46,7 @@ Aracınızı çağıran modeldir. Argümanları o seçti. Bu yüzden araç hatas
|
|||
|
||||
## Modelin düzeltemeyeceği bir hata {#an-error-the-model-cannot-fix}
|
||||
|
||||
Şimdi `ValueError` yerine `MCPError` koyun.
|
||||
Şimdi `ToolError` yerine `MCPError` koyun.
|
||||
|
||||
```python title="server.py" hl_lines="1 3 14"
|
||||
--8<-- "docs_src/handling_errors/tutorial002.py"
|
||||
|
|
@ -77,10 +79,10 @@ Aracınızı çağıran modeldir. Argümanları o seçti. Bu yüzden araç hatas
|
|||
|
||||
İki yol, iki farklı soruyu yanıtlar.
|
||||
|
||||
* *Yürütme* başarısızlığı için **herhangi bir istisna fırlatın**: aracınızın yapmaya çalıştığı şey işe yaramadı. Çağrıyı model seçti, bu yüzden sonucunu da model görmeli ve toparlanma şansı bulmalı. Yanlış yazılmış bir başlık, zaman aşımına uğrayan bir dış API, var olmayan bir satır: hepsi araç hatası.
|
||||
* *Yürütme* başarısızlığı için **`ToolError` fırlatın**: aracınızın yapmaya çalıştığı şey işe yaramadı. Çağrıyı model seçti, bu yüzden sonucunu da model görmeli ve toparlanma şansı bulmalı. Yanlış yazılmış bir başlık, zaman aşımına uğrayan bir dış API, var olmayan bir satır: hepsi araç hatası.
|
||||
* *İsteğin kendisi* reddedilmesi gerektiğinde **`MCPError` fırlatın**: istemcide aracınızın bağımlı olduğu bir yetenek eksik, sunucu kimseye hizmet verecek durumda değil, çağıran taraf zorunlu bir adımı atlamış. Modelin hiçbir yeniden denemesi bunları düzeltmez; bu yüzden mesajı ona vermenin bir kazancı yok.
|
||||
|
||||
Kararı tek bir soru verir: **daha akıllı bir model bundan kaçınabilir miydi?** Evet -> sıradan istisna. Hayır -> `MCPError`.
|
||||
Kararı tek bir soru verir: **daha akıllı bir model bundan kaçınabilir miydi?** Evet -> `ToolError`. Hayır -> `MCPError`.
|
||||
|
||||
Bu ölçüte göre `get_author`'ın ikinci sürümü yanlış seçim yaptı: daha iyi bir başlık sorunu çözer, yani model mesajı görmeyi hak ediyordu. O sürüm size mekanizmayı göstermek için orada, onu önermek için değil.
|
||||
|
||||
|
|
@ -89,6 +91,25 @@ Bu ölçüte göre `get_author`'ın ikinci sürümü yanlış seçim yaptı: dah
|
|||
bir `data` yükü alır. Bunlara ne koyarsanız istemci onu alır: SDK, fırlatılan bir
|
||||
`MCPError`'ı temizlemek yerine olduğu gibi iletir.
|
||||
|
||||
## Başka herhangi bir istisna {#any-other-exception}
|
||||
|
||||
Şimdi denetimi çıkarın ve sözlük aramasının kendi kendine başarısız olmasına izin verin:
|
||||
|
||||
```python title="server.py" hl_lines="11"
|
||||
--8<-- "docs_src/handling_errors/tutorial004.py"
|
||||
```
|
||||
|
||||
`CATALOG[title]`, `KeyError` fırlatır. Bunu planlamadınız, bu yüzden SDK onu bir çökme olarak ele alır:
|
||||
|
||||
```python
|
||||
result.is_error # True
|
||||
result.content # [TextContent(text="Error executing tool get_author")]
|
||||
```
|
||||
|
||||
Çağrı yine `is_error=True` döndürür; yani model başarısız olduğunu bilir ve yoluna devam edebilir. Almadığı şey istisnanın metnidir: kodunuzdan gelen bir `KeyError` ya da üç kütüphane alttaki bir sürücüden gelen bir yığın SQL, sunucunuzun iç yapısını ele verebilir; bu yüzden sunucudan asla çıkmaz.
|
||||
|
||||
Onu siz alırsınız. Sunucu çökmeyi tam traceback ile `ERROR` düzeyinde, `Tool 'get_author' raised an unexpected exception` olarak log'a yazar. Bu yüzden `WARNING` düzeyindeki bir üretim log'u her `ToolError` boyunca sessiz kalır ve bir şey gerçekten bozulduğu anda sesini çıkarır.
|
||||
|
||||
## Var olmayan bir kaynak {#a-resource-that-doesnt-exist}
|
||||
|
||||
Kaynaklar da aynı çizgiyi çeker ve yaygın durum için adlandırılmış bir istisna sunar.
|
||||
|
|
@ -109,7 +130,7 @@ Yanıtlayamadığında `ResourceNotFoundError` fırlatın. SDK bunu, spesifikasy
|
|||
}
|
||||
```
|
||||
|
||||
Burada `is_error=True` taşıyan yarım bir sonuç olmadığına dikkat edin. Bir kaynak okuması ya içerik döndürür ya da başarısız olur: kaynakların yalnızca protokol yolu vardır. Şablonlar ve kaynaklarla ilgili diğer her şey **[Kaynaklar](resources.md)** sayfasında.
|
||||
Burada `is_error=True` taşıyan yarım bir sonuç olmadığına dikkat edin. Bir kaynak okuması ya içerik döndürür ya da başarısız olur: kaynakların yalnızca protokol yolu vardır. `ResourceError`, "bulunamadı" olmayan bir başarısızlık için aynı şeydir (`-32603`, sizin mesajınız); ikisi de log'unuzda tek bir `INFO` satırıdır. `MCPError` dışındaki diğer her istisna bir çökmedir: istemci yalnızca URI'yi belirten `-32603` alır, traceback ise `ERROR` düzeyinde log'unuza gider. Şablonlar ve kaynaklarla ilgili diğer her şey **[Kaynaklar](resources.md)** sayfasında.
|
||||
|
||||
## Hiç fırlatmadığınız hatalar {#errors-you-never-raise}
|
||||
|
||||
|
|
@ -120,19 +141,21 @@ Hatalı bir argüman fonksiyonunuza asla ulaşmaz.
|
|||
Bu, yazmadığınız koca bir `raise` ifadesi sınıfı demektir: kendi tür ipuçlarınızı yeniden doğrulamayın.
|
||||
|
||||
!!! info
|
||||
Bu sayfadaki her şey bir **istemcinin** gördüğüdür; testleri yazarken kullanacağınız bellek içi
|
||||
`Client` da tam olarak aynı şeyi görür. `raise_exceptions=True` bile bir araç hatasını tekrar
|
||||
traceback'e çevirmez: o bayrak devreye girebilecek noktaya geldiğinde istisnanız çoktan
|
||||
`is_error=True` sonucuna dönüşmüştür. Doğrulamayı sonuç üzerinde yapın. **[Test etme](../get-started/testing.md)** sayfası bu kalıbı anlatır.
|
||||
Bu sayfada bir **istemcinin** gördüğü her şeyi, testleri yazarken kullanacağınız bellek içi
|
||||
`Client` da görür. `raise_exceptions=True` bile başarısız olan bir
|
||||
aracın istisnasını çağırana geri vermez: o bayrak devreye girebilecek noktaya geldiğinde istisnanız çoktan
|
||||
`is_error=True` sonucuna dönüşmüştür. Doğrulamayı sonuç üzerinde yapın. Bir çökmenin traceback'ine ihtiyacınız varsa o
|
||||
sunucunun log'undadır ve pytest'in `caplog`'u onu yakalar. **[Test etme](../get-started/testing.md)** sayfası bu kalıbı anlatır.
|
||||
|
||||
## Özet {#recap}
|
||||
|
||||
* Bir araçta **herhangi bir istisna** fırlatın -> çağrı, mesajınız `content`'te olacak şekilde `is_error=True` döndürür. Model bunu okur ve yeniden deneyebilir. Varsayılan budur.
|
||||
* Bir araçta **`ToolError`** fırlatın -> çağrı, mesajınız `content`'te olacak şekilde `is_error=True` döndürür. Model bunu okur ve yeniden deneyebilir.
|
||||
* **`MCPError`** fırlatın -> çağrının kendisi bir JSON-RPC hatasıyla başarısız olur. Model hiçbir şey görmez; bununla host ilgilenir. `code`, `message` ve `data` bozulmadan ulaşır.
|
||||
* Belirleyici soru: *daha akıllı bir model bundan kaçınabilir miydi?* Evet -> istisna. Hayır -> `MCPError`.
|
||||
* Belirleyici soru: *daha akıllı bir model bundan kaçınabilir miydi?* Evet -> `ToolError`. Hayır -> `MCPError`.
|
||||
* Diğer **her istisna** bir çökmedir -> model için yalnızca `Error executing tool <name>` içeren `is_error=True`, sizin için ise traceback'li bir `ERROR` kaydı.
|
||||
* Bir kaynak işleyicisinden `ResourceNotFoundError` -> protokolün `-32602` kodu, URI `data`'da.
|
||||
* Hatalı argümanlar, fonksiyonunuz çalışmadan önce şemaya göre reddedilir; bunlar için `raise` yazmazsınız.
|
||||
* `from mcp import MCPError`; hata kodu sabitleri `mcp.types`'tan gelir.
|
||||
* İçe aktarmalar: `from mcp import MCPError`, `from mcp.server.mcpserver.exceptions import ToolError, ResourceError, ResourceNotFoundError` ve `mcp.types`'tan hata kodu sabitleri.
|
||||
|
||||
Hatalar halloldu. Bir sunucunun *sunduğu* her şey bu kadar. Her işleyicinin çalışırken neleri okuyabildiği ve istemciye geri neler yapabildiği bir sonraki bölümde: **[İşleyicinin içinde](../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
|
||||
---
|
||||
# Medya {#media}
|
||||
|
|
@ -86,6 +86,24 @@ Tanımadığı bir uzantı `application/octet-stream`'e geri düşer.
|
|||
MP3 baytlarından bu şekilde bir `Audio` oluşturursanız istemciye `mime_type="audio/wav"`
|
||||
söylenir ve o da sadakatle çözmeyi başaramaz. `data=` geçirdiğinizde `format=` da geçirin.
|
||||
|
||||
## Bir kaynağı gömme {#embedding-a-resource}
|
||||
|
||||
Bir araç bir belge de döndürebilir: bulunduğu URI ve bir MIME türüyle birlikte bir miktar metin ya da bayt. Bu bir **`EmbeddedResource`**'tur, bir başka içerik bloğu türü. Düz bir `str`'den farklı olarak istemciye içeriğin ne olduğunu söyler; böylece istemci onu bir ek olarak gösterebilir ya da zaten bildiği bir kaynağı tanıyabilir.
|
||||
|
||||
```python title="server.py" hl_lines="7 14 16-18"
|
||||
--8<-- "docs_src/media/tutorial005.py"
|
||||
```
|
||||
|
||||
* `brand://guidelines` sıradan bir kaynaktır (bunları **[Kaynaklar](resources.md)** sayfası anlatır). Araç, istek üzerine aynı belgeyi modele verir ve `guidelines()`'ı doğrudan çağırmak tek bir doğruluk kaynağını korur.
|
||||
* `EmbeddedResource` ve `TextResourceContents`, `mcp.types` modülünden gelir. Görsellerdeki gibi bir yardımcı yoktur: oluşturduğunuz blok sonuca olduğu gibi girer ve `structured_content` yoktur.
|
||||
* Kaynağın kaydedildiği URI'yi kullanın; böylece istemci ekin ve `brand://guidelines` kaynağının aynı belge olduğunu anlayabilir. Kayıtlı olsun olmasın her URI geçerlidir.
|
||||
|
||||
```python
|
||||
result.content # [EmbeddedResource(type="resource", resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text="# Brand guidelines\n\n..."))]
|
||||
```
|
||||
|
||||
İkili içerik için `TextResourceContents` yerine, baytları base64 ile kodlayıp `blob` alanına koyarak `BlobResourceContents(uri=..., mime_type=..., blob=...)` kullanın. Yalnızca istemcinin daha sonra `resources/read` ile okuyabileceği bir işaretçi göndermek için bunun yerine bir `ResourceLink(name=..., uri=...)` döndürün; o da bir içerik bloğudur.
|
||||
|
||||
## Simgeler {#icons}
|
||||
|
||||
`Icon` içerik değil, meta veridir. Görseli taşımaz; bir URI ile ona işaret eder ve istemci onu getirip sunucunuzun adının, bir aracın, bir kaynağın veya bir prompt'un yanında gösterebilir.
|
||||
|
|
@ -115,6 +133,7 @@ Bir aracın simgeleri `tools/list`'ten gelen `Tool` nesnesinde, bir kaynağınki
|
|||
|
||||
* Bir araçtan `Image` veya `Audio` döndürün; istemci bir `ImageContent` / `AudioContent` bloğu alır: base64 ile kodlanmış baytlarınız ve bir MIME türü.
|
||||
* Bunu bir `path=` ile oluşturup MIME türünü uzantının belirlemesine bırakın ya da bellekteki `data=` ile açık bir `format=` kullanın.
|
||||
* Sonuca bir belge (URI'si ve MIME türüyle birlikte metin ya da base64 blob) koymak için bir `EmbeddedResource`, yalnızca işaretçiyi göndermek için bir `ResourceLink` döndürün.
|
||||
* Medya sonuçları `structured_content` ve çıktı şeması taşımaz.
|
||||
* `Icon` bir işaretçidir: bir `src` URI'si ile isteğe bağlı `mime_type`, `sizes` ve `theme`.
|
||||
* `icons=[...]` sunucuda, araçlarda, kaynaklarda ve prompt'larda çalışır; istemciler bunları eşleşen nesnelerde bulur.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, ffe823cb0fedd488, f33651add1b59094]
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, d30d3c20168b88b2, f5ef38dad59d6f76, 6e38a699ba57fbdf, 2b984a3bf37a0ddd]
|
||||
tool: 1
|
||||
---
|
||||
# Prompt'lar {#prompts}
|
||||
|
|
@ -139,10 +139,55 @@ Sonuncusuna dikkat edin. Bir `assistant` turunu önceden doldurmak, yönlendirme
|
|||
```
|
||||
|
||||
!!! info
|
||||
**[Araçlar](tools.md)** sayfasını okuduysanız bu sayfadaki her şeyi zaten biliyorsunuz. Aynı dekoratör,
|
||||
**[Araçlar](tools.md)** sayfasını okuduysanız buraya kadarki her şeyi zaten biliyorsunuz. Aynı dekoratör,
|
||||
açıklama olarak aynı docstring, aynı `Annotated`/`Field`. Değişen tek şey onu kimin
|
||||
tetiklediği (kullanıcı) ve sonucun nereye gittiğidir (konuşmaya).
|
||||
|
||||
## Metinden fazlası {#more-than-text}
|
||||
|
||||
`UserMessage` ve `AssistantMessage`, `str` kabul ettikleri her yerde bir içerik bloğunu ya da bir `Image` / `Audio` yardımcısını da kabul eder. Prompt'larda iki durum öne çıkar: bir belge eklemek ve bir resim eklemek.
|
||||
|
||||
### Dosya gömme {#embedding-a-file}
|
||||
|
||||
```python title="server.py" hl_lines="5 12 21 23"
|
||||
--8<-- "docs_src/prompts/tutorial004.py"
|
||||
```
|
||||
|
||||
* Stil kılavuzu `style://python` adresindeki bir kaynaktır (bunları **[Kaynaklar](resources.md)** sayfası anlatır) ve `server.py` dosyasının yanındaki `style-guide.md` dosyasından okunur. Oraya herhangi bir Markdown dosyası koyun.
|
||||
* Her ikisi de `mcp.types` modülünden gelen `EmbeddedResource(resource=TextResourceContents(...))`, dosyayı URI'si ve MIME türüyle birlikte ilk mesaj olarak taşır; ona atıfta bulunan istek düz metin olarak ardından gelir.
|
||||
* Kılavuzu f-string'e yapıştırmak yerine gömmek, istemcinin onu bir ek olarak göstermesini ve `style://python` kaynağını daha sonra yeniden açabilmesini sağlar; model de dosyayı olduğu gibi alır. İkili bir dosya için base64 `blob` içeren `BlobResourceContents` kullanın.
|
||||
|
||||
İşlendiğinde ilk mesajın `content` alanı bir `resource` bloğudur:
|
||||
|
||||
```json
|
||||
{"type": "resource", "resource": {"uri": "style://python", "mimeType": "text/markdown", "text": "* Prefer early returns.\n..."}}
|
||||
```
|
||||
|
||||
### Görsel ekleme {#attaching-an-image}
|
||||
|
||||
```python title="server.py" hl_lines="4 15"
|
||||
--8<-- "docs_src/prompts/tutorial005.py"
|
||||
```
|
||||
|
||||
* `Image`, **[Görseller, ses ve simgeler](media.md)** sayfasındaki yardımcıdır. Prompt işlendiğinde `UserMessage` onu bir `ImageContent` bloğuna dönüştürür (dosya base64 ile kodlanır, MIME türü `.png` uzantısından tahmin edilir); `Audio` da aynı şekilde bir `AudioContent` olur.
|
||||
* `server.py` dosyasının yanına `architecture.png` adında herhangi bir PNG koyun. Prompt argümanları dizedir, bu yüzden resim her zaman sunucudan gelir; `component` yalnızca sözcükleri sağlar.
|
||||
|
||||
```json
|
||||
{"type": "image", "data": "iVBORw0KGgoAAAANSUhEUg...", "mimeType": "image/png"}
|
||||
```
|
||||
|
||||
## Listeyi çalışma zamanında değiştirme {#changing-the-list-at-runtime}
|
||||
|
||||
İstemciler bağlıyken prompt eklenebilir; örneğin bir kullanıcının bir talimatı kendine ait bir menü girdisi olarak kaydetmesine izin vermek için. Prompt'u kaydedin, ardından bildirin:
|
||||
|
||||
```python title="server.py" hl_lines="5 23-27"
|
||||
--8<-- "docs_src/prompts/tutorial006.py"
|
||||
```
|
||||
|
||||
* `mcp.add_prompt(Prompt.from_function(fn, name=..., description=...))` bir fonksiyonu tıpkı `@mcp.prompt()`'un yapacağı gibi kaydeder; `mcp.remove_prompt(name)` ise bunun tersidir. `add_prompt` aynı ada sahip mevcut bir girdinin üzerine yazmak yerine onu korur; bu yüzden araç, kaydetmenin değiştirme anlamına gelmesi için önce varsa eskisini kaldırır. `prompts/list` değişikliği hemen yansıtır.
|
||||
* `await ctx.notify_prompts_changed()`, bir `subscriptions/listen` akışını dinleyen her `2026-07-28` istemcisine `notifications/prompts/list_changed` gönderir (**[Abonelikler](../handlers/subscriptions.md)**). `await ctx.session.send_prompt_list_changed()` ise çağıran istemci 2026 öncesiyse bildirimi ona gönderir (**[Eski nesil istemcilere hizmet verme](../run/legacy-clients.md)**). İkisini de çağırın; haber verecek kimse yoksa her biri hiçbir şey yapmaz.
|
||||
* Bildirimi alan bir istemci `prompts/list`'i yeniden çağırır. Python `Client`'ında bu, bir `PromptsListChanged` olayı üreten `async with client.listen(prompts_list_changed=True) as sub:` biçimindedir.
|
||||
|
||||
## Özet {#recap}
|
||||
|
||||
* Bir fonksiyonun üzerindeki `@mcp.prompt()` onu bir prompt yapar. Ad fonksiyondan, açıklama docstring'den gelir.
|
||||
|
|
@ -151,5 +196,7 @@ Sonuncusuna dikkat edin. Bir `assistant` turunu önceden doldurmak, yönlendirme
|
|||
* Bir `str` döndürün, tek bir kullanıcı mesajına dönüşür. Çok turlu bir konuşmanın temelini atmak için `UserMessage` / `AssistantMessage` listesi döndürün.
|
||||
* `title=` ve `Field(description=...)`, bir istemcinin arayüzüne koyduğu şeylerdir.
|
||||
* Eksik bir zorunlu argüman isteğin tamamını başarısız kılar. Prompt'a özgü bir hata sonucu yoktur.
|
||||
* Bir belge veya resim eklemek için bir `EmbeddedResource` ya da `Image` nesnesini `UserMessage` içine sarın.
|
||||
* Çalışma zamanında `mcp.add_prompt(...)` / `mcp.remove_prompt(...)` ile prompt ekleyin veya kaldırın, ardından `await ctx.notify_prompts_changed()` ve `await ctx.session.send_prompt_list_changed()` çağırın.
|
||||
|
||||
Bir prompt'un (veya bir kaynak şablonunun) argümanları için sunucu tarafı otomatik tamamlama **[Tamamlamalar](completions.md)** sayfasındadır.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
# Yapılandırılmış çıktı {#structured-output}
|
||||
|
|
@ -105,7 +105,7 @@ Her biçim bir sınıfı hak etmez. Bir `TypedDict` aynı şemayı üretir:
|
|||
--8<-- "docs_src/structured_output/tutorial003.py"
|
||||
```
|
||||
|
||||
`TypedDict` çalışma zamanında düz bir `dict`'tir; siz de onu oluşturup döndürürsünüz. Şema, doğrulama ve `structured_content`, `BaseModel` sürümüyle birebir aynıdır (`TypedDict`'te yeri olmayan açıklamalar hariç).
|
||||
`TypedDict` çalışma zamanında düz bir `dict`'tir; siz de onu oluşturup döndürürsünüz. Şema, doğrulama ve `structured_content`, `BaseModel` sürümüyle aynı kurallara uyar: bir sınıf docstring'i ya da `Annotated[..., Field(description=...)]` ekleyin, bunlar şemadaki tanımlar (description) olur; dict'in dışında bıraktığınız bir `NotRequired` anahtar da `structured_content`'in dışında kalır.
|
||||
|
||||
## Bir dataclass {#a-dataclass}
|
||||
|
||||
|
|
@ -188,17 +188,18 @@ Açıklama `WeatherData` vaat ediyor. Üst servisin yanıtı `humidity` gönderm
|
|||
|
||||
!!! check
|
||||
`get_weather`'ı çağırdığınızda istemciye sessizce yarı boş bir nesne vermez. Çağrı başarısız
|
||||
olur ve hatanın ilk satırları alanın adını verir:
|
||||
olur: istemci `Error executing tool get_weather` iletisiyle birlikte `is_error=True` alır; böylece
|
||||
model, var olmayan bir hava durumunu kendinden emin biçimde okumak yerine çağrının başarısız
|
||||
olduğunu bilir. Alanın adı ise sizin için, sunucu log'unda `ERROR` düzeyinde:
|
||||
|
||||
```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]
|
||||
```
|
||||
|
||||
Bu metin, `is_error=True` ile araç sonucu olarak geri döner; böylece model, var olmayan bir hava
|
||||
durumunu kendinden emin biçimde okumak yerine çağrının başarısız olduğunu bilir.
|
||||
|
||||
Bu arada, `-> WeatherData` bir araçtan düz bir `dict` döndürmek sorun değil. `json.loads`'un ürettiği tam olarak buydu. Doğrulama Python türüne değil, değere uygulanır.
|
||||
|
||||
## Devre dışı bırakma {#opting-out}
|
||||
|
|
@ -213,6 +214,10 @@ Bazen dönüş açıklaması protokol için değil, tür denetleyiciniz içindir
|
|||
|
||||
Tersi olan `structured_output=True`, otomatik algılamayı bir zorunluluğa çevirir: dönüş türü şema üretemeyen bir araç, metne geri düşmek yerine içe aktarma anında istisna fırlatır.
|
||||
|
||||
## İçerik blokları ve medya {#content-blocks-and-media}
|
||||
|
||||
İçerik blokları ve medya (`TextContent`, `EmbeddedResource`, `Image`, `Audio` ve benzerleri; tek başlarına, bir `list`, `tuple` ya da `Sequence`'in öğeleri olarak veya bir union'ın kolları olarak) sizin yerinize devre dışı bırakılır: bunlar modelin okuması içindir, bu yüzden otomatik algılama onlardan şema türetmez (`Image` ve `Audio`'yu **[Görseller, ses ve simgeler](media.md)** sayfası anlatır). `structured_output=True`, içerik bloğu sınıfları için yine de bir şemayı zorunlu kılar.
|
||||
|
||||
## Tür ipucu olmayan bir sınıf {#a-class-without-type-hints}
|
||||
|
||||
İstemeden yapılandırılmamış sonuca varmanın bir yolu vardır: **gövdesinde hiç açıklama olmayan** bir sınıf döndürmek.
|
||||
|
|
@ -245,6 +250,6 @@ Tersi olan `structured_output=True`, otomatik algılamayı bir zorunluluğa çev
|
|||
* Skalerler, listeler, tuple'lar ve union'lar `{"result": ...}` içine sarılır. Modeller, `TypedDict`'ler, dataclass'lar, açıklamalı sınıflar ve `dict[str, ...]` zaten nesnedir ve oldukları gibi kalırlar.
|
||||
* Her sonuç hem `content` (metin, model için) **hem de** `structured_content` (veri, uygulama için) taşır.
|
||||
* Döndürdüğünüz şey şemaya göre doğrulanır. Uyuşmazlık bozuk bir sonuç değil, bir araç hatasıdır.
|
||||
* `structured_output=False` bir aracı devre dışı bırakır. Tür ipucu olmayan bir sınıf sessizce devre dışı kalır; buna dikkat edin.
|
||||
* `structured_output=False` bir aracı devre dışı bırakır. İçerik blokları, `Image` ve `Audio` varsayılan olarak devre dışıdır; tür ipucu olmayan bir sınıf sessizce devre dışı kalır, buna dikkat edin.
|
||||
|
||||
Artık bir aracın geri söyleyebileceği her şeye hâkimsiniz. Sırada ikinci ilkel yapı var: **[Kaynaklar](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
|
||||
---
|
||||
# Araçlar {#tools}
|
||||
|
|
@ -39,6 +39,8 @@ SDK bu tür ipuçlarından bir JSON Schema üretir ve `tools/list` sırasında i
|
|||
|
||||
Hiçbirinin varsayılan değeri olmadığı için iki argüman da `required` içinde. Bunu birazdan düzelteceksiniz. (`title` anahtarları Pydantic'in ürettiği kalıntılardır; sözleşmeyi oluşturan şey özellikler, türleri ve `required`'dır.)
|
||||
|
||||
`$schema` anahtarı da yok: MCP, bu anahtarı taşımayan bir şemayı **JSON Schema 2020-12** olarak kabul eder; Pydantic'in ürettiği de budur. Bu yüzden **[alt düzey Server](../advanced/low-level-server.md#the-dialect-is-json-schema-2020-12)** üzerinde şemaları elle yazana kadar seçmeniz gereken bir şey yoktur.
|
||||
|
||||
!!! tip
|
||||
Tür ipuçları burada dokümantasyon değildir. **Sözleşmenin ta kendisidir**. Bir istemci `"limit": "ten"`
|
||||
gönderirse SDK bunu, fonksiyonunuz daha çalışmadan reddeder.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [4a7033e1ed8ad602, 55dcbfff0c6271bf, 101ef9d14bf4ec46, 4b6c4a845438abc7, f98b46bafbee4acd]
|
||||
sections: [4a7033e1ed8ad602, 55dcbfff0c6271bf, 317f4256a650cab6, 4b6c4a845438abc7, f98b46bafbee4acd]
|
||||
tool: 1
|
||||
---
|
||||
# URI şablonları ve yol güvenliği {#uri-templates-and-path-safety}
|
||||
|
|
@ -169,7 +169,7 @@ Yerleşik denetimler yaygın durumları durdurur ama sizin sandbox sınırınız
|
|||
bilemez. Dosya sistemi erişimi için yolu çözümlemek ve temel dizininizin
|
||||
içinde kaldığını doğrulamak üzere `safe_join` kullanın:
|
||||
|
||||
```python title="server.py" hl_lines="4 14"
|
||||
```python title="server.py" hl_lines="5 15"
|
||||
--8<-- "docs_src/uri_templates/tutorial002.py"
|
||||
```
|
||||
|
||||
|
|
@ -209,10 +209,11 @@ Bu denetimler sezgisel bir ön süzgeçtir; dosya sistemi erişimi için
|
|||
kapsama sınırı `safe_join` olmaya devam eder.
|
||||
|
||||
!!! tip
|
||||
İşleyiciniz isteği karşılayamıyorsa (dosya yok, kimlik bilinmiyor) bir
|
||||
istisna fırlatın. SDK bunu bir hata yanıtına dönüştürür. Protokol hatası
|
||||
ile araç hatası arasındaki fark için **[Hataları ele alma](handling-errors.md)**
|
||||
sayfasına bakın.
|
||||
İşleyiciniz isteği karşılayamıyorsa (dosya yok, kimlik bilinmiyor), yukarıda
|
||||
`read_manual`'ın yaptığı gibi `ResourceNotFoundError` fırlatın. İstemci,
|
||||
mesajınız ve URI ile birlikte `-32602` alır. Beklenmedik bir istisna ise
|
||||
bunun yerine genel bir `-32603` olur. Bkz.
|
||||
**[Hataları ele alma](handling-errors.md#a-resource-that-doesnt-exist)**.
|
||||
|
||||
## Düşük seviyeli Server üzerinde kaynaklar {#resources-on-the-low-level-server}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue