히스토리

• 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에서 일반 제공됩니다.
• GitLab 18.0에서 Premium을 포함하도록 변경되었습니다.
• GitLab 18.5에서 GitLab Dedicated for Government에 활성화되었습니다.

AI Gateway는 LiteLLM을 통해 여러 LLM 공급자를 지원합니다. 플랫폼마다 서로 다른 요구 사항에 맞는 고유한 기능과 이점이 있습니다. 아래 문서는 GitLab이 검증하고 테스트한 공급자를 정리한 것입니다. 사용하려는 플랫폼이 이 문서에 없으면 플랫폼 요청 이슈(이슈 526144)에 의견을 남깁니다.

여러 모델 및 플랫폼 사용#

같은 GitLab 인스턴스에서 여러 모델과 플랫폼을 사용할 수 있습니다.

예를 들어 한 기능은 Azure OpenAI를 사용하도록 구성하고, 다른 기능은 AWS Bedrock 또는 vLLM으로 서빙하는 셀프 호스팅 모델을 사용하도록 구성할 수 있습니다.

이렇게 구성하면 사용 사례마다 가장 적합한 모델과 플랫폼을 선택할 수 있습니다. 모델은 지원 대상이어야 하고, 호환되는 플랫폼으로 서빙해야 합니다.

셀프 호스팅 모델 배포#

vLLM#

vLLM은 메모리를 효율적으로 사용하면서 LLM을 서빙하도록 설계된 고성능 추론 서버입니다. 모델 병렬 처리를 지원하며 기존 워크플로에 쉽게 통합됩니다.

vLLM 설치 방법은 vLLM 설치 가이드를 참고합니다. 버전 v0.18.1 이상을 설치해야 합니다.

vLLM으로 GPT OSS 120B를 서빙하는 구체적인 설정 절차는 vLLM으로 GPT OSS 120B 서빙을 참고합니다.

엔드포인트 URL 구성#

GitLab에서 OpenAI API와 호환되는 플랫폼(vLLM 등)의 엔드포인트 URL을 구성할 때는 다음을 따릅니다.

• URL 끝에 /v1을 붙여야 합니다
• 기본 vLLM 구성을 사용하면 엔드포인트 URL은 https://<hostname>:8000/v1이 됩니다
• 서버가 프록시나 로드 밸런서 뒤에 구성되어 있으면 포트를 지정하지 않아도 되며, 이 경우 URL은 https://<hostname>/v1이 됩니다

모델 이름 확인#

모델을 배포한 뒤 GitLab의 모델 식별자 필드에 입력할 모델 이름을 확인하려면 vLLM 서버의 /v1/models 엔드포인트를 쿼리합니다.

curl \
  --header "Authorization: Bearer API_KEY" \
  --header "Content-Type: application/json" \
  http://your-vllm-server:8000/v1/models

모델 이름은 응답의 data.id 필드 값입니다.

응답 예시:

{
  "object": "list",
  "data": [
    {
      "id": "Mixtral-8x22B-Instruct-v0.1",
      "object": "model",
      "created": 1739421415,
      "owned_by": "vllm",
      "root": "mistralai/Mixtral-8x22B-Instruct-v0.1",
      // Additional fields removed for readability
    }
  ]
}

이 예시에서 모델의 id가 Mixtral-8x22B-Instruct-v0.1이면 GitLab의 모델 식별자는 custom_openai/Mixtral-8x22B-Instruct-v0.1로 설정합니다.

자세한 내용은 다음 문서를 참고합니다.

• vLLM이 지원하는 모델은 vLLM 지원 모델 문서를 참고합니다.
• vLLM으로 모델을 실행할 때 사용할 수 있는 옵션은 엔진 인수에 관한 vLLM 문서를 참고합니다.

Mistral-7B-Instruct-v0.2#

