AiHubMix Documentation Hub

LiteLLM 개요

LiteLLM은 BerriAI가 개발한 오픈 소스 통합 AI 게이트웨이입니다. 시장의 거의 모든 주요 LLM을 호출할 수 있는 단일 표준화된 인터페이스를 제공합니다. 저장소: https://github.com/BerriAI/litellm

모든 LLM 공급자는 자체 SDK와 API 형식을 제공합니다 — OpenAI, Anthropic, Google 모두 다릅니다. 모델을 전환하거나 여러 모델을 동시에 사용하는 것은 별도의 코드베이스를 유지해야 함을 의미합니다. LiteLLM은 이를 해결합니다: 한 번 작성하고, 파라미터 하나를 변경하여, 어떤 모델이든 호출.

두 가지 사용 모드

모드	설명	가장 적합한 용도
Python SDK	`pip install litellm`, 코드에서 직접 호출	개인 프로젝트, 빠른 프로토타이핑
Proxy Server	독립적으로 배포 가능한 AI 게이트웨이	팀 공유, 엔터프라이즈 액세스 제어

핵심 기능

통합 OpenAI 형식: OpenAI, Anthropic, Gemini, Bedrock, Azure 등 100+ 공급자 지원
가상 키 관리: 원본을 노출하지 않고 팀 API 키를 중앙에서 관리
비용 추적: 사용자 또는 프로젝트별 토큰 사용량 및 지출 모니터링
로드 밸런싱: 페일오버 지원과 함께 모델 간 자동 트래픽 분산
고성능: 1,000 RPS에서 P95 지연 ~8ms

설치

요구 사항

Python 3.8+ macOS Homebrew를 통해 설치:

brew install python

확인:

python3 --version

Windows python.org/downloads에서 설치 프로그램을 다운로드합니다. 설치 중에 **“Add Python to PATH”**를 체크합니다. 확인:

python --version

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3 python3-pip

pip

pip는 일반적으로 Python과 함께 번들로 제공됩니다. 사용 가능한지 확인합니다:

pip --version
# or
pip3 --version

찾을 수 없는 경우 수동으로 설치합니다:

# Universal method
python3 -m ensurepip --upgrade

# Ubuntu/Debian
sudo apt install python3-pip

# Upgrade to latest
pip install --upgrade pip

LiteLLM 설치

환경이 준비되면:

python3 -m pip install litellm

설치 확인:

python3 -m pip show litellm

선택적 종속성

일부 공급자는 추가 패키지가 필요합니다:

# AWS Bedrock
pip install litellm[bedrock]

# Google Vertex AI
pip install litellm[vertex]

# All dependencies (not recommended for production)
pip install litellm[all]

Proxy Server 설치

독립 실행형 게이트웨이를 배포하려면:

pip install 'litellm[proxy]'

Docker (선택 사항)

docker pull ghcr.io/berriai/litellm:main-latest

권장 사항: 개인 개발에는 pip install litellm을 사용하세요; 팀 배포에는 Proxy + Docker를 선택하세요.

API 키 구성 및 첫 호출

AiHubMix API 키 얻기

aihubmix.com 대시보드로 이동하여 API 키를 생성합니다.

환경 변수 설정

export AIHUBMIX_API_KEY="your-aihubmix-key"

첫 호출

import os
from litellm import completion

response = completion(
    model="openai/gpt-4o-mini",
    api_base="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY"),
    messages=[{"role": "user", "content": "Hello, introduce yourself"}]
)

print(response.choices[0].message.content)

기본 사용법

1. 모델 전환

AiHubMix는 모든 주요 모델을 지원합니다. 전환은 model 파라미터를 변경하기만 하면 됩니다:

import os
from litellm import completion

response = completion(
    model="openai/claude-sonnet-4-6",  # change this
    api_base="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY"),
    messages=[{"role": "user", "content": "Hello, introduce yourself"}]
)

print(response.choices[0].message.content)

2. 스트리밍

토큰 단위로 출력을 받으려면 stream=True를 추가합니다:

import os
from litellm import completion

response = completion(
    model="openai/claude-sonnet-4-6",
    api_base="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY"),
    messages=[{"role": "user", "content": "Explain Python in 100 words"}],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
print()

3. 다중 턴 대화

모델이 컨텍스트를 기억하도록 messages 목록에 대화 기록을 전달합니다:

import os
from litellm import completion

messages = [
    {"role": "user", "content": "My name is Alex"},
    {"role": "assistant", "content": "Hello, Alex!"},
    {"role": "user", "content": "What is my name?"}
]

response = completion(
    model="openai/claude-sonnet-4-6",
    api_base="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY"),
    messages=messages
)

print(response.choices[0].message.content)

4. 비동기 호출

