オフライン環境でGitLab Duo Agent Platformセルフホスト版をデプロイする

GitLabインスタンスとRunnerがパブリックインターネットにアクセスできないオフライン環境に、GitLab Duo Agent Platformセルフホスト版をデプロイできます。これらの手順は、接続が制限されている環境や制限的なファイアウォールポリシーを持つ環境にも適用されます。

オフライン環境では、AIゲートウェイコンテナイメージ、LLMモデルウェイト、vLLM推論サーバーイメージ、およびAgent Platform Flows executorイメージを内部インフラストラクチャに手動で転送する必要があります。

オフライン環境にAgent Platformをデプロイするには、次の手順を実行してください:

1. コンテナイメージを内部レジストリに転送する
2. LLMモデルウェイトをオフラインファイルシステムに転送する
3. AIゲートウェイを起動する
4. vLLMを起動する
5. GitLab管理者でAIゲートウェイを設定する
6. セルフホストモデルを追加する
7. オフラインフロー実行を設定する
8. デプロイを検証する

前提条件

• GitLab 18.9以降とoffline cloud licenseが必要です。
• アーティファクトをダウンロードするためのインターネット接続を備えたマシン。
• 接続されたマシンとオフラインホストにskopeoとjqがインストールされていること（Red Hatシステムではdnf install --assumeyes skopeo jq）。
• オフライン環境にファイルを転送する方法（物理メディア、クロスドメインソリューション、または踏み台ホスト）。
• オフライン環境のコンテナレジストリ。例えば、GitLabコンテナレジストリ、Harbor、またはNexus。
• vLLMの場合: 推論ホストにNVIDIA GPUドライバー、CUDAライブラリ、およびNVIDIA Container Toolkitがインストールされていること。オフラインインストールオプションについては、NVIDIA CUDA installation guideを参照してください。

必要なアーティファクト

LLMモデルウェイトを除くすべてのアーティファクトはOCIコンテナイメージです。

コンテナイメージ

AIゲートウェイのタグは、お使いのGitLabバージョン番号を使用します: self-hosted-v<your-gitlab-version>-ee。

現在のexecutorイメージバージョンを確認するには、次のコマンドを実行します:

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

GitLab Duo Agentic Chat、コード提案、GitLab Duoコードレビュー、およびAgent Platformのフローでは、ClickHouseは不要です。GitLab Duoの使用状況に関する分析が必要な場合は、ClickHouse（docker.io/clickhouse/clickhouse-server）も転送して設定する必要があります。

FIPS検証済み環境では、標準イメージの代わりにAIゲートウェイFIPSイメージを使用してください。FIPSイメージは、同じself-hosted-vX.Y.Z-eeタグ形式を使用します。FIPSのバージョン管理されたタグは、GitLab 18.10以降で利用できます。詳細については、FIPS検証済みイメージを参照してください。

LLMモデルウェイト

LLMモデルウェイトは、vLLMがファイルシステムから直接読み込む大きなファイルです。これらのファイルはコンテナイメージとして配布されません。

Mistral Small 24B（約48 GB）は、このページの例で使用されています。これはコード提案とGitLab Duo Chatの両方をサポートします。その他のモデルオプションとGPU要件については、Supported models and hardware requirementsを参照してください。

コンテナイメージの転送

接続されたマシンで、必要なイメージをアーカイブとして保存し、オフライン側の内部レジストリに読み込みます。

接続されたマシンでイメージを保存する

イメージを保存するには、インターネットに接続されたマシンで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ゲートウェイを起動する

内部レジストリイメージを使用してAIゲートウェイコンテナを実行するには:

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ゲートウェイコンテナを実行します:

   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=を空の文字列に設定すると、AIゲートウェイがCustomersDotサービスにアクセスしようとするのを防ぎます。このサービスはオフライン環境では利用できません。この設定がない場合、各リクエストに20秒の遅延が発生します。

TLS終端と追加の設定オプションについては、GitLab AIゲートウェイのインストールを参照してください。

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適用システムでは、GPUデバイスアクセスに--security-opt label=disableフラグが必要です。

起動後、モデルが読み込まれていることを確認します:

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

• vLLMの設定に関する詳細については、サポートされているLLMサービスプラットフォームを参照してください。
• vLLMをデプロイする方法については、vLLMを使用したモデルデプロイの例を参照してください。

GitLabでAIゲートウェイを設定する

AIゲートウェイとvLLMが稼働した後、GitLabがそれらを使用するように設定します:

1. 右上隅で、管理者を選択します。
2. 左側のサイドバーで、GitLab Duoを選択します。
3. 設定の変更を選択します。
4. ローカルAIゲートウェイURLの下に、http://<ai-gateway-host>:5052を入力します。
5. GitLab Duo Agent PlatformサービスのローカルURLの下に、<ai-gateway-host>:50052を入力します。
6. GitLab Duo Agent Platformをオンにします。オンにすると、フローの実行セクションが展開されます。
7. イメージレジストリの下に、内部レジストリURL（例: registry.internal.example.com/duo）を入力します。
8. 変更を保存を選択します。

セルフホストモデルを追加する

セルフホストモデルのデプロイをGitLabインスタンスに追加します:

1. 右上隅で、管理者を選択します。
2. 左側のサイドバーで、GitLab Duoを選択します。
3. GitLab Duoのモデルを設定するを選択します。
4. セルフホストモデルの追加を選択します。
5. フィールドに入力します:
   • エンドポイントに、vLLMサーバーのURLを入力します。
   • モデル識別子に、custom_openai/mistral-small-3.2-24bを入力します。
6. オプション。オプション。接続をテストを選択して、AIゲートウェイエンドポイントに到達できることを検証します。
7. セルフホストモデルの追加を選択します。

オフラインフロー実行を設定する

オフラインフロー実行の場合、duo-cliがプリインストールされたカスタムexecutorイメージを使用します。

1. 接続されたマシンでカスタムイメージをビルドします:

   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ページを確認してください。

2. 上記で説明した同じskopeo copy手順を使用してイメージを内部レジストリに転送し、プロジェクトのagent-config.ymlでそれを参照します:

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

デプロイを検証する

1. AIゲートウェイが実行中であることを確認します:

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

2. GitLab Duoのヘルスチェックを実行します:

   1. 右上隅で、管理者を選択します。
   2. 左側のサイドバーで、GitLab Duoを選択します。
   3. ヘルスチェックを実行するを選択します。

   ヘルスチェックは、AIゲートウェイの接続性とライセンスステータスを検証します。モデル推論はテストしません。

3. モデル推論を検証するには、GitLab Duo Chatまたはコード提案をGitLab UIまたはIDEからテストリクエストを送信します。

4. Agent Platform Flowsを検証するには、フローをトリガーし、executorイメージが内部レジストリからプルされ、duo-cliがNPMからダウンロードされていないことを確認します。

一般的な問題については、トラブルシューティングを参照してください。

アーティファクトの更新

GitLabインスタンスをアップグレードする際は、同じ手順で更新されたコンテナイメージを転送してください。新しいGitLabバージョンと一致するAIゲートウェイイメージタグを使用してください。

GitLabをアップグレードしても、モデルウェイトを更新する必要はありません。更新は、別のモデルに変更する場合にのみ必要です。

関連トピック

• オフラインGitLab
• セルフホストモデル