히스토리

• GitLab 17.9에서 셀프 호스팅 모델 지원이 일반적으로 사용 가능해졌습니다.
• GitLab 18.9에서 오프라인 플로 실행 지원이 도입됐습니다.

GitLab 인스턴스와 러너가 공용 인터넷에 접근할 수 없는 오프라인 환경에도 GitLab Duo Agent Platform Self-Hosted를 배포할 수 있습니다. 이 지침은 연결이 제한적이거나 방화벽 정책이 엄격한 환경에도 적용됩니다.

오프라인 환경에서는 AI Gateway 컨테이너 이미지, LLM 모델 가중치, vLLM 추론 서버 이미지, Agent Platform Flows 실행기 이미지를 내부 인프라로 직접 전송해야 합니다.

오프라인 환경에 Agent Platform을 배포하려면 다음 단계를 수행합니다.

1. 컨테이너 이미지를 내부 레지스트리로 전송합니다.
2. LLM 모델 가중치를 오프라인 파일 시스템으로 전송합니다.
3. AI Gateway를 시작합니다.
4. vLLM을 시작합니다.
5. GitLab Admin에서 AI Gateway를 구성합니다.
6. 셀프 호스팅 모델을 추가합니다.
7. 오프라인 플로 실행을 구성합니다.
8. 배포를 확인합니다.

사전 요구 사항#

• 오프라인 클라우드 라이선스가 적용된 GitLab 18.9 이상.
• 아티팩트를 내려받을 인터넷 연결이 있는 머신.
• 연결된 머신과 오프라인 호스트에 설치된 skopeo와 jq (Red Hat 계열 시스템에서는 dnf install --assumeyes skopeo jq 명령을 사용합니다).
• 오프라인 환경으로 파일을 전송할 방법 (물리 매체, 크로스 도메인 솔루션, 배스천 호스트).
• 오프라인 환경의 컨테이너 레지스트리. 예를 들어 GitLab 컨테이너 레지스트리, Harbor, Nexus가 있습니다.
• vLLM의 경우: 추론 호스트에 NVIDIA GPU 드라이버, CUDA 라이브러리, NVIDIA Container Toolkit을 설치합니다. 오프라인 설치 옵션은 NVIDIA CUDA 설치 가이드를 참고합니다.

필수 아티팩트#

LLM 모델 가중치를 제외한 모든 아티팩트는 OCI 컨테이너 이미지입니다.

GitLab 인스턴스 자체가 실행하는 컨테이너 이미지는 별도로 전송합니다. 자세한 내용은 오프라인 GitLab을 참고합니다.

컨테이너 이미지#

표에 적힌 크기는 전송하는 압축 크기입니다. 각 이미지는 레지스트리에 로드하거나 호스트로 가져오면 더 커집니다. 전송 전에 크기를 확인하려면 skopeo inspect --raw docker://<image>:<tag>를 실행하고 출력에 나오는 config와 layers 크기를 더합니다.

AI Gateway 태그는 GitLab 버전 번호를 사용합니다. 형식은 self-hosted-v<your-gitlab-version>-ee입니다.

실행기 태그는 사용 중인 GitLab 버전이 플로를 시작할 때 요청하는 태그와 일치해야 합니다. 이 태그는 릴리스마다 고정돼 있습니다. 태그를 확인하려면 ee/app/services/ai/duo_workflows/start_workflow_service.rb 파일에서 해당 버전의 IMAGE_PATH 상수를 확인합니다. 이 태그는 플로가 생성하는 CI/CD job의 이미지로도 표시됩니다. 레지스트리의 최신 태그는 사용 중인 버전이 요청하는 태그보다 앞서 있는 경우가 많으므로, 레지스트리 목록을 보고 태그를 고르지 않습니다.

오프라인 환경에서는 버전 기본값을 따라가지 말고 전송한 이미지로 인스턴스를 고정합니다. 다음 중 하나를 사용합니다.

• 프로젝트의 .gitlab/duo/agent-config.yml 파일에 있는 image 키. 이 키는 해당 프로젝트의 플로에 적용됩니다.
• duo_workflows_default_image_registry 애플리케이션 설정. 이 설정은 태그를 포함한 전체 이미지 참조를 받으며 모든 프로젝트에 적용됩니다.