1. HuggingFace에서 모델을 다운로드합니다.

   git clone https://<your-hugging-face-username>:<your-hugging-face-token>@huggingface.co/mistralai/Mistral-7B-Instruct-v0.3
   

2. 서버를 실행합니다.

   vllm serve <path-to-model>/Mistral-7B-Instruct-v0.3 \
      --served_model_name <choose-a-name-for-the-model>  \
      --tokenizer_mode mistral \
      --tensor_parallel_size <number-of-gpus> \
      --load_format mistral \
      --config_format mistral \
      --tokenizer <path-to-model>/Mistral-7B-Instruct-v0.3
   

Mixtral-8x7B-Instruct-v0.1#

1. HuggingFace에서 모델을 다운로드합니다.

   git clone https://<your-hugging-face-username>:<your-hugging-face-token>@huggingface.co/mistralai/Mixtral-8x7B-Instruct-v0.1
   

2. 토큰 설정 파일의 이름을 변경합니다.

   cd <path-to-model>/Mixtral-8x7B-Instruct-v0.1
   cp tokenizer.model tokenizer.model.v3
   

3. 모델을 실행합니다.

   vllm serve <path-to-model>/Mixtral-8x7B-Instruct-v0.1 \
     --tensor_parallel_size 4 \
     --served_model_name <choose-a-name-for-the-model> \
     --tokenizer_mode mistral \
     --load_format safetensors \
     --tokenizer <path-to-model>/Mixtral-8x7B-Instruct-v0.1
   

지연 시간 감소를 위한 요청 로깅 비활성화#

프로덕션에서 vLLM을 운영할 때 --disable-log-requests 플래그로 요청 로깅을 비활성화하면 지연 시간을 크게 줄일 수 있습니다.

요청 로깅을 비활성화하면 특히 부하가 높을 때 상세 로그가 유발하는 오버헤드가 줄어들어 성능 수준을 높이는 데 도움이 됩니다.

vllm serve <path-to-model>/<model-version> \
--served_model_name <choose-a-name-for-the-model>  \
--disable-log-requests

이 변경으로 내부 벤치마크에서 응답 시간이 눈에 띄게 개선되는 것이 확인됐습니다.

클라우드 호스팅 모델 배포#

GitLab은 다음 공급자를 검증하고 테스트했습니다. AI Gateway는 LiteLLM과 호환되는 LLM 공급자를 지원합니다.

• AWS Bedrock
• Amazon Bedrock Mantle
• Gemini Enterprise Agent Platform
• Azure OpenAI
• Anthropic
• OpenAI

AWS Bedrock 인증 구성#

AI Gateway에서 AWS Bedrock 인증에 사용할 수 있는 방법은 여러 가지입니다.

사전 요구 사항:

• Bedrock의 모델은 처음 호출할 때 자동으로 활성화됩니다. 자세한 내용은 Bedrock 모델 액세스를 참고합니다.
• 적절한 IAM 권한이 구성된 AWS 자격 증명이 있어야 합니다.

Amazon EKS(Helm Chart 사용, 권장)#

정적 자격 증명을 저장하지 않고 AI Gateway Pod가 AWS Bedrock에 인증하도록 IRSA(IAM Roles for Service Accounts)를 사용합니다.

IRSA로 Amazon EKS 인증을 구성하면 AI Gateway는 IRSA 역할에서 임시 자격 증명을 자동으로 가져옵니다.

IRSA로 Amazon EKS를 인증하는 방법은 다음과 같습니다.

1. Bedrock 모델 액세스를 허용하는 IAM 정책을 만듭니다. 보안을 더 강화해야 하면 특정 모델로 범위를 좁힐 수 있습니다.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "bedrock:InvokeModel",
           "bedrock:InvokeModelWithResponseStream"
         ],
         "Resource": "arn:aws:bedrock:*::foundation-model/*"
       }
     ]
   }
   

   aws iam create-policy \
     --policy-name bedrock-ai-gateway-access \
     --policy-document file://bedrock-policy.json \
     --description "Bedrock access for AI Gateway"
   

