히스토리

• 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을 포함하도록 변경되었습니다.

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#

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
• Google Vertex AI
• Azure OpenAI
• Anthropic
• OpenAI

AWS Bedrock으로 인증 구성#

AI Gateway로 AWS Bedrock을 인증하는 데 여러 가지 방법을 사용할 수 있습니다.

사전 조건:

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

Helm Chart를 사용한 Amazon EKS (권장)#

정적 자격 증명을 저장하지 않고 AWS Bedrock에 인증하기 위해 AI Gateway 파드에 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 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"
   ]
   

   [!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"
           }
         }
       }
     ]
   }
   

   # 역할 만들기
   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 정책을 연결합니다.

   # 역할 연결
   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 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 guardrails#

히스토리

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

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

이 guardrails를 적용하려면 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를 참조하세요.

Google Vertex AI로 인증 구성#

Google Vertex AI의 모델을 사용하려면 AI Gateway 인스턴스를 인증해야 합니다. 다음 메커니즘 중 하나를 사용할 수 있습니다:

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

  GOOGLE_APPLICATION_CREDENTIALS=/path/to/application_default_credentials.json
  VERTEXAI_PROJECT=<gcp-project-id>
  VERTEXAI_LOCATION=global
  

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

관련 항목#

• 지원되는 모델 및 하드웨어 요구 사항 문서.
• Amazon Bedrock 지원 기반 모델
• AWS IAM 모범 사례
• Amazon Bedrock 보안
• 구성 정보는 다음 문서를 참조하세요:
  • Anthropic API 개요
  • OpenAI API 개요
  • Azure OpenAI 모델 작업