GitLab Duo Agentic Chat, Code Suggestions, GitLab Duo Code Review, Agent Platform 플로에는 ClickHouse가 필요하지 않습니다. GitLab Duo 사용량 분석이 필요하면 ClickHouse (docker.io/clickhouse/clickhouse-server)도 전송하고 구성해야 합니다.

FIPS 검증 환경에서는 표준 이미지 대신 AI Gateway FIPS 이미지를 사용합니다. FIPS 이미지는 동일한 self-hosted-vX.Y.Z-ee 태그 형식을 사용합니다. FIPS 버전 태그는 GitLab 18.10 이상에서 제공됩니다. 자세한 내용은 FIPS 검증 이미지를 참고합니다.

skopeo copy와 docker save 모두 이미지 서명을 전송하지 않습니다. FIPS 이미지의 진위를 확인하려면 이미지를 전송하기 전에 연결된 머신에서 cosign verify를 실행합니다.

LLM 모델 가중치#

LLM 모델 가중치는 vLLM이 파일 시스템에서 직접 읽는 대용량 파일입니다. 이 파일은 컨테이너 이미지로 배포되지 않습니다.

이 페이지의 예시에서는 Mistral Small 24B(약 48GB)를 사용합니다. 이 모델은 Code Suggestions와 GitLab Duo Chat을 모두 지원합니다. 다른 모델 선택지와 GPU 요구 사항은 지원 모델 및 하드웨어 요구 사항을 참고합니다.

컨테이너 이미지 전송#

연결된 머신에서 필요한 이미지를 아카이브로 저장한 다음, 오프라인 환경의 내부 레지스트리로 로드합니다.

연결된 머신에서 이미지 저장#

이미지를 저장하려면 인터넷에 연결된 머신에서 다음 명령으로 skopeo를 실행합니다.

GITLAB_VERSION="18.10.0"
EXECUTOR_VERSION="v0.0.6"
VLLM_VERSION="v0.18.1"

skopeo copy \
  docker://registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v${GITLAB_VERSION}-ee \
  docker-archive:aigw.tar

skopeo copy \
  docker://registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:${EXECUTOR_VERSION} \
  docker-archive:executor.tar

skopeo copy \
  docker://docker.io/vllm/vllm-openai:${VLLM_VERSION} \
  docker-archive:vllm.tar

연결된 머신이 프록시를 사용하면 skopeo를 실행하기 전에 HTTPS_PROXY를 설정합니다.

export HTTPS_PROXY="http://proxy.example.com:8080"

skopeo를 사용할 수 없으면 docker save를 대신 사용합니다.

GITLAB_VERSION="18.10.0"

docker pull registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v${GITLAB_VERSION}-ee
docker save \
  registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v${GITLAB_VERSION}-ee \
  --output aigw.tar

내부 레지스트리로 이미지 로드#

아카이브를 오프라인 환경으로 전송한 다음 내부 레지스트리로 로드합니다.

내부 레지스트리가 자체 서명 인증서를 사용하면 skopeo가 이를 신뢰하도록 구성합니다.

mkdir --parents /etc/containers/certs.d/<registry-host>
cp ca.crt /etc/containers/certs.d/<registry-host>/ca.crt

그런 다음 이미지를 로드합니다.

INTERNAL_REGISTRY="registry.internal.example.com/duo"
GITLAB_VERSION="18.10.0"
EXECUTOR_VERSION="v0.0.6"
VLLM_VERSION="v0.18.1"

skopeo copy \
  docker-archive:aigw.tar \
  docker://${INTERNAL_REGISTRY}/ai-gateway:self-hosted-v${GITLAB_VERSION}-ee

skopeo copy \
  docker-archive:executor.tar \
  docker://${INTERNAL_REGISTRY}/workflow-generic-image:${EXECUTOR_VERSION}

skopeo copy \
  docker-archive:vllm.tar \
  docker://${INTERNAL_REGISTRY}/vllm-openai:${VLLM_VERSION}

LLM 모델 가중치 전송#

연결된 머신에서 모델 가중치를 내려받으려면 Hugging Face CLI 또는 git lfs를 사용합니다.

Hugging Face CLI를 사용하는 경우는 다음과 같습니다.

pip install huggingface_hub
huggingface-cli download mistralai/Mistral-Small-3.2-24B-Instruct-2506 \
  --local-dir ./mistral-small-3.2-24b