2. 선택 사항. 액세스 제어를 더 엄격하게 하려면 와일드카드 리소스를 특정 모델의 Amazon 리소스 이름(ARN)으로 바꿉니다. 이렇게 하면 GitLab 구성이 바뀌어도 승인된 모델만 액세스할 수 있습니다. 사용할 수 있는 모델 ARN은 Amazon Bedrock 모델 ID를 참고합니다.

   "Resource": [
     "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-5-sonnet-20241022-v2:0",
     "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
   ]
   

   [!note] 일부 모델은 다른 ARN 형식을 사용할 수 있습니다. 예를 들어 최신 모델은 파운데이션 모델 ARN 외에 추론 프로필 ARN을 요구할 수 있습니다. 사용하는 모델의 ARN 형식은 Amazon Bedrock 모델 ID를 참고합니다.

3. Amazon EKS 서비스 계정이 사용할 신뢰 정책이 포함된 IAM 역할을 만듭니다. 다음 값을 바꿉니다.

   • YOUR_ACCOUNT_ID: AWS 계정 ID입니다.
   • REGION: Amazon EKS 클러스터 리전입니다(예: us-east-1).
   • YOUR_OIDC_ID: Amazon EKS 클러스터의 OIDC 공급자 ID입니다.
   • NAMESPACE: AI Gateway가 배포된 Kubernetes 네임스페이스입니다.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/oidc.eks.REGION.amazonaws.com/id/YOUR_OIDC_ID"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "oidc.eks.REGION.amazonaws.com/id/YOUR_OIDC_ID:sub": "system:serviceaccount:NAMESPACE:ai-gateway",
             "oidc.eks.REGION.amazonaws.com/id/YOUR_OIDC_ID:aud": "sts.amazonaws.com"
           }
         }
       }
     ]
   }
   

   # Create the role
   aws iam create-role \
     --role-name eks-ai-gateway-bedrock \
     --assume-role-policy-document file://trust-policy.json \
     --description "EKS IRSA role for AI Gateway to access Bedrock"
   

4. 이 역할에 Bedrock IAM 정책을 연결합니다.

   # Attach the role
   aws iam attach-role-policy \
     --role-name eks-ai-gateway-bedrock \
     --policy-arn arn:aws:iam::YOUR_ACCOUNT_ID:policy/bedrock-ai-gateway-access
   

5. Helm 차트를 구성하려면 IAM 역할 주석과 함께 AI Gateway를 설치합니다.

   serviceAccount:
     create: true
     name: ai-gateway
     annotations:
       eks.amazonaws.com/role-arn: arn:aws:iam::YOUR_ACCOUNT_ID:role/YOUR_ROLE_NAME
   extraEnvironmentVariables:
     - name: AWS_REGION
       value: us-east-1
   

자세한 내용은 서비스 계정용 IAM 역할을 참고합니다.

Docker 배포#

AI Gateway 컨테이너를 시작할 때 환경 변수로 IAM 자격 증명을 구성합니다.

docker run -d \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  -e AWS_REGION=us-east-1 \
  -p 5052:5052 \
  registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-vX.Y.Z-ee

IAM 사용자 또는 역할에는 Helm Chart를 사용하는 Amazon EKS에서 설정하는 것과 비슷한 정책이 있어야 합니다.

Kubernetes 배포#

Amazon EKS가 아닌 Kubernetes 클러스터에서는 Kubernetes 시크릿에 AWS 자격 증명을 저장할 수 있습니다.

1. Kubernetes 시크릿을 만듭니다.

   kubectl create secret generic aws-credentials \
     --from-literal=access-key-id=YOUR_ACCESS_KEY_ID \
     --from-literal=secret-access-key=YOUR_SECRET_ACCESS_KEY \
     -n YOUR_NAMESPACE
   

