[LiteLLM 1] Docker와 Ollama로 내 LLM Gateway 만들기

Об этом предложении

LiteLLM 1 · 로컬 Gateway 설치 이 글에서 다룰 주제 SDK와 Proxy의 역할을 구분하고 로컬 모델까지 요청을 연결한다. Docker와 PostgreSQL로 UI·키·사용량 기록의 기반을 만든다. health, 일반 응답, 스트리밍을 각각 확인한다. 주요 단어 · Proxy · Gateway · 모델 별칭 · Virtual Key · Ollama LLM을 호출하는 프로그램이 늘어나면 각 프로그램 안에 모델 주소와 키가 흩어진다. AIOps 에이전트도 장애 분석용 호출과 평가용 호출을 같은 방식으로 관리하기 어렵다. 이번 실습에서는 공통 API 진입점 하나를 두고 로컬 모델까지 연결한다. 1. Gateway의 역할 LiteLLM Proxy 는 애플리케이션의 LLM 요청을 받아 인증·모델 선택·제한을 적용하고 대상 Provider로 전달하는 서버다. LiteLLM SDK 는 이 호출 변환을 Python 프로그램 안에서 사용하는 라이브러리다. 이 시리즈는 여러 애플리케이션을 중앙에서 관리하려는 목적이므로 Proxy부터 시작한다. 공식 개요 요청은 클라이언트 → LiteLLM → Ollama로 흐른다. PostgreSQL에는 키와 사용량 같은 관리 데이터가 남는다. 이 그림의 PostgreSQL은 이전 실습의 DB를 재사용하지 않는 별도 저장소다. 모델 자체는 Ollama가 실행한다. LiteLLM을 설치했다고 새로운 LLM이 생기는 것은 아니다. Langfuse가 실행 과정과 품질을 관찰하는 데 초점을 둔다면, 이번 LiteLLM 실습은 요청이 모델에 도달하는 경로와 접근 정책을 다룬다. 2. 버전과 자원 2026-10-05에 다음 조합을 직접 실행했다. 구성요소 실행 환경 호스트 Apple Silicon macOS, 메모리 64GB LiteLLM 1.104.0, Linux ARM64 Docker 이미지 PostgreSQL 17.11, 전용 Docker 볼륨 Ollama macOS 네이티브 0.35.1 텍스트 모델 qwen3:8b 접속 주소 http://localhost:4000/ui , API /v1 공식 v1.104.0 릴리스 와 이미지 manifest를 확인하고 digest로 고정했다. 별도의 cosign 서명 검증까지 수행했다는 뜻은 아니다. 이전 Langfuse 실습 컨테이너는 데이터를 보존한 채 중지했다. 설치 후 한 시점의 실제 사용량은 Proxy 약 585MiB, PostgreSQL 약 46MiB였다. 설정한 상한은 각각 2GiB와 768MiB다. 이는 소규모 로컬 실습 조건이며 운영 최소 사양이나 최대 처리량을 의미하지 않는다. Ollama가 모델을 적재하는 메모리는 별도로 필요하다. 3. 설치 파일 아래는 실행한 구성에서 텍스트 경로를 추린 재현용 설정이다. Docker Desktop과 Ollama가 먼저 실행되어 있어야 한다. 작업 폴더에 compose.yaml , config.yaml , .env 를 만든다. 3.1 로컬 모델 ollama pull qwen3:8b ollama list Docker 컨테이너에서 macOS의 Ollama로 연결할 때는 host.docker.internal 을 사용했다. 컨테이너 안의 localhost 는 그 컨테이너 자신이다. 아래의 ollama_chat/ 는 Ollama 네이티브 Chat API를 선택하므로 api_base 뒤에 /v1 을 붙이지 않는다. Ollama Provider 문서 3.2 비밀값 생성 다음 Python 코드는 비밀값을 출력하지 않고 .env 를 만든다. 파일이 이미 있으면 덮어쓰지 않고 실패하게 했다. import os import secrets values = { "POSTGRES_PASSWORD": secrets.token_hex(32), "LITELLM_MASTER_KEY": "sk-" + secrets.token_hex(32), "LITELLM_SALT_KEY": "sk-" + secrets.token_hex(32), "UI_USERNAME": "learner", "UI_PASSWORD": secrets.token_urlsafe(32), } fd = os.open(".env", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) with os.fdopen(fd, "w") as f: f.write("\n".join(f"{k}={v}" for k, v in values.items()) + "\n") Master Key는 관리용이다. 일반 애플리케이션에는 다음 편에서 만드는 Virtual Key를 전달한다. Salt Key는 저장된 자격 증명의 암호화·복호화에 사용되므로 DB와 함께 보존한다. 공식 Quickstart 3.3 모델 설정 # config.yaml model_list: - model_name: local-text litellm_params: model: ollama_chat/qwen3:8b api_base: http://host.docker.internal:11434 input_cost_per_token: 0 output_cost_per_token: 0 keep_alive: 5m model_info: id: local-text-qwen3-8b mode: chat router_settings: num_retries: 0 timeout: 120 fallbacks: [] cache_responses: false litellm_settings: num_retries: 0 request_timeout: 120 cache: false turn_off_message_logging: true redact_messages_in_exceptions: true redact_user_api_key_info: true set_verbose: false json_logs: true global_disable_no_log_param: true general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: os.environ/DATABASE_URL store_prompts_in_spend_logs: false disable_error_logs: true database_connection_pool_limit: 5 enforce_fallback_model_access: true local-text 는 클라이언트가 사용하는 모델 별칭 이다. 실제 모델 이름은 ollama_chat/qwen3:8b 다. 애플리케이션은 별칭을 사용하고 운영자는 그 별칭의 목적지와 정책을 관리한다. 본문 로깅·응답 캐시·fallback은 끄고 retry는 0으로 시작했다. 기능을 하나씩 추가해야 결과가 어느 설정 때문에 달라졌는지 읽기 쉽다. 로그의 메시지 가림과 DB 본문 저장 설정은 별개로 확인해야 한다. 로깅 설정 3.4 Docker Compose # compose.yaml name: litellm-study services: proxy: image: ghcr.io/berriai/litellm@sha256:625981c83410a3ea68eb0697590a57ec1d764d634514d54fa5db0591077ee839 command: ["--config", "/app/config.yaml", "--port", "4000", "--num_workers", "1"] restart: unless-stopped mem_limit: 2g cpus: 2 ports: ["127.0.0.1:4000:4000"] volumes: ["./config.yaml:/app/config.yaml:ro"] environment: DATABASE_URL: postgresql://litellm:${POSTGRES_PASSWORD:?required}@postgres:5432/litellm LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?required} LITELLM_SALT_KEY: ${LITELLM_SALT_KEY:?required} UI_USERNAME: ${UI_USERNAME:?required} UI_PASSWORD: ${UI_PASSWORD:?required} LITELLM_MODE: PRODUCTION LITELLM_LOG: ERROR LITELLM_LOCAL_MODEL_COST_MAP: "True" STORE_MODEL_IN_DB: "False" depends_on: postgres: {condition: service_healthy} postgres: image: postgres@sha256:d74eeac9a635390a49bc21bd49fccd973de707e2a53a76ac49b552b8712ec46f restart: unless-stopped mem_limit: 768m cpus: 1 environment: POSTGRES_USER: litellm POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?required} POSTGRES_DB: litellm volumes: ["postgres-data:/var/lib/postgresql/data"] healthcheck: test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"] interval: 5s timeout: 5s retries: 20 volumes: postgres-data: PostgreSQL 포트는 호스트에 공개하지 않는다. Proxy는 127.0.0.1 에 바인딩했으므로 로컬 학습용이다. STORE_MODEL_IN_DB: False 는 모델 경로를 파일에서 관리하려는 선택이며, 키와 사용량 기록용 DB 연결은 유지한다. docker compose config --quiet docker compose up -d docker compose ps curl -fsS http://127.0.0.1:4000/health/liveliness 비밀값이 확장되는 docker compose config 전체 출력을 블로그에 붙이지 않는다. 구문 확인에는 --quiet 면 충분하다. 4. UI와 첫 응답 http://localhost:4000/ui 에서 .env 의 UI 계정으로 로그인한다. 모델 목록에서 local-text 별칭과 실제 연결 대상을 확인한다. 이번 전체 실습 환경에는 이후 비용·Vision 실험을 위한 별칭도 함께 등록했다. health 응답은 서버가 살아 있다는 신호다. 모델 호출까지 성공했다는 뜻은 아니므로 실제 /v1/chat/completions 요청을 추가로 보냈다. 발급한 앱 키를 LITELLM_API_KEY 환경변수로 준비한 뒤 호출한다. curl -sS http://127.0.0.1:4000/v1/chat/completions \ -H "Authorization: Bearer $LITELLM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "local-text", "messages": [{"role":"user","content":"Reply with one short sentence explaining an API gateway. /no_think"}], "temperature": 0, "reasoning_effort": "none", "max_tokens": 64 }' 실측 일반 응답은 HTTP 200, 입력 30·출력 29·총 59토큰, finish_reason=stop 이었다. 약 0.814초가 걸렸다. 이어 동일 질문을 스트리밍으로 호출해 [DONE] 과 최종 usage를 확인했고 총 약 0.627초, 첫 content 약 40.5ms였다. 이미 모델을 호출한 뒤의 작은 두 요청이며 성능 벤치마크가 아니다. 첫 시도에서는 /no_think 만 넣고 max_tokens=32 로 제한해 reasoning 토큰으로 예산을 소진했고 최종 content가 비었다. 이 버전의 Ollama 어댑터에서 reasoning_effort: "none" 가 think: false 로 매핑되는 것을 확인한 뒤 성공했다. HTTP 200뿐 아니라 content·usage·종료 이유까지 읽어야 한다. 5. 보존하고 중지하기 docker compose stop docker compose up -d stop 은 컨테이너와 볼륨을 보존한다. 학습 데이터를 남기려면 down -v 나 볼륨 prune을 실행하지 않는다. .env 도 DB와 함께 보존한다. 전체 실습 종료 뒤에는 적재된 Ollama 모델을 메모리에서 내리고 모델 파일은 보존했다. 이전 Langfuse와 심화 실습 컨테이너는 중지했으며, 재사용할 기본 Proxy·PostgreSQL 두 개의 최종 사용량은 합계 약 536MiB였다. 이 값은 모델이 적재되지 않은 대기 상태의 한 시점이다. 이제 다음 편에서는 Master Key 대신 목적별 Virtual Key를 만들고, 접근이 허용되는 경우와 실제로 거절되는 경우를 함께 확인한다. 기준: 2026-10-05, LiteLLM 1.104.0 로컬 OSS 실습. 일반 응답·스트리밍은 실제 실행했고, 외부 유료 Provider는 연결하지 않았다. 다음 글: LiteLLM 2 · 목적별 키와 모델 접근 다음 · [LiteLLM 2] 서비스·AIOps·평가용 Virtual Key와 접근 정책