mirror of
https://github.com/ggml-org/llama.cpp.git
synced 2026-07-21 10:15:53 +00:00
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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user