2. 시크릿을 참조하도록 Helm 차트를 구성합니다.

   extraEnvironmentVariables:
     - name: AWS_ACCESS_KEY_ID
       valueFrom:
         secretKeyRef:
           name: aws-credentials
           key: access-key-id
     - name: AWS_SECRET_ACCESS_KEY
       valueFrom:
         secretKeyRef:
           name: aws-credentials
           key: secret-access-key
     - name: AWS_REGION
       value: us-east-1
   

AWS Bedrock에서 IAM 역할 수임#

히스토리

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

기본적으로 AI Gateway는 이미 가지고 있는 자격 증명(예: IRSA 역할이나 환경 변수)으로 Bedrock을 호출합니다. 다른 역할(예: 다른 AWS 계정의 역할)로 Bedrock을 호출하려면 셀프 호스팅 모델마다 IAM 역할을 지정합니다. AI Gateway는 자체 자격 증명으로 AWS Security Token Service(STS)의 AssumeRole 작업을 통해 해당 역할을 수임합니다. 그런 다음 AI Gateway는 임시 자격 증명으로 Bedrock을 호출합니다.

사전 요구 사항:

• 관리자 액세스.
• AWS에 인증된 AI Gateway. AI Gateway가 실행되는 AWS ID가 해당 역할에 대해 sts:AssumeRole을 호출할 수 있어야 합니다.

Bedrock을 호출할 때 IAM 역할을 수임하려면 다음 단계를 따릅니다.

1. 대상 AWS 계정에서 다음 신뢰 관계 정책으로 IAM 역할을 만듭니다. 다음 값을 바꿉니다.

   • AI_GATEWAY_PRINCIPAL_ARN을 AI Gateway가 실행되는 AWS ID의 ARN으로 바꿉니다 (예: arn:aws:iam::AI_GATEWAY_ACCOUNT_ID:role/eks-ai-gateway-bedrock IRSA 역할).
   • GITLAB_INSTANCE_ID를 IAM role to assume 텍스트 상자에 표시되는 GitLab 인스턴스의 ID로 바꿉니다.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "AI_GATEWAY_PRINCIPAL_ARN"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "GITLAB_INSTANCE_ID"
           }
         }
       }
     ]
   }
   

   AI Gateway는 역할을 수임할 때 인스턴스 ID를 STS 외부 ID로 보냅니다. 이 조건은 역할 ARN을 아는 다른 AI Gateway 고객이 AI Gateway의 ID를 이용해 사용자의 역할을 수임하는 것(혼동된 대리인 문제)을 막습니다. 인스턴스 ID는 비밀 값이 아닙니다.

2. Bedrock 모델을 호출하려면 역할에 권한 정책을 연결합니다. Resource의 범위를 특정 모델로 한정할 수 있습니다.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "bedrock:InvokeModel",
           "bedrock:InvokeModelWithResponseStream"
         ],
         "Resource": "arn:aws:bedrock:*::foundation-model/*"
       }
     ]
   }
   

3. AI Gateway가 역할과 다른 계정에서 실행된다면, ID 기반 정책으로 AI Gateway ID가 해당 역할에 대해 sts:AssumeRole을 호출하도록 추가로 허용합니다.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "sts:AssumeRole",
         "Resource": "arn:aws:iam::ROLE_ACCOUNT_ID:role/YOUR_ROLE_NAME"
       }
     ]
   }
   

4. 오른쪽 위에서 Admin을 선택합니다.

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

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

7. Amazon Bedrock 플랫폼에서 셀프 호스팅 모델을 추가하거나 편집합니다.

8. 선택 사항. IAM role to assume 텍스트 상자에 역할의 ARN을 입력합니다 (예: arn:aws:iam::123456789012:role/YOUR_ROLE_NAME). 비워 두면 AI Gateway는 자체 자격 증명을 사용합니다.

9. 선택 사항. Test connection을 선택합니다.

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

