正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

GitLab AIゲートウェイをインストールする

このAIゲートウェイは、AIネイティブなGitLab Duo機能へのアクセスを提供する2つのサービスの組み合わせです:

Dockerを使用してインストール

GitLabAIゲートウェイのDockerイメージには、必要なすべてのコードと依存関係が1つのコンテナに含まれています。

前提条件:

  • DockerのようなDockerコンテナエンジンをインストールします。

  • ネットワークからアクセスできる有効なホスト名を使用してください。localhostは使用しないでください。

  • linux/amd64アーキテクチャ用に約340MB（圧縮）と、最低512MBのRAMがあることを確認してください。

  • コンテナがai_gatewayサービスとduo-workflow-serviceサービス用に少なくとも2つのCPUにアクセスできることを確認してください。

  • GitLab Duo Agent Platform機能のJWT署名キーを生成します:

    openssl genrsa -out duo_workflow_jwt.key 2048

    duo_workflow_jwt.keyファイルを安全に保管し、公開しないでください。このキーはJWTトークンの署名に使用され、機密性の高い資格情報として扱われる必要があります。

特に高いワークロードの下でのパフォーマンスを向上させるには、最小要件よりも多くのディスクスペース、メモリ、リソースを割り当てることを検討してください。RAMとディスク容量が増加すると、AIゲートウェイの効率性はピーク負荷時に向上します。

GitLabAIゲートウェイにはGPUは必要ありません。

AIゲートウェイイメージを見つける

GitLab公式Dockerイメージは以下で利用可能です:

セルフホストモデルのAIゲートウェイのリリースプロセスを表示します。

GitLabバージョンがvX.Y.*-eeの場合、最新のself-hosted-vX.Y.*-eeタグが付いたAIゲートウェイDockerイメージを使用します。たとえば、GitLabバージョンがv18.2.1-eeで、AIゲートウェイDockerイメージに次のものが含まれる場合:

  • バージョンself-hosted-v18.2.0-ee、self-hosted-v18.2.1-ee、およびself-hosted-v18.2.2-eeの場合、self-hosted-v18.2.2-eeを使用します。
  • バージョンself-hosted-v18.2.0-eeとself-hosted-v18.2.1-eeの場合、self-hosted-v18.2.1-eeを使用します。
  • バージョンが1つしかない場合（self-hosted-v18.2.0-ee）、self-hosted-v18.2.0-eeを使用します。

新しい機能はナイトリービルドから利用できますが、下位互換性は保証されていません。

ナイトリーバージョンの使用は、GitLabバージョンがAIゲートウェイリリースより古い場合や新しい場合に互換性の問題を引き起こす可能性があるため、not recommended。必ず明示的なバージョンタグを使用してください。

イメージからコンテナを開始する

  1. コンテナを起動するには、次のコマンドラインを実行します:

    docker run -d -p 5052:5052 -p 50052:50052 \
 -e AIGW_GITLAB_URL=<your_gitlab_instance> \
 -e AIGW_GITLAB_API_URL=https://<your_gitlab_domain>/api/v4/ \
 -e DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat duo_workflow_jwt.key)" \
 registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:<ai-gateway-tag>

    次のプレースホルダーを置き換えてください:

    • <your_gitlab_instance>: あなたのGitLabインスタンスのURL（例: https://gitlab.example.com）。
    • <your_gitlab_domain>: あなたのドメイン（例: gitlab.example.com）。
    • <ai-gateway-tag>: あなたのGitLabインスタンスに一致するバージョン。あなたのGitLabバージョンがvX.Y.0の場合、self-hosted-vX.Y.0-eeを使用します。

    コンテナホストからhttp://localhost:5052にアクセスすると、{"error":"No authorization header presented"}が返されるはずです。

  2. ホストから5052ポートと50052ポートがコンテナに転送されていることを確認してください。5052ポートはAIゲートウェイのHTTP通信を処理します。50052ポートはGitLab Duo Agent PlatformサービスのgRPC通信を処理します。

  3. オフラインライセンスを使用するGitLabインスタンスの場合、AIGWコンテナで-e DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL=（空文字列）を設定します。この設定では:

    • GitLab DuoワークフローサービスがローカルのGitLabインスタンスに対してのみ認証するように強制します。
    • CustomersDot呼び出しが到達不能であることによって引き起こされる20秒の遅延を解消します。

  4. AIゲートウェイ URLとGitLab Duo Agent PlatformサービスURLを設定します。

  5. モデルのセットアップに基づいてDUO_AGENT_PLATFORM_SERVICE_SECUREの環境変数を設定します:

    • TLSなしのセルフホストモデルを使用している場合、GitLabインスタンスでDUO_AGENT_PLATFORM_SERVICE_SECUREの環境変数をfalseに設定します:

      • Linuxパッケージインストールの場合: gitlab_rails['env']で、'DUO_AGENT_PLATFORM_SERVICE_SECURE' => falseを設定します。
      • セルフコンパイルインストールの場合: /etc/default/gitlabで、export DUO_AGENT_PLATFORM_SERVICE_SECURE=falseを設定します。

    • GitLabマネージドモデルを使用している場合、DUO_AGENT_PLATFORM_SERVICE_SECUREの環境変数は設定しないでください。

