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

게이트웨이 및 클라우드용 모델 카탈로그 구현

버전별 Codex 기본값을 가져오고, 공급자 재정의를 적용하고, 모델 카탈로그를 제공하세요

이 페이지는 모델 카탈로그를 정의하고 모델 선택기에 사용되는 Codex Models 형식을 구현하는 개발자를 위한 문서입니다. 게이트웨이나 클라우드 서비스 같은 추론 공급자를 구축한다면, 이 사양을 사용하여 Codex 데스크톱 앱과 CLI가 모델을 검색하고 해당 모델의 지침과 기능 설정을 사용할 수 있도록 하세요.

기업을 관리하며 모델 카탈로그를 제어하려면 model_catalog_url 구성 안내를 참조하세요.

이 형식을 지원하려면 인증이 필요한 카탈로그 엔드포인트를 구현하세요. 요청한 Codex 버전에 맞는 업스트림 공급자의 최신 기본값을 가져오고, 재정의를 적용한 다음, 완성된 카탈로그를 반환하세요.

카탈로그 엔드포인트 구현

기본 카탈로그 엔드포인트는 공급자의 base_url 아래에 있는 /models입니다. 예를 들어 base_url = "https://gateway.example.com/v1"인 경우 Codex는 다음과 같이 요청합니다.

GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>

기본 검색은 명령 기반 인증과 ChatGPT 같은 Codex 백엔드 인증을 지원합니다. 명령 기반 인증 없이 API key 인증을 사용하는 사용자 지정 공급자는 원격 검색을 활성화하려면 model_providers.<id>.model_catalog_url을 명시적으로 설정해야 합니다. API key만으로는 기본 경로에서 검색이 시작되지 않습니다.

model_catalog_url을 사용하여 https://gateway.example.com/codex/models 같은 전체 카탈로그 URL을 지정하세요. 기본 /v1/models 엔드포인트를 가리킬 수도 있습니다. Codex는 /models를 덧붙이지 않고 이 URL을 직접 사용합니다. API key를 사용하는 검색에서는 features.api_key_model_discovery를 활성화된 상태로 유지하세요. 이 설정은 기본적으로 켜져 있습니다. 사용자 지정 헤더만으로는 검색이 활성화되지 않습니다.

Codex는 선택한 공급자의 인증 정보와 구성된 헤더를 전송하고, client_version 및 공급자의 query_params를 추가합니다. 해당 자격 증명을 받을 권한이 있는 서비스에서 카탈로그를 호스팅하세요.

호출자를 인증하고, 해당하는 업스트림 기본값을 가져오고, 재정의를 적용한 다음, 완전한 ModelsResponse JSON을 직접 반환하세요. 모든 항목에 고유하고 비어 있지 않은 slug를 지정하세요. model_catalog_url을 명시적으로 지정한 경우 Codex는 리디렉션과 1 MiB보다 큰 응답을 거부합니다. 추론 요청에서도 모델 접근 제어를 계속 적용하세요.

엔드포인트를 사용하는 클라이언트에서 유효한 model_catalog_json 설정을 모두 제거하세요. 로컬 파일이 우선 적용되어 원격 가져오기가 차단됩니다.

클라이언트 스키마에 맞추기

카탈로그 요청의 client_version 쿼리 매개변수를 읽으세요. Codex는 시험판 접미사를 제거한 CLI 버전을 major.minor.patch로 전송합니다. 데스크톱 클라이언트에서는 번들로 제공되는 CLI 버전입니다.

공개 Codex 저장소에서 일치하는 rust-v<version> 태그를 사용하거나, 사용자 지정 빌드의 정확한 소스 커밋을 사용하세요. 다음 링크는 rust-v0.162.1을 사용하므로, 클라이언트와 일치하는 리비전을 선택하세요.

번들 파일은 릴리스 시점의 스냅샷입니다. 카탈로그를 생성하기 전에 최신 기본값을 가져오세요.

