docs: publish translated docs in twelve languages and the tool that maintains them (#3280)
This commit is contained in:
parent
14aa889992
commit
52ad0a8876
1 changed files with 89737 additions and 54 deletions
122
i18n/ru/pages/servers/media.md
Normal file
122
i18n/ru/pages/servers/media.md
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
---
|
||||
translation:
|
||||
sections: [496394d24d221bf1, 4ceb4591180dc6c3, 0fd63e4682d02e0c, 969ede0bd3686a16, 043f526230dd243d, 6ee3e9bcfd24047a]
|
||||
tool: 1
|
||||
---
|
||||
# Медиа {#media}
|
||||
|
||||
Текст — не единственное, что может вернуть инструмент.
|
||||
|
||||
В SDK есть два вспомогательных класса для двоичных результатов (**`Image`** и **`Audio`**) и тип **`Icon`**, который даёт серверу, инструментам, ресурсам и промптам лицо в интерфейсе клиента.
|
||||
|
||||
## Возврат изображения {#returning-an-image}
|
||||
|
||||
Укажите `Image` в аннотации возвращаемого типа, передайте путь к файлу и верните результат:
|
||||
|
||||
```python title="server.py" hl_lines="8 12 14"
|
||||
--8<-- "docs_src/media/tutorial001.py"
|
||||
```
|
||||
|
||||
* `Image` принимает ровно один из параметров: `path` (файл для чтения) или `data` (сырые байты).
|
||||
* MIME-тип, который увидит клиент, определяется по расширению: `logo.png` объявляется как `image/png`.
|
||||
* В логотипах нет ничего особенного. Подойдёт любой PNG рядом с `server.py`: график, который построил ваш код, диаграмма, фотография.
|
||||
|
||||
`Image` — это удобство SDK, а не тип протокола. В передаваемых данных возвращаемое значение превращается в блок **`ImageContent`** (байты файла в кодировке base64 плюс MIME-тип):
|
||||
|
||||
```python
|
||||
result.content # [ImageContent(type="image", data="iVBORw0KGgoAAAANSUhEUg...", mime_type="image/png")]
|
||||
result.structured_content # None
|
||||
```
|
||||
|
||||
Обратите внимание на две вещи:
|
||||
|
||||
* `data` — это base64. К байтам вы не прикасались: SDK прочитал файл и закодировал его сам.
|
||||
* `structured_content` равно `None`. `Image` — это содержимое, на которое смотрит модель, а не данные, которые разбирает приложение: схемы выходных данных нет. (Сравните со страницей **[Структурированный вывод](structured-output.md)**, где аннотация возвращаемого типа и *есть* схема.)
|
||||
|
||||
!!! info
|
||||
`ImageContent` и `AudioContent` находятся в `mcp.types`, рядом с `TextContent`,
|
||||
в который превращается обычный результат типа `str` (**[Инструменты](tools.md)**). Результат инструмента — это список блоков содержимого; `Image` и `Audio` —
|
||||
самый короткий способ получить два двоичных вида.
|
||||
|
||||
### Попробуйте сами {#try-it}
|
||||
|
||||
Положите любой PNG рядом с `server.py`, назовите его `logo.png` и запустите:
|
||||
|
||||
```console
|
||||
uv run mcp dev server.py
|
||||
```
|
||||
|
||||
Откройте вкладку **Tools** и вызовите `logo`. Результат — не строка, а блок содержимого `image`, и Inspector показывает вашу картинку. Всё, что произошло между файлом на диске и пикселями на экране, сделал SDK.
|
||||
|
||||
## Возврат аудио {#returning-audio}
|
||||
|
||||
`Audio` устроен так же. Оставьте `logo.png` на месте и положите рядом любой WAV под именем `chime.wav`:
|
||||
|
||||
```python title="server.py" hl_lines="18-21"
|
||||
--8<-- "docs_src/media/tutorial002.py"
|
||||
```
|
||||
|
||||
Результат — блок **`AudioContent`**:
|
||||
|
||||
```python
|
||||
result.content # [AudioContent(type="audio", data="UklGR...", mime_type="audio/wav")]
|
||||
result.structured_content # None
|
||||
```
|
||||
|
||||
Всё то же самое: на входе файл на диске, на выходе base64 и MIME-тип, схемы выходных данных нет.
|
||||
|
||||
## Байты или файл {#bytes-or-a-file}
|
||||
|
||||
Оба класса принимают и `data=` (сырые байты) вместо `path=`. Этот режим — для байтов, у которых никогда не было собственного файла: столбец базы данных, HTTP-ответ, то, что только что нарисовал Pillow:
|
||||
|
||||
```python title="server.py" hl_lines="14 15"
|
||||
--8<-- "docs_src/media/tutorial003.py"
|
||||
```
|
||||
|
||||
С `path=` объявлять нечего: файл читается при сборке результата, а MIME-тип определяется по расширению:
|
||||
|
||||
* `Image`: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`.
|
||||
* `Audio`: `.wav`, `.mp3`, `.ogg`, `.flac`, `.aac`, `.m4a`.
|
||||
|
||||
Для неизвестного расширения используется `application/octet-stream`.
|
||||
|
||||
!!! check
|
||||
С `data=` имени файла нет, и угадывать не по чему. Забудете `format=` —
|
||||
и SDK возьмёт значение по умолчанию: `image/png` для изображений, `audio/wav` для аудио. Соберите так
|
||||
`Audio` из байтов MP3 — и клиенту сообщат `mime_type="audio/wav"`, после чего
|
||||
он честно не сможет это декодировать. Передаёте `data=` — передавайте и `format=`.
|
||||
|
||||
## Иконки {#icons}
|
||||
|
||||
`Icon` — это метаданные, а не содержимое. Изображение он не несёт: он указывает на него через URI, а клиент может загрузить его и показать рядом с именем сервера, инструментом, ресурсом или промптом.
|
||||
|
||||
```python title="server.py" hl_lines="4-5 7 10 16"
|
||||
--8<-- "docs_src/media/tutorial004.py"
|
||||
```
|
||||
|
||||
* `src` — это URI, который клиент может разрешить: `https:` или `data:`, если нужно встроить иконку без дополнительной загрузки.
|
||||
* `mime_type` и `sizes` (`"48x48"` или `"any"` для масштабируемого формата) позволяют клиенту выбрать подходящую иконку, когда вы предлагаете несколько.
|
||||
* `theme="light"` или `theme="dark"` помечает иконку для одной цветовой схемы.
|
||||
|
||||
Тот же именованный аргумент `icons=[...]` принимают `MCPServer(...)`, `@mcp.tool()`, `@mcp.resource()` и `@mcp.prompt()`.
|
||||
|
||||
### Где их видит клиент {#where-a-client-sees-them}
|
||||
|
||||
Иконки путешествуют вместе с тем, что они украшают. Иконки сервера приходят при подключении клиента, в `client.server_info` (на подключениях поколения 2026 это поле необязательное, поэтому сначала сузьте тип):
|
||||
|
||||
```python
|
||||
assert client.server_info is not None # python-sdk servers identify themselves by default
|
||||
client.server_info.icons # [Icon(src="https://example.com/brand-kit.png", mime_type="image/png", sizes=["48x48"])]
|
||||
```
|
||||
|
||||
Иконки инструмента находятся в объекте `Tool` из `tools/list`, ресурса — в `Resource` из `resources/list`, промпта — в `Prompt` из `prompts/list`. Поле всегда называется `icons`.
|
||||
|
||||
## Итоги {#recap}
|
||||
|
||||
* Верните `Image` или `Audio` из инструмента — и клиент получит блок `ImageContent` / `AudioContent`: ваши байты в кодировке base64 с MIME-типом.
|
||||
* Собирайте их из `path=`, и тогда MIME-тип определит расширение, или из данных в памяти через `data=` с явным `format=`.
|
||||
* У медиарезультатов нет ни `structured_content`, ни схемы выходных данных.
|
||||
* `Icon` — это указатель: URI в `src` плюс необязательные `mime_type`, `sizes` и `theme`.
|
||||
* `icons=[...]` работает на сервере, инструментах, ресурсах и промптах, а клиенты находят их в соответствующих объектах.
|
||||
|
||||
Это всё, что инструмент может положить *в* результат. Что происходит, когда инструмент *завершается ошибкой* (и кто должен об этом узнать), — на странице **[Обработка ошибок](handling-errors.md)**.
|
||||
Loading…
Reference in a new issue