히스토리

• GitLab 17.1에서 ai_custom_model이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.6에서 GitLab Self-Managed에 활성화되었습니다.
• GitLab 17.6 이상에서 GitLab Duo 애드온을 요구하도록 변경되었습니다.
• GitLab 17.8에서 기능 플래그 ai_custom_model 이 제거되었습니다.
• GitLab 17.9에서 UI로 AI Gateway URL을 설정하는 기능이 추가되었습니다.
• GitLab 17.9에서 일반 제공되었습니다.
• GitLab 18.0에서 Premium을 포함하도록 변경되었습니다.
• GitLab 18.5에서 GitLab Dedicated for Government에 활성화되었습니다.

사전 요구 사항:

• GitLab을 17.9 이상 버전으로 업그레이드합니다.
• 관리자여야 합니다.

인프라의 셀프 호스팅 모델에 접근하도록 GitLab 인스턴스를 구성하는 방법은 다음과 같습니다.

1. AI Gateway에 접근하도록 GitLab 인스턴스를 구성합니다.
2. GitLab 18.4 이상에서는 GitLab Duo Agent Platform 서비스에 접근하도록 GitLab 인스턴스를 구성합니다.
3. GitLab 인스턴스에 셀프 호스팅 모델을 추가합니다.
4. 기능에 사용할 셀프 호스팅 모델을 선택합니다.

로컬 AI Gateway에 대한 접근 구성#

GitLab 인스턴스와 로컬 AI Gateway 사이의 접근을 구성하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Change configuration을 선택합니다.
4. Local AI Gateway URL 아래에 AI Gateway URL을 입력합니다.
5. Save changes를 선택합니다.

AI Gateway 타임아웃 구성#

히스토리

• GitLab Self-Managed용으로 GitLab 18.7에서 도입되었습니다.
• GitLab 19.2에서 GitLab Dedicated에 제공됩니다.

리소스를 아끼고 장시간 실행되는 쿼리를 방지하려면, 모델 응답을 기다리는 동안 GitLab 이 AI Gateway에 보내는 요청의 타임아웃을 구성합니다. 컨텍스트 창이 크거나 쿼리가 복잡한 셀프 호스팅 모델에는 더 긴 타임아웃을 사용합니다.

타임아웃은 60 초에서 600 초(10 분) 사이로 구성할 수 있습니다. 타임아웃을 설정하지 않으면 GitLab은 기본값인 60 초를 사용합니다.

AI Gateway 타임아웃을 구성하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Change configuration을 선택합니다.
4. AI Gateway request timeout 아래에 타임아웃 값을 초 단위로(60에서 600 사이) 입력합니다.
5. Save changes를 선택합니다.

타임아웃 값 결정#

타임아웃 값은 배포 환경과 사용 사례에 따라 달라집니다.

타임아웃 값을 결정하는 방법은 다음과 같습니다.

• 기본값인 60 초로 시작해 타임아웃 오류가 발생하는지 모니터링합니다.
• 로그에서 A1000 타임아웃 오류를 모니터링합니다. 이 오류가 자주 발생하면 타임아웃을 늘리는 방안을 검토합니다.
• 사용 사례를 고려합니다. 프롬프트가 크거나, 코드 생성 작업이 복잡하거나, 대용량 설계 문서를 처리하는 경우 더 긴 타임아웃이 필요할 수 있습니다.
• 인프라를 고려합니다. 모델 성능은 사용 가능한 GPU 리소스, AI Gateway와 모델 엔드포인트 사이의 네트워크 지연, 모델의 처리 능력에 따라 달라집니다.
• 단계적으로 늘립니다. 타임아웃이 발생하면 값을 점진적으로(예: 30 ~ 60 초씩) 늘리고 결과를 모니터링합니다.

타임아웃 오류 문제 해결에 대한 자세한 내용은 Error A1000을 참고합니다. 타임아웃 값을 늘려도 오류 없이 응답이 잘린다면 오류 없이 응답이 잘리는 문제를 참고합니다.

채팅 모델 요청 타임아웃 구성#

히스토리

• GitLab 19.2에서 도입되었습니다.

AI Gateway 요청 타임아웃은 GitLab 이 AI Gateway를 얼마나 오래 기다릴지를 제어합니다. AI Gateway가 셀프 호스팅 모델의 채팅 응답을 얼마나 오래 기다릴지는 별도의 타임아웃이 제어합니다. 기본적으로 AI Gateway는 단일 채팅 모델 요청을 30 초 후에 종료합니다.

컨텍스트 창이 크거나 에이전트형 프롬프트가 복잡한 경우, 처리 속도가 느린 셀프 호스팅 모델에서는 30 초를 넘길 수 있습니다. 이 타임아웃을 늘리려면 AI Gateway 컨테이너에서 AIGW_DUO_CHAT__MODEL_REQUEST_TIMEOUT 환경 변수를 초 단위로 설정합니다.

