ChatGPT 문서
한국어
문의 goolvyouyou@gmail.com

LiteLLM을 통해 Bedrock 사용하기

조직에서 LiteLLM을 통해 Codex를 Amazon Bedrock으로 라우팅하는 경우 이 페이지를 사용하세요. LiteLLM 게이트웨이가 이미 있다면 먼저 Codex를 연결하세요. LiteLLM은 조직에 새 게이트웨이가 필요한 경우에만 배포하세요.

다른 게이트웨이 제품에도 동일한 게이트웨이 요구 사항과 Codex 연결 절차가 적용됩니다.

기존 게이트웨이에 연결하기

게이트웨이 관리자에게 다음 값을 받으세요.

  • https://gateway.example.com/v1과 같은 HTTPS 기본 URL.
  • LiteLLM이 승인된 Bedrock 모델로 라우팅하는 모델 별칭.
  • Codex 구성에 사용할 공급자 ID.
  • 권한 범위가 제한된 게이트웨이 자격 증명 또는 이를 반환하는 인증 헬퍼.
  • 조직의 구성과 함께 배포되는 모델 카탈로그.

그런 다음 다음 순서로 연결을 완료하세요.

  1. 게이트웨이 팀에 게이트웨이가 POST /v1/responses를 제공하고, 응답을 스트리밍하며, 후속 턴과 도구 호출을 유지하고, 승인된 별칭을 라우팅하는지 확인해 달라고 요청합니다. 게이트웨이 호환성을 참조하세요.
  2. 게이트웨이에 연결하기에 따라 공급자, 모델, 자격 증명을 구성합니다.
  3. 활성 공급자와 별칭을 검증하고, 연결 가이드의 짧은 gateway-ok 프롬프트를 전송한 다음, LiteLLM 기록에 예상한 사용자와 별칭이 표시되는지 확인합니다.
  4. 조직 전체에 배포하려면 게이트웨이를 통해 Codex 배포하기로 이어서 진행합니다.

게이트웨이 자격 증명은 LiteLLM에 사용자를 인증합니다. 게이트웨이가 자체 Bedrock 자격 증명을 관리하므로 해당 자격 증명을 워크스테이션에 복사할 필요가 없습니다.

게이트웨이 준비하기

Codex를 연결하기 전에 LiteLLM 게이트웨이를 만들어야 하는 경우에만 이 섹션을 사용하세요.

배포 전 준비 사항

다음이 준비되어 있는지 확인하세요.

  • AWS 환경에 승인된 LiteLLM 아키텍처를 배포할 권한.
  • 라우팅할 모델 또는 추론 프로필에 대한 Bedrock 접근 권한.
  • 검토를 마친 LiteLLM 이미지와 배포 패턴.
  • 신뢰할 수 있는 HTTPS 호스트 이름과 인증서.
  • 제한된 클라이언트 네트워크 범위.

아래 Runtime 예제에서는 게이트웨이의 AWS ID에 선택한 추론 프로필과 계정의 기본 프로젝트에 대한 bedrock:InvokeModel 권한이 필요합니다. 필요한 권한은 AWS의 GPT-6 Sol 설정 지침을 참조하세요.

아키텍처

이 배포에서는 Codex와 Bedrock 사이에 LiteLLM을 두고 클라이언트 경계에서 HTTPS를 사용합니다. 로드 밸런서와 LiteLLM은 조직의 게이트웨이 경계 안에 있으며, 공급자 자격 증명은 게이트웨이에 보관됩니다.

Codex는 권한 범위가 제한된 게이트웨이 자격 증명으로 HTTPS 로드 밸런서를 통해 LiteLLM에 Responses API 요청을 보냅니다. LiteLLM은 승인된 별칭을 Amazon Bedrock으로 라우팅하며 공급자 자격 증명은 서버 측에 유지됩니다.

인바운드 접근을 승인된 클라이언트로 제한하고, 데이터베이스와 캐시 포트를 비공개로 유지하며, 게이트웨이에는 필요한 Bedrock 권한만 부여하세요. 다시 시작할 때 구현이 알림 없이 변경되지 않도록 배포 이미지를 다이제스트로 고정하세요.

프롬프트, 소스 발췌문, 도구 결과는 게이트웨이를 통과하며 로그에 기록될 수 있습니다. 요청 로깅을 활성화하기 전에 보존, 접근, 민감 정보 마스킹 정책을 결정하세요. MCP server와 플러그인은 별도의 연결과 인증을 사용하므로 이 게이트웨이 구성으로 설정되지 않습니다.

배포 점검 단계

개발자에게 게이트웨이를 제공하기 전에 다음 점검 단계를 순서대로 완료하세요.