사용 중인 huggingface_hub 버전에 huggingface-cli가 없으면 같은 인수로 hf download를 사용합니다.

git lfs를 사용하는 경우는 다음과 같습니다(Python이 필요하지 않습니다).

dnf install --assumeyes git-lfs  # On Debian/Ubuntu: apt-get install git-lfs
git lfs install
git clone https://huggingface.co/mistralai/Mistral-Small-3.2-24B-Instruct-2506

내려받은 디렉터리를 오프라인 환경으로 전송한 다음, vLLM 컨테이너가 접근할 수 있는 파일 시스템 경로에 둡니다 (예: /data/models/mistral-small-3.2-24b).

AI Gateway 시작#

내부 레지스트리 이미지로 AI Gateway 컨테이너를 실행하려면 다음을 수행합니다.

1. 필요한 JWT 서명 키를 생성합니다.

   openssl genrsa -out aigw_signing.key 2048
   openssl genrsa -out aigw_validation.key 2048
   openssl genrsa -out duo_workflow_jwt.key 2048
   openssl genrsa -out duo_workflow_validation.key 2048
   

2. 내부 레지스트리 이미지로 AI Gateway 컨테이너를 실행합니다.

   INTERNAL_REGISTRY="registry.internal.example.com/duo"
   GITLAB_VERSION="18.10.0"
   GITLAB_DOMAIN="gitlab.internal.example.com"
   
   docker run --detach \
     --publish 5052:5052 \
     --publish 50052:50052 \
     --env AIGW_GITLAB_URL=https://${GITLAB_DOMAIN} \
     --env AIGW_GITLAB_API_URL=https://${GITLAB_DOMAIN}/api/v4/ \
     --env AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \
     --env AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)" \
     --env DUO_WORKFLOW_AUTH__ENABLED="true" \
     --env DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat duo_workflow_jwt.key)" \
     --env DUO_WORKFLOW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat duo_workflow_validation.key)" \
     --env DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL=https://${GITLAB_DOMAIN} \
     --env AIGW_CUSTOMER_PORTAL_URL=https://${GITLAB_DOMAIN} \
     ${INTERNAL_REGISTRY}/ai-gateway:self-hosted-v${GITLAB_VERSION}-ee
   

DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL과 AIGW_CUSTOMER_PORTAL_URL을 GitLab 인스턴스 URL로 설정하면 다음이 보장됩니다.

• AI Gateway가 오프라인 환경에서 사용할 수 없는 Customers Portal에 접근을 시도하지 않습니다.
• 요청마다 20초 지연이 발생하지 않습니다.

TLS 종료와 추가 구성 옵션은 GitLab AI Gateway 설치를 참고합니다.

vLLM 시작#

전송한 모델 가중치를 제공하도록 vLLM을 실행합니다.

INTERNAL_REGISTRY="registry.internal.example.com/duo"
VLLM_VERSION="v0.18.1"

docker run --detach \
  --gpus all \
  --volume /data/models/mistral-small-3.2-24b:/model \
  --publish 8000:8000 \
  ${INTERNAL_REGISTRY}/vllm-openai:${VLLM_VERSION} \
  --model /model \
  --served_model_name custom_openai/mistral-small-3.2-24b \
  --tensor-parallel-size <number-of-gpus>

<number-of-gpus>를 사용 가능한 GPU 수로 바꿉니다. GPU가 하나면 --tensor-parallel-size 1을 사용합니다. Podman에서는 --gpus all을 --device nvidia.com/gpu=all --security-opt label=disable로 바꿉니다. SELinux를 enforcing 모드로 사용하는 시스템에서 GPU 장치에 접근하려면 --security-opt label=disable 플래그가 필요합니다.

시작한 뒤 모델이 로드됐는지 확인합니다.

curl --silent "http://localhost:8000/v1/models"

• vLLM 구성에 대한 자세한 내용은 지원되는 LLM 서빙 플랫폼을 참고합니다.
• vLLM 배포 방법은 vLLM을 사용한 모델 배포 예시를 참고합니다.

GitLab에서 AI Gateway 구성#

AI Gateway와 vLLM이 실행되면 GitLab이 이를 사용하도록 구성합니다.

