Update API docs (ollama#527)

* Update API docs Signed-off-by: Matt Williams <[email protected]> * strange TOC was getting auto generated Signed-off-by: Matt Williams <[email protected]> * Update docs/api.md Co-authored-by: Bruce MacDonald <[email protected]> * Update docs/api.md Co-authored-by: Bruce MacDonald <[email protected]> * Update docs/api.md Co-authored-by: Bruce MacDonald <[email protected]> * Update api.md --------- Signed-off-by: Matt Williams <[email protected]> Co-authored-by: Bruce MacDonald <[email protected]> Co-authored-by: Michael Chiang <[email protected]>
Clivern · Sep 14, 2023 · fc87076 · fc87076
1 parent f89c237
commit fc87076
Showing 1 changed file with 113 additions and 25 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -3,26 +3,29 @@
 ## Endpoints
 
 - [Generate a completion](#generate-a-completion)
-- [Create a model](#create-a-model)
-- [List local models](#list-local-models)
-- [Copy a model](#copy-a-model)
-- [Delete a model](#delete-a-model)
-- [Pull a model](#pull-a-model)
-- [Generate embeddings](#generate-embeddings)
+- [Create a Model](#create-a-model)
+- [List Local Models](#list-local-models)
+- [Show Model Information](#show-model-information)
+- [Copy a Model](#copy-a-model)
+- [Delete a Model](#delete-a-model)
+- [Pull a Model](#pull-a-model)
+- [Push a Model](#push-a-model)
+- [Generate Embeddings](#generate-embeddings)
+
 
 ## Conventions
 
 ### Model names
 
-Model names follow a `model:tag` format. Some examples are `orca-mini:3b-q4_1` and `llama2:70b`. The tag is optional and if not provided will default to `latest`. The tag is used to identify a specific version.
+Model names follow a `model:tag` format. Some examples are `orca-mini:3b-q4_1` and `llama2:70b`. The tag is optional and, if not provided, will default to `latest`. The tag is used to identify a specific version.
 
 ### Durations
 
 All durations are returned in nanoseconds.
 
 ## Generate a completion
 
-```
+```shell
 POST /api/generate
 ```
 
@@ -42,7 +45,7 @@ Advanced parameters:
 
 ### Request
 
-```
+```shell
 curl -X POST http://localhost:11434/api/generate -d '{
   "model": "llama2:7b",
   "prompt": "Why is the sky blue?"
@@ -95,7 +98,7 @@ To calculate how fast the response is generated in tokens per second (token/s),
 
 ## Create a Model
 
-```
+```shell
 POST /api/create
 ```
 
@@ -108,7 +111,7 @@ Create a model from a [`Modelfile`](./modelfile.md)
 
 ### Request
 
-```
+```shell
 curl -X POST http://localhost:11434/api/create -d '{
   "name": "mario",
   "path": "~/Modelfile"
@@ -117,7 +120,7 @@ curl -X POST http://localhost:11434/api/create -d '{
 
 ### Response
 
-A stream of JSON objects. When finished, `status` is `success`
+A stream of JSON objects. When finished, `status` is `success`.
 
 ```json
 {
@@ -127,15 +130,15 @@ A stream of JSON objects. When finished, `status` is `success`
 
 ## List Local Models
 
-```
+```shell
 GET /api/tags
 ```
 
 List models that are available locally.
 
 ### Request
 
-```
+```shell
 curl http://localhost:11434/api/tags
 ```
 
@@ -158,17 +161,48 @@ curl http://localhost:11434/api/tags
 }
 ```
 
-## Copy a Model
+## Show Model Information
+
+```shell
+POST /api/show
+```
+
+Show details about a model including modelfile, template, parameters, license, and system prompt.
+
+### Parameters
+
+- `name`: name of the model to show
 
+### Request
+
+```shell  
+curl http://localhost:11434/api/show -d '{
+  "name": "llama2:7b"
+}'
 ```
+
+### Response
+
+```json
+{
+    "license": "<contents of license block>",
+    "modelfile": "# Modelfile generated by \"ollama show\"\n# To build a new Modelfile based on this one, replace the FROM line with:\n# FROM llama2:latest\n\nFROM /Users/username/.ollama/models/blobs/sha256:8daa9615cce30c259a9555b1cc250d461d1bc69980a274b44d7eda0be78076d8\nTEMPLATE \"\"\"[INST] {{ if and .First .System }}<<SYS>>{{ .System }}<</SYS>>\n\n{{ end }}{{ .Prompt }} [/INST] \"\"\"\nSYSTEM \"\"\"\"\"\"\nPARAMETER stop [INST]\nPARAMETER stop [/INST]\nPARAMETER stop <<SYS>>\nPARAMETER stop <</SYS>>\n",
+    "parameters": "stop                           [INST]\nstop                           [/INST]\nstop                           <<SYS>>\nstop                           <</SYS>>",
+    "template": "[INST] {{ if and .First .System }}<<SYS>>{{ .System }}<</SYS>>\n\n{{ end }}{{ .Prompt }} [/INST] "
+}
+```
+
+## Copy a Model
+
+```shell
 POST /api/copy
 ```
 
 Copy a model. Creates a model with another name from an existing model.
 
 ### Request
 
-```
+```shell
 curl http://localhost:11434/api/copy -d '{
   "source": "llama2:7b",
   "destination": "llama2-backup"
@@ -177,7 +211,7 @@ curl http://localhost:11434/api/copy -d '{
 
 ## Delete a Model
 
-```
+```shell
 DELETE /api/delete
 ```
 
@@ -189,27 +223,28 @@ Delete a model and its data.
 
 ### Request
 
-```
+```shell
 curl -X DELETE http://localhost:11434/api/delete -d '{
   "name": "llama2:13b"
 }'
 ```
 
 ## Pull a Model
 
-```
+```shell
 POST /api/pull
 ```
 
-Download a model from a the model registry. Cancelled pulls are resumed from where they left off, and multiple calls to will share the same download progress.
+Download a model from the ollama library. Cancelled pulls are resumed from where they left off, and multiple calls will share the same download progress.
 
 ### Parameters
 
 - `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.
 
 ### Request
 
-```
+```shell
 curl -X POST http://localhost:11434/api/pull -d '{
   "name": "llama2:7b"
 }'
@@ -225,9 +260,63 @@ curl -X POST http://localhost:11434/api/pull -d '{
 }
 ```
 
-## Generate Embeddings
+## Push a Model
+
+```shell
+POST /api/push
+```
+
+Upload a model to a model library. Requires registering for ollama.ai and adding a public key first.
+
+### Parameters
+
+- `name`: name of the model to push in the form of `<namespace>/<model>:<tag>`
+- `insecure`: (optional) allow insecure connections to the library. Only use this if you are pushing to your library during development.  
+
+### Request
+
+```shell
+curl -X POST http://localhost:11434/api/push -d '{
+  "name": "mattw/pygmalion:latest"
+}'
+```
+
+### Response
 
+Streaming response that starts with:
+
+```json
+{"status":"retrieving manifest"}
 ```
+
+and then:
+
+```json
+{
+"status":"starting upload","digest":"sha256:bc07c81de745696fdf5afca05e065818a8149fb0c77266fb584d9b2cba3711ab",
+"total":1928429856
+}
+```
+
+Then there is a series of uploading responses:
+
+```json
+{
+"status":"starting upload",
+"digest":"sha256:bc07c81de745696fdf5afca05e065818a8149fb0c77266fb584d9b2cba3711ab",
+"total":1928429856}
+```
+
+Finally, when the upload is complete:
+
+```json
+{"status":"pushing manifest"}
+{"status":"success"}
+```
+
+## Generate Embeddings
+
+```shell
 POST /api/embeddings
 ```
 
@@ -244,7 +333,7 @@ Advanced parameters:
 
 ### Request
 
-```
+```shell
 curl -X POST http://localhost:11434/api/embeddings -d '{
   "model": "llama2:7b",
   "prompt": "Here is an article about llamas..."
@@ -259,5 +348,4 @@ curl -X POST http://localhost:11434/api/embeddings -d '{
     0.5670403838157654, 0.009260174818336964, 0.23178744316101074, -0.2916173040866852, -0.8924556970596313,
     0.8785552978515625, -0.34576427936553955, 0.5742510557174683, -0.04222835972905159, -0.137906014919281
   ]
-}
-```
+}```