점검 단계 결과
비공개 데이터베이스 및 캐시 의존성과 함께 프록시를 배포합니다. /v1로 끝나는 안정적인 HTTPS 기본 URL과 게이트웨이가 관리하는 Bedrock 인증.
모델 경로와 이에 맞는 클라이언트 카탈로그를 구성합니다. 의도한 Bedrock 대상에 매핑된 안정적인 Codex용 별칭.
Responses 지원을 검증합니다. POST /v1/responses 응답이 스트리밍되고 response.completed로 종료됩니다.
테스트 자격 증명을 발급합니다. 해당 별칭으로 제한되고 만료 시점, 예산, 요청 속도 제한이 설정된 사용자별 가상 키.
개발자 한 명을 연결합니다. Codex 공급자 구성과 게이트웨이를 통해 검증된 짧은 프롬프트.

아래 섹션에서는 각 점검 단계를 설명합니다. 프로덕션 도입을 위해서는 후속 턴, 도구, 자격 증명 취소도 테스트하세요.

Bedrock 경로 선택하기

LiteLLM 업스트림 경로는 Bedrock 엔드포인트, 모델 식별자, 인증 방식을 결정합니다. 게이트웨이를 배포하거나 변경할 때 이 선택 사항들을 함께 관리하세요.

새 구성에는 Bedrock Runtime을 사용하세요. 아래 예제는 OpenAI 호환 Responses 엔드포인트를 사용합니다.

대체 경로는 LiteLLM의 Bedrock Mantle 통합을 참조하세요.

AWS 배포 예제로는 버전이 고정된 ECS의 LiteLLM 참조 구현을 사용하세요. 이 구현은 Bedrock Runtime을 사용하며 ECS 작업 역할에서 인증 정보를 갱신합니다. 배포 단계와 인증 단계를 함께 따르고, 프로덕션 요구 사항이 조직의 네트워킹, TLS, 로깅, 리소스 보존 정책에 맞는지 검토하세요.

어떤 경로를 선택하든 배포된 게이트웨이 버전, 업스트림 엔드포인트, 모델의 조합을 게이트웨이 호환성에 따라 검증하세요. 업스트림 모델이 게이트웨이의 모델 목록에 표시된다고 해서 스트리밍, 대화 이어가기, 도구 동작이 Codex에서 작동한다는 증거는 아닙니다.

Runtime 모델 경로 구성하기

안정적인 Codex용 별칭을 승인된 업스트림 모델에 매핑하세요. 이 Runtime 예제를 사용하기 전에 AWS 계정과 리전에서 접근 권한을 확인하세요.

model_list:
  - model_name: company-coding-model
    litellm_params:
      model: openai/global.openai.gpt-6-sol
      api_key: os.environ/AWS_BEARER_TOKEN_BEDROCK
      api_base: https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1

비밀 정보 관리 시스템을 통해 유효한 Bedrock API key를 AWS_BEARER_TOKEN_BEDROCK로 제공하세요. 단기 키라면 만료되기 전에 대체 키를 발급하고, 게이트웨이 프로세스 환경을 업데이트한 다음, 해당 키를 사용하는 워커를 다시 시작하거나 재배포하세요. ECS 참조 구현은 대신 작업 역할에서 프로세스 내부의 자격 증명을 갱신합니다. 해당 구성과 진입점을 함께 사용하세요.

openai/ 접두사는 LiteLLM의 OpenAI 호환 어댑터를 선택하며, 구성된 api_base는 Bedrock Runtime으로 요청을 보냅니다. Global 추론 프로필은 요청을 출발 리전 외부로 라우팅할 수 있습니다. AWS 권한 및 데이터 상주 요구 사항을 충족하는 프로필과 리전을 선택하고 필요에 따라 두 값을 모두 바꾸세요.

클라이언트는 company-coding-model를 전송하고 LiteLLM은 구성된 업스트림 경로를 사용합니다. 이 사용자 지정 별칭에는 다음에 설명하는 일치하는 클라이언트 카탈로그가 필요합니다. 일반 게이트웨이는 기본 제공 Bedrock 공급자의 메타데이터 조정을 상속하지 않습니다.

클라이언트 카탈로그 준비하기

Codex 0.158.0을 사용하는 이 GPT-6 Sol/Runtime 예제에서는 해당 버전의 모델 카탈로그에 있는 완전한 gpt-6-sol 항목을 시작점으로 삼으세요. 해당 항목에 다음 수정 사항을 모두 적용하세요.

필드 필수 수정 사항
slug LiteLLM 별칭과 일치하도록 "company-coding-model"로 설정합니다.
visibility "list"로 설정합니다.
availability_nux null로 설정합니다.
upgrade null로 설정합니다.
use_responses_lite false로 설정합니다.
tool_mode null로 설정합니다.
supported_reasoning_levels effort가 "ultra"인 항목을 제거하고 나머지 항목은 유지합니다.
additional_speed_tiers []로 설정합니다.
service_tiers []로 설정합니다.
default_service_tier null로 설정합니다.
web_search_tool_type "text"로 설정합니다.
multi_agent_version "v1"로 설정합니다.
supports_search_tool Runtime에서는 false로 설정합니다.