각 호출이 완료될 때까지 기다리지 않고 여러 요청을 동시에 보냅니다:

import os
import asyncio
from litellm import acompletion

async def ask(question):
    response = await acompletion(
        model="openai/claude-sonnet-4-6",
        api_base="https://aihubmix.com/v1",
        api_key=os.environ.get("AIHUBMIX_API_KEY"),
        messages=[{"role": "user", "content": question}]
    )
    return response.choices[0].message.content

async def main():
    questions = [
        "What color is an apple?",
        "What color is the sky?",
        "What color is grass?"
    ]
    results = await asyncio.gather(*[ask(q) for q in questions])
    for q, r in zip(questions, results):
        print(f"Q: {q}")
        print(f"A: {r}")
        print()

asyncio.run(main())

5. 타임아웃 및 재시도

네트워크 문제로 요청이 멈추거나 실패하는 것을 방지합니다:

import os
from litellm import completion

response = completion(
    model="openai/claude-sonnet-4-6",
    api_base="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY"),
    messages=[{"role": "user", "content": "Hello"}],
    timeout=10,      # raise an error after 10 seconds
    num_retries=3    # retry up to 3 times on failure
)

print(response.choices[0].message.content)

timeout은 초 단위입니다. num_retries를 2-3으로 설정하세요; 높은 값은 응답을 느리게 합니다.

6. 토큰 사용량 및 비용 추적

모든 응답에는 토큰 사용량 데이터가 포함됩니다:

import os
from litellm import completion

response = completion(
    model="openai/claude-sonnet-4-6",
    api_base="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY"),
    messages=[{"role": "user", "content": "Explain Python in 100 words"}]
)

print(response.choices[0].message.content)
print()
print("Token usage:")
print(f"  Input:  {response.usage.prompt_tokens}")
print(f"  Output: {response.usage.completion_tokens}")
print(f"  Total:  {response.usage.total_tokens}")

호출당 비용 추적:

import os
from litellm import completion, completion_cost

response = completion(
    model="openai/claude-sonnet-4-6",
    api_base="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY"),
    messages=[{"role": "user", "content": "Explain Python in 100 words"}]
)

cost = completion_cost(completion_response=response)
print(f"Cost: ${cost:.6f}")

7. 로드 밸런싱 및 페일오버

여러 모델을 구성하여 트래픽을 자동으로 분산하거나 하나가 실패할 때 백업으로 전환:

import os
from litellm import Router

router = Router(
    model_list=[
        {
            "model_name": "my-model",
            "litellm_params": {
                "model": "openai/claude-sonnet-4-6",
                "api_base": "https://aihubmix.com/v1",
                "api_key": os.environ.get("AIHUBMIX_API_KEY"),
            }
        },
        {
            "model_name": "my-model",
            "litellm_params": {
                "model": "openai/gpt-4o",
                "api_base": "https://aihubmix.com/v1",
                "api_key": os.environ.get("AIHUBMIX_API_KEY"),
            }
        }
    ]
)

response = router.completion(
    model="my-model",
    messages=[{"role": "user", "content": "Hello"}]
)

print(response.choices[0].message.content)

두 모델은 동일한 model_name을 공유합니다. LiteLLM은 그 사이에서 라운드 로빈을 수행하며 하나가 오류를 반환하면 자동으로 페일오버됩니다.

8. Proxy Server 배포

Proxy Server는 독립 실행형 게이트웨이입니다. 팀원은 자체 API 키 없이 모든 요청을 그것을 통해 라우팅합니다. 설치

python3 -m pip install 'litellm[proxy]'

config.yaml 생성

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_base: https://aihubmix.com/v1
      api_key: os.environ/AIHUBMIX_API_KEY

  - model_name: claude-sonnet
    litellm_params:
      model: openai/claude-sonnet-4-6
      api_base: https://aihubmix.com/v1
      api_key: os.environ/AIHUBMIX_API_KEY

  - model_name: gemini-flash
    litellm_params:
      model: openai/gemini-2.0-flash
      api_base: https://aihubmix.com/v1
      api_key: os.environ/AIHUBMIX_API_KEY

서버 시작

litellm --config config.yaml --port 4000

성공적인 시작은 다음을 표시합니다:

LiteLLM: Proxy running on http://0.0.0.0:4000

로컬 서버 호출

import os
from litellm import completion

response = completion(
    model="gpt-4o",
    api_base="http://localhost:4000",
    api_key="any-string",
    messages=[{"role": "user", "content": "Hello"}]
)

print(response.choices[0].message.content)

여기의 api_key는 임의의 문자열이 될 수 있습니다. 실제 AiHubMix 키는 Proxy에 의해 관리됩니다.

9. 가상 키 관리