최신 업스트림 기본값 가져오기

OpenAI 모델을 제공하는 클라우드 공급자는 OpenAI에서 기본값을 가져옵니다. 게이트웨이는 클라우드 또는 업스트림 공급자의 카탈로그를 읽어 배포된 모델의 설정과 계정 및 리전별 가용성을 유지합니다. 각 단계에서 요청한 Codex 버전을 전달하고, 각 엔드포인트에 별도로 인증하세요.

OpenAI에서 기본값을 직접 가져오려면 동일한 client_version으로 Codex 모델 엔드포인트를 호출하세요. 예를 들어 OpenAI API key를 사용하는 경우는 다음과 같습니다.

curl --fail --silent --show-error \
  'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
  -H "Authorization: Bearer $OPENAI_API_KEY"

ChatGPT 통합에서는 호출자의 ChatGPT 액세스 토큰과, 해당하는 경우 ChatGPT-Account-ID 헤더를 사용하세요. 업스트림 엔드포인트에 대한 권한이 있는 자격 증명을 사용하세요. 게이트웨이 자체의 API key로는 OpenAI에 인증할 수 없습니다.

최상위 models 배열을 포함한 전체 응답을 파싱하세요. 이 엔드포인트는 지침, 추론 기본값, 도구 설정, 컨텍스트 한도, 서비스 등급 등의 Codex 메타데이터를 반환합니다. 공개 /v1/models 엔드포인트는 이 카탈로그를 제공하지 않습니다.

Codex 버전이 변경되지 않았더라도 이 기본값을 새로 고치세요. 요청은 의도한 업스트림 ID의 범위로 제한하고 응답의 캐시 제어를 준수하세요. 카탈로그는 호출자의 접근 권한에 따라 달라질 수 있습니다. 재정의를 별도로 관리하여 최신 기본값에 다시 적용할 수 있도록 하세요.

공급자 재정의 적용

해당 버전의 응답 구조를 유지하면서 필드 값을 변경하세요.

  • 호출자가 사용할 수 있는 모델만 남기도록 필터링하세요. 각 slug를 지원되는 추론 경로에 매핑하고, display_name, description 또는 priority를 조정하세요. 모델 마이그레이션이 없는 별칭의 경우 upgrade를 null로 설정하세요.
  • 추론 옵션, 컨텍스트 한도, 입력 모달리티, 서비스 등급을 모델과 경로가 지원하는 값으로 설정하세요. 기본값은 지원되는 선택지 범위 내에서 유지하세요. 서비스 등급이 없는 경로에서는 service_tiers 및 additional_speed_tiers를 비우고, default_service_tier를 null로 설정하세요.
  • 대체 설정을 테스트한 경우가 아니라면 업스트림 지침과 도구 설정을 유지하세요. 메타데이터는 모델 기능을 추가하거나 추론 접근 권한을 부여하지 않습니다.

LiteLLM을 통해 Bedrock을 사용하는 경우 필수 카탈로그 수정 사항을 적용하세요. 지원되는 각 Codex 버전에서 완성된 카탈로그를 테스트하세요.

공개 Rust 타입 사용

클라이언트 스키마와 동일한 공개 Git 태그 또는 커밋의 크레이트를 사용하세요.

  • codex_protocol::openai_models::{ModelsResponse, ModelInfo}에는 codex-protocol을 사용하세요. serde_json::from_slice::<ModelsResponse>()로 파싱하고, catalog.models를 수정하고, serde_json::to_vec()로 전체 래퍼를 직렬화하세요. 래퍼는 모델 지침의 호환성 필드를 처리합니다.
  • codex-models-manager::bundled_models_response()을 사용하여 해당 리비전에 번들로 제공되는 정적 카탈로그를 ModelsResponse로 로드하세요. 이 기능은 최신 업스트림 기본값을 가져오지 않습니다.