패스 스루 엔드포인트 만들기

패스 스루 엔드포인트 만들기 (Create Pass Through Endpoints)

LiteLLM 프록시에서 어떤 외부 API로든 요청을 라우팅할 수 있어요. 커스텀 모델, 이미지 생성 API, 또는 LiteLLM을 통해 프록시하고 싶은 어떤 서비스에도 완벽해요.

주요 장점:

• Bria API, Mistral OCR 같은 서드파티 엔드포인트 온보딩
• 요청별 커스텀 가격을 설정하거나, 여러 모델로 확장되는 대상을 자체 비용과 사용량을 보고하게 할 수 있음
• 프록시 관리자는 Bria, Mistral OCR 같은 업스트림 LLM 공급자에 개발자에게 api 키를 줄 필요가 없음
• 중앙화된 인증, 지출 추적, 예산 관리 유지

출처: 문서

본문

LiteLLM 프록시에서 어떤 외부 API로든 요청을 라우팅해요. 커스텀 모델, 이미지 생성 API, 또는 LiteLLM을 통해 프록시하고 싶은 어떤 서비스에도 완벽해요.

주요 장점:

• Bria API, Mistral OCR 같은 서드파티 엔드포인트 온보딩
• 요청별 커스텀 가격을 설정하거나, 여러 모델로 확장되는 대상을 자체 비용과 사용량을 보고하게 함
• 프록시 관리자는 Bria, Mistral OCR 같은 업스트림 LLM 공급자에 개발자에게 api 키를 줄 필요가 없음
• 중앙화된 인증, 지출 추적, 예산 관리 유지

UI로 빠른 시작 (추천)

패스 스루 엔드포인트를 만드는 가장 쉬운 방법은 LiteLLM UI를 통해서예요. 이 예제에서는 Bria API를 온보딩하고 요청당 비용을 설정할 거예요.

1단계: 라우트 매핑 만들기

패스 스루 엔드포인트를 만들려면:

1. LiteLLM Proxy UI로 이동해요
2. Models + Endpoints 탭으로 가요
3. Pass Through Endpoints를 클릭해요
4. "Add Pass Through Endpoint"를 클릭해요
5. 다음 세부 정보를 입력해요:

필수 필드:

• Path Prefix: 클라이언트가 LiteLLM Proxy를 호출할 때 쓰는 라우트 (예: /bria, /mistral-ocr)
• Target URL: 요청이 전달될 URL

라우트 매핑 예시:

위 구성은 다음 라우트 매핑을 만들어요:

LiteLLM Proxy 라우트	Target URL
/bria	https://engine.prod.bria-api.com
/bria/v1/text-to-image/base/model	https://engine.prod.bria-api.com/v1/text-to-image/base/model
/bria/v1/enhance_image	https://engine.prod.bria-api.com/v1/enhance_image
/bria/<any-sub-path>	https://engine.prod.bria-api.com/<any-sub-path>

info

모든 라우트는 LiteLLM 프록시 베이스 URL이 앞에 붙어요: https://<litellm-proxy-base-url>

2단계: 헤더와 가격 구성하기

필요한 인증과 가격을 구성해요:

인증 설정:

• Bria API는 api_token 헤더가 필요해요
• Bria API 키를 api_token 헤더의 값으로 입력해요

기본 쿼리 파라미터 (선택):

• 모든 요청에 자동으로 보내질 쿼리 파라미터를 추가해요
• API 버전 관리, 형식 지정, 기본 구성에 완벽해요
• 클라이언트가 자신의 값으로 이 파라미터를 덮어쓸 수 있어요
• 예: version=v1, format=json, timeout=30

가격 구성:

• 요청당 비용을 설정해요 (이 예제에선 $12.00)
• 이렇게 하면 사용자에 대한 비용 추적과 청구가 가능해져요
• 요청당 고정 비용은 가격이 변하지 않는 대상에 적합해요. 대상이 내부적으로 여러 모델을 호출하고 자체 총액을 안다면 대신 그 값을 보고하게 하세요. Pass-Through Cost & Usage Tracking 참고

3단계: 엔드포인트 저장하기

구성을 완료한 뒤:

1. 설정을 검토해요
2. "Add Pass Through Endpoint"를 클릭해요
3. 엔드포인트가 생성되고 즉시 사용 가능해져요