docker run -e AIGW_GITLAB_URL=<your_gitlab_instance> \
  -e AIGW_DUO_CHAT__MODEL_REQUEST_TIMEOUT=600 \
  <ai_gateway_image>

값은 0보다 커야 합니다. 모델이 MODEL_SPECIFICATIONS에 자체 타임아웃을 가지고 있으면 그 값이 이 기본값보다 우선합니다.

모델 엔드포인트에 사용할 사용자 ID 헤더 구성#

히스토리

• GitLab 19.4에서 도입되었습니다.

기본적으로 AI Gateway가 셀프 호스팅 모델로 보내는 모든 요청은 하나의 서비스 계정에서 온 것처럼 보입니다. 모델 서빙 플랫폼이 호출자별로 사용량을 귀속하거나 측정한다면, 요청을 발생시킨 GitLab 사용자의 ID를 헤더로 추가하도록 AI Gateway를 구성할 수 있습니다.

이 헤더를 구성하려면 AI Gateway 컨테이너에서 AIGW_CUSTOM_MODELS__USER_ID_HEADER 환경 변수를 모델 엔드포인트가 기대하는 헤더 이름으로 설정합니다.

docker run -e AIGW_GITLAB_URL=<your_gitlab_instance> \
  -e AIGW_CUSTOM_MODELS__USER_ID_HEADER=x-gitlab-user-id \
  <ai_gateway_image>

AI Gateway는 OpenAI 호환 엔드포인트, Amazon Bedrock, Google Vertex AI를 포함해 모델 엔드포인트로 보내는 모든 요청에 이 헤더를 추가합니다. 헤더 값은 GitLab 인스턴스에서의 사용자 숫자 ID 입니다. 예를 들어 이 구성에서는 ID가 42 인 사용자가 발생시킨 요청이 모델 엔드포인트에 다음 헤더와 함께 도착합니다.

x-gitlab-user-id: 42

GitLab 관리 모델은 해당 요청이 AI Gateway를 거치지 않으므로 영향을 받지 않습니다.

헤더 이름은 다음 조건을 충족해야 합니다.

• 유효한 HTTP 헤더 이름입니다.
• Authorization, Host, Content-Type 같은 전송 또는 인증 헤더가 아닙니다.
• anthropic-version처럼 AI Gateway가 이미 설정하는 헤더가 아닙니다.

상태 확인처럼 사용자를 대신해 보내지 않는 요청에는 이 헤더가 포함되지 않습니다. 이 헤더는 사용량을 귀속하거나 측정하는 용도로만 사용하고, 모델 엔드포인트에서 인가를 판단하는 데는 사용하지 않습니다.

구성을 검증하려면 셀프 호스팅 모델을 사용하는 GitLab Duo 기능을 실행하고 모델 서빙 플랫폼의 접근 로그에서 요청 헤더를 확인합니다.

GitLab Duo Agent Platform에 대한 접근 구성#

히스토리

• GitLab 18.4에서 self_hosted_agent_platform이라는 기능 플래그와 함께 실험 기능으로 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.5에서 실험에서 베타로 변경되었습니다.
• GitLab 18.7에서 활성화되었습니다.
• GitLab 18.8에서 일반 제공되었습니다.
• GitLab 18.9에서 기능 플래그 self_hosted_agent_platform 이 제거되었습니다.
• GitLab 18.7과 18.8에서는 온라인 라이선스를 사용하는 고객에게 이 기능이 베타입니다. 이 기능을 사용하려면 셀프 호스팅 베타 모델 및 기능을 켜야 합니다.

사전 요구 사항:

• 인스턴스가 오프라인 라이선스를 사용한다면 GitLab Duo Agent Platform Self-Hosted 애드온이 있어야 합니다.

GitLab 인스턴스에서 Agent Platform 서비스에 접근하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Change configuration을 선택합니다.
4. Local URL for the GitLab Duo Agent Platform service 아래에 로컬 Agent Platform 서비스의 URL을 입력합니다.
   • 이 URL은 대개 Local AI Gateway URL과 같지만 gRPC 포트 :50052를 사용합니다.
   • http:// 나 https:// 같은 URL 접두사는 포함하지 않습니다.
   • 권장되는 NGINX 리버스 프록시로 SSL을 구성했거나 Ingress를 활성화한 Helm chart를 사용한다면 포트를 지정하지 않습니다. NGINX Ingress가 포트 포워딩을 처리합니다.
5. 선택 사항. 로컬 GitLab Duo Agent Platform 엔드포인트가 TLS를 사용한다면 Security 아래에서 Use secure connection (TLS) for GitLab Duo Agent Platform service 체크박스를 선택합니다.
6. Save changes를 선택합니다.

