> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LiteLLM 접속 가이드

> Crazyrouter를 LiteLLM AI 게이트웨이에 접속하기: 모델 및 가격 설정 내보내기, 프록시 실행, 요청 검증, 팀 예산 및 호환성 제한 이해

> 내용 업데이트: 2026-10-24

LiteLLM은 기업의 통합 AI 게이트웨이 역할을 할 수 있습니다: 애플리케이션은 LiteLLM에 접속하고, LiteLLM이 Crazyrouter를 호출합니다. 프로젝트, 부서, 가상 키, 예산 및 감사 정책은 여러분이 직접 구축한 LiteLLM에 구성해야 하며, Crazyrouter API Key를 입력한다고 자동 활성화되지는 않습니다.

```text theme={null}
Application → LiteLLM Proxy → Crazyrouter → Model
```

## 접속 구조와 준비

Python 3.11, 별도의 Crazyrouter 추론 키, 해당 키로 접근 가능한 모델을 준비하세요. 본 문서는 **LiteLLM 1.106.2** 기준으로 검증되었습니다. 최신 버전임을 의미하지는 않습니다. 네 가지 예시 모델은 `claude-opus-5-5`, `gpt-6-astra`, `glm-5.3`, `deepseek-v4.1-flash`이며, 실제 사용 가능 모델로 조정해주십시오.

> [!WARNING]
>
> `CRAZYROUTER_API_KEY`는 LiteLLM 서버에서 Crazyrouter를 호출하기 위한 인증 정보이고, `LITELLM_MASTER_KEY`는 여러분의 LiteLLM 관리자 키입니다. 서로 혼용하지 말고, 관리자 키를 부서나 최종 사용자에게 제공하지 마십시오. 실제 키는 서버 환경이나 키 관리기에만 보관하며, Git, 문서, 프론트엔드에 제출하지 마세요.

## 1. 설치 및 환경 변수

새 작업 디렉터리에서 다음 명령어를 실행하세요. 환경 변수는 해당 터미널에만 적용됩니다. 기존 게이트웨이는 기존 방식의 안전한 관리자 키를 그대로 사용하세요. 임의로 재생성하면 안 됩니다. 컨테이너 배포의 경우, 변수는 컨테이너 내부로 전달해야 합니다. Windows에서 가상환경 활성화가 안될 경우, `.venv\Scripts` 내의 `python.exe`와 `litellm.exe`를 직접 호출하세요.

```bash macOS / Linux theme={null}
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "litellm[proxy]==1.106.2"
read -rsp 'Crazyrouter API key: ' CRAZYROUTER_API_KEY; echo
export CRAZYROUTER_API_KEY
export LITELLM_MASTER_KEY="$(python -c 'import secrets; print("sk-" + secrets.token_hex(32))')"
```

```powershell Windows PowerShell theme={null}
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install "litellm[proxy]==1.106.2"
$secret = Read-Host 'Crazyrouter API key' -AsSecureString
$env:CRAZYROUTER_API_KEY = [System.Net.NetworkCredential]::new('', $secret).Password
$env:LITELLM_MASTER_KEY = python -c "import secrets; print('sk-' + secrets.token_hex(32))"
```

## 2. 설정 내보내기 및 실행

인증된 `GET /v1/litellm/config`를 사용하여 모델 및 해당 인증 정보에 맞는 가격 스냅샷을 받아오기를 추천합니다. 응답은 래핑된 객체입니다: **이 중 `config`만 LiteLLM 설정으로 저장하세요**, 전체 응답을 직접 넣으면 안 됩니다. 아래 스크립트를 `export_config.py`로 저장하고, JSON을 사용하세요(YAML도 가능). `model_info`의 가격을 남기되 환경 변수로 참조하고, 실제 키는 기록하지 않습니다.

```python export_config.py theme={null}
import json
import os
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import HTTPRedirectHandler, Request, build_opener


class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None


key = os.environ["CRAZYROUTER_API_KEY"]
if not key:
    raise SystemExit("CRAZYROUTER_API_KEY is empty")
query = urlencode({
    "provider": "openai",
    "models": "claude-opus-5-5,gpt-6-astra,glm-5.3,deepseek-v4.1-flash",
})
request = Request(
    "https://api.crazyrouter.com/v1/litellm/config?" + query,
    headers={"Authorization": "Bearer " + key,
             "User-Agent": "Crazyrouter-LiteLLM-Setup/1.0"},
)
try:
    with build_opener(NoRedirect).open(request, timeout=30) as response:
        payload = json.load(response)
except HTTPError as error:
    raise SystemExit(f"Export failed (HTTP {error.code}); no file written.")
except URLError:
    raise SystemExit("Export connection failed; no file written.")

config = payload["config"]
if not config.get("model_list"):
    raise SystemExit("Export contains no models")
config.setdefault("litellm_settings", {})["drop_params"] = False
config.setdefault("general_settings", {})["master_key"] = "os.environ/LITELLM_MASTER_KEY"
output = json.dumps(config, ensure_ascii=False, indent=2)
if key in output:
    raise SystemExit("Refusing to write a secret")
with Path("crazyrouter.config.json").open("x", encoding="utf-8") as handle:
    handle.write(output + "\n")
print("Saved configuration. Import/reload it in LiteLLM explicitly.")
```