4단계: 엔드포인트 테스트하기

LiteLLM Proxy를 통해 Bria API에 테스트 요청을 보내 설정을 검증해요:

    curl -i -X POST \
      'http://localhost:4000/bria/v1/text-to-image/base/2.3' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <your-...key>' \
      -d '{
        "prompt": "a book",
        "num_results": 2,
        "sync": true
      }'

기대 응답: 모든 것이 올바르게 설정됐다면 생성된 이미지 데이터를 포함한 Bria API의 응답을 받을 수 있어요.

---

Config.yaml 설정

config.yaml 파일로도 패스 스루 엔드포인트를 만들 수 있어요. Cohere의 API로 전달하는 /v1/rerank 라우트를 추가하는 방법이에요:

예시 구성

    general_settings:
      master_key: os.environ/LITELLM_MASTER_KEY
      pass_through_endpoints:
        - path: "/v1/rerank"                                  # Route on LiteLLM Proxy
          target: "https://api.cohere.com/v1/rerank"          # Target endpoint
          headers:                                            # Headers to forward
            Authorization: "bearer os.environ/COHERE_API_KEY"
            content-type: application/json
            accept: application/json
          forward_headers: true                               # Forward all incoming headers
          default_query_params:                               # Optional: Default query parameters
            version: "v1"                                     # Always send version=v1
            format: "json"                                    # Default format (can be overridden)

시작하고 테스트하기

1. 프록시 시작:

litellm --config config.yaml --detailed_debug

2. 테스트 요청 보내기:

curl --request POST \
          --url http://localhost:4000/v1/rerank \
          --header 'accept: application/json' \
          --header 'content-type: application/json' \
          --data '{
            "model": "rerank-english-v3.0",
            "query": "What is the capital of the United States?",
            "top_n": 3,
            "documents": ["Carson City is the capital city of the American state of Nevada."]
          }'

기대 응답

    {
      "id": "37103a5b-8cfb-48d3-87c7-da288bedd429",
      "results": [
        {
          "index": 2,
          "relevance_score": 0.999071
        }
      ],
      "meta": {
        "api_version": {"version": "1"},
        "billed_units": {"search_units": 1}
      }
    }

---

구성 레퍼런스 (Configuration Reference)

전체 스펙

    general_settings:
      pass_through_request_timeout: 600   # Optional: upstream timeout (seconds) for all pass-through routes. Default: 600
      pass_through_endpoints:
        - path: string                    # Route on LiteLLM Proxy Server
          target: string                  # Target URL for forwarding
          auth: boolean                   # Enable LiteLLM authentication (Enterprise)
          forward_headers: boolean        # Forward all incoming headers
          include_subpath: boolean        # If true, forwards requests to sub-paths (default: false)
          timeout: float                  # Optional: per-endpoint upstream timeout (seconds). Overrides pass_through_request_timeout
          methods: list[string]           # Optional: HTTP methods (e.g., ["GET", "POST"]). If not specified, all methods are supported.
          default_query_params:           # Optional: Default query parameters sent with every request
            <param-name>: string          # Key-value pairs (e.g., version: "v1", format: "json")
          headers:                        # Custom headers to add
            Authorization: string         *** Auth header for target API
            content-type: string         # Request content type
            accept: string               # Expected response format
            LANGFUSE_PUBLIC_KEY: string  # For Langfuse endpoints
            LANGFUSE_SECRET_KEY: string  # For Langfuse endpoints
            <custom-header>: string      # Any custom header

요청 타임아웃

패스 스루 라우트는 기본적으로 600초 업스트림 타임아웃을 사용해요. general_settings.pass_through_request_timeout으로 전역 오버라이드하거나, 커스텀 엔드포인트의 timeout으로 설정할 수 있어요(엔드포인트별 값이 우선). 커스텀 패스 스루 엔드포인트와 네이티브 provider 패스스루 라우트(예: Bedrock /converse)에 적용돼요.

헤더 옵션

• Authorization : 대상 API 인증
• content-type : 요청 본문 형식 지정
• accept : 기대 응답 형식
• LANGFUSE_PUBLIC_KEY/SECRET_KEY : Langfuse 통합용
• 커스텀 헤더 : 추가 키-값 쌍

기본 쿼리 파라미터

