LLM 게이트웨이 구성

Claude Code를 LLM 게이트웨이 솔루션과 함께 사용하도록 구성하는 방법을 알아봅니다. 게이트웨이 요구사항, 인증 구성, 모델 선택, 프로바이더별 엔드포인트 설정을 다룹니다.

LLM 게이트웨이는 Claude Code와 모델 프로바이더 사이에 중앙 집중식 프록시 레이어를 제공하며, 주로 다음과 같은 기능을 지원합니다:

중앙 집중식 인증 - API 키 관리를 위한 단일 지점
사용량 추적 - 팀 및 프로젝트 전반의 사용량 모니터링
비용 제어 - 예산 및 속도 제한 구현
감사 로깅 - 규정 준수를 위한 모든 모델 상호작용 추적
모델 라우팅 - 코드 변경 없이 프로바이더 간 전환

게이트웨이 요구사항

LLM 게이트웨이가 Claude Code와 작동하려면 다음 요구사항을 충족해야 합니다:

API 형식

게이트웨이는 클라이언트에 다음 API 형식 중 하나 이상을 노출해야 합니다:

Anthropic Messages: /v1/messages, /v1/messages/count_tokens
- 요청 헤더를 전달해야 합니다: anthropic-beta, anthropic-version
Bedrock InvokeModel: /invoke, /invoke-with-response-stream
- 요청 본문 필드를 보존해야 합니다: anthropic_beta, anthropic_version
Vertex rawPredict: :rawPredict, :streamRawPredict, /count-tokens:rawPredict
- 요청 헤더를 전달해야 합니다: anthropic-beta, anthropic-version

헤더 전달 또는 본문 필드 보존에 실패하면 기능 제한이나 Claude Code 기능 사용 불가가 발생할 수 있습니다.

참고: Claude Code는 API 형식에 따라 활성화할 기능을 결정합니다. Bedrock 또는 Vertex에서 Anthropic Messages 형식을 사용하는 경우, 환경 변수 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정해야 할 수 있습니다.

구성

모델 선택

기본적으로 Claude Code는 선택된 API 형식에 대한 표준 모델 이름을 사용합니다.

게이트웨이에서 사용자 정의 모델 이름을 구성한 경우, 모델 구성에 문서화된 환경 변수를 사용하여 사용자 정의 이름과 일치시키세요.

LiteLLM 구성

참고: LiteLLM은 서드파티 프록시 서비스입니다. Anthropic은 LiteLLM의 보안이나 기능을 보증, 유지보수 또는 감사하지 않습니다. 이 가이드는 정보 제공 목적으로 제공되며 오래될 수 있습니다. 재량에 따라 사용하세요.

사전 요구사항

Claude Code가 최신 버전으로 업데이트되어 있어야 합니다
LiteLLM Proxy Server가 배포되고 접근 가능해야 합니다
선택한 프로바이더를 통해 Claude 모델에 접근할 수 있어야 합니다

기본 LiteLLM 설정

Claude Code 구성:

인증 방법

정적 API 키

고정 API 키를 사용하는 가장 간단한 방법:

# Set in environment
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# Or in Claude Code settings
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

이 값은 Authorization 헤더로 전송됩니다.

헬퍼를 사용한 동적 API 키

키 순환 또는 사용자별 인증의 경우:

API 키 헬퍼 스크립트를 생성합니다:

#!/bin/bash
# ~/bin/get-litellm-key.sh

# Example: Fetch key from vault
vault kv get -field=api_key secret/litellm/claude-code

# Example: Generate JWT token
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'

헬퍼를 사용하도록 Claude Code 설정을 구성합니다:

{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}

토큰 갱신 간격을 설정합니다:

# Refresh every hour (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

이 값은 Authorization 및 X-Api-Key 헤더로 전송됩니다. apiKeyHelper는 ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY보다 우선순위가 낮습니다.

통합 엔드포인트 (권장)

LiteLLM의 Anthropic 형식 엔드포인트를 사용합니다:

export ANTHROPIC_BASE_URL=https://litellm-server:4000

패스스루 엔드포인트 대비 통합 엔드포인트의 장점:

로드 밸런싱
폴백
비용 추적 및 최종 사용자 추적에 대한 일관된 지원

프로바이더별 패스스루 엔드포인트 (대안)

LiteLLM을 통한 Claude API

패스스루 엔드포인트를 사용합니다:

export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic

LiteLLM을 통한 Amazon Bedrock

패스스루 엔드포인트를 사용합니다:

export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

LiteLLM을 통한 Google Vertex AI

패스스루 엔드포인트를 사용합니다:

export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

더 자세한 정보는 LiteLLM 문서를 참조하세요.

추가 리소스

LLM 게이트웨이 구성

Claude Code를 LLM 게이트웨이 솔루션과 함께 사용하도록 구성하는 방법을 알아봅니다. 게이트웨이 요구사항, 인증 구성, 모델 선택, 프로바이더별 엔드포인트 설정을 다룹니다.

LLM 게이트웨이는 Claude Code와 모델 프로바이더 사이에 중앙 집중식 프록시 레이어를 제공하며, 주로 다음과 같은 기능을 지원합니다:

