히스토리

• GitLab 17.9에서 셀프 호스팅 모델 지원이 일반적으로 사용 가능해짐.

• GitLab 18.9에서 오프라인 플로우 실행 지원이 도입됨.

오프라인 환경을 설정하려면 구매 전에 클라우드 라이선스 옵트아웃 면제를 받아야 합니다. 자세한 내용은 GitLab 영업 담당자에게 문의하세요.

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

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

오프라인 환경에 Agent Platform을 배포하려면 다음 단계를 완료하세요:

• 컨테이너 이미지를 내부 레지스트리로 전송

• LLM 모델 가중치를 오프라인 파일시스템으로 전송

• AI Gateway 시작

• vLLM 시작

• GitLab 관리자에서 AI Gateway 구성

• 셀프 호스팅 모델 추가

• 오프라인 플로우 실행 구성

• 배포 확인

사전 요구 사항#

• 오프라인 클라우드 라이선스가 있는 GitLab 18.9 이상.

• 아티팩트를 다운로드할 인터넷 연결이 있는 머신.

• 연결된 머신과 오프라인 호스트에 skopeo와 jq가 설치되어 있어야 합니다 (Red Hat 시스템의 경우 dnf install --assumeyes skopeo jq).

• 오프라인 환경으로 파일을 전송하는 방법(물리적 미디어, 크로스 도메인 솔루션, 또는 배스천 호스트).

• 오프라인 환경의 컨테이너 레지스트리. 예를 들어 GitLab 컨테이너 레지스트리, Harbor, 또는 Nexus.

• vLLM의 경우: 추론 호스트에 NVIDIA GPU 드라이버, CUDA 라이브러리, NVIDIA Container Toolkit이 설치되어 있어야 합니다. 오프라인 설치 옵션은 NVIDIA CUDA 설치 가이드를 참조하세요.

이 페이지의 모든 명령어는 Docker와 Podman 모두에서 작동합니다. 해당하는 경우 docker를 podman으로 바꾸세요.

필수 아티팩트#

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

컨테이너 이미지#

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

현재 실행기 이미지 버전을 확인하려면 다음 명령어를 실행하세요:

skopeo list-tags \
  docker://registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image \
  | jq --raw-output '.Tags[]' | grep --extended-regexp '^v[0-9]' | sort --version-sort | tail --lines=1

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

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

LLM 모델 가중치#

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

이 페이지의 예시에서는 Mistral Small 24B (~48 GB)를 사용합니다. 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

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

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

셸 변수는 머신 간에 유지되지 않습니다. 오프라인 호스트에서 INTERNAL_REGISTRY, GITLAB_VERSION, EXECUTOR_VERSION, VLLM_VERSION을 다시 설정하세요.

내부 레지스트리가 자체 서명 인증서를 사용하는 경우 신뢰하도록 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 컨테이너를 실행하려면:

• 필요한 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

• 내부 레지스트리 이미지를 사용하여 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= \
  ${INTERNAL_REGISTRY}/ai-gateway:self-hosted-v${GITLAB_VERSION}-ee

DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL=을 빈 문자열로 설정하면 오프라인 환경에서 사용할 수 없는 CustomersDot 서비스에 AI Gateway가 접근을 시도하는 것을 방지합니다. 이 설정이 없으면 각 요청마다 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로 바꾸세요. --security-opt label=disable 플래그는 GPU 장치 접근을 위해 SELinux 적용 시스템에서 필요합니다.

시작 후 모델이 로드되었는지 확인합니다:

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

• vLLM 구성에 대한 자세한 내용은 지원되는 LLM 서빙 플랫폼을 참조하세요.

• vLLM 배포 방법은 vLLM을 사용한 모델 배포 예시를 참조하세요.

GitLab에서 AI Gateway 구성#

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

• 오른쪽 상단 모서리에서 Admin을 선택합니다.

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

• Change configuration을 선택합니다.

• Local AI Gateway URL 아래에 http://<ai-gateway-host>:5052를 입력합니다.

• Local URL for the GitLab Duo Agent Platform service 아래에 <ai-gateway-host>:50052를 입력합니다.

• GitLab Duo Agent Platform을 켭니다. 켜면 Flow execution 섹션이 확장됩니다.

• Image registry 아래에 내부 레지스트리 URL을 입력합니다 (예: registry.internal.example.com/duo).

• Save changes를 선택합니다.

셀프 호스팅 모델 추가#

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

• 오른쪽 상단 모서리에서 Admin을 선택합니다.

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

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

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

• 필드를 작성합니다:

Endpoint에는 vLLM 서버의 URL을 입력합니다.

• Model identifier에는 custom_openai/mistral-small-3.2-24b를 입력합니다.

• 선택 사항. Test connection을 선택하여 AI Gateway가 vLLM 엔드포인트에 접근할 수 있는지 확인합니다.

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

오프라인 플로우 실행 구성#

오프라인 플로우 실행을 위해 duo-cli가 사전 설치된 커스텀 실행기 이미지를 사용합니다.

• 연결된 머신에서 커스텀 이미지를 빌드합니다:

FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:v0.0.6
RUN npm install --global @gitlab/duo-cli@8.86.0

현재 duo-cli 버전을 찾으려면 GitLab Rails 소스의 DUO_CLI_VERSION 상수 또는 GitLab Duo CLI npm 페이지를 확인하세요.

• 위에서 설명한 동일한 skopeo copy 절차를 사용하여 이미지를 내부 레지스트리로 전송한 다음 프로젝트의 agent-config.yml에서 참조합니다:

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

배포 확인#

• AI Gateway가 실행 중인지 확인합니다:

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

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

GitLab Duo Agent Platform 기능에 셀프 호스팅 모델을 할당하기 전까지는 헬스 체크가 통과되지 않습니다.

• GitLab Duo 헬스 체크를 실행합니다:

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

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

• Run health check를 선택합니다.

헬스 체크는 AI Gateway 연결 및 라이선스 상태를 검증합니다. GitLab Duo Chat 또는 Code Suggestions의 모델 추론은 테스트하지 않습니다.

• 모델 추론을 확인하려면 GitLab UI 또는 IDE의 GitLab Duo Chat이나 Code Suggestions를 통해 테스트 요청을 전송합니다.

• Agent Platform 플로우를 확인하려면 플로우를 트리거하고 실행기 이미지가 내부 레지스트리에서 가져와지고 duo-cli가 npm에서 다운로드되지 않는지 확인합니다.

일반적인 문제는 문제 해결을 참조하세요.

아티팩트 업데이트#

GitLab 인스턴스를 업그레이드할 때 동일한 절차를 사용하여 업데이트된 컨테이너 이미지를 전송합니다. 새 GitLab 버전과 일치하는 AI Gateway 이미지 태그를 사용하세요.

모델 가중치는 GitLab을 업그레이드할 때 업데이트할 필요가 없습니다. 업데이트는 다른 모델로 변경할 때만 필요합니다.

관련 항목#

• 오프라인 GitLab

• 셀프 호스팅 모델