GitLab AI Gateway의 모델 전환 프레임워크는 고객이 다양한 기능에 대해 다른 AI 모델 중에서 선택할 수 있게 합니다.

이 기능은 클라우드 연결 AI Gateway를 사용하는 GitLab.com 및 셀프 매니지드 인스턴스에서 사용 가능합니다.

• GitLab.com에서 이 기능은 네임스페이스 수준에서 사용 가능하여 그룹이 네임스페이스에 대해 다른 모델 중에서 선택할 수 있게 합니다.
  • 네임스페이스가 모델을 "고정"하기로 결정하지 않은 경우 기본 모델이 사용됩니다. 이는 또한 사용자가 에이전틱 채팅과 같은 특정 기능에 대해 직접 모델을 변경할 수 있게 합니다. 이 기능을 "사용자 모델 선택"이라고 합니다.
• 클라우드 연결 AI Gateway를 사용하는 셀프 매니지드 인스턴스에서 이 기능은 인스턴스 수준에서 사용 가능합니다.

이 가이드는 SaaS 및 셀프 매니지드 인스턴스 모두에서 사용자가 선택할 수 있도록 새 모델을 추가하는 방법을 설명합니다.

모델 전환 프레임워크에 모델 추가#

개요#

모델 전환 프레임워크에 새 모델 추가는 두 가지 주요 단계를 포함합니다:

1. 구성 파라미터와 함께 models.yml에 모델 정의
2. unit_primitives.yml에서 관련 기능에 대해 모델을 선택 가능하게 만들기

두 파일 모두 gitlab-ai-gateway 저장소에 있습니다.

사전 요구 사항#

새 모델을 추가하기 전에 다음을 확인하세요:

• Runway에 적절한 인증/자격 증명이 구성되어 있는지 확인합니다(필요한 경우). 가장 일반적인 공급자에 대한 접근은 이미 구성되어 있습니다. 여기에는 OpenAI, Anthropic 및 Vertex AI가 포함됩니다. 그러나 완전히 새로운 공급자의 모델을 추가해야 하는 경우 Runway에 자격 증명을 추가해야 합니다.
• 로컬 GDK 환경에 적절한 인증/자격 증명이 구성되어 있는지 확인합니다(필요한 경우). 예: ANTHROPIC_API_KEY, OPENAI_API_KEY 등.
• 특정 기능의 폴더에 모델 패밀리에 대한 프롬프트 정의가 있는지 확인합니다. 이는 gitlab-ai-gateway 저장소에 있습니다.
• GDK 환경에서 FETCH_MODEL_SELECTION_DATA_FROM_LOCAL=true 환경 변수를 설정합니다. 이렇게 하면 모델 선택 데이터가 로컬 models.yml 및 unit_primitives.yml 파일에서 가져옵니다.

1단계: 모델 정의#

ai_gateway/model_selection/models.yml에 모델 정의를 추가합니다. 각 모델에는 다음 속성이 필요합니다:

모델 정의 예시#

# ai_gateway/model_selection/models.yml
models:
  - name: "OpenAI GPT-5-Mini"
    gitlab_identifier: "gpt_5_mini"
    family:
      - gpt_5
    params:
      model: gpt-5-mini-2025-08-07
      max_tokens: 4_096

일반적인 파라미터#

params 딕셔너리에는 일반적으로 다음이 포함됩니다:

• model: 공급자의 API에서 사용하는 실제 모델 식별자
• max_tokens: 응답의 최대 토큰 수
• temperature: 무작위성 제어(0.0 = 결정론적, 높을수록 더 무작위)
• model_class_provider: 공급자(예: anthropic, litellm, vertex_ai)
• 공급자별 파라미터(예: top_p, top_k, verbosity)

프롬프트 선택#

선택적 family 필드는 이 모델에 사용되는 프롬프트 정의를 결정합니다:

• 프레임워크는 각 패밀리 이름과 일치하는 디렉토리에서 프롬프트를 순서대로 검색합니다
• 일치하는 프롬프트 폴더가 있으면 해당 프롬프트 정의를 사용합니다
• 패밀리가 지정되지 않거나 일치 항목이 없으면 base 프롬프트가 사용됩니다

2단계: 모델 선택 가능하게 만들기#

모델을 정의한 후 ai_gateway/model_selection/unit_primitives.yml에서 해당 기능의 selectable_models 목록에 추가합니다.

구성 예시#

# ai_gateway/model_selection/unit_primitives.yml
configurable_unit_primitives:
  - feature_setting: "duo_agent_platform"
    unit_primitives:
      - "duo_agent_platform"
    default_model: "claude_sonnet_4_20250514"
    selectable_models:
      - "claude_sonnet_3_7_20250219"
      - "claude_sonnet_4_20250514"
      - "claude_sonnet_4_5_20250929"
      - "gpt_5"
      - "gpt_5_mini"      # 새 모델을 여기에 추가
      - "gpt_5_codex"

구성 속성#

각 기능 설정 항목에는 다음이 포함됩니다:

• feature_setting: 기능 식별자
• unit_primitives: 이 구성을 사용하는 유닛 프리미티브 목록
• default_model: 기본 모델의 gitlab_identifier
• selectable_models: 사용자가 선택할 수 있는 gitlab_identifier 값 목록

유효성 검사#

AI Gateway는 구성을 자동으로 검증합니다:

• unit_primitives.yml에서 참조된 모든 모델은 models.yml에 정의되어 있어야 합니다
• default_model은 selectable_models에 포함되어야 합니다
• 모델 식별자는 고유해야 합니다

유효성 검사에 실패하면 수정해야 할 사항을 나타내는 명확한 오류 메시지가 표시됩니다.

테스트#

새 모델을 추가한 후:

1. 구성 파일이 구문적으로 올바른지 확인합니다(유효한 YAML)

2. GitLab UI에서 모델 선택을 테스트합니다

3. 모델이 요청에 올바르게 응답하고 올바른 프롬프트가 사용되고 있는지 확인합니다. 다음을 사용하여 ai_gateway 서비스 및 GitLab Duo workflow service의 로그를 tail하면 됩니다:

   gdk tail duo-workflow-service gitlab-ai-gateway
   

4. 적절한 프롬프트가 사용되고 있는지 검증합니다

참고#

• 새 모델을 추가하면 GitLab.com뿐만 아니라 클라우드 연결 AI Gateway를 사용하는 셀프 매니지드 인스턴스에서도 자동으로 해당 기능에 사용 가능하게 됩니다.
• 새 모델 추가의 실제 예시는 gpt-5-mini 및 gpt-5-codex 모델을 추가한 커밋 16b9fee8을 참조하세요.