셀프 호스팅 모델 추가#

GitLab Duo 기능과 함께 사용하려면 GitLab 인스턴스에 셀프 호스팅 모델을 추가해야 합니다.

셀프 호스팅 모델을 추가하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.

2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.

3. Configure models for GitLab Duo를 선택합니다.

   • Configure models for GitLab Duo가 표시되지 않으면 구매 후 구독을 동기화합니다.
     1. 왼쪽 사이드바에서 Subscription을 선택합니다.
     2. Subscription details에서 Last sync 오른쪽에 있는 구독 동기화([retry])를 선택합니다.

4. Add self-hosted model을 선택합니다.

5. 다음 필드를 채웁니다.

   • Deployment name: 모델 배포를 고유하게 식별할 이름을 입력합니다. 예를 들어 Mixtral-8x7B-it-v0.1 on GCP와 같이 입력합니다.

   • Model family: 배포가 속한 모델 계열을 선택합니다. 지원 모델과 호환 모델 중에서 선택할 수 있습니다.

   • Endpoint: 모델이 호스팅된 URL을 입력합니다.

   • API key: 선택 사항. 모델에 접근하는 데 API 키가 필요하면 추가합니다.

   • IAM role to assume: 선택 사항. AI Gateway가 Amazon Bedrock을 호출하기 위해 가정(assume)하는 IAM 역할의 ARN을 입력합니다. 역할의 신뢰 정책은 GitLab 인스턴스 ID를 sts:ExternalId로 요구해야 합니다. IAM 역할은 API 키와 함께 사용할 수 없습니다. 자세한 내용은 AWS Bedrock에서 IAM 역할 가정을 참고합니다.

   • Model identifier: 배포 방법에 따른 모델 식별자를 입력합니다. 모델 식별자는 다음 형식을 따라야 합니다.

     배포 방법	형식	예시
     vLLM	custom_openai/<name of the model served through vLLM>	custom_openai/Mixtral-8x7B-Instruct-v0.1
     Amazon Bedrock - 모델 식별자 설정	bedrock/<model ID of the model>	bedrock/mistral.mixtral-8x7b-instruct-v0:1
     Amazon Bedrock - 애플리케이션 추론 프로필 ARN 사용	bedrock/converse/<application inference profile ARN>	bedrock/converse/arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abcd1234efgh
     Amazon Bedrock Mantle	bedrock_mantle/<model ID of the model>	bedrock_mantle/openai.gpt-oss-120b
     Gemini Enterprise Agent Platform	vertex_ai/<model ID of the model>	vertex_ai/claude-sonnet-4-6@default
     Anthropic	anthropic/<model ID of the model>	anthropic/claude-opus-4-6
     OpenAI	openai/<model ID of the model>	openai/gpt-5
     Azure OpenAI	azure/<deployment name>	azure/gpt-4o
     Azure OpenAI Responses API	azure/responses/<deployment name>	azure/responses/gpt-5

6. Add self-hosted model을 선택합니다.

Amazon Bedrock 모델 추가#

Amazon Bedrock 셀프 호스팅 모델을 추가할 때는 다음 중 하나를 선택할 수 있습니다.

• 모델 식별자를 설정합니다. 이 방법이 기본값입니다.
• 애플리케이션 추론 프로필 ARN을 사용합니다. 팀이나 프로젝트별로 비용 배분 또는 지출을 추적하려는 경우에 이 방법을 사용합니다.

모델 식별자 설정#

Amazon Bedrock 모델의 모델 식별자를 설정하는 방법은 다음과 같습니다.

1. AWS_REGION을 설정합니다. AI Gateway Docker 구성에서 해당 리전의 모델에 접근할 수 있는지 확인합니다.

2. 교차 리전 추론을 위해 모델의 추론 프로필 ID에 리전 접두사를 추가합니다.

3. 모델 식별자의 접두사로 bedrock/ 접두사 리전을 사용합니다.

   예를 들어 도쿄 리전의 Anthropic Claude 4.0 모델이라면 다음과 같습니다.

   • AWS_REGION은 ap-northeast-1 입니다.
   • 교차 리전 추론 접두사는 apac. 입니다.
   • 모델 식별자는 bedrock/apac.anthropic.claude-sonnet-4-20250514-v1:0 입니다.

일부 리전은 교차 리전 추론을 지원하지 않습니다. 이러한 리전에서는 모델 식별자에 리전 접두사를 지정하지 않습니다. 예를 들면 다음과 같습니다.

• AWS_REGION은 eu-west-2 입니다.
• 모델 식별자는 anthropic.claude-sonnet-4-5-20250929-v1:0 입니다.

