---

LLM 플랫폼 구성#

  - 
  Tier: Premium, Ultimate

- Offering: GitLab Self-Managed, GitLab Dedicated for Government

히스토리

• 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 공급자를 지원합니다. 각 플랫폼은 다양한 요구 사항에 맞는 고유한 기능과 장점을 제공합니다. 다음 문서에서는 검증 및 테스트를 완료한 공급자를 요약합니다. 원하는 플랫폼이 이 문서에 없는 경우, 플랫폼 요청 이슈(이슈 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에서 vLLM과 같은 OpenAI API 호환 플랫폼의 엔드포인트 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#

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

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

서버를 실행합니다:

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#

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

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

토큰 구성 파일의 이름을 변경합니다:

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

모델을 실행합니다:

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

• 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에 IRSA(IAM Roles for Service Accounts)를 사용하여 정적 자격 증명 없이 AWS Bedrock에 인증합니다.

IRSA로 Amazon EKS를 인증하면 AI Gateway가 IRSA 역할에서 임시 자격 증명을 자동으로 획득합니다.

IRSA를 사용하여 Amazon EKS를 인증하려면:

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"

선택 사항. 더 엄격한 액세스 제어를 위해 와일드카드 리소스를 특정 모델의 Amazon Resource Name(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"
]

일부 모델은 다른 ARN 형식을 사용할 수 있습니다. 예를 들어, 최신 모델은 파운데이션 모델 ARN 외에

추론 프로필 ARN이 필요할 수 있습니다. 특정 모델의 ARN 형식을 확인하려면 Amazon Bedrock 모델 ID를 참조하세요.

Amazon EKS 서비스 계정이 사용할 신뢰 정책이 있는 IAM 역할을 생성합니다. 다음 값을 대체하세요:

YOUR_ACCOUNT_ID: AWS 계정 ID.

• REGION: Amazon EKS 클러스터 리전(예: us-east-1).

• YOUR_OIDC_ID: Amazon EKS 클러스터의 OIDC 공급자 ID.

• NAMESPACE: AI Gateway가 배포된 쿠버네티스 네임스페이스.

{
  "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"

이 역할에 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

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 사용자 또는 역할에는 Amazon EKS에서 Helm 차트로 설정하는 정책과 유사한 정책이 있어야 합니다.

쿠버네티스 배포#

Amazon EKS 이외의 쿠버네티스 클러스터에서는 쿠버네티스 시크릿을 사용해 AWS 자격 증명을 저장할 수 있습니다:

쿠버네티스 시크릿을 생성합니다:

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

해당 시크릿을 참조하도록 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 API 키#

IAM 자격 증명 대신 AWS Bedrock API 키를 사용하려면 다음을 수행합니다:

Bedrock API 키 생성

API 키로 쿠버네티스 시크릿을 생성합니다:

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

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 가드레일#

History

• GitLab 19.0에서 도입됨.

Amazon Bedrock 가드레일을 사용해 Bedrock 모델 요청에 안전 및 개인 정보 보호 제어를 적용할 수 있습니다.

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

가드레일이 요청을 차단하면 사용자에게 반환되는 메시지는 GitLab에서 제공하는 메시지가 아니라

AWS Bedrock 가드레일에 구성된 사용자 지정 차단 메시지입니다. 사용자가 적절한 안내를 받을 수 있도록 AWS 콘솔에서 가드레일의 차단 메시지를 구성하세요.

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 가드레일을 참조하세요.

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 모델 사용하기