NGINXとSSLでDockerをセットアップする

NGINXまたはCaddyをリバースプロキシとしてデプロイするこの方法は、イシュー455854が実装されるまでのSSLをサポートする一時的な回避策です。

AIゲートウェイインスタンスにSSLを使用するには、次を使用します:

  • Docker
  • NGINXをリバースプロキシとして使用
  • SSL証明書にはLet’s Encrypt。

NGINXは外部クライアントとの安全な接続を管理します。受信したHTTPSリクエストをAIゲートウェイに渡す前に復号化する。

前提条件:

  • DockerおよびDocker Composeがインストール済み
  • 登録され設定済みのドメイン名

設定ファイルを作成する

作業ディレクトリに次のファイルを作成することから始めます。

  1. nginx.conf:

    user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;
events {
    worker_connections  1024;
}
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;
    sendfile        on;
    keepalive_timeout  65;
    include /etc/nginx/conf.d/*.conf;
}

  2. default.conf:

    # nginx/conf.d/default.conf
server {
    listen 80;
    server_name _;

    # Forward all requests to the AI Gateway
    location / {
        proxy_pass http://gitlab-ai-gateway:5052;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
        proxy_buffering off;
    }
}

server {
    listen 443 ssl;
    server_name _;

    # SSL configuration
    ssl_certificate /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    # Configuration for self-signed certificates
    ssl_verify_client off;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # Proxy headers
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket support (if needed)
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # Forward all requests to the AI Gateway
    location / {
        proxy_pass http://gitlab-ai-gateway:5052;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
        proxy_buffering off;
    }
}

  3. grpc-nginx.conf:

# Configuration for Duo Agent Platform with TLS
events {
    worker_connections 1024;
}

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;
    error_log /var/log/nginx/error.log debug;

    upstream grpcservers {
        server gitlab-ai-gateway:50052;
    }

    server {
        listen 8443 ssl;
        http2 on;

        ssl_certificate /etc/nginx/ssl/server.crt;
        ssl_certificate_key /etc/nginx/ssl/server.key;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;

        location / {
            grpc_pass grpc://grpcservers;
            grpc_set_header Host $host;
        }
    }
}

Let’s Encryptを使用してSSL証明書をセットアップする

SSL証明書をセットアップするには:

環境変数ファイルを作成する

.envファイルを作成してJWT署名キーを保存します:

echo "DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY=\"$(cat duo_workflow_jwt.key)\"" > .env

Docker Composeファイルを作成する

次に、docker-compose.yamlファイルを作成します。

services:
  nginx-proxy:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /path/to/nginx.conf:/etc/nginx/nginx.conf:ro
      - /path/to/default.conf:/etc/nginx/conf.d/default.conf:ro
      - /path/to/fullchain.pem:/etc/nginx/ssl/server.crt:ro
      - /path/to/privkey.pem:/etc/nginx/ssl/server.key:ro
    networks:
      - proxy-network
    depends_on:
      - gitlab-ai-gateway

grpc-proxy:
    image: nginx:alpine
    ports:
      - "8443:8443"
    volumes:
      - /path/to/grpc-nginx.conf:/etc/nginx/nginx.conf:ro
      - /path/to/fullchain.pem:/etc/nginx/ssl/server.crt:ro
      - /path/to/privkey.pem:/etc/nginx/ssl/server.key:ro
    networks:
      - proxy-network
    depends_on:
      - gitlab-ai-gateway
    restart: always

  gitlab-ai-gateway:
    image: registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:<ai-gateway-tag>
    ports:
      - "50052:50052" # Agent Platform gRPC exposed to the host
    expose:
      - "5052" # Only exposed internally to the proxy network
    environment:
      - AIGW_GITLAB_URL=<your_gitlab_instance>
      - AIGW_GITLAB_API_URL=https://<your_gitlab_domain>/api/v4/
    env_file:
      - .env
    networks:
      - proxy-network
    restart: always

networks:
  proxy-network:
    driver: bridge

デプロイして検証する

ソリューションをデプロイして検証するには:

  1. nginxおよびAIGWのコンテナを開始し、それらが実行されていることを確認します:

    docker compose up
docker ps

  2. GitLabのインスタンスがAIゲートウェイにアクセスできるように設定します。

  3. GitLabインスタンスがGitLab Duo Agent PlatformサービスのURLにアクセスできるように設定します。

  4. ヘルスチェックを実行し、AIゲートウェイとエージェントPlatformの両方にアクセスできることを確認します。

Helmチャートを使用してインストールする

前提条件:

  • 次の条件を満たしている必要があります:
    • あなたが所有するドメインで、DNSレコードを追加できること。
    • Kubernetesクラスター。
    • kubectlの動作するインストール。
    • Helmの動作するインストール（バージョンv3.11.0以降）。

詳細については、GKEまたはEKSでGitLabチャートをテストするを参照してください。

AIゲートウェイHelmリポジトリを追加する

AIゲートウェイHelmリポジトリをHelm設定に追加します:

helm repo add ai-gateway \
https://gitlab.com/api/v4/projects/gitlab-org%2fcharts%2fai-gateway-helm-chart/packages/helm/devel

AIゲートウェイをインストール

  1. ai-gatewayネームスペースを作成します:

    kubectl create namespace ai-gateway

  2. AIゲートウェイを公開する予定のドメインの証明書を生成します。

  3. 以前に作成したネームスペースにTLSシークレットを作成します:

    kubectl -n ai-gateway create secret tls ai-gateway-tls --cert="<path_to_cert>" --key="<path_to_cert_key>"

  4. チャートのパッケージレジストリで最新パッケージのバージョン番号を取得します。

  5. AIゲートウェイがAPIにアクセスするには、GitLabインスタンスがどこにあるかを知る必要があります。これを行うには、gitlab.urlとgitlab.apiUrlをingress.hostsとingress.tlsの値と共に次のように設定します:

    helm repo add ai-gateway \
  https://gitlab.com/api/v4/projects/gitlab-org%2fcharts%2fai-gateway-helm-chart/packages/helm/devel
helm repo update

helm upgrade --install ai-gateway \
  ai-gateway/ai-gateway \
  --version <latest-package-in-registery> \
  --namespace=ai-gateway \
  --set="image.tag=<ai-gateway-image-version>" \
  --set="gitlab.url=https://<your_gitlab_domain>" \
  --set="gitlab.apiUrl=https://<your_gitlab_domain>/api/v4/" \
  --set "ingress.enabled=true" \
  --set "ingress.hosts[0].host=<your_gateway_domain>" \
  --set "ingress.hosts[0].paths[0].path=/" \
  --set "ingress.hosts[0].paths[0].pathType=ImplementationSpecific" \
  --set "ingress.tls[0].secretName=ai-gateway-tls" \
  --set "ingress.tls[0].hosts[0]=<your_gateway_domain>" \
  --set="ingress.className=nginx" \
  --set "extraEnvironmentVariables[0].name=DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY" \
  --set "extraEnvironmentVariables[0].value=$(cat duo_workflow_jwt.key)" \
  --timeout=300s --wait --wait-for-jobs

image.tagとして使用できるAIゲートウェイバージョンのリストは、コンテナレジストリで確認できます。

このステップは、すべてのリソースが割り当てられAIゲートウェイが起動するまで数秒かかる場合があります。

既存のnginxIngressコントローラーが別のネームスペース内のサービスを提供しない場合、AIゲートウェイ用に独自のIngress Controllerをセットアップする必要があるかもしれません。マルチネームスペースデプロイメント用にIngressが正しく設定されていることを確認してください。

ai-gatewayHelmチャートのバージョンについては、helm search repo ai-gateway --versionsを使用して適切なチャートバージョンを見つけてください。

ポッドが起動して実行されるのを待ちます:

kubectl wait pod \
  --all \
  --for=condition=Ready \
  --namespace=ai-gateway \
  --timeout=300s

ポッドが起動して実行されたら、IPイングレスとDNSレコードをセットアップできます。

自己署名SSL証明書を使用してGitLabインスタンスまたはモデルエンドポイントに接続する

GitLabインスタンスまたはモデルエンドポイントが自己署名証明書で設定されている場合、ルート認証局（CA）証明書をAIゲートウェイの証明書バンドルに追加する必要があります。

これを行うには、次のいずれかの方法があります:

  • ルート認証局証明書をAIゲートウェイに渡して、認証が成功するようにします。
  • ルート認証局証明書をAIゲートウェイコンテナのCAバンドルに追加します。

ルート認証局証明書をAIゲートウェイに渡す

ルート認証局証明書をAIゲートウェイに渡し、認証が成功するようにするには、REQUESTS_CA_BUNDLEの環境変数を設定します。GitLabは信頼できるベースCAリストにCertifiを使用するため、カスタムCAバンドルを次のように設定します:

  1. Certifi cacert.pemファイルをダウンロードします:

    curl "https://raw.githubusercontent.com/certifi/python-certifi/2024.07.04/certifi/cacert.pem" --output cacert.pem

  2. 自己署名ルート認証局証明書をファイルに追加します。たとえば、mkcertを使用して証明書を作成した場合:

    cat "$(mkcert -CAROOT)/rootCA.pem" >> path/to/your/cacert.pem

  3. REQUESTS_CA_BUNDLEをcacert.pemファイルのパスに設定します。たとえば、GDKでは、$GDK_ROOT/env.runitに以下を追加します:

    export REQUESTS_CA_BUNDLE=/path/to/your/cacert.pem

ルート認証局証明書をAIゲートウェイコンテナのCAバンドルに追加する

AIゲートウェイがカスタム認証局によって署名されたGitLabSelf-Managedインスタンスの証明書を信頼できるようにするには、ルート認証局証明書をAIゲートウェイコンテナのCAバンドルに追加します。

この方法では、チャートのバージョンでルートCAバンドルに加えられた変更は許可されません。

AIゲートウェイのHelmチャートデプロイメントに対してこれを行うには:

  1. カスタムルート認証局証明書をローカルファイルに追加します:

    cat customCA-root.crt >> ca-certificates.crt

  2. AIゲートウェイコンテナから/etc/ssl/certs/ca-certificates.crtバンドルファイルをローカルファイルにコピーします:

    kubectl cp -n gitlab ai-gateway-55d697ff9d-j9pc6:/etc/ssl/certs/ca-certificates.crt ca-certificates.crt.

  3. ローカルファイルから新しいシークレットを作成します:

    kubectl create secret generic ca-certificates -n gitlab --from-file=cacertificates.crt=ca-certificates.crt

  4. values.ymlのシークレットを使用して、volumeとvolumeMountを定義します。これにより、/tmp/ca-certificates.crtファイルがコンテナ内に作成されます:

    volumes:
  - name: cacerts
    secret:
      secretName: ca-certificates
      optional: false

volumeMounts:
  - name: cacerts
    mountPath: "/tmp"
    readOnly: true

  5. マウントされたファイルを指すようにREQUESTS_CA_BUNDLEとSSL_CERT_FILEの環境変数を設定します:

    extraEnvironmentVariables:
  - name: REQUESTS_CA_BUNDLE
    value: /tmp/ca-certificates.crt
  - name: SSL_CERT_FILE
    value: /tmp/ca-certificates.crt

  6. チャートを再デプロイします。

Helmチャートでこれをネイティブにサポートするためのイシュー3が存在します。

Dockerデプロイの場合

Dockerデプロイの場合は、同じ方法を使用します。唯一の違いは、ローカルファイルをコンテナにマウントするには、--volume /root/ca-certificates.crt:/tmp/ca-certificates.crtを使用することです。

AIゲートウェイDockerイメージをアップグレードする

AIゲートウェイをアップグレードするには、最新のDockerイメージタグをダウンロードします。

  1. 実行中のコンテナを停止します。

    sudo docker stop gitlab-aigw

  2. 既存のコンテナを削除します。

    sudo docker rm gitlab-aigw

  3. イメージをプルするし、新しいイメージを実行します。

  4. 環境変数がすべて正しく設定されていることを確認します。

GitLab Dedicatedインスタンスの追加インストール手順

セルフホストモデルのAIゲートウェイにアクセスするには、GitLab Dedicatedインスタンス用のセルフホストモデルのAIゲートウェイを参照してください。

セキュリティアップデートとイメージの検証

最新のセキュリティパッチを実行していることを確認するには、デプロイ方法に基づいて次のガイドラインに従ってください。

KubernetesまたはHelmのデプロイの場合

0.7.0より前のチャートバージョンとKubernetesは、デフォルトでimagePullPolicy: IfNotPresentを使用します。これは、タグが変更されていない場合、更新されたイメージをプルすることはありません。これは、同じバージョンタグでリリースされたセキュリティパッチを見逃す可能性があることを意味します。

イメージダイジェストを使用する次のアプローチを使用してください:

# Find the image digest from the container registry
# Use this digest in your Helm install/upgrade command

helm upgrade --install ai-gateway \
  ai-gateway/ai-gateway \
  --set="image.tag=self-hosted-v18.2.1-ee@sha256:abc123..." \
  # ... other flags

あるいは、次のいずれかの方法でimagePullPolicyを使用することもできます:

  • imagePullPolicyを常に以下のように設定します:

    helm upgrade --install ai-gateway \
  ai-gateway/ai-gateway \
  --set="image.pullPolicy=Always" \
  # ... other flags

  • pullPolicyをvalues.yamlに追加します:

    image:
  pullPolicy: Always

更新のプルするを強制するには:

kubectl rollout restart deployment/ai-gateway -n ai-gateway

Dockerデプロイの場合

アップグレード時には、最新のイメージをプルするしていることを検証するしてください:

# Check current image digest
docker images --digests | grep ai-assist

# Pull latest version explicitly
docker pull registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:<ai-gateway-tag>

# Verify digest changed
docker images --digests | grep ai-assist

イミュータブルデプロイメントにイメージダイジェストを使用するには:

docker run -d -p 5052:5052 -p 50052:50052 \
 -e AIGW_GITLAB_URL=<your_gitlab_instance> \
 -e AIGW_GITLAB_API_URL=https://<your_gitlab_domain>/api/v4/ \
 -e DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat duo_workflow_jwt.key)" \
 registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v18.2.1-ee@sha256:abc123...

その他のインストール方法

AIゲートウェイの代替インストール方法については、イシュー463773を参照してください。

ヘルスチェックとデバッグ

GitLab Duoセルフホストモデルのインストールに関する問題をデバッグするには、次のコマンドラインを実行します:

sudo gitlab-rake gitlab:duo:verify_self_hosted_setup

以下を確認してください:

  • AIゲートウェイのURLは正しく設定されています（Ai::Setting.instance.ai_gateway_url経由）。
  • GitLab Duoへのアクセスは、ルートユーザーに対して/admin/code_suggestionsを通じて明示的に有効化されています。

アクセスイシューが解決しない場合は、認証が正しく設定されていること、およびヘルスチェックが合格していることを確認してください。

解決しないイシューがある場合、エラーメッセージはAIGW_AUTH__BYPASS_EXTERNAL=trueで認証をバイパスすることを提案するかもしれませんが、これはトラブルシューティングの場合のみにしてください。

また、管理者 > GitLab Duoに移動してヘルスチェックを実行することもできます。

これらのテストはオフライン環境で実行されます:

テスト説明
ネットワーク次の項目をテストします:
- AIゲートウェイのURLがai_settingsテーブルを通じてデータベースに適切に設定されているか。
- あなたのインスタンスが設定されたURLに接続できるか。

あなたのインスタンスがURLに接続できない場合、ファイアウォールまたはプロキシサーバーの設定が接続を許可していることを確認してください。環境変数AI_GATEWAY_URLはレガシー互換性のために依然としてサポートされていますが、管理のしやすさの観点から、データベースを通じてURLを設定することをお勧めします。
ライセンスライセンスにコード提案機能へのアクセス権があるかどうかをテストします。
システム連携インスタンスでコード提案を使用できるかどうかをテストします。システム連携アセスメントが失敗した場合、ユーザーはGitLab Duo機能を使用できない可能性があります。

AIゲートウェイを監視する

Prometheusを使用して、AIゲートウェイの使用状況とパフォーマンスに関するメトリクスを収集します。

AIゲートウェイ用のPrometheusメトリクスをセットアップする

Prometheusメトリクスをセットアップするには:

  1. 必要な環境変数を設定し、8082ポートを開きます:

    -e AIGW_FASTAPI__METRICS_HOST=0.0.0.0
-e AIGW_FASTAPI__METRICS_PORT=8082

GitLab Duoワークフローサービス用のPrometheusをセットアップする

GitLab DuoワークフローサービスでPrometheusメトリクスをセットアップするには:

  1. 必要な環境変数を設定し、8083ポートを開きます:

    -e PROMETHEUS_METRICS__ADDR=0.0.0.0
-e PROMETHEUS_METRICS__PORT=8083

  2. gitlab-ai-gatewayコンテナからホストにメトリクスポートを公開します:

    • DockerCLIの場合:

      -p 8082:8082 \
-p 8083:8083 \

    • Docker Composeの場合、gitlab-ai-gatewayサービスに追加します:

      ports:
  - "8082:8082"
  - "8083:8083"

    これにより、AIゲートウェイメトリクスエンドポイントは8082ポートで、GitLab Duoワークフローサービスメトリクスエンドポイントは8083ポートで公開されます。

  3. AIゲートウェイコンテナを再起動します。

Prometheusをメトリクスをスクレイプするように設定する

AIゲートウェイおよびGitLab Duoワークフローサービスからメトリクスを収集するには、次のprometheus.yml設定をPrometheusインスタンスに追加します。この設定では、Prometheusは15秒ごとに両方のサービスからメトリクスをスクレイプするします。

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'ai-gateway'
    static_configs:
      - targets: ['<your_AIGW_domain>:8082']
    scheme: 'http'
    metrics_path: '/metrics'

  - job_name: 'duo-agent-platform-service'
    static_configs:
      - targets: ['<your_duo_agent_platform_service_domain>:8083']
    scheme: 'http'
    metrics_path: '/metrics'

メトリクス収集の検証する

AIゲートウェイとGitLab Duoワークフローサービスのターゲットが収集されていることを検証するには:

  1. PrometheusUIで、ステータス > Targetsに移動します。

  2. アラートまたはグラフタブに移動してメトリクスをクエリするします。AIゲートウェイとGitLab Duoワークフローサービスは、次のエンドポイントでメトリクスを公開します:

    • AIゲートウェイ: http://<your_AIGW_domain>:8082/metrics
    • GitLab Duoワークフローサービス: http://<your_duo_agent_platform_service_domain>:8083/metrics

AIゲートウェイはオートスケールする必要がありますか？

オートスケールは必須ではありませんが、変動するワークロード、高い並行処理要件、または予測不能な使用パターンを持つ環境には推奨されます。GitLabの本番環境では:

  • ベースラインセットアップ: 2 CPUコアと8 GB RAMを搭載した単一のAIゲートウェイインスタンスは、約40件の並行処理リクエストを処理できます。
  • スケーリングガイドライン: AWS t3.2xlargeインスタンス（8 vCPU、32 GB RAM）のような大規模なセットアップでは、このゲートウェイは最大160件の並行処理リクエストを処理でき、これはベースラインセットアップの4倍に相当します。
  • リクエストスループット: GitLab.comで観測された使用状況によると、1000アクティブユーザーあたり7 RPS（1秒あたりのリクエスト数）は、計画にとって妥当なメトリクスです。
  • オートスケールのオプション: Kubernetes Horizontal Pod Autoscalers（HPA）または同様のメカニズムを使用して、CPU、メモリ使用率、または要求レイテンシーしきい値などのメトリクスに基づいてインスタンスの数を動的に調整します。

デプロイサイズ別の設定例

  • 小規模デプロイ:
    • 2 vCPUと8 GB RAMを備えた単一のインスタンス。
    • 最大40件の並行処理リクエストを処理します。
    • 最大50ユーザーで予測可能なワークロードを持つチームまたは組織。
    • 固定されたインスタンスで十分な場合があります。コスト効率性のためにオートスケールを無効にすることができます。
  • 中規模デプロイ:
    • 8 vCPUと32 GB RAMを備えた単一のAWS t3.2xlargeインスタンス。
    • 最大160件の並行処理リクエストを処理します。
    • 50～200ユーザーで中程度の並行処理要件を持つ組織。
    • Kubernetes HPAを、CPU使用率が50％を超える、または要求レイテンシーが500ミリ秒を超えるしきい値で実装します。
  • 大規模デプロイ:
    • 複数のAWS t3.2xlargeインスタンスまたは同等のクラスター。
    • 各インスタンスは160件の並行処理リクエストを処理し、複数のインスタンスで数千人のユーザーにスケールするできます。
    • 200人を超えるユーザーと変動する高並行処理ワークロードを持つ企業。
    • HPAを使用してリアルタイムの需要に基づいてポッドをスケールするし、クラスター全体のリソース調整のためにノードオートスケールと組み合わせます。

AIゲートウェイコンテナはどのような仕様にアクセスでき、リソース割り当てはパフォーマンスにどのように影響しますか？

AIゲートウェイは次のリソース割り当ての下で効果的に動作します:

  • コンテナあたり2 CPUコアと8 GBのRAM。
  • コンテナは通常、GitLab本番環境で約7.39％のCPUとそれに比例するメモリを使用し、成長またはバーストアクティビティを処理するための余地を残しています。

リソース競合の緩和戦略

  • Kubernetesのリソースリクエストと制限を使用して、AIゲートウェイコンテナが保証されたCPUとメモリ割り当てを受け取るようにします。例:

    resources:
  requests:
    memory: "16Gi"
    cpu: "4"
  limits:
    memory: "32Gi"
    cpu: "8"

  • PrometheusやGrafanaのようなツールを実装して、リソース使用率（CPU、メモリ、レイテンシー）を追跡するし、ボトルネックを早期に検出します。

  • ノードまたはインスタンスをAIゲートウェイに排他的に割り当てて、他のサービスとのリソース競合を防ぎます。

スケーリング戦略

  • Kubernetes HPAを使用して、次のようなリアルタイムメトリクスに基づいてポッドをスケールするします:
    • 平均CPU使用率が50％を超える。
    • 要求レイテンシーが常に500ミリ秒を超える。
    • ノードオートスケールを有効にして、ポッドの増加に応じてインフラストラクチャリソースを動的にスケールするします。

スケーリング推奨事項

デプロイサイズインスタンスタイプリソース容量（並行処理リクエスト）スケーリング推奨事項
S2 vCPU、8 GB RAM単一のインスタンス40固定デプロイ。 オートスケールなし。
中程度AWS t3.2xlarge単一のインスタンス160CPUまたはレイテンシーのしきい値に基づくHPA。
L複数のt3.2xlargeクラスター化されたインスタンスインスタンスあたり160HPA + 高需要向けノードオートスケール。

複数のGitLabインスタンスをサポートする

単一のAIゲートウェイをデプロイして複数のGitLabインスタンスをサポートすることも、インスタンスごとまたは地理的リージョンごとに個別のAIゲートウェイをデプロイすることもできます。どちらが適切かを判断するのに役立つのは次の点です:

  • 1,000請求対象ユーザーあたり約7 1秒あたりのリクエスト数の予想トラフィック。
  • すべてのインスタンスにおける合計並行処理リクエストに基づくリソース要件。
  • 各GitLabインスタンスのベストプラクティス認証設定。

AIゲートウェイとインスタンスを併置する

AIゲートウェイは、場所に関わらずユーザーに最適なパフォーマンスを保証するために、世界中の複数の地域で利用可能です:

  • GitLab Duo機能の応答時間の改善。
  • 地理的に分散したユーザーのレイテンシーの削減。
  • データ主権要件のコンプライアンス。

AIゲートウェイをGitLabインスタンスと同じ地理的リージョンに配置して、特にコード提案のようなレイテンシーの影響を受けやすい機能で、スムーズなDevExを提供できるようにする必要があります。

トラブルシューティング

AIゲートウェイを使用する際、次のイシューに遭遇する可能性があります。

OpenShiftの権限イシュー

OpenShiftにAIゲートウェイをデプロイする際、OpenShiftのセキュリティモデルにより権限エラーが発生する可能性があります。

/tmpにある読み取り専用ファイルシステム

AIゲートウェイは/tmpに書き込む必要があります。ただし、セキュリティ制限のあるOpenShift環境では、/tmpは読み取り専用である可能性があります。

このイシューを解決するするには、新しいEmptyDirボリュームを作成し、それを/tmpにマウントします。これを行うには、次のいずれかの方法があります:

  • コマンドラインから:

    oc set volume <object_type>/<name> --add --name=tmpVol --type=emptyDir --mountPoint=/tmp

  • values.yamlに追加:

    volumes:
- name: tmp-volume
  emptyDir: {}

volumeMounts:
- name: tmp-volume
  mountPath: "/tmp"

HuggingFaceモデル

デフォルトでは、AIゲートウェイはHuggingFaceモデルのキャッシュに/home/aigateway/.hfを使用しますが、これはOpenShiftのセキュリティ制限された環境では書き込み可能でない場合があります。これにより、次のような権限エラーが発生する可能性があります:

[Errno 13] Permission denied: '/home/aigateway/.hf/...'

これを解決するするには、HF_HOMEの環境変数を書き込み可能な場所に設定します。/var/tmp/huggingfaceまたはコンテナが書き込み可能なその他のディレクトリを使用できます。

これを設定するには、次のいずれかの方法があります:

  • values.yamlに追加:

    extraEnvironmentVariables:
  - name: HF_HOME
    value: /var/tmp/huggingface  # Use any writable directory

  • または、Helmアップグレードコマンドラインに含めます:

    --set "extraEnvironmentVariables[0].name=HF_HOME" \
--set "extraEnvironmentVariables[0].value=/var/tmp/huggingface"  # Use any writable directory

この設定により、AIゲートウェイはOpenShiftのセキュリティ制約を尊重しつつ、HuggingFaceモデルを適切にキャッシュできます。選択する正確なディレクトリは、特定のOpenShift設定とセキュリティポリシーによって異なる場合があります。

自己署名証明書エラー

AIゲートウェイがカスタム認証局（CA）によって署名された証明書または自己署名証明書を使用してGitLabインスタンスまたはモデルエンドポイントに接続しようとすると、AIゲートウェイによって[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chainエラーがログに記録されます。

これを解決するするには、自己署名SSL証明書を使用してGitLabインスタンスまたはモデルエンドポイントに接続するを参照してください。

PEMファイルの読み込み時のSSL証明書エラー

DockerコンテナにPEMファイルを読み込む際にJWKErrorというエラーが発生した場合、SSL証明書エラーを解決する必要があるかもしれません。

このイシューを修正するには、Dockerコンテナで適切な証明書バンドルパスを設定するために、次の環境変数を使用します:

  • SSL_CERT_FILE=/path/to/ca-bundle.pem
  • REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

/path/to/ca-bundle.pemを証明書バンドルのパスに置き換えます。