```shell theme={null}
python export_config.py
litellm --config ./crazyrouter.config.json --host 127.0.0.1 --port 4100
```

> [!NOTE]
>
> 스크립트는 기존 파일을 덮어쓰지 않습니다. 업데이트 시, 설정을 먼저 백업·비교하고, 기존 게이트웨이에 병합 후 명시적으로 재시작하세요. `4100`는 예시 포트입니다. 이미 사용 중이면, 실행 명령어와 검증 주소 모두 변경하세요. 본 명령은 내 컴퓨터에서만 듣고, 기존 서비스를 변경 또는 재시작하지 않습니다.

## 3. 로컬 게이트웨이 검증

프록시 터미널을 실행한 상태에서, 다른 환경이 동일한 터미널에서 **같은** `LITELLM_MASTER_KEY`를 안전하게 설정하세요. 재생성하지 마세요. 아래 스크립트를 `verify_proxy.py`로 저장하세요. 이번 관리자 스모크 테스트는 정상 모델 사용량이 발생합니다. 일상 애플리케이션은 제한된 가상 키를 사용해야 합니다.

```python verify_proxy.py theme={null}
import json
import os
from urllib.request import Request, urlopen

base = "http://127.0.0.1:4100/v1"
headers = {"Authorization": "Bearer " + os.environ["LITELLM_MASTER_KEY"],
           "Content-Type": "application/json"}

with urlopen(Request(base + "/models", headers=headers), timeout=30) as response:
    models = json.load(response)["data"]
assert any(model["id"] == "gpt-6-astra" for model in models), "Model not registered"

body = {"model": "gpt-6-astra", "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Reply with exactly OK."}]}
with urlopen(Request(base + "/chat/completions", headers=headers,
                     data=json.dumps(body).encode()), timeout=120) as response:
    result = json.load(response)
choice = result["choices"][0]
assert choice["finish_reason"] == "stop", "Incomplete response"
assert (choice["message"].get("content") or "").strip() == "OK", "Check final answer"
assert result.get("usage", {}).get("total_tokens", 0) > 0, "Missing usage"
print("PASS: model registration, final answer, finish reason, usage")
```

```shell theme={null}
python verify_proxy.py
```

이것은 최소 스모크 테스트이며, 완전한 호환성 인증이 아닙니다. 실제 모델마다 일반/스트림 요청을 계속 검증해야 합니다: 최종 본문, 종료 원인, SSE의 `[DONE]` 및 최종 usage를 확인하세요. 툴 테스트는 파라미터 확인 및 툴 결과 회수까지 마쳐야 합니다. HTTP 200, 생각 텍스트 또는 Markdown JSON 코드 블럭만으로는 통과가 아닙니다.

## 4. Claude 원본 프로토콜(선택)

기본 내보내기는 `openai/<model>`를 사용하며, `api_base`는 `https://api.crazyrouter.com/v1`가 됩니다. Claude 원본 캐시, thinking 등 의미가 필요하면, `provider=anthropic&models=claude-opus-5-5`로 별도 내보내기 하고, `anthropic/<model>`와 루트 주소 `https://api.crazyrouter.com`를 사용하세요. `/v1` 또는 `/chat/completions`를 추가하지 마세요.

```yaml theme={null}
model_list:
  - model_name: claude-native
    litellm_params:
      model: anthropic/claude-opus-5-5
      api_base: https://api.crazyrouter.com
      api_key: os.environ/CRAZYROUTER_API_KEY
litellm_settings:
  drop_params: false
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
```

위 예시는 연결 구조만 보여주며, 가격은 포함하지 않습니다. 실제 사용 시, 원본 내보내기 항목의 `model_info`를 합치세요. OpenAI 어댑터와 동시 등록할 경우, 원본 항목에는 `claude-native`와 같은 독립 `model_name`를 사용하세요. 클라이언트는 해당 별칭을 통해 호출하며, 동일 이름 항목 혼합 라우팅을 피할 수 있습니다.