1. 오른쪽 위에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Change configuration을 선택합니다.
4. Local AI Gateway URL에 http://<ai-gateway-host>:5052를 입력합니다.
5. Local URL for the GitLab Duo Agent Platform service에 <ai-gateway-host>:50052를 입력합니다.
6. GitLab Duo Agent Platform을 켭니다. 켜면 Flow execution 섹션이 펼쳐집니다.
7. Image registry에 내부 레지스트리 URL을 입력합니다 (예: registry.internal.example.com/duo).
8. Save changes를 선택합니다.

셀프 호스팅 모델 추가#

GitLab 인스턴스에 셀프 호스팅 모델 배포를 추가합니다.

1. 오른쪽 위에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
3. Configure models for GitLab Duo를 선택합니다.
4. Add self-hosted model을 선택합니다.
5. 다음 필드를 입력합니다.
   • Endpoint에는 vLLM 서버의 URL을 입력합니다.
   • Model identifier에는 custom_openai/mistral-small-3.2-24b를 입력합니다.
6. 선택 사항. Test connection을 선택해 AI Gateway가 vLLM 엔드포인트에 연결할 수 있는지 확인합니다.
7. Add self-hosted model을 선택합니다.

오프라인 플로 실행 구성#

오프라인 플로 실행에는 duo-cli가 미리 설치된 사용자 지정 실행기 이미지를 사용합니다.

1. 연결된 머신에서 duo-cli 바이너리를 내려받습니다.

   curl --location "https://gitlab.com/api/v4/projects/46519181/packages/generic/duo-cli/9.8.0/duo-linux-x64" \
     --output duo-linux-x64
   

   현재 duo-cli 버전은 GitLab Rails 소스의 DUO_CLI_VERSION 상수 또는 GitLab 패키지 레지스트리의 duo-cli 패키지에서 확인합니다.

2. 바이너리를 포함한 사용자 지정 이미지를 빌드합니다.

   FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:v0.0.14
   COPY duo-linux-x64 /usr/bin/duo
   RUN chmod +x /usr/bin/duo
   

   v0.0.14를 사용 중인 GitLab 버전이 요청하는 태그로 바꿉니다.

3. 앞에서 설명한 것과 같은 skopeo copy 절차로 이미지를 내부 레지스트리로 전송한 다음, 프로젝트의 agent-config.yml에서 해당 이미지를 참조합니다.

   image: registry.internal.example.com/duo/duo-executor:v0.0.14
   

배포 확인#

1. AI Gateway가 실행 중인지 확인합니다.

   curl --silent "http://<ai-gateway-host>:5052/monitoring/healthz"
   

2. 사용하려는 각 GitLab Duo 기능에 셀프 호스팅 모델을 선택합니다. GitLab Duo Agent Platform 기능도 포함합니다.

   GitLab Duo Agent Platform 기능에 셀프 호스팅 모델을 할당하기 전에는 상태 점검이 통과하지 않습니다.

3. GitLab Duo 상태 점검을 실행합니다.

   1. 오른쪽 위에서 Admin을 선택합니다.
   2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
   3. Run health check를 선택합니다.

   상태 점검은 AI Gateway 연결과 라이선스 상태를 검증합니다. GitLab Duo Chat이나 Code Suggestions의 모델 추론은 테스트하지 않습니다.

4. 모델 추론을 확인하려면 GitLab UI 또는 IDE에서 GitLab Duo Chat이나 Code Suggestions로 테스트 요청을 보냅니다.

5. Agent Platform Flows를 확인하려면 플로를 트리거한 다음, 실행기 이미지가 내부 레지스트리에서 전달되고 duo-cli가 gitlab.com에서 내려받아지지 않는지 확인합니다.

일반적인 문제는 문제 해결을 참고합니다.

아티팩트 업데이트#

GitLab 인스턴스를 업그레이드할 때는 같은 절차로 갱신된 컨테이너 이미지를 전송합니다. 새 GitLab 버전에 맞는 AI Gateway 이미지 태그를 사용합니다.

업그레이드하면 새 버전이 요청하는 실행기 태그도 달라질 수 있습니다. 업그레이드 전에 그 태그를 확인하고, AI Gateway 이미지와 함께 해당 실행기 이미지를 전송합니다.

GitLab을 업그레이드할 때 모델 가중치는 업데이트하지 않아도 됩니다. 다른 모델로 바꿀 때만 업데이트가 필요합니다.

관련 주제#

• 오프라인 GitLab
• 셀프 호스팅 모델