From f21bd6210d0d331ab94468791b4761e6bb5bc638 Mon Sep 17 00:00:00 2001 From: Matt Williams Date: Tue, 31 Oct 2023 13:11:33 -0700 Subject: [PATCH] docs: clarify and clean up API docs Signed-off-by: Matt Williams --- docs/api.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 82 insertions(+), 8 deletions(-) diff --git a/docs/api.md b/docs/api.md index cacdbcc6..8c3b3966 100644 --- a/docs/api.md +++ b/docs/api.md @@ -45,7 +45,7 @@ Advanced parameters (optional): - `system`: system prompt to (overrides what is defined in the `Modelfile`) - `template`: the full prompt or prompt template (overrides what is defined in the `Modelfile`) - `context`: the context parameter returned from a previous request to `/generate`, this can be used to keep a short conversational memory -- `stream`: if `false` the response will be be returned as a single response object, rather than a stream of objects +- `stream`: if `false` the response will be returned as a single response object, rather than a stream of objects ### Request @@ -58,7 +58,7 @@ curl -X POST http://localhost:11434/api/generate -d '{ ### Response -A stream of JSON objects: +If `stream` is not specified, or set to `true`, a stream of JSON objects is returned: ```json { @@ -102,6 +102,26 @@ To calculate how fast the response is generated in tokens per second (token/s), } ``` +If `stream` is set to `false`, the response will be a single JSON object: + +```json +{ + "model": "llama2:7b", + "created_at": "2023-08-04T19:22:45.499127Z", + "response": "The sky is blue because it is the color of the sky.", + "context": [1, 2, 3], + "done": true, + "total_duration": 5589157167, + "load_duration": 3013701500, + "sample_count": 114, + "sample_duration": 81442000, + "prompt_eval_count": 46, + "prompt_eval_duration": 1160282000, + "eval_count": 13, + "eval_duration": 1325948000 +} +``` + ## Create a Model ```shell @@ -114,7 +134,7 @@ Create a model from a [`Modelfile`](./modelfile.md) - `name`: name of the model to create - `path`: path to the Modelfile -- `stream`: (optional) if `false` the response will be be returned as a single response object, rather than a stream of objects +- `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects ### Request @@ -151,6 +171,8 @@ curl http://localhost:11434/api/tags ### Response +A single JSON object will be returned. + ```json { "models": [ @@ -216,6 +238,10 @@ curl http://localhost:11434/api/copy -d '{ }' ``` +### Response + +The only response is a 200 OK if successful. + ## Delete a Model ```shell @@ -226,7 +252,7 @@ Delete a model and its data. ### Parameters -- `model`: model name to delete +- `name`: model name to delete ### Request @@ -236,6 +262,10 @@ curl -X DELETE http://localhost:11434/api/delete -d '{ }' ``` +### Response + +If successful, the only response is a 200 OK. + ## Pull a Model ```shell @@ -248,7 +278,7 @@ Download a model from the ollama library. Cancelled pulls are resumed from where - `name`: name of the model to pull - `insecure`: (optional) allow insecure connections to the library. Only use this if you are pulling from your own library during development. -- `stream`: (optional) if `false` the response will be be returned as a single response object, rather than a stream of objects +- `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects ### Request @@ -260,11 +290,49 @@ curl -X POST http://localhost:11434/api/pull -d '{ ### Response +If `stream` is not specified, or set to `true`, a stream of JSON objects is returned: + +The first object is the manifest: + +```json +{ + "status": "pulling manifest" +} +``` + +Then there is a series of downloading responses. Until any of the download is completed, the `completed` key may not be included. The number of files to be downloaded depends on the number of layers specified in the manifest. + ```json { "status": "downloading digestname", "digest": "digestname", - "total": 2142590208 + "total": 2142590208, + "completed": 241970 +} +``` + +After all the files are downloaded, the final responses are: + +```json +{ + "status": "verifying sha256 digest" +} +{ + "status": "writing manifest" +} +{ + "status": "removing any unused layers" +} +{ + "status": "success" +} +``` + +if `stream` is set to false, then the response is a single JSON object: + +```json +{ + "status": "success" } ``` @@ -280,7 +348,7 @@ Upload a model to a model library. Requires registering for ollama.ai and adding - `name`: name of the model to push in the form of `/:` - `insecure`: (optional) allow insecure connections to the library. Only use this if you are pushing to your library during development. -- `stream`: (optional) if `false` the response will be be returned as a single response object, rather than a stream of objects +- `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects ### Request @@ -292,7 +360,7 @@ curl -X POST http://localhost:11434/api/push -d '{ ### Response -Streaming response that starts with: +If `stream` is not specified, or set to `true`, a stream of JSON objects is returned: ```json { "status": "retrieving manifest" } @@ -325,6 +393,12 @@ Finally, when the upload is complete: {"status":"success"} ``` +If `stream` is set to `false`, then the response is a single JSON object: + +```json +{"status":"success"} +``` + ## Generate Embeddings ```shell