애플리케이션 추론 프로필 ARN 사용#

애플리케이션 추론 프로필 ARN을 모델 식별자로 사용하려면 다음 형식을 사용합니다.

bedrock/converse/arn:aws:bedrock:<region>:<account-id>:application-inference-profile/<id>

예를 들면 다음과 같습니다.

bedrock/converse/arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abcd1234efgh

converse/ 접두사는 요청을 Amazon Bedrock Converse API로 라우팅하며, ARN 기반 식별자에는 이 접두사가 필요합니다.

임베딩 모델#

히스토리

• GitLab 19.1에서 semantic_search_user_model_selection이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• 기능 플래그 semantic_search_user_model_selection이 GitLab 19.3에서 제거되었습니다.
• 빈 API 키가 openai/ 임베딩 모델에서 지원되는 키로 2026년 10월 5일에 추가되었습니다.
• 임베딩 모델에 대한 Test connection이 GitLab 19.5에서 추가되었습니다.

임베딩 모델 패밀리에서 플랫폼별로 지원되는 모델은 다음과 같습니다.

• API: openai/ 접두사와 함께 OpenAI 호환 임베딩 모델을 사용합니다. LiteLLM은 임베딩 모델에 custom_openai/ 접두사를 지원하지 않습니다. 접두사가 없는 모델 식별자는 기본적으로 openai로 처리됩니다.
• Google Vertex AI: 모든 Vertex AI 임베딩 모델을 사용합니다. 최신 모델은 Gemini Enterprise Agent Platform 문서도 참고하고 Test connection으로 구성을 테스트합니다.
• Amazon Bedrock: 모든 Bedrock 임베딩 모델을 사용합니다. 최신 모델은 Amazon Bedrock 문서도 참고하고 Test connection으로 구성을 테스트합니다.

추가 임베딩 모델 지원을 요청하려면 에픽 23917을 참고합니다.

셀프 호스팅 베타 모델 및 기능 켜기#

셀프 호스팅 베타 모델 및 기능을 활성화하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Change configuration을 선택합니다.
4. Self-hosted beta models and features 아래에서 Use beta models and features in GitLab Duo Self-Hosted 체크박스를 선택합니다.
5. Save changes를 선택합니다.

셀프 호스팅 모델을 사용하도록 GitLab Duo 기능 구성#

구성된 기능 보기#

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Configure models for GitLab Duo를 선택합니다.
   • Configure models for GitLab Duo가 표시되지 않으면 구매 후 구독을 동기화합니다.
     1. 왼쪽 사이드바에서 Subscription을 선택합니다.
     2. Subscription details에서 Last sync 오른쪽에 있는 구독 동기화([retry])를 선택합니다.
4. AI-native features 탭을 선택합니다.

기능에 대한 셀프 호스팅 모델 선택#

셀프 호스팅 모델을 선택하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Configure models for GitLab Duo를 선택합니다.
4. AI-native features 탭을 선택합니다.
5. 셀프 호스팅 모델을 지정할 기능에서 드롭다운 목록으로 모델을 선택합니다.

기능에 대한 GitLab 관리 모델 선택#

히스토리

• GitLab 18.3에서 ai_self_hosted_vendored_features라는 기능 플래그와 함께 베타로 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.7에서 기본적으로 활성화되었습니다.
• GitLab 18.9에서 일반 제공되었습니다. 기능 플래그 ai_self_hosted_vendored_features는 제거되었습니다.

셀프 호스팅 AI Gateway와 셀프 호스팅 모델을 사용하더라도 기능에 GitLab 관리 모델을 선택할 수 있습니다.

오프라인 라이선스에서는 GitLab 관리 모델을 사용할 수 없습니다. 자세한 내용은 모델 선택을 참고합니다.

기능에 GitLab 관리 모델을 선택하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Configure models for GitLab Duo를 선택합니다.
4. AI-native features 탭을 선택합니다.
5. 구성하려는 기능과 하위 기능에서 드롭다운 목록으로 GitLab-managed model을 선택합니다.

GitLab Duo 기능 끄기#

기능에 모델을 선택하지 않아도 GitLab Duo 기능은 켜진 상태로 유지됩니다.

GitLab Duo 기능을 끄는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Configure models for GitLab Duo를 선택합니다.
4. AI-native features 탭을 선택합니다.
5. 끄려는 기능에서 드롭다운 목록으로 Disabled를 선택합니다.

GitLab 문서 셀프 호스팅#

환경 때문에 docs.gitlab.com의 GitLab 문서에 접근할 수 없다면 문서를 직접 호스팅할 수 있습니다. 자세한 내용은 GitLab 제품 문서 호스팅을 참고합니다.

관련 주제#

• 지원 모델
• 호환 모델
• AI Gateway 구성 유형