IAM 역할과 API 키(베어러 토큰)는 함께 사용할 수 없습니다. GitLab은 API 키가 있는 모델에는 IAM 역할을 허용하지 않으며, AI Gateway는 둘 다 포함한 요청을 거부합니다.

AWS Bedrock API 키#

IAM 자격 증명 대신 AWS Bedrock API 키를 사용하는 방법은 다음과 같습니다.

1. Bedrock API 키를 만듭니다

2. API 키로 Kubernetes 시크릿을 만듭니다.

   kubectl create secret generic bedrock-api-key \
     --from-literal=token=YOUR_BEDROCK_API_KEY \
     -n YOUR_NAMESPACE
   

3. AI Gateway를 구성합니다(values.yaml에 추가).

   extraEnvironmentVariables:
     - name: AWS_BEARER_TOKEN_BEDROCK
       valueFrom:
         secretKeyRef:
           name: bedrock-api-key
           key: token
     - name: AWS_REGION
       value: us-east-1
   

프라이빗 VPC 엔드포인트#

VPC에서 프라이빗 Bedrock 엔드포인트를 사용하려면 AWS_BEDROCK_RUNTIME_ENDPOINT 환경 변수를 설정합니다.

Helm 배포의 경우:

extraEnvironmentVariables:
  - name: AWS_BEDROCK_RUNTIME_ENDPOINT
    value: https://bedrock-runtime.us-east-1.amazonaws.com

Docker 배포의 경우:

docker run -d \
  -e AWS_BEDROCK_RUNTIME_ENDPOINT=https://bedrock-runtime.us-east-1.amazonaws.com \
  -e AWS_REGION=us-east-1 \
  # ... other configuration

VPC 엔드포인트에는 https://vpce-{vpc-endpoint-id}-{service-name}.{region}.vpce.amazonaws.com 형식을 사용합니다

Bedrock 가드레일#

히스토리

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

Amazon Bedrock Guardrails로 Bedrock 모델 요청에 안전성 및 개인정보 보호 제어를 적용할 수 있습니다.

이 가드레일을 적용하려면 AIGW_BEDROCK_GUARDRAIL_CONFIG 환경 변수 값을 다음 필드가 포함된 JSON 객체로 설정합니다.

Helm 배포에서는 다음과 같이 환경 변수를 설정합니다.

extraEnvironmentVariables:
  - name: AIGW_BEDROCK_GUARDRAIL_CONFIG
    value: '{"guardrailIdentifier": "<guardrail_id>", "guardrailVersion": "1", "trace": "disabled"}'

Docker 배포의 경우:

docker run -d \
  -e AIGW_BEDROCK_GUARDRAIL_CONFIG='{"guardrailIdentifier": "<guardrail_id>", "guardrailVersion": "1", "trace": "disabled"}' \
  # ... other configuration

자세한 내용은 Amazon Bedrock Guardrails를 참고합니다.

Amazon Bedrock Mantle 구성#

히스토리

• GitLab 19.3에서 베타로 도입되었습니다.
• 2026년 9월 16일에 GPT-5 이상 모델이 지원 모델로 추가되었습니다.

Amazon Bedrock Mantle은 AWS가 제공하는 OpenAI API 호환 추론 서비스입니다. 다른 OpenAI 호환 엔드포인트와 마찬가지로 API 플랫폼으로 Amazon Bedrock Mantle을 구성합니다.

Amazon Bedrock Mantle에서 검증되어 지원되는 모델은 다음과 같습니다.

AI Gateway는 GPT-5 이상 모델에 대한 요청을 Amazon Bedrock Mantle의 Responses API로 보냅니다. 모든 모델에 같은 bedrock_mantle/ 접두사를 사용합니다.

