diff --git a/docs/api.md b/docs/api.md index 4a8e2f170..65aefc25b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -3,18 +3,21 @@ ## 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 @@ -22,7 +25,7 @@ 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,7 +130,7 @@ A stream of JSON objects. When finished, `status` is `success` ## List Local Models -``` +```shell GET /api/tags ``` @@ -135,7 +138,7 @@ List models that are available locally. ### Request -``` +```shell curl http://localhost:11434/api/tags ``` @@ -158,9 +161,40 @@ curl http://localhost:11434/api/tags } ``` +## 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 ``` @@ -168,7 +202,7 @@ 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,7 +223,7 @@ Delete a model and its data. ### Request -``` +```shell curl -X DELETE http://localhost:11434/api/delete -d '{ "name": "llama2:13b" }' @@ -197,19 +231,20 @@ curl -X DELETE http://localhost:11434/api/delete -d '{ ## 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 '{ } ``` +## 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 ] -} -``` +}```