#2196 serve: the image encoder only while there are pictures ("elastic": true in the vision section)

说明

**serve: the image encoder only while there are pictures (`"elastic": true` in the `"vision"` section, opt-in)**

A GPU image encoder holds its VRAM (~1.3-1.5 GB here) for as long as the server runs, so the expert cache is smaller
for every request, with or without pictures. With `"vram_elastic": true` (#533) the engine can give VRAM back between
requests, so the server can lend the encoder its VRAM only while pictures come.

**What it changes** (`serve/server.py`, opt-in; docs in `docs/VRAM_ELASTIC.md` and the images part of `docs/DETAILS.md`)

- `"elastic": true` in the `"vision"` section, with the config's `"vram_elastic": true`: the encoder does not start with
  the server or with a load. `"elastic_mib"` (default 2048) and `"elastic_idle_s"` (default 120) set its share and how
  long it stays without a picture. Without `"vram_elastic"` the server says so and starts the encoder as before.
- **A picture's turn** (the FIFO turn an encode already takes, so nothing runs on the GPU beside it): if the encoder is not
  running, the engine's `VRAM` first keeps `elastic_mib` free on top of the reserve (the last `POST /v1/vram`, or 0),
  then the encoder starts. If the cache cannot shrink (the resident low-RAM mode, no `--vram-elastic`) the encoder
  starts anyway and the log says why.
- **Idle:** a thread stops the encoder between requests after `elastic_idle_s` without a picture and sends `VRAM` with
  the reserve again; 0 when none was asked, because `null` (the start's reserve) left the cache a segment or more below
  the size it had (measured: 10446 of 10736 slots with `null`, 10736 with 0).
- `POST /v1/vram` while the encoder runs keeps the asked reserve on top of its share; an unload stops it too.
  `Service._vision_down()` no longer counts a stopped elastic encoder as down, so a load never starts it.

**What it leaves alone:** everything without the key (the encoder starts as before; the 725 server tests that were
there pass unchanged), the engine, setup, the CPU encoder.

**Checked**

- `serve/test_vision_elastic.py` (7 tests, fake engine and encoder): the first picture shrinks then starts, later ones
  reuse it, idle stops and grows back to the full size (and not while a request holds the turn or a picture came
  recently), the reserve stacks, an engine that cannot shrink still gets its encoder, an unload lets go, the load never
  starts it, the config keys. Four mutations, each caught: no start in the image turn, growing back to the start's
  reserve (`null`), the load restarting an elastic encoder, the reserve not stacking.
- The whole server suite: 732 tests OK (11 skipped; 725 before plus these 7), on this branch (base `a0116b2`).
- Live on an R9700 32 GB (gfx1201, ROCm 7.14.1, Linux; HIP's virtual memory from #2189), UD-IQ4_XS with every expert in
  RAM, the BF16 encoder at up to 1,024 tokens: the first picture made the cache keep 2 GiB free and the encoder started
  in 4.7 s taking 1,339 MiB; a request with one picture took 8.6 s including that start (5.0 s on a later cold start,
  the encoder starting in 2.7 s); 2 / 5 / 10 pictures with the encoder running took 3.8 / 5.6 / 9.0 s (~0.45 s to encode
  each, the same as the encoder on a second card); after 60 s idle it stopped and the cache grew back to its full
  size (21,704 of 21,702 MiB).

**Not tested:** NVIDIA live (the server path is the same; the engine's `VRAM` there is the existing #533), Windows,
several requests with pictures at once with `--parallel` (the turn is the same FIFO turn an encode takes today).

A note found on the way: `--vram-elastic` turns `--kv-grow` off (the engine says so), so a config with both runs with the
whole K/V in VRAM; on this box that was 9,405 cache slots instead of 10,818. Making the two work together is a separate
change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)