Anthropic 모델은 Amazon Bedrock Mantle에서 지원되지 않습니다. Amazon Bedrock Mantle은 이러한 모델을 Anthropic Messages API로만 제공하며, AI Gateway는 이 플랫폼에서 해당 API를 사용하지 않습니다. AWS에서 Anthropic 모델을 사용하려면 대신 Amazon Bedrock 모델을 추가합니다.

Amazon Bedrock Mantle 모델을 구성하려면 다음 값으로 셀프 호스팅 모델을 추가합니다.

• Model family에는 모델에 맞는 패밀리를 선택합니다. OpenAI 모델에는 GPT를 선택합니다.
• Endpoint에는 https://bedrock-mantle.<region>.api.aws/v1 형식의 리전 엔드포인트를 입력합니다 (예: https://bedrock-mantle.us-east-1.api.aws/v1).
• Model identifier에는 bedrock_mantle/ 접두사를 사용합니다 (예: bedrock_mantle/openai.gpt-oss-120b).
• API key에는 Amazon Bedrock Mantle API 키를 입력합니다. 자세한 내용은 AWS Bedrock API 키를 참고합니다.

Azure OpenAI 구성#

Azure OpenAI는 Chat Completions API와 Responses API로 모델을 제공합니다. 대부분의 모델은 Chat Completions API를 지원합니다. 일부 최신 모델은 Responses API로만 사용할 수 있습니다.

Azure OpenAI 모델을 구성하려면 셀프 호스팅 모델을 추가합니다.

• Model family에는 모델에 맞는 패밀리를 선택합니다. GPT-5에는 GPT를 선택합니다.
• Endpoint에는 Azure OpenAI 리소스의 엔드포인트를 https://<resource-name>.openai.azure.com 형식으로 입력합니다. 경로나 API 버전은 추가하지 않습니다.
• Model identifier에는 azure/ 접두사 뒤에 배포 이름을 붙여 사용합니다 (예: azure/gpt-4o). 이 식별자는 요청을 Chat Completions API로 보냅니다. 대신 요청을 Responses API로 보내려면 Responses API 사용을 참조합니다.
• API key에는 Azure OpenAI 리소스의 API 키를 입력합니다.

Responses API 사용#

Responses API로만 사용할 수 있는 배포에는 azure/responses/ 접두사를 사용합니다. Model identifier에는 접두사 뒤에 배포 이름을 붙여 입력합니다 (예: azure/responses/gpt-5).

AI Gateway는 리소스의 /openai/responses 경로로 요청을 보냅니다. AI Gateway는 각 요청을 Responses API 형식으로 변환하고 응답을 다시 원래 형식으로 변환합니다. 이 변환은 스트리밍 응답과 도구 호출을 지원합니다. 두 API 사이를 변환하기 위한 프록시는 필요하지 않습니다.

Gemini Enterprise Agent Platform 인증 구성#

Gemini Enterprise Agent Platform의 모델을 사용하려면 AI Gateway 인스턴스를 인증해야 합니다. 다음 방법 중 하나를 사용할 수 있습니다.

• Docker 컨테이너를 시작할 때 환경 변수를 내보냅니다. AI Gateway 컨테이너를 실행할 때 다음 환경 변수를 설정합니다.

  GOOGLE_APPLICATION_CREDENTIALS=/path/to/application_default_credentials.json
  VERTEXAI_PROJECT=<gcp-project-id>
  VERTEXAI_LOCATION=global # or any specific location, e.g., "europe-west1"
  

• Google Cloud Run에서 AI Gateway 컨테이너를 실행하고 Gemini Enterprise Agent Platform 액세스에 Cloud Run 서비스 계정을 사용합니다.

관련 주제#

• 지원되는 모델 및 하드웨어 요구 사항 문서.
• Amazon Bedrock이 지원하는 파운데이션 모델
• AWS IAM 모범 사례
• Amazon Bedrock 보안
• 구성 정보는 다음 문서를 참고합니다.
  • Anthropic API 개요
  • OpenAI API 개요
  • Azure OpenAI 모델 사용