모델의 지침과 컨텍스트 한도를 포함한 나머지 필드는 유지하세요. 편집한 항목은 카탈로그의 최상위 models 배열에 유지하세요. 이러한 변경 사항은 출시된 Bedrock 메타데이터 조정과 Runtime 검색 제한을 반영합니다. 클라이언트 버전이나 업스트림 모델을 변경할 때는 해당 소스와 대조해 다시 확인하세요.

게이트웨이를 통해 Codex 배포하기에 따라 전체 JSON 파일을 배포하고 model_catalog_json를 구성하세요. Runtime 클라이언트 구성에서 web_search = "disabled"를 유지하세요. 더 많은 사용자에게 배포하기 전에 게이트웨이를 통해 편집한 카탈로그를 검증하세요.

Responses 지원 검증하기

클라이언트용 HTTPS 엔드포인트에서 POST /v1/responses를 제공하세요. 로드 밸런서와 모든 리버스 프록시가 버퍼링 없이 스트리밍 이벤트를 전달하도록 구성하세요. 후속 턴과 함수 호출 결과를 유지하세요. Chat Completions 엔드포인트가 작동하는 것만으로는 이 연결에 충분하지 않습니다.

클라이언트 구성을 배포하기 전에 게이트웨이 호환성의 점검을 완료하세요. 사용자가 사용할 것과 동일한 호스트 이름, 네트워크 제어, 인증 경로를 통해 테스트하세요.

테스트 자격 증명 발급하기

테스트 사용자 한 명을 위해 권한 범위가 제한된 LiteLLM 가상 키를 만드세요. 승인된 별칭으로 제한하고 만료 시점, 요청 속도 제한, 예산을 구성하세요. 적용 가능한 제어는 LiteLLM의 가상 키 문서를 참조하세요.

비밀 정보 관리 절차 또는 인증 헬퍼를 통해 키를 배포하세요. 사용자에게 LiteLLM 관리자 키를 제공하거나 config.toml에 게이트웨이 자격 증명을 포함하지 마세요.

사용자 연결 검증하기

접근 범위를 확대하기 전에 다음 점검을 완료하세요.

  1. HTTPS 인증서가 게이트웨이 호스트 이름과 일치하고 서비스가 정상인지 확인합니다.
  2. 게이트웨이에 연결하기를 통해 사용자 한 명을 연결합니다.
  3. 짧은 프롬프트, 후속 턴, 읽기 전용 도구 작업을 실행합니다.
  4. 게이트웨이 기록에 자격 증명이나 민감한 프롬프트 내용이 노출되지 않으면서 예상한 ID, 별칭, 업스트림 경로가 표시되는지 확인합니다.
  5. 자격 증명 만료 또는 취소를 테스트하고 승인되지 않은 모델 별칭이 거부되는지 확인합니다.

배포된 이미지 버전, 경로 구성, 테스트 결과를 도입 기록과 함께 보관하세요. 팀 배포 및 지속적인 운영은 게이트웨이를 통해 Codex 배포하기로 이어서 진행하세요.

연결 문제 해결하기

실패한 계층을 기준으로 문제의 범위를 좁히세요.

증상 확인할 사항
추론 전에 HTTPS가 실패합니다 DNS, 인증서 호스트 이름, 로드 밸런서 상태, 허용된 클라이언트 네트워크를 확인하세요.
게이트웨이가 401 또는 403를 반환합니다 게이트웨이 로그를 사용해 사용자 자격 증명 거부와 업스트림 Bedrock 인증 또는 권한 실패를 구분하세요.
요청한 모델을 찾을 수 없습니다 정확한 클라이언트용 별칭과 해당 업스트림 모델 또는 추론 프로필 매핑을 확인하세요.
LiteLLM에 도달하기 전에 요청이 차단됩니다 요청 본문 크기 제한을 포함해 로드 밸런서와 웹 애플리케이션 방화벽 로그를 확인하세요. 대표적인 Codex 요청을 테스트하는 동안 보안 제어를 유지하세요.
텍스트는 작동하지만 턴이 끝나지 않습니다 스트리밍 버퍼, 시간 초과, 종료 이벤트를 확인하고 게이트웨이 호환성의 후속 대화 및 도구 호출 점검을 수행하세요.
업스트림 요청 시간이 초과됩니다 시간 제한을 변경하기 전에 출발 리전의 모델 가용성, 라우팅 구성, 할당량, 게이트웨이 로그를 확인하세요.

문제를 해결한 후 동일한 사용자 경로를 다시 테스트하세요. 게이트웨이 상태 확인이 성공해도 인증된 추론 요청이나 완전한 Codex 턴이 검증되는 것은 아닙니다.