AIゲートウェイのトラブルシューティング
AIゲートウェイを使用する際に、次の問題が発生する可能性があります。
OpenShiftのパーミッションの問題
OpenShiftにAIゲートウェイをデプロイする場合、OpenShiftのセキュリティモデルにより、パーミッションエラーが発生することがあります。
/tmpでの読み取り専用ファイルシステム
AIゲートウェイは/tmpに書き込みます。ただし、OpenShift環境はセキュリティ制限があるため、/tmpが読み取り専用になっている場合があります。
この問題を解決するには、新しいEmptyDirボリュームを作成し、次のいずれかの方法で/tmpにマウントします:
コマンドラインから:
oc set volume <object_type>/<name> --add --name=tmpVol --type=emptyDir --mountPoint=/tmpvalues.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 directoryHelmのアップグレードコマンド内:
--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ゲートウェイのポッドで次を実行します:
ls -la /home/aigateway/.hf/hub/ 2>/dev/null || echo "NO_CACHE_DIR"
env | grep -E '^(HF_|TRANSFORMERS_)'キャッシュディレクトリが存在しないか空の場合は、次の操作を行います:
/home/aigateway/.hfまたはHF_HOMEで設定されたパスを対象とするvolumeMountsがないか、values.yamlを確認します。- マウントを削除するか、イメージの組み込みキャッシュと重複しないディレクトリに再マッピングします。
自己署名証明書のエラー
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の逆シリアル化に失敗します。
この問題を解決するには:
必要なキーを生成します:
openssl genrsa -out aigw_signing.key 2048 openssl genrsa -out aigw_validation.key 2048環境変数として渡すことで、キーをAIゲートウェイコンテナに追加します:
-e AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \ -e AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)"AIゲートウェイコンテナを再起動します。
PEMファイルを読み込む際のSSL証明書エラー
PEMファイルをDockerコンテナに読み込む際にJWKErrorというエラーが表示される場合、SSL証明書エラーを解決する必要がある可能性があります。
この問題を解決するには、次の環境変数を使用して、Dockerコンテナ内の適切な証明書バンドルパスを設定します:
SSL_CERT_FILE=/path/to/ca-bundle.pemREQUESTS_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インスタンスへの課金イベントの送信を参照してください。