Skip to content

DMR: clarify base urls #22623

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 15, 2025
Merged

DMR: clarify base urls #22623

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9520fd4
update packages
ArthurFlag May 9, 2025
206fefd
update: clarify base urls
ArthurFlag May 12, 2025
2c8be89
fix
ArthurFlag May 13, 2025
83edda5
Apply suggestions from code review
ArthurFlag May 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 59 additions & 51 deletions content/manuals/ai/model-runner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@
text: Beta
group: AI
weight: 20
description: Learn how to use Docker Model Runner to manage and run AI models.
description: Learn how to use Docker Model Runner to manage and run AI models.
keywords: Docker, ai, model runner, docker deskotp, llm
aliases:
aliases:
- /desktop/features/model-runner/
- /ai/model-runner/
---
Expand All @@ -34,8 +34,8 @@

1. Navigate to the **Features in development** tab in settings.
2. Under the **Experimental features** tab, select **Access experimental features**.
3. Select **Apply and restart**.
4. Quit and reopen Docker Desktop to ensure the changes take effect.
3. Select **Apply and restart**.
4. Quit and reopen Docker Desktop to ensure the changes take effect.
5. Open the **Settings** view in Docker Desktop.
6. Navigate to **Features in development**.
7. From the **Beta** tab, check the **Enable Docker Model Runner** setting.
Expand All @@ -46,7 +46,7 @@

### Model runner status

Check whether the Docker Model Runner is active:
Check whether the Docker Model Runner is active and displays the current inference engine:

```console
$ docker model status
Expand All @@ -55,7 +55,7 @@
### View all commands

Displays help information and a list of available subcommands.

```console
$ docker model help
```
Expand All @@ -74,15 +74,15 @@
version Show the current version
```

### Pull a model
### Pull a model

Pulls a model from Docker Hub to your local environment.

```console
$ docker model pull <model>
```

Example:
Example:

```console
$ docker model pull ai/smollm2
Expand Down Expand Up @@ -114,7 +114,13 @@

### Run a model

Run a model and interact with it using a submitted prompt or in chat mode.
Run a model and interact with it using a submitted prompt or in chat mode. When you run a model, Docker
calls an Inference Server API endpoint hosted by the Model Runner through Docker Desktop. The model
stays in memory until another model is requested, or until a pre-defined inactivity timeout is reached (currently 5 minutes).

You do not have to use `Docker model run` before interacting with a specific model from a
host process or from within a container. Model Runner transparently loads the requested model on-demand, assuming it has been
pulled beforehand and is locally available.

#### One-time prompt

Expand Down Expand Up @@ -150,18 +156,18 @@

### Push a model to Docker Hub

Use the following command to push your model to Docker Hub:
To push your model to Docker Hub:

```console
$ docker model push <namespace>/<model>
```

### Tag a model

You can specify a particular version or variant of the model:
To specify a particular version or variant of the model:

```console
$ docker model tag
$ docker model tag
```

If no tag is provided, Docker defaults to `latest`.
Expand All @@ -171,7 +177,7 @@
Fetch logs from Docker Model Runner to monitor activity or debug issues.

```console
$ docker model logs
$ docker model logs
```

The following flags are accepted:
Expand Down Expand Up @@ -211,53 +217,54 @@

4. Open you app in the browser at the addresses specified in the repository [README](https://github.com/docker/hello-genai).

You'll see the GenAI app's interface where you can start typing your prompts.
You'll see the GenAI app's interface where you can start typing your prompts.

You can now interact with your own GenAI app, powered by a local model. Try a few prompts and notice how fast the responses are — all running on your machine with Docker.

## FAQs

### What models are available?

All the available models are hosted in the [public Docker Hub namespace of `ai`](https://hub.docker.com/u/ai).
All the available models are hosted in the [public Docker Hub namespace of `ai`](https://hub.docker.com/u/ai).

### What API endpoints are available?

Once the feature is enabled, the following new APIs are available:
Once the feature is enabled, new API endpoints are available under the following base URLs:

```text
#### Inside containers ####
- From containers: `http://model-runner.docker.internal/`
- From host processes: `http://localhost:12434/`, assuming you have enabled TCP host access on default port 12434.

http://model-runner.docker.internal/
Docker Model management endpoints:

# Docker Model management
POST /models/create
GET /models
GET /models/{namespace}/{name}
DELETE /models/{namespace}/{name}
```text
POST /models/create
GET /models
GET /models/{namespace}/{name}
DELETE /models/{namespace}/{name}
```