• 파라미터 우선순위 : 클라이언트 파라미터 > URL 파라미터 > 기본 파라미터
• 사용 사례 : API 버전 관리, 인증 토큰, 형식 제어, 기능 플래그
• 오버라이드 가능 : 클라이언트가 기본 파라미터를 덮어쓸 수 있음
• 예시 : version: "v1", format: "json", timeout: "30"

서브 경로 라우팅

기본적으로 패스 스루 엔드포인트는 지정된 정확한 경로만 일치해요. 서브 경로로 요청을 전달하려면 include_subpath: true를 설정하세요:

    general_settings:
      pass_through_endpoints:
        - path: "/custom-api"                    # Any path prefix you choose
          target: "https://api.example.com"
          include_subpath: true  # Forward /custom-api/*, not just /custom-api

설정	동작
include_subpath: false (기본)	/custom-api만 전달
include_subpath: true	/custom-api, /custom-api/v1/chat, /custom-api/anything 모두 전달

---

기본 쿼리 파라미터

패스 스루 엔드포인트는 모든 요청에 자동으로 추가되는 기본 쿼리 파라미터를 지원해요. API 버전 관리, 형식 지정, 인증 토큰 또는 어떤 기본 구성에도 유용해요.

동작 방식

파라미터 우선순위 (높은 것부터 낮은 것):

1. 클라이언트 제공 파라미터 (요청 URL에 있는 것)
2. URL 파라미터 (대상 URL에서 온 것)
3. 기본 파라미터 (구성에서 온 것)

예시 구성

    general_settings:
      pass_through_endpoints:
        - path: "/api/v1"
          target: "https://external-api.com/service?timeout=60"  # URL has timeout=60
          default_query_params:
            version: "v1"          # Always add version=v1
            format: "json"         # Default format=json (can be overridden)
            auth_level: "basic"    # Always add auth_level=basic

요청 예시

클라이언트 요청: GET /api/v1/users 실제 백엔드 호출: https://external-api.com/service?version=v1&format=json&auth_level=basic&timeout=60

클라이언트 요청: GET /api/v1/users?format=xml&custom=value 실제 백엔드 호출: https://external-api.com/service?version=v1&auth_level=basic&timeout=60&format=xml&custom=value

• 클라이언트의 format=xml이 기본 format=json을 덮어씀
• 기본 version=v1과 auth_level=basic은 유지됨
• URL의 timeout=60은 유지됨
• 클라이언트의 custom=value가 추가됨

사용 사례

• API 버전 관리 : 호환성 유지를 위해 항상 version=v2 전송
• 인증 : api_key=default_key 같은 인증 토큰 추가
• 형식 제어 : 기본 format=json이지만 클라이언트 오버라이드 허용
• 레이트 리밋 : 기본으로 rate_limit=standard 설정
• 기능 플래그 : 기본으로 experimental=false 활성화

---

같은 경로에 다른 HTTP 메서드를 사용해 서로 다른 대상 URL을 구성할 수 있어요. 서로 다른 백엔드가 서로 다른 작업을 처리할 때 유용해요:

    general_settings:
      pass_through_endpoints:
        # GET requests to /azure/kb go to read API
        - path: "/azure/kb"
          target: "https://read-api.example.com/knowledge-base"
          methods: ["GET"]
          headers:
            Authorization: "bearer os.environ/READ_API_KEY"

        # POST requests to /azure/kb go to write API
        - path: "/azure/kb"
          target: "https://write-api.example.com/knowledge-base"
          methods: ["POST"]
          headers:
            Authorization: "bearer os.environ/WRITE_API_KEY"

        # PUT requests to /azure/kb go to update API
        - path: "/azure/kb"
          target: "https://update-api.example.com/knowledge-base"
          methods: ["PUT"]
          headers:
            Authorization: "bearer os.environ/UPDATE_API_KEY"

핵심 포인트:

• methods를 지정하지 않으면 엔드포인트는 모든 HTTP 메서드(GET, POST, PUT, DELETE, PATCH)를 지원해요
• 메서드가 다르면 여러 엔드포인트가 같은 경로를 공유할 수 있어요
• 단일 엔드포인트에 여러 메서드를 지정할 수 있어요: methods: ["GET", "POST"]
• 이렇게 하면 작업 유형에 따라 다른 백엔드로 라우팅할 수 있어요