중앙 집중식 인증 - API 키 관리를 위한 단일 지점
사용량 추적 - 팀 및 프로젝트 전반의 사용량 모니터링
비용 제어 - 예산 및 속도 제한 구현
감사 로깅 - 규정 준수를 위한 모든 모델 상호작용 추적
모델 라우팅 - 코드 변경 없이 프로바이더 간 전환

게이트웨이 요구사항

LLM 게이트웨이가 Claude Code와 작동하려면 다음 요구사항을 충족해야 합니다:

API 형식

게이트웨이는 클라이언트에 다음 API 형식 중 하나 이상을 노출해야 합니다:

Anthropic Messages: /v1/messages, /v1/messages/count_tokens
- 요청 헤더를 전달해야 합니다: anthropic-beta, anthropic-version
Bedrock InvokeModel: /invoke, /invoke-with-response-stream
- 요청 본문 필드를 보존해야 합니다: anthropic_beta, anthropic_version
Vertex rawPredict: :rawPredict, :streamRawPredict, /count-tokens:rawPredict
- 요청 헤더를 전달해야 합니다: anthropic-beta, anthropic-version

헤더 전달 또는 본문 필드 보존에 실패하면 기능 제한이나 Claude Code 기능 사용 불가가 발생할 수 있습니다.

참고: Claude Code는 API 형식에 따라 활성화할 기능을 결정합니다. Bedrock 또는 Vertex에서 Anthropic Messages 형식을 사용하는 경우, 환경 변수 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정해야 할 수 있습니다.

구성

모델 선택

기본적으로 Claude Code는 선택된 API 형식에 대한 표준 모델 이름을 사용합니다.

게이트웨이에서 사용자 정의 모델 이름을 구성한 경우, 모델 구성에 문서화된 환경 변수를 사용하여 사용자 정의 이름과 일치시키세요.

LiteLLM 구성

참고: LiteLLM은 서드파티 프록시 서비스입니다. Anthropic은 LiteLLM의 보안이나 기능을 보증, 유지보수 또는 감사하지 않습니다. 이 가이드는 정보 제공 목적으로 제공되며 오래될 수 있습니다. 재량에 따라 사용하세요.

사전 요구사항

Claude Code가 최신 버전으로 업데이트되어 있어야 합니다
LiteLLM Proxy Server가 배포되고 접근 가능해야 합니다
선택한 프로바이더를 통해 Claude 모델에 접근할 수 있어야 합니다

기본 LiteLLM 설정

Claude Code 구성:

인증 방법

정적 API 키

고정 API 키를 사용하는 가장 간단한 방법:

# Set in environment
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# Or in Claude Code settings
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

이 값은 Authorization 헤더로 전송됩니다.

헬퍼를 사용한 동적 API 키

키 순환 또는 사용자별 인증의 경우:

API 키 헬퍼 스크립트를 생성합니다:

#!/bin/bash
# ~/bin/get-litellm-key.sh

# Example: Fetch key from vault
vault kv get -field=api_key secret/litellm/claude-code

# Example: Generate JWT token
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'

헬퍼를 사용하도록 Claude Code 설정을 구성합니다:

{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}

토큰 갱신 간격을 설정합니다:

# Refresh every hour (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

이 값은 Authorization 및 X-Api-Key 헤더로 전송됩니다. apiKeyHelper는 ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY보다 우선순위가 낮습니다.

통합 엔드포인트 (권장)

LiteLLM의 Anthropic 형식 엔드포인트를 사용합니다:

export ANTHROPIC_BASE_URL=https://litellm-server:4000

패스스루 엔드포인트 대비 통합 엔드포인트의 장점:

로드 밸런싱
폴백
비용 추적 및 최종 사용자 추적에 대한 일관된 지원

프로바이더별 패스스루 엔드포인트 (대안)

LiteLLM을 통한 Claude API

패스스루 엔드포인트를 사용합니다:

export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic

LiteLLM을 통한 Amazon Bedrock

패스스루 엔드포인트를 사용합니다:

export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

LiteLLM을 통한 Google Vertex AI

패스스루 엔드포인트를 사용합니다:

export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

더 자세한 정보는 LiteLLM 문서를 참조하세요.

35. LLM 게이트웨이 구성

LLM 게이트웨이 구성

게이트웨이 요구사항

API 형식

구성

모델 선택

LiteLLM 구성

사전 요구사항

기본 LiteLLM 설정

인증 방법

정적 API 키

헬퍼를 사용한 동적 API 키

통합 엔드포인트 (권장)

프로바이더별 패스스루 엔드포인트 (대안)

LiteLLM을 통한 Claude API

LiteLLM을 통한 Amazon Bedrock

LiteLLM을 통한 Google Vertex AI

추가 리소스

35. LLM 게이트웨이 구성

LLM 게이트웨이 구성

게이트웨이 요구사항

API 형식

구성

모델 선택

LiteLLM 구성

사전 요구사항

기본 LiteLLM 설정

인증 방법

정적 API 키

헬퍼를 사용한 동적 API 키

통합 엔드포인트 (권장)

프로바이더별 패스스루 엔드포인트 (대안)

LiteLLM을 통한 Claude API

LiteLLM을 통한 Amazon Bedrock

LiteLLM을 통한 Google Vertex AI

추가 리소스