|
| 1 | +--- |
| 2 | +title: Use Docker Model Runner |
| 3 | +description: Learn how to integrate Docker Model Runner with Docker Compose to build AI-powered applications |
| 4 | +keywords: compose, docker compose, model runner, ai, llm, artificial intelligence, machine learning |
| 5 | +weight: 20 |
| 6 | +aliases: |
| 7 | + - /compose/how-tos/model-runner/ |
| 8 | +params: |
| 9 | + sidebar: |
| 10 | + badge: |
| 11 | + color: green |
| 12 | + text: New |
| 13 | +--- |
| 14 | + |
| 15 | +{{< summary-bar feature_name="Compose model runner" >}} |
| 16 | + |
| 17 | +Docker Model Runner can be integrated with Docker Compose to run AI models as part of your multi-container applications. |
| 18 | +This lets you define and run AI-powered applications alongside your other services. |
| 19 | + |
| 20 | +## Prerequisites |
| 21 | + |
| 22 | +- Docker Compose v2.38 or later |
| 23 | +- Docker Desktop 4.43 or later |
| 24 | +- Docker Desktop for Mac with Apple Silicon or Docker Desktop for Windows with NVIDIA GPU |
| 25 | +- [Docker Model Runner enabled in Docker Desktop](/manuals/ai/model-runner.md#enable-docker-model-runner) |
| 26 | + |
| 27 | +## Use `models` definition |
| 28 | + |
| 29 | +The [`models` top-level element](/manuals/ai/compose/models-and-compose.md) in the Compose file lets you define AI models to be used by your application. |
| 30 | +Compose can then use Docker Model Runner as the model runtime. |
| 31 | + |
| 32 | +The following example shows how to provide the minimal configuration to use a model within your Compose application: |
| 33 | + |
| 34 | +```yaml |
| 35 | +services: |
| 36 | + my-chat-app: |
| 37 | + image: my-chat-app |
| 38 | + models: |
| 39 | + - smollm2 |
| 40 | + |
| 41 | +models: |
| 42 | + smollm2: |
| 43 | + image: ai/smollm2 |
| 44 | +``` |
| 45 | +
|
| 46 | +### How it works |
| 47 | +
|
| 48 | +During the `docker compose up` process, Docker Model Runner automatically pulls and runs the specified model. |
| 49 | +It also sends Compose the model tag name and the URL to access the model runner. |
| 50 | + |
| 51 | +This information is then passed to services which declare a dependency on the model provider. |
| 52 | +In the example above, the `my-chat-app` service receives 2 environment variables prefixed by the service name: |
| 53 | +- `SMOLLM2_ENDPOINT` with the URL to access the model |
| 54 | +- `SMOLLM2_MODEL` with the model name |
| 55 | + |
| 56 | +This lets the `my-chat-app` service to interact with the model and use it for its own purposes. |
| 57 | + |
| 58 | +### Customizing environment variables |
| 59 | + |
| 60 | +You can customize the environment variable names which will be passed to your service container using the long syntax: |
| 61 | + |
| 62 | +```yaml |
| 63 | +services: |
| 64 | + my-chat-app: |
| 65 | + image: my-chat-app |
| 66 | + models: |
| 67 | + smollm2: |
| 68 | + endpoint_var: AI_MODEL_URL |
| 69 | + model_var: AI_MODEL_NAME |
| 70 | +
|
| 71 | +models: |
| 72 | + smollm2: |
| 73 | + image: ai/smollm2 |
| 74 | +``` |
| 75 | + |
| 76 | +With this configuration, your `my-chat-app` service will receive: |
| 77 | +- `AI_MODEL_URL` with the URL to access the model |
| 78 | +- `AI_MODEL_NAME` with the model name |
| 79 | + |
| 80 | +This allows you to use more descriptive variable names that match your application's expectations. |
| 81 | + |
| 82 | + |
| 83 | +## Alternative configuration with Provider services |
| 84 | + |
| 85 | +> [!TIP] |
| 86 | +> |
| 87 | +> Use the []`models` top-level element](#use-models-definition) instead. |
| 88 | + |
| 89 | +Compose introduced a new service type called `provider` that allows you to declare platform capabilities required by your application. For AI models, you can use the `model` type to declare model dependencies. |
| 90 | + |
| 91 | +Here's an example of how to define a model provider: |
| 92 | + |
| 93 | +```yaml |
| 94 | +services: |
| 95 | + chat: |
| 96 | + image: my-chat-app |
| 97 | + depends_on: |
| 98 | + - ai_runner |
| 99 | +
|
| 100 | + ai_runner: |
| 101 | + provider: |
| 102 | + type: model |
| 103 | + options: |
| 104 | + model: ai/smollm2 |
| 105 | +``` |
| 106 | + |
| 107 | +Notice the dedicated `provider` attribute in the `ai_runner` service. |
| 108 | +This attribute specifies that the service is a model provider and lets you define options such as the name of the model to be used. |
| 109 | + |
| 110 | +There is also a `depends_on` attribute in the `my-chat-app` service. |
| 111 | +This attribute specifies that the `my-chat-app` service depends on the `ai_runner` service. |
| 112 | +This means that the `ai_runner` service will be started before the `my-chat-app` service to allow injection of model information to the `my-chat-app` service. |
| 113 | + |
| 114 | +## Reference |
| 115 | + |
| 116 | +- [Docker Model Runner documentation](/manuals/ai/model-runner.md) |
0 commit comments