From ab39872cb471bed8e0795b097b248c3930faa440 Mon Sep 17 00:00:00 2001 From: Patrick Devine Date: Mon, 13 Jan 2025 17:30:24 -0800 Subject: [PATCH] add new create api doc (#8388) --- docs/api.md | 110 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 91 insertions(+), 19 deletions(-) diff --git a/docs/api.md b/docs/api.md index 50402ecc7..ede6446f9 100644 --- a/docs/api.md +++ b/docs/api.md @@ -928,14 +928,25 @@ A single JSON object is returned: POST /api/create ``` -Create a model from a [`Modelfile`](./modelfile.md). It is recommended to set `modelfile` to the content of the Modelfile rather than just set `path`. This is a requirement for remote create. Remote model creation must also create any file blobs, fields such as `FROM` and `ADAPTER`, explicitly with the server using [Create a Blob](#create-a-blob) and the value to the path indicated in the response. +Create a model from: + * another model; + * a safetensors directory; or + * a GGUF file. + +If you are creating a model from a safetensors directory or from a GGUF file, you must [create a blob](#create-a-blob) for each of the files and then use the file name and SHA256 digest associated with each blob in the `files` field. ### Parameters - `model`: name of the model to create -- `modelfile` (optional): contents of the Modelfile +- `from`: (optional) name of an existing model to create the new model from +- `files`: (optional) a dictionary of file names to SHA256 digests of blobs to create the model from +- `adapters`: (optional) a dictionary of file names to SHA256 digests of blobs for LORA adapters +- `template`: (optional) the prompt template for the model +- `license`: (optional) a string or list of strings containing the license or licenses for the model +- `system`: (optional) a string containing the system prompt for the model +- `parameters`: (optional) a dictionary of parameters for the model (see [Modelfile](./modelfile.md#valid-parameters-and-values) for a list of parameters) +- `messages`: (optional) a list of message objects used to create a conversation - `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects -- `path` (optional): path to the Modelfile - `quantize` (optional): quantize a non-quantized (e.g. float16) model #### Quantization types @@ -961,14 +972,15 @@ Create a model from a [`Modelfile`](./modelfile.md). It is recommended to set `m #### Create a new model -Create a new model from a `Modelfile`. +Create a new model from an existing model. ##### Request ```shell curl http://localhost:11434/api/create -d '{ "model": "mario", - "modelfile": "FROM llama3\nSYSTEM You are mario from Super Mario Bros." + "from": "llama3.2", + "system": "You are Mario from Super Mario Bros." }' ``` @@ -999,7 +1011,7 @@ Quantize a non-quantized model. ```shell curl http://localhost:11434/api/create -d '{ "model": "llama3.1:quantized", - "modelfile": "FROM llama3.1:8b-instruct-fp16", + "from": "llama3.1:8b-instruct-fp16", "quantize": "q4_K_M" }' ``` @@ -1019,52 +1031,112 @@ A stream of JSON objects is returned: {"status":"success"} ``` +#### Create a model from GGUF -### Check if a Blob Exists +Create a model from a GGUF file. The `files` parameter should be filled out with the file name and SHA256 digest of the GGUF file you wish to use. Use [/api/blobs/:digest](#push-a-blob) to push the GGUF file to the server before calling this API. + + +##### Request + +```shell +curl http://localhost:11434/api/create -d '{ + "model": "my-gguf-model", + "files": { + "test.gguf": "sha256:432f310a77f4650a88d0fd59ecdd7cebed8d684bafea53cbff0473542964f0c3" + } +}' +``` + +##### Response + +A stream of JSON objects is returned: + +``` +{"status":"parsing GGUF"} +{"status":"using existing layer sha256:432f310a77f4650a88d0fd59ecdd7cebed8d684bafea53cbff0473542964f0c3"} +{"status":"writing manifest"} +{"status":"success"} +``` + + +#### Create a model from a Safetensors directory + +The `files` parameter should include a dictionary of files for the safetensors model which includes the file names and SHA256 digest of each file. Use [/api/blobs/:digest](#push-a-blob) to first push each of the files to the server before calling this API. Files will remain in the cache until the Ollama server is restarted. + +##### Request + +```shell +curl http://localhost:11434/api/create -d '{ + "model": "fred", + "files": { + "config.json": "sha256:dd3443e529fb2290423a0c65c2d633e67b419d273f170259e27297219828e389", + "generation_config.json": "sha256:88effbb63300dbbc7390143fbbdd9d9fa50587b37e8bfd16c8c90d4970a74a36", + "special_tokens_map.json": "sha256:b7455f0e8f00539108837bfa586c4fbf424e31f8717819a6798be74bef813d05", + "tokenizer.json": "sha256:bbc1904d35169c542dffbe1f7589a5994ec7426d9e5b609d07bab876f32e97ab", + "tokenizer_config.json": "sha256:24e8a6dc2547164b7002e3125f10b415105644fcf02bf9ad8b674c87b1eaaed6", + "model.safetensors": "sha256:1ff795ff6a07e6a68085d206fb84417da2f083f68391c2843cd2b8ac6df8538f" + } +}' +``` + +##### Response + +A stream of JSON objects is returned: + +```shell +{"status":"converting model"} +{"status":"creating new layer sha256:05ca5b813af4a53d2c2922933936e398958855c44ee534858fcfd830940618b6"} +{"status":"using autodetected template llama3-instruct"} +{"status":"using existing layer sha256:56bb8bd477a519ffa694fc449c2413c6f0e1d3b1c88fa7e3c9d88d3ae49d4dcb"} +{"status":"writing manifest"} +{"status":"success"} +``` + +## Check if a Blob Exists ```shell HEAD /api/blobs/:digest ``` -Ensures that the file blob used for a FROM or ADAPTER field exists on the server. This is checking your Ollama server and not ollama.com. +Ensures that the file blob (Binary Large Object) used with create a model exists on the server. This checks your Ollama server and not ollama.com. -#### Query Parameters +### Query Parameters - `digest`: the SHA256 digest of the blob -#### Examples +### Examples -##### Request +#### Request ```shell curl -I http://localhost:11434/api/blobs/sha256:29fdb92e57cf0827ded04ae6461b5931d01fa595843f55d36f5b275a52087dd2 ``` -##### Response +#### Response Return 200 OK if the blob exists, 404 Not Found if it does not. -### Create a Blob +## Push a Blob ```shell POST /api/blobs/:digest ``` -Create a blob from a file on the server. Returns the server file path. +Push a file to the Ollama server to create a "blob" (Binary Large Object). -#### Query Parameters +### Query Parameters - `digest`: the expected SHA256 digest of the file -#### Examples +### Examples -##### Request +#### Request ```shell -curl -T model.bin -X POST http://localhost:11434/api/blobs/sha256:29fdb92e57cf0827ded04ae6461b5931d01fa595843f55d36f5b275a52087dd2 +curl -T model.gguf -X POST http://localhost:11434/api/blobs/sha256:29fdb92e57cf0827ded04ae6461b5931d01fa595843f55d36f5b275a52087dd2 ``` -##### Response +#### Response Return 201 Created if the blob was successfully created, 400 Bad Request if the digest used is not expected.