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

AIゲートウェイのトラブルシューティング

AIゲートウェイを使用する際に、次の問題が発生する可能性があります。

OpenShiftのパーミッションの問題

OpenShiftにAIゲートウェイをデプロイする場合、OpenShiftのセキュリティモデルにより、パーミッションエラーが発生することがあります。

/tmpでの読み取り専用ファイルシステム

AIゲートウェイは/tmpに書き込みます。ただし、OpenShift環境はセキュリティ制限があるため、/tmpが読み取り専用になっている場合があります。

この問題を解決するには、新しいEmptyDirボリュームを作成し、次のいずれかの方法で/tmpにマウントします:

  • コマンドラインから:

    shell
    oc set volume <object_type>/<name> --add --name=tmpVol --type=emptyDir --mountPoint=/tmp
  • values.yaml内:

    yaml
    volumes:
    - name: tmp-volume
      emptyDir: {}
    
    volumeMounts:
    - name: tmp-volume
      mountPath: "/tmp"

HuggingFaceモデル

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

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

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

  • values.yaml内:

    yaml
    extraEnvironmentVariables:
      - name: HF_HOME
        value: /var/tmp/huggingface  # Use any writable directory
  • Helmのアップグレードコマンド内:

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

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

ボリュームマウントによってトークナイザーのキャッシュが隠される問題

次の場合、AIゲートウェイイメージ内の事前キャッシュされたトークナイザーファイルがボリュームマウントによって隠されることがあります:

  • コード補完のリクエストが500エラーを返す。
  • AIゲートウェイのログに、transformers/utils/hub.pyからSalesforce/codegen2-16Bをhuggingface.coからダウンロードしようとして発生したOSErrorが表示される。

セルフホストのAIゲートウェイイメージ(self-hosted-vX.Y.Z-ee)はHF_HUB_OFFLINE=trueを設定し、ビルド時にトークナイザーを事前キャッシュするため、実行時にhuggingface.coへのネットワークアクセスは発生しないはずです。ネットワークアクセスが発生する場合、Helmの値にある空のディレクトリが/home/aigateway/.hfにマウントされ、キャッシュされたファイルが上書きされている可能性があります。

huggingface.coへのエグレスアクセスを許可することでこの問題を解決しようとしないでください。代わりに、問題を診断するには、AIゲートウェイのポッドで次を実行します:

shell
ls -la /home/aigateway/.hf/hub/ 2>/dev/null || echo "NO_CACHE_DIR"
env | grep -E '^(HF_|TRANSFORMERS_)'

キャッシュディレクトリが存在しないか空の場合は、次の操作を行います:

  1. /home/aigateway/.hfまたはHF_HOMEで設定されたパスを対象とするvolumeMountsがないか、values.yamlを確認します。
  2. マウントを削除するか、イメージの組み込みキャッシュと重複しないディレクトリに再マッピングします。

自己署名証明書のエラー

AIゲートウェイが、カスタム認証局(CA)によって署名された証明書または自己署名証明書を使用しているGitLabインスタンスまたはモデルエンドポイントに接続しようとすると、次のエラーが発生することがあります:

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

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

トークン作成の失敗

GitLab Duo Chatなどの機能を使用する際にToken creation failedエラーが発生する場合、AIゲートウェイにAIGW_SELF_SIGNED_JWT__SIGNING_KEYおよびAIGW_SELF_SIGNED_JWT__VALIDATION_KEY環境変数が設定されていない可能性があります。

これらのキーは、AIゲートウェイが短期間有効なユーザーJWTを発行するために必要です。これらのキーがない場合、AIゲートウェイはトークンに署名できず、JWKの逆シリアル化に失敗します。

この問題を解決するには:

  1. 必要なキーを生成します:

    shell
    openssl genrsa -out aigw_signing.key 2048
    openssl genrsa -out aigw_validation.key 2048
  2. 環境変数として渡すことで、キーをAIゲートウェイコンテナに追加します:

    shell
    -e AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \
    -e AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)"
  3. AIゲートウェイコンテナを再起動します。

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

PEMファイルをDockerコンテナに読み込む際にJWKErrorというエラーが表示される場合、SSL証明書エラーを解決する必要がある可能性があります。

この問題を解決するには、次の環境変数を使用して、Dockerコンテナ内の適切な証明書バンドルパスを設定します:

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

/path/to/ca-bundle.pemを、お使いの証明書バンドルへのパスに置き換えてください。

オフラインのGitLabインスタンスに課金イベントを送信する際のエラー

オフライン環境では、AIゲートウェイはGitLabインスタンス上の/api/v4/ai/billable_usage/events APIエンドポイントにイベントを送信します。リクエストが失敗した場合は、AIゲートウェイのログでレスポンスのステータスを確認してください:

  • 401: AIGW_BILLING_EVENT__API_KEYが設定されていないか、トークンが無効です。
  • 403: トークンにai_featuresスコープがないか、サービスアカウントに属していません。
  • 404: local_billing_persistence機能フラグが無効になっているか、GitLabインスタンスがオフラインライセンスを使用していません。

詳細については、GitLabインスタンスへの課金イベントの送信を参照してください。