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
107
i18n/ru/pages/handlers/lifespan.md
Normal file
107
i18n/ru/pages/handlers/lifespan.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
translation:
|
||||
sections: [f3ca8ac5f90f2dfa, 85a1ef3588ba0736, 563346d4d5804933, 9e3528340d0bab53]
|
||||
tool: 1
|
||||
---
|
||||
# Жизненный цикл {#lifespan}
|
||||
|
||||
Большинство настоящих серверов держат что-то на протяжении всей своей работы: пул соединений с базой данных, HTTP-клиент, загруженную модель.
|
||||
|
||||
Создавать это при каждом вызове не хочется, а вот закрыть аккуратно — нужно. Для этого и служит **жизненный цикл** (lifespan).
|
||||
|
||||
## Типизированный жизненный цикл {#a-typed-lifespan}
|
||||
|
||||
Жизненный цикл — это `@asynccontextmanager`, который получает сервер и отдаёт через `yield` **один объект**. Всё, что вы отдаёте, доступно каждому обработчику, пока сервер работает.
|
||||
|
||||
```python title="server.py" hl_lines="25-31 34 38 40"
|
||||
--8<-- "docs_src/lifespan/tutorial001.py"
|
||||
```
|
||||
|
||||
Читайте снизу вверх:
|
||||
|
||||
* `app_lifespan` подключает `Database` **до** `yield` и отключает её **после**, в блоке `finally`. Это запуск и остановка.
|
||||
* Он отдаёт `AppContext` — обычный dataclass с тем, что вы подготовили. Сегодня одно поле, завтра десять.
|
||||
* `MCPServer("Bookshop", lifespan=app_lifespan)` — вот и вся связка.
|
||||
* Внутри инструмента отданный объект — это `ctx.request_context.lifespan_context`.
|
||||
|
||||
Жизненный цикл выполняется **один раз**. Вход в него происходит при запуске сервера (до первого запроса), выход — при остановке. Все запросы между этими моментами разделяют один и тот же `AppContext`.
|
||||
|
||||
!!! info
|
||||
Если вы писали `lifespan` для FastAPI, вы это уже знаете. Тот же декоратор, тот же `yield`, тот же `finally`.
|
||||
|
||||
### Что видит модель {#what-the-model-sees}
|
||||
|
||||
Ничего нового. `ctx` — параметр типа **Context**, поэтому SDK внедряет его сам, и во входную схему он не попадает:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"genre": {"title": "Genre", "type": "string"}
|
||||
},
|
||||
"required": ["genre"],
|
||||
"title": "count_booksArguments"
|
||||
}
|
||||
```
|
||||
|
||||
`genre` — единственный аргумент, который может передать модель. Жизненный цикл — внутреннее дело вашего сервера.
|
||||
|
||||
Функции `@mcp.resource()` и `@mcp.prompt()` тоже могут принимать параметр `ctx`, записанный как просто `Context` — почему, объясняется в следующем разделе. Всё, что несёт в себе `ctx`, описано на странице **[Объект Context](context.md)**.
|
||||
|
||||
### Он действительно типизирован {#it-really-is-typed}
|
||||
|
||||
Посмотрите на аннотацию ещё раз: `ctx: Context[AppContext]`.
|
||||
|
||||
Именно благодаря этому одному параметру типа `ctx.request_context.lifespan_context` для анализатора типов **и есть** `AppContext`. `.db` дополняется автоматически; `.dbb` — ошибка ещё до того, как вы запустите сервер.
|
||||
|
||||
Напишите вместо этого просто `Context` — и `lifespan_context` получит тип `dict[str, Any]`: анализатору типов неоткуда узнать, что отдал ваш жизненный цикл. Во время выполнения объект по-прежнему на месте; вы лишь теряете подсказки.
|
||||
|
||||
!!! warning
|
||||
`Context[AppContext]` — запись **только для инструментов**. Поставьте её на функцию
|
||||
`@mcp.resource()` или `@mcp.prompt()` — и каждый вызов этого обработчика завершится ошибкой.
|
||||
Клиент получит ошибку в ответ, а в логе сервера будет видна причина:
|
||||
|
||||
```text
|
||||
Context is not available outside of a request
|
||||
```
|
||||
|
||||
В ресурсах и промптах пишите просто `ctx: Context`. Объект, который отдал ваш жизненный
|
||||
цикл, во время выполнения по-прежнему лежит в `ctx.request_context.lifespan_context`; вы
|
||||
отказываетесь от параметра типа, а не от объекта.
|
||||
|
||||
!!! tip
|
||||
Жизненный цикл есть всегда. Если не передать свой, вариант SDK по умолчанию отдаёт пустой
|
||||
`dict`, так что `ctx.request_context.lifespan_context` равен `{}` и никогда не `None`. Из-за
|
||||
этого же значения по умолчанию простой `Context` типизирует его как `dict[str, Any]`.
|
||||
|
||||
## Посмотрите, как это происходит {#watch-it-happen}
|
||||
|
||||
«Запуск выполняется до первого запроса» — из тех утверждений, которые не стоит принимать на веру.
|
||||
|
||||
Урежьте сервер до одного только жизненного цикла: дайте `Database` флаг `connected`, переключайте его в `connect()` и `disconnect()` и добавьте инструмент, который о нём сообщает.
|
||||
|
||||
```python title="server.py" hl_lines="11 14 17 25 44"
|
||||
--8<-- "docs_src/lifespan/tutorial002.py"
|
||||
```
|
||||
|
||||
`database` живёт на уровне модуля по одной причине: чтобы на неё можно было посмотреть *снаружи* сервера.
|
||||
|
||||
!!! check
|
||||
Три момента — три значения:
|
||||
|
||||
* До запуска сервера `database.connected` равно `False`. Импорт модуля ничего не подключил.
|
||||
* Пока сервер работает, вызовите `database_status` — результат будет `"connected"`.
|
||||
* Остановите сервер, и выполнится блок `finally`: `database.connected` снова `False`.
|
||||
|
||||
Работа произошла ровно там, куда вы её поместили: вокруг `yield`, а не при импорте и не на каждый запрос.
|
||||
|
||||
## Итоги {#recap}
|
||||
|
||||
* `lifespan=` принимает `@asynccontextmanager`, который получает сервер и отдаёт через `yield` один объект.
|
||||
* Код до `yield` — это запуск. `finally` после него — остановка.
|
||||
* Он выполняется один раз, вокруг всей жизни сервера, а не на каждый запрос.
|
||||
* Всё, что вы отдаёте через `yield`, — это `ctx.request_context.lifespan_context` в каждом инструменте, ресурсе и промпте.
|
||||
* `ctx: Context[AppContext]` делает этот доступ полностью типизированным в инструментах. Ресурсы и промпты принимают просто `Context`.
|
||||
* Нет `lifespan=` — значит, пустой `dict`, и никогда не `None`.
|
||||
|
||||
Обработчик, который останавливается посреди вызова, чтобы спросить пользователя о том, что знает только он, — это **[элицитация (elicitation)](elicitation.md)**.
|
||||
Loading…
Reference in a new issue