# OpenAI endpoints
GET /engines/llama.cpp/v1/models
GET /engines/llama.cpp/v1/models/{namespace}/{name}
POST /engines/llama.cpp/v1/chat/completions
POST /engines/llama.cpp/v1/completions
POST /engines/llama.cpp/v1/embeddings
Note: You can also omit llama.cpp.
E.g., POST /engines/v1/chat/completions.
OpenAI endpoints:

#### Inside or outside containers (host) ####
```text
GET /engines/llama.cpp/v1/models
GET /engines/llama.cpp/v1/models/{namespace}/{name}
POST /engines/llama.cpp/v1/chat/completions
POST /engines/llama.cpp/v1/completions
POST /engines/llama.cpp/v1/embeddings
```

Same endpoints on /var/run/docker.sock
To call these endpoints via a Unix socket (`/var/run/docker.sock`), prefix their path with

Check failure on line 256 in content/manuals/ai/model-runner.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Repetition] 'with' is repeated!

Raw Output:
{"message": "[Vale.Repetition] 'with' is repeated!", "location": {"path": "content/manuals/ai/model-runner.md", "range": {"start": {"line": 256, "column": 87}}}, "severity": "ERROR"}
with `/exp/vDD4.40`.

> [!NOTE]
> You can omit `llama.cpp` from the path. For example: `POST /engines/v1/chat/completions`.

# While still in Beta
Prefixed with /exp/vDD4.40
```

### How do I interact through the OpenAI API?

#### From within a container

Examples of calling an OpenAI endpoint (`chat/completions`) from within another container using `curl`:
To call the `chat/completions` OpenAI endpoint from within another container using `curl`:

```bash
#!/bin/sh
Expand All @@ -280,15 +287,18 @@

```

#### From the host using a Unix socket
#### From the host using TCP

Examples of calling an OpenAI endpoint (`chat/completions`) through the Docker socket from the host using `curl`:
To call the `chat/completions` OpenAI endpoint from the host via TCP:

1. Enable the host-side TCP support from the Docker Desktop GUI, or via the [Docker Desktop CLI](/manuals/desktop/features/desktop-cli.md).
For example: `docker desktop enable model-runner --tcp <port>`.
2. Interact with it as documented in the previous section using `localhost` and the correct port.

```bash
#!/bin/sh

curl --unix-socket $HOME/.docker/run/docker.sock \
localhost/exp/vDD4.40/engines/llama.cpp/v1/chat/completions \
curl http://localhost:12434/engines/llama.cpp/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "ai/smollm2",
Expand All @@ -303,19 +313,17 @@
}
]
}'

```

#### From the host using TCP

In case you want to interact with the API from the host, but use TCP instead of a Docker socket, you can enable the host-side TCP support from the Docker Desktop GUI, or via the [Docker Desktop CLI](/manuals/desktop/features/desktop-cli.md). For example, using `docker desktop enable model-runner --tcp <port>`.
#### From the host using a Unix socket

Afterwards, interact with it as previously documented using `localhost` and the chosen, or the default port.
To call the `chat/completions` OpenAI endpoint through the Docker socket from the host using `curl`:

```bash
#!/bin/sh

curl http://localhost:12434/engines/llama.cpp/v1/chat/completions \
curl --unix-socket $HOME/.docker/run/docker.sock \
localhost/exp/vDD4.40/engines/llama.cpp/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "ai/smollm2",
Expand Down Expand Up @@ -354,15 +362,15 @@

### No safeguard for running oversized models

Currently, Docker Model Runner doesn't include safeguards to prevent you from launching models that exceed their system’s available resources. Attempting to run a model that is too large for the host machine may result in severe slowdowns or render the system temporarily unusable. This issue is particularly common when running LLMs models without sufficient GPU memory or system RAM.
Currently, Docker Model Runner doesn't include safeguards to prevent you from launching models that exceed their system's available resources. Attempting to run a model that is too large for the host machine may result in severe slowdowns or render the system temporarily unusable. This issue is particularly common when running LLMs models without sufficient GPU memory or system RAM.

### No consistent digest support in Model CLI

The Docker Model CLI currently lacks consistent support for specifying models by image digest. As a temporary workaround, you should refer to models by name instead of digest.

## Share feedback

Thanks for trying out Docker Model Runner. Give feedback or report any bugs you may find through the **Give feedback** link next to the **Enable Docker Model Runner** setting.
Thanks for trying out Docker Model Runner. Give feedback or report any bugs you may find through the **Give feedback** link next to the **Enable Docker Model Runner** setting.

## Disable the feature

Expand All @@ -371,4 +379,4 @@
1. Open the **Settings** view in Docker Desktop.
2. Navigate to the **Beta** tab in **Features in development**.
3. Clear the **Enable Docker Model Runner** checkbox.
4. Select **Apply & restart**.
4. Select **Apply & restart**.
Loading