## 호환성 및 오류 처리

* `drop_params: false`를 유지하고, 지원되지 않는 파라미터는 조용히 폐기하지 않습니다.
* Claude의 `json_schema`는 검증되었고, `json_object`는 지원하지 않으며, 자동으로 다른 출력 보증으로 변환되지 않습니다.
* 검증된 Claude 경로에서는 툴/`required` 요청이 명확히 거부됩니다: HTTP `400`, 직결 오류 코드 `unsupported_forced_tool_choice`. 자동 툴 선택이 필요할 경우, 클라이언트가 명시적으로 `tool_choice: "auto"`를 사용해야 합니다. 게이트웨이가 자동으로 강제로 호출을 다운그레이드하지 않습니다.
* 위 거부에 대해 클라이언트는 고정된 안전 영어 문구를 받고 내부 서비스 설정이나 인증 정보는 반환하지 않습니다. LiteLLM 1.106.2의 OpenAI 어댑터는 영문 메시지를 보존하며, 오류 코드를 `"400"`에 래핑합니다. 원래 오류 코드만으로 매칭하지 마세요.
* Claude `cache_control`의 `5m`/`1h` TTL은 직접 전달 가능한데, 5분 생성 및 읽기는 테스트되었고, 1시간은 냉(콜드) 기록만 검증했으니, 실제 히트율 및 1시간 후 읽기는 보장하지 않습니다.
* 모델 기능, 사용 가능 여부, 비전, 장문 맥락, 장애 조치, 기업 예산은 각각 검증해야 하며, 모델 이름 또는 본 가이드 문서에서 판정할 수 없습니다.

## 팀, 예산 및 운영 보안

* 프로젝트 또는 부서별로 LiteLLM 팀과 제한된 가상 키를 생성하고, 모델 권한, 예산, 속도 제한을 설정하세요. 관리자 키를 공유하지 마세요.
* LiteLLM 공식 요구에 따라 데이터베이스, 인증, 권한, 영속화 설정하세요. 로컬에서 데이터베이스 없이 실행 시 추론 체인만 검증되며, 예산 활성화는 의미하지 않으므로, 기능 및 권한은 사용 버전에 따르세요.
* 출시 전 각 권한 모델 거부, 예산 소진, 키 폐기, 제한 및 감사 기능을 개별적으로 테스트하세요. 로그의 프롬프트 및 개인정보는 보호하고 보존 기간도 명확히 하세요.
* 외부 접속에는 HTTPS 및 액세스 제어를 설정하고, 로컬 데모 서비스나 관리 페이지를 직접 노출하지 마세요.
* 내보내기된 가격은 스냅샷입니다. 가격 또는 할인 변경 시 재내보내기 및 재불러오기를 해야 하며, 자동 푸시되지 않습니다. LiteLLM의 비용 추정치는 Crazyrouter 최종 영수증과 다를 수 있으니, 정기적으로 대사하세요.

## 자주 묻는 질문

| 현상 | 체크 방향 |
| - | - |
| 내보내기 401 반환 | Crazyrouter 추론 키를 사용하세요. LiteLLM 관리자 키나 콘솔 세션 인증 정보를 쓰지 마세요. |
| 내보내기 404 반환 | 모델 ID 및 현재 키의 접근 권한을 확인하세요. |
| 내보내기 422 반환 | 선택한 provider와 가격이 산식으로 표현 가능한지 확인하세요. 추측한 고정 가격을 쓰지 마세요. |
| LiteLLM이 401 반환 | 하위 호출은 LiteLLM의 관리자 키(로컬 관리 테스트 전용) 또는 유효한 가상 키를 사용하세요. |
| 모델 미등록/환경 변수 없음 | `config`를 저장했는지, 환경 변수가 프록시 또는 컨테이너에 전달되어 있고, 재시작했는지 확인하세요. |
| 강제 툴 400 반환 | `auto`를 명시적으로 선택하거나, 해당 툴 및 thinking 설정을 지원하는 모델을 확인 후 사용하세요. |
| 예산 제한 미적용 | 데이터베이스, 팀/가상 키 정책을 확인하고 실제 예산 거부 테스트를 진행하세요. |

## 공식 참고

* [LiteLLM Proxy configuration](https://docs.litellm.ai/docs/proxy/configs)
* [LiteLLM virtual keys](https://docs.litellm.ai/docs/proxy/virtual_keys)
* [LiteLLM budgets](https://docs.litellm.ai/docs/proxy/users)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.