DMR REST API

DMR REST API

Model Runner을 활성화하면 새 API 엔드포인트가 생겨요. 이 엔드포인트를 사용해 모델과 프로그래밍 방식으로 상호작용할 수 있어요. Docker Model Runner는 OpenAI, Anthropic, Ollama API 형식과 호환성을 제공해요.

출처: 문서

본문

기본 URL 결정

엔드포인트와 상호작용하기 위한 기본 URL은 Docker 실행 방식과 사용하는 API 형식에 따라 달라져요.

Docker Desktop:

접근 위치 Base URL
컨테이너 http://model-runner.docker.internal
호스트 프로세스(TCP) http://localhost:12434

참고: TCP 호스트 접근을 활성화해야 해요. Docker Model Runner 활성화 문서를 참고해 주세요.

Docker Engine:

접근 위치 Base URL
컨테이너 http://172.17.0.1:12434
호스트 프로세스 http://localhost:12434

참고: 172.17.0.1 인터페이스는 Compose 프로젝트 안의 컨테이너에는 기본적으로 사용하지 못할 수 있어요. 이 경우 Compose 서비스 YAML에 extra_hosts 지시어를 추가하세요:

extra_hosts:
  - "model-runner.docker.internal:host-gateway"

그러면 http://model-runner.docker.internal:12434/에서 Docker Model Runner API에 접근할 수 있어요.

제3자 도구용 기본 URL

OpenAI 호환 API를 기대하는 제3자 도구를 구성할 때는 다음 기본 URL을 사용하세요:

도구 유형 Base URL 형식
OpenAI SDK / 클라이언트 http://localhost:12434/engines/v1
Anthropic SDK / 클라이언트 http://localhost:12434
Ollama 호환 클라이언트 http://localhost:12434

특정 구성 예시는 IDE 및 도구 통합 문서를 참고해 주세요.

지원되는 API

Docker Model Runner는 여러 API 형식을 지원해요:

API 설명 사용 사례
OpenAI API OpenAI 호환 채팅 완성, 임베딩 대부분의 AI 프레임워크와 도구
Anthropic API Anthropic 호환 messages 엔드포인트 Claude용으로 빌드된 도구
Ollama API Ollama 호환 엔드포인트 Ollama용으로 빌드된 도구
이미지 생성 API Diffusers 기반 이미지 생성 텍스트 프롬프트에서 이미지 생성
DMR API 네이티브 Docker Model Runner 엔드포인트 모델 관리

OpenAI 호환 API

DMR은 기존 도구와 프레임워크와의 최대 호환성을 위해 OpenAI API 스펙을 구현해요.

엔드포인트

엔드포인트 메서드 설명
/engines/v1/models GET 모델 목록
/engines/v1/models/{namespace}/{name} GET 모델 조회
/engines/v1/chat/completions POST 채팅 완성 생성
/engines/v1/completions POST 완성 생성
/engines/v1/embeddings POST 임베딩 생성

참고: 경로에 엔진 이름을 선택적으로 포함할 수 있어요: /engines/llama.cpp/v1/chat/completions. 여러 추론 엔진을 실행할 때 유용해요.

모델 이름 형식

API 요청에서 모델을 지정할 때는 네임스페이스를 포함한 전체 모델 식별자를 사용하세요:

{
  "model": "ai/smollm2",
  "messages": [...]
}

일반적인 모델 이름 형식:

  • Docker Hub 모델: ai/smollm2, ai/llama3.2, ai/qwen2.5-coder
  • 태그된 버전: ai/smollm2:360M-Q4_K_M
  • 커스텀 모델: myorg/mymodel

지원되는 파라미터

다음 OpenAI API 파라미터가 지원돼요:

파라미터 타입 설명
model string 필수. 모델 식별자.
messages array 채팅 완성에 필수. 대화 기록.
prompt string 완성에 필수. 프롬프트 텍스트.
max_tokens integer 생성할 최대 토큰 수.
temperature float 샘플링 온도(0.0-2.0).
top_p float 핵(kernel) 샘플링 파라미터(0.0-1.0).
stream Boolean 스트리밍 응답 활성화.
stop string/array 중지 시퀀스.
presence_penalty float 존재 페널티(-2.0 to 2.0).
frequency_penalty float 빈도 페널티(-2.0 to 2.0).

OpenAI와의 제한 사항 및 차이점

DMR의 OpenAI 호환 API를 사용할 때 알아야 할 차이점:

기능 DMR 동작
API 키 필요 없음. DMR은 Authorization 헤더를 무시해요.
함수 호출 호환 모델에서 llama.cpp로 지원.
비전(Vision) 다중 모달 모델(예: LLaVA)에서 지원.
JSON 모드 response_format: {"type": "json_object"}로 지원.
Logprobs 지원됨.
토큰 계산 모델의 네이티브 토큰 인코더를 사용하며 OpenAI와 다를 수 있어요.

Anthropic 호환 API

DMR은 Claude용으로 빌드된 도구와 프레임워크를 위한 Anthropic Messages API 호환성을 제공해요.

엔드포인트

엔드포인트 메서드 설명
/anthropic/v1/messages POST 메시지 생성
/anthropic/v1/messages/count_tokens POST 토큰 수 계산

지원되는 파라미터

다음 Anthropic API 파라미터가 지원돼요:

