server: (router) add model management API (#23976)

* wip

* server: (router) add SSE realtime updates API

* nits

* wip

* add download API

* add download api

* update docs

* add delete endpoint

* fix std::terminate

* fix crash

* fix 2

* add tests

* nits
This commit is contained in:
Xuan-Son Nguyen
2026-06-17 18:04:58 +02:00
committed by GitHub
parent b4024af6c2
commit 4b4d13ae72
16 changed files with 855 additions and 63 deletions
+115
View File
@@ -1778,6 +1778,20 @@ The `status` object can be:
}
```
Note: for "downloading" state, there can be multiple files be downloading in parallel
```json
"status": {
"value": "downloading",
"progress": {
"https://...model.gguf": {
"done": 195963406,
"total": 219307424
}
}
}
```
### POST `/models/load`: Load a model
Load a model
@@ -1820,6 +1834,107 @@ Response:
}
```
### GET `/models/sse`: Real-time events
Example events:
```js
{
"model": "...",
"event": "model_status",
"data": {
"status": "loading"
}
}
{
"model": "...",
"event": "download_progress",
"data": {
// note: there can be multiple files being downloaded in parallel
"https://...model.gguf": {
"done": 195963406,
"total": 219307424
}
}
}
{
"model": "...",
"event": "download_finished",
"data": {
"status": "loading"
}
}
{
"model": "...",
"event": "model_remove"
}
// special event: reload of the list of all models
{
"model": "*",
"event": "models_reload"
}
```
### POST `/models`: Download new model
Trigger a new download (non-blocking), the progress can be tracked via SSE endpoint `/models/sse`
To cancel model downloading, send an event to `/models/unload`
Download procedure:
- Send POST request to `/models`
- Subscribe to `/models/sse` for updates
- On downloading completed, you will receive either `download_finished` or `download_failed` event
- Call GET `/models` to trigger model list update. If the download success, you should see the new model in the list
Payload:
```json
{
"model": "ggml-org/gemma-3-4b-it-GGUF:Q4_K_M",
}
```
Response (download is started in the background):
```json
{
"success": true
}
```
Response (error, cannot start the download):
```json
{
"error": {
"code": 400,
"message": "model validation failed, unable to download",
"type": "invalid_request_error"
}
}
```
### DELETE `/models`: Delete a model from cache
IMPORTANT: only model stored in cache can be deleted. You cannot delete models in a preset.
Model name must be passed via query param: `?model={name}`
If delete success, it will send an SSE event of type `model_remove`
Response:
```json
{
"success": true
}
```
## API errors
`llama-server` returns errors in the same format as OAI: https://github.com/openai/openai-openapi