가상 키를 사용하면 다른 팀원 또는 프로젝트에 독립적인 키를 할당할 수 있으며, 실제 AiHubMix 키를 노출하지 않고 액세스 및 사용량을 제어할 수 있습니다. 전제 조건: PostgreSQL 인스턴스 시작

docker run -d \
  --name litellm-db \
  -e POSTGRES_USER=litellm \
  -e POSTGRES_PASSWORD=litellm \
  -e POSTGRES_DB=litellm \
  -p 5432:5432 \
  postgres

config.yaml 업데이트

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_base: https://aihubmix.com/v1
      api_key: os.environ/AIHUBMIX_API_KEY

  - model_name: claude-sonnet
    litellm_params:
      model: openai/claude-sonnet-4-6
      api_base: https://aihubmix.com/v1
      api_key: os.environ/AIHUBMIX_API_KEY

general_settings:
  master_key: sk-my-master-key
  database_url: postgresql://litellm:litellm@localhost:5432/litellm

서버 재시작

litellm --config config.yaml --port 4000

가상 키 생성

curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-my-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "team-a",
    "max_budget": 10,
    "models": ["gpt-4o", "claude-sonnet"]
  }'

응답의 key 필드는 가상 키입니다, 예: sk-xxxxxx. 가상 키 사용

from litellm import completion

response = completion(
    model="claude-sonnet",
    api_base="http://localhost:4000",
    api_key="sk-xxxxxx",
    messages=[{"role": "user", "content": "Hello"}]
)

print(response.choices[0].message.content)

사용량 확인

curl http://localhost:4000/key/info \
  -H "Authorization: Bearer sk-my-master-key" \
  -H "Content-Type: application/json" \
  -d '{"key": "sk-xxxxxx"}'

각 가상 키는 개별 모델 제한, 예산 한도 및 만료 시간을 지원합니다 — 다중 멤버 팀 워크플로우에 이상적입니다.

실용적 예시: 다중 모델 비교

여러 모델에 동시에 동일한 질문을 보내고 출력 품질, 속도 및 토큰 사용량을 비교합니다. API Key 설정

export AIHUBMIX_API_KEY="your-key"

비교 실행

import os
import time
import asyncio
from litellm import acompletion

MODELS = [
    "gpt-5.5",
    "claude-opus-4-7",
    "deepseek-v4-flash",
    "coding-glm-5.1-free",
]

QUESTION = "If you could give a programmer only one piece of advice, what would it be?"

async def ask_model(model, question):
    start = time.time()
    try:
        response = await acompletion(
            model=f"openai/{model}",
            api_base="https://aihubmix.com/v1",
            api_key=os.environ.get("AIHUBMIX_API_KEY"),
            messages=[{"role": "user", "content": question}]
        )
        return {
            "model": model,
            "answer": response.choices[0].message.content.strip(),
            "tokens": response.usage.total_tokens,
            "time": round(time.time() - start, 2),
            "error": None
        }
    except Exception as e:
        return {
            "model": model,
            "answer": None,
            "tokens": 0,
            "time": round(time.time() - start, 2),
            "error": str(e)
        }

async def main():
    print(f"Question: {QUESTION}")
    print("=" * 60)
    tasks = [ask_model(m, QUESTION) for m in MODELS]
    results = await asyncio.gather(*tasks)
    for r in results:
        print(f"\nModel: {r['model']}")
        print(f"Time: {r['time']}s  |  Tokens: {r['tokens']}")
        print("-" * 40)
        if r["error"]:
            print(f"Error: {r['error']}")
        else:
            print(r["answer"])
    print("\n" + "=" * 60)
    print(f"{'Model':<30} {'Time':>8} {'Tokens':>8}")
    print("-" * 50)
    for r in sorted(results, key=lambda x: x["time"]):
        status = f"{r['time']}s" if not r["error"] else "failed"
        print(f"{r['model']:<30} {status:>8} {r['tokens']:>8}")

asyncio.run(main())

마지막 업데이트: 2026년 4월 29일

Documentation Index

​LiteLLM 개요

​두 가지 사용 모드

​핵심 기능

​설치

​요구 사항

​pip

​LiteLLM 설치

​선택적 종속성

​Proxy Server 설치

​Docker (선택 사항)

​API 키 구성 및 첫 호출

​AiHubMix API 키 얻기

​환경 변수 설정

​첫 호출

​기본 사용법

​1. 모델 전환

​2. 스트리밍

​3. 다중 턴 대화

​4. 비동기 호출

​5. 타임아웃 및 재시도

​6. 토큰 사용량 및 비용 추적

​7. 로드 밸런싱 및 페일오버

​8. Proxy Server 배포

​9. 가상 키 관리

​실용적 예시: 다중 모델 비교