파라미터 타입 설명
model string 필수. 모델 식별자.
messages array 필수. 대화 메시지.
max_tokens integer 생성할 최대 토큰 수.
temperature float 샘플링 온도(0.0-1.0).
top_p float 핵 샘플링 파라미터.
top_k integer Top-k 샘플링 파라미터.
stream Boolean 스트리밍 응답 활성화.
stop_sequences array 커스텀 중지 시퀀스.
system string 시스템 프롬프트.

예시: Anthropic API로 채팅

curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

예시: 스트리밍 응답

curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from 1 to 10"}
    ]
  }'

Ollama 호환 API

DMR은 Ollama용으로 빌드된 도구와 프레임워크를 위한 Ollama 호환 엔드포인트도 제공해요.

엔드포인트

엔드포인트 메서드 설명
/api/tags GET 사용 가능한 모델 나열
/api/show POST 모델 정보 표시
/api/chat POST 채팅 완성 생성
/api/generate POST 완성 생성
/api/embeddings POST 임베딩 생성

예시: Ollama API로 채팅

curl http://localhost:12434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

예시: 모델 목록

curl http://localhost:12434/api/tags

이미지 생성 API(Diffusers)

DMR은 Diffusers 백엔드를 통한 이미지 생성을 지원해서 Stable Diffusion 같은 모델을 사용해 텍스트 프롬프트에서 이미지를 생성할 수 있어요.

참고: Diffusers 백엔드는 CUDA를 지원하는 NVIDIA GPU가 필요하며 Linux(x86_64와 ARM64)에서만 사용할 수 있어요. 설정 안내는 추론 엔진 문서를 참고해 주세요.

엔드포인트

엔드포인트 메서드 설명
/engines/diffusers/v1/images/generations POST 텍스트 프롬프트에서 이미지 생성

지원되는 파라미터

파라미터 타입 설명
model string 필수. 모델 식별자(예: stable-diffusion:Q4).
prompt string 필수. 생성할 이미지의 텍스트 설명.
size string WIDTHxHEIGHT 형식의 이미지 크기(예: 512x512).

응답 형식

API는 생성된 이미지가 base64로 인코딩된 JSON 응답을 반환해요:

{
  "data": [
    {
      "b64_json": "<base64-encoded-image-data>"
    }
  ]
}

예시: 이미지 생성

curl -s -X POST http://localhost:12434/engines/diffusers/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion:Q4",
    "prompt": "A picture of a nice cat",
    "size": "512x512"
  }' | jq -r '.data[0].b64_json' | base64 -d > image.png

이 명령은:

  1. Diffusers 이미지 생성 엔드포인트에 POST 요청을 보내고
  2. 모델, 프롬프트, 출력 이미지 크기를 지정하며
  3. jq로 응답에서 base64로 인코딩된 이미지를 추출하고
  4. base64 데이터를 디코딩해 image.png로 저장해요.

DMR 네이티브 엔드포인트

이 엔드포인트는 모델 관리를 위한 Docker Model Runner 고유의 것이에요:

엔드포인트 메서드 설명
/models/create POST 모델 풀/생성
/models GET 로컬 모델 목록
/models/{namespace}/{name} GET 모델 세부 정보 가져오기
/models/{namespace}/{name} DELETE 로컬 모델 삭제

REST API 예시

컨테이너 안에서 요청

다른 컨테이너 안에서 curl로 chat/completions OpenAI 엔드포인트를 호출하려면:

#!/bin/sh
curl http://model-runner.docker.internal/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Please write 500 words about the fall of Rome."
      }
    ]
  }'

호스트에서 TCP로 요청

호스트에서 TCP로 chat/completions OpenAI 엔드포인트를 호출하려면:

  1. Docker Desktop GUI에서 호스트 측 TCP 지원을 활성화하거나 Docker Desktop CLI를 사용해요. 예: docker desktop enable model-runner --tcp <port>.
  2. Windows에서 실행 중이라면 GPU 지원 추론(GPU-backed inference)도 활성화하세요. Docker Model Runner 활성화 문서를 참고해 주세요.
  3. localhost와 올바른 포트를 사용해 이전 섹션에 문서화된 대로 상호작용해요.
#!/bin/sh
curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Please write 500 words about the fall of Rome."
      }
    ]
  }'

호스트에서 Unix 소켓으로 요청

호스트에서 curl로 Docker 소켓을 통해 chat/completions OpenAI 엔드포인트를 호출하려면:

#!/bin/sh
curl --unix-socket $HOME/.docker/run/docker.sock \
  localhost/exp/vDD4.40/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Please write 500 words about the fall of Rome."
      }
    ]
  }'

스트리밍 응답

스트리밍 응답을 받으려면 stream: true를 설정해요:

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from 1 to 10"}
    ]
  }'

OpenAI SDK와 함께 사용

Python

from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed" # DMR doesn't require an API key
)
response = client.chat.completions.create(
    model="ai/smollm2",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)
print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';
const client = new OpenAI({
    baseURL: 'http://localhost:12434/engines/v1',
    apiKey: 'not-needed' // DMR doesn't require an API key
});
const response = await client.chat.completions.create({
    model: 'ai/smollm2',
    messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);

다음 단계

  • IDE 및 도구 통합 — Cline, Continue, Cursor 등 다른 도구 구성
  • 구성 옵션 — 컨텍스트 크기와 런타임 파라미터 조정
  • 추론 엔진 — llama.cpp, vLLM, Diffusers 옵션 알아보기

더 알아보기 (Learn more)