---

고급: 커스텀 어댑터 (Custom Adapters)

복잡한 통합(Anthropic/Bedrock 클라이언트 같은)을 위해 서로 다른 API 스키마를 변환하는 커스텀 어댑터를 만들 수 있어요.

1. 어댑터 만들기

    from litellm import adapter_completion
    from litellm.integrations.custom_logger import CustomLogger
    from litellm.types.llms.anthropic import AnthropicMessagesRequest, AnthropicResponse

    class AnthropicAdapter(CustomLogger):
        def translate_completion_input_params(self, kwargs):
            """Translate Anthropic format to OpenAI format"""
            request_body = AnthropicMessagesRequest(**kwargs)
            return litellm.AnthropicConfig().translate_anthropic_to_openai(
                anthropic_message_request=request_body
            )

        def translate_completion_output_params(self, response):
            """Translate OpenAI response back to Anthropic format"""
            return litellm.AnthropicConfig().translate_openai_response_to_anthropic(
                response=response
            )

    anthropic_adapter = AnthropicAdapter()

2. 엔드포인트 구성하기

    model_list:
      - model_name: my-claude-endpoint
        litellm_params:
          model: gpt-5.6-luna
          api_key: os.environ/OPENAI_API_KEY

    general_settings:
      master_key: os.environ/LITELLM_MASTER_KEY
      pass_through_endpoints:
        - path: "/v1/messages"
          target: custom_callbacks.anthropic_adapter
          headers:
            litellm_user_api_key: "x-api-key"

3. 커스텀 엔드포인트 테스트하기

    curl --location 'http://0.0.0.0:4000/v1/messages' \
      -H "x-api-key: *** \
      -H 'anthropic-version: 2023-06-01' \
      -H 'content-type: application/json' \
      -d '{
        "model": "my-claude-endpoint",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello, world"}]
      }'

---

튜토리얼 - Azure OpenAI Assistants API를 패스 스루 엔드포인트로 추가하기

이 영상에서는 Azure OpenAI Assistants API를 LiteLLM Proxy에 패스 스루 엔드포인트로 추가해요.

---

문제 해결 (Troubleshooting)

일반적인 문제

인증 오류:

• 헤더에 API 키가 올바르게 설정됐는지 확인해요
• 대상 API가 제공된 인증 방식을 수락하는지 확인해요

라우팅 문제:

• 경로 접두사가 요청 URL과 일치하는지 확인해요
• 대상 URL에 접근할 수 있는지 확인해요
• 구성에서 후행 슬래시를 확인해요

응답 오류:

• --detailed_debug로 상세 디버깅을 켜요
• 오류 세부 정보를 위해 LiteLLM 프록시 로그를 확인해요
• 대상 API가 기대하는 요청 형식을 확인해요

팀 JWT가 패스 스루 라우트를 사용하도록 허용하기

패스 스루 provider 라우트(예: /anthropic/*)를 사용 중이고 JWT 팀 토큰이 이 라우트에 접근하게 하려면 litellm_jwtauth의 team_allowed_routes에 mapped_pass_through_routes를 추가하거나 관련 라우트를 명시적으로 추가하세요.

예시 (proxy_server_config.yaml):

    general_settings:
      enable_jwt_auth: True
      litellm_jwtauth:
        team_ids_jwt_field: "team_ids"
        team_allowed_routes: ["openai_routes","info_routes","mapped_pass_through_routes"]

자체 패스 스루 엔드포인트에서는 mapped_pass_through_routes가 LiteLLM이 제공하는 provider 접두사만 커버해요. 엔드포인트가 커스텀 접두사를 공유한다면, 후행 *가 있는 접두사를 한 번 허용하고 이후 그 아래에 등록하는 모든 엔드포인트는 구성 변경 없이 허용돼요.

    general_settings:
      enable_jwt_auth: True
      litellm_jwtauth:
        team_ids_jwt_field: "team_ids"
        team_allowed_routes: ["openai_routes","info_routes","/internal-models/*"]

도움 받기

데모 예약 👋

커뮤니티 Discord 💭

이메일 ✉️ [email protected] / [email protected]

더 알아보기 (Learn more)

• Pass-Through Cost & Usage Tracking: 대상이 자체 비용과 사용량을 보고하는 방법