GitLab Duoセルフホストモデルのトラブルシューティング

プラン: Premium、Ultimate
アドオン: GitLab Duo Enterprise
提供形態: GitLab Self-Managed

GitLab 17.1でai_custom_modelフラグとともに導入されました。デフォルトでは無効になっています。
GitLab 17.6のGitLab Self-Managedで有効になりました。
GitLab 17.6以降、GitLab Duoアドオンが必須となりました。
機能フラグai_custom_modelはGitLab 17.8で削除されました。
GitLab 17.9で一般提供となりました。
GitLab 18.0で、Premiumに含まれるようになりました。

GitLab Duoセルフホストモデルを使用していると、問題が発生することがあります。

トラブルシューティングを開始する前に、次のことを行う必要があります:

gitlab-railsコンソールにアクセスできること。
AIゲートウェイDockerイメージでShellを開きます。
以下のエンドポイントを知っておくこと:
- AIゲートウェイがホストされている場所
- モデルがホストされている場所
ログを有効化して、GitLabからAIゲートウェイへのリクエストとレスポンスがllm.logに記録されていることを確認します。

GitLab Duoのトラブルシューティングの詳細については、以下を参照してください:

GitLab Duoのトラブルシューティング
コード提案のトラブルシューティング。
GitLab Duo Chatのトラブルシューティング

デバッグスクリプトを使用する

管理者がセルフホストモデルの設定を検証するのに役立つ、2つのデバッグスクリプトを提供しています。

GitLabからAIゲートウェイへの接続をデバッグします。GitLabインスタンスから、Rakeタスクを実行します:
```
gitlab-rake "gitlab:duo:verify_self_hosted_setup[<username>]"
```
（オプション）: 割り当てられたシートを持つ<username>を含めます。ユーザー名パラメータを含めない場合、Rakeタスクはrootユーザー名を使用します。

AIゲートウェイのセットアップをデバッグします。AIゲートウェイコンテナの場合:

次のように設定して、認証を無効にしてAIゲートウェイコンテナを再起動します:
```
-e AIGW_AUTH__BYPASS_EXTERNAL=true
```
この設定は、トラブルシューティングコマンドがSystem Exchange test（システム交換テスト）を実行するために必要です。トラブルシューティングが完了したら、この設定を削除する必要があります。

AIゲートウェイコンテナから、以下を実行します:

docker exec -it <ai-gateway-container> sh
poetry run troubleshoot [options]

troubleshootコマンドは、次のオプションをサポートしています:

オプション	デフォルト	例	説明
`--endpoint`	`localhost:5052`	`--endpoint=localhost:5052`	AIゲートウェイエンドポイント
`--model-family`	-	`--model-family=mistral`	テストするモデルファミリー。使用できる値は、`mistral`、`mixtral`、`gpt`、または`claude_3`です。
`--model-endpoint`	-	`--model-endpoint=http://localhost:4000/v1`	モデルエンドポイント。vLLMでホストされているモデルの場合は、`/v1`サフィックスを追加します。
`--model-identifier`	-	`--model-identifier=custom_openai/Mixtral-8x7B-Instruct-v0.1`	モデル識別子。
`--api-key`	-	`--api-key=your-api-key`	モデルAPIキー。

Examples（例）:

AWS Bedrockで実行されているclaude_3モデルの場合:

poetry run troubleshoot \
  --model-family=claude_3 \
  --model-identifier=bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0

vLLMで実行されているmixtralモデルの場合:

poetry run troubleshoot \
  --model-family=mixtral \
  --model-identifier=custom_openai/Mixtral-8x7B-Instruct-v0.1 \
  --api-key=your-api-key \
  --model-endpoint=http://<your-model-endpoint>/v1

トラブルシューティングが完了したら、AIGW_AUTH__BYPASS_EXTERNAL=truewithout（なしで）AIゲートウェイコンテナを停止して再起動します。

本番環境で認証を回避しないでください。

コマンドの出力を検証し、必要に応じて修正します。

両方のコマンドが成功しても、GitLab Duoコード提案がまだ機能しない場合は、イシュートラッカーでイシューを提起してください。

GitLab Duoヘルスチェックが機能していません

GitLab Duoのヘルスチェックを実行すると、401 response from the AI gatewayのようなエラーが発生する場合があります。

解決するには、まずGitLab Duoの機能が正しく機能しているかどうかを確認してください。たとえば、Duoチャットにメッセージを送信します。

これで問題が解決しない場合、GitLab Duoヘルスチェックの既知の問題が原因である可能性があります。詳細については、issue 517097を参照してください。

GitLabがモデルにリクエストを送信できるかどうかを確認する

GitLab Railsコンソールから、次のコマンドを実行して、GitLabがモデルにリクエストを送信できることを検証します:

model_name = "<your_model_name>"
model_endpoint = "<your_model_endpoint>"
model_api_key = "<your_model_api_key>"
body = {:prompt_components=>[{:type=>"prompt", :metadata=>{:source=>"GitLab EE", :version=>"17.3.0"}, :payload=>{:content=>[{:role=>:user, :content=>"Hello"}], :provider=>:litellm, :model=>model_name, :model_endpoint=>model_endpoint, :model_api_key=>model_api_key}}]}
ai_gateway_url = Ai::Setting.instance.ai_gateway_url # Verify that the AI gateway URL is set in the database
client = Gitlab::Llm::AiGateway::Client.new(User.find_by_id(1), unit_primitive_name: :self_hosted_models)
client.complete(url: "#{ai_gateway_url}/v1/chat/agent", body: body)

これは、次の形式でモデルからのレスポンスを返すはずです:

{"response"=> "<Model response>",
 "metadata"=>
  {"provider"=>"litellm",
   "model"=>"<>",
   "timestamp"=>1723448920}}

そうでない場合、これは次のいずれかを意味する可能性があります:

ユーザーがコード提案にアクセスできない可能性があります。解決するには、ユーザーがコード提案をリクエストできるかどうかを確認してください。
GitLabの環境変数が正しく設定されていません。解決するには、GitLabの環境変数が正しくセットアップされていることを確認してください。
GitLabインスタンスが、セルフホストモデルを使用するように設定されていません。解決するには、GitLabインスタンスが、セルフホストモデルを使用するように設定されているかどうかを確認します。
AIゲートウェイに到達できません。解決するには、GitLabがAIゲートウェイにHTTPリクエストを送信できるかどうかを確認します。
LLMサーバーがAIゲートウェイコンテナと同じインスタンスにインストールされている場合、ローカルリクエストが機能しない可能性があります。解決するには、Dockerコンテナからのローカルリクエストを許可します。

ユーザーがコード提案をリクエストできるかどうかを確認する

GitLab Railsコンソールで、次のコマンドを実行して、ユーザーがコード提案をリクエストできるかどうかを確認します:

User.find_by_id("<user_id>").can?(:access_code_suggestions)

これによりfalseが返される場合、いくつかの設定が欠落しており、ユーザーはコード提案にアクセスできません。

この欠落している設定は、次のいずれかが原因である可能性があります:

ライセンスが有効ではありません。解決するには、ライセンスを確認または更新してください。
GitLab Duoが、セルフホストモデルを使用するように設定されていません。解決するには、GitLabインスタンスが、セルフホストモデルを使用するように設定されているかどうかを確認します。

GitLabインスタンスがセルフホストモデルを使用するように設定されているかどうかを確認する

GitLab Duoが正しく設定されているかどうかを確認するには:

左側のサイドバーの下部で、管理者を選択します。
セルフホスティングモデルを選択します
AIネイティブ機能を展開します。
機能で、コード提案とCode generation（コード生成）がセルフホストモデルに設定されていることを確認します。

AIゲートウェイURLが正しくセットアップされていることを確認してください

AIゲートウェイURLが正しいことを確認するには、GitLab Railsコンソールで以下を実行します:

Ai::Setting.instance.ai_gateway_url == "<your-ai-gateway-instance-url>"

AIゲートウェイがセットアップされていない場合は、AIゲートウェイにアクセスするようにGitLabインスタンスを設定します。

GitLab DuoエージェントプラットフォームサービスURLを検証する

エージェントプラットフォームサービスのURLが正しいことを確認するには、GitLab Railsコンソールで以下を実行します:

Ai::Setting.instance.duo_agent_platform_service_url == "<your-duo-agent-platform-instance-url>"

エージェントプラットフォームサービスのURLはTCP URLであり、http://またはhttps://のプレフィックスを持つことはできません。

エージェントプラットフォームのURLがセットアップされていない場合は、URLにアクセスするようにGitLabインスタンスを設定する必要があります。

GitLabがAIゲートウェイにHTTPリクエストを送信できるかどうかを確認する

GitLab Railsコンソールで、次のコマンドを実行して、GitLabがAIゲートウェイにHTTPリクエストを送信できることを確認します:

HTTParty.get('<your-aigateway-endpoint>/monitoring/healthz', headers: { 'accept' => 'application/json' }).code

レスポンスが200でない場合、これは次のいずれかを意味します:

ネットワークが、GitLabがAIゲートウェイコンテナに到達できるように適切に設定されていません。ネットワーク管理者に連絡して、セットアップを検証してください。
AIゲートウェイはリクエストを処理できません。この問題を解決するには、AIゲートウェイがモデルにリクエストを送信できるかどうかを確認します。

AIゲートウェイがモデルにリクエストを送信できるかどうかを確認する

AIゲートウェイコンテナから、コード提案のAIゲートウェイAPIにHTTPリクエストを送信します。以下の値を置き換えます:

使用しているモデルの名前で<your_model_name>。例: mistral、codegemma。
モデルがホストされているエンドポイントで<your_model_endpoint>。

docker exec -it <ai-gateway-container> sh
curl --request POST "http://localhost:5052/v1/chat/agent" \
     --header 'accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{ "prompt_components": [ { "type": "string", "metadata": { "source": "string", "version": "string" }, "payload": { "content": "Hello", "provider": "litellm", "model": "<your_model_name>", "model_endpoint": "<your_model_endpoint>" } } ], "stream": false }'

リクエストが失敗した場合:

AIゲートウェイが、セルフホストモデルを使用するように適切に設定されていない可能性があります。これを解決するには、AIゲートウェイURLが正しくセットアップされていることを確認します。
AIゲートウェイがモデルにアクセスできない可能性があります。解決するには、AIゲートウェイからモデルに到達できるかどうかを確認します。
モデル名またはエンドポイントが正しくない可能性があります。値をチェックし、必要に応じて修正します。

AIゲートウェイがリクエストを処理できるかどうかを確認する

docker exec -it <ai-gateway-container> sh
curl '<your-aigateway-endpoint>/monitoring/healthz'

レスポンスが200でない場合、これはAIゲートウェイが正しくインストールされていないことを意味します。解決するには、AIゲートウェイのインストール方法に関するドキュメントに従ってください。

AIゲートウェイの環境変数が正しくセットアップされていることを確認する

AIゲートウェイの環境変数が正しくセットアップされていることを確認するには、AIゲートウェイコンテナのコンソールで以下を実行します:

docker exec -it <ai-gateway-container> sh
echo $AIGW_CUSTOM_MODELS__ENABLED # must be true

環境変数が正しくセットアップされていない場合は、コンテナを作成してセットアップします。

AIゲートウェイからモデルに到達できるかどうかを確認する

AIゲートウェイコンテナでShellを作成し、モデルにcURLリクエストを送信します。AIゲートウェイがそのリクエストを送信できないことが判明した場合、これは次のことが原因である可能性があります:

モデルサーバーが正しく機能していません。
モデルがホストされている場所にリクエストを許可するように、コンテナ周辺のネットワーク設定が適切に設定されていません。

これを解決するには、ネットワーク管理者にお問い合わせください。

AIゲートウェイがGitLabインスタンスにリクエストを送信できるかどうかを確認する

AIGW_GITLAB_URLで定義されたGitLabインスタンスは、リクエスト認証のためにAIゲートウェイコンテナからアクセスできる必要があります。インスタンスに到達できない場合（たとえば、プロキシ設定エラーが原因）、リクエストが次のエラーで失敗する可能性があります:

jose.exceptions.JWTError: Signature verification failed

gitlab_cloud_connector.providers.CompositeProvider.CriticalAuthError: No keys founds in JWKS; are OIDC providers up?

このシナリオでは、AIGW_GITLAB_URLと$AIGW_GITLAB_API_URLがコンテナに適切に設定され、アクセスできるかどうかを検証します。次のコマンドは、コンテナから実行すると成功するはずです:

poetry run troubleshoot
curl "$AIGW_GITLAB_API_URL/projects"

成功しない場合は、ネットワーク設定を検証してください。

イメージのプラットフォームがホストと一致しません

AIゲートウェイリリースを見つけると、The requested image's platform (linux/amd64) does not match the detected hostというエラーが表示される場合があります。

この回避策として、--platform linux/amd64をdocker runコマンドに追加します:

docker run --platform linux/amd64 -e AIGW_GITLAB_URL=<your-gitlab-endpoint> <image>

LLMサーバーがAIゲートウェイコンテナ内で使用できません

LLMサーバーがAIゲートウェイコンテナと同じインスタンスにインストールされている場合、ローカルホストからはアクセスできない可能性があります。

これを解決するには:

AIゲートウェイコンテナからのローカルリクエストを有効にするには、--network hostをdocker runコマンドに含めます。
ポートの競合に対処するには、-e AIGW_FASTAPI__METRICS_PORT=8083フラグを使用します。

docker run --network host -e AIGW_GITLAB_URL=<your-gitlab-endpoint> -e AIGW_FASTAPI__METRICS_PORT=8083 <image>

vLLM 404エラー

vLLMの使用中に404 error（404エラー）が発生した場合は、次の手順に従って問題を解決してください:

次のコンテンツを含むchat_template.jinjaという名前のチャットテンプレートファイルを作成します:

{%- for message in messages %}
  {%- if message["role"] == "user" %}
    {{- "[INST] " + message["content"] + "[/INST]" }}
  {%- elif message["role"] == "assistant" %}
    {{- message["content"] }}
  {%- elif message["role"] == "system" %}
    {{- bos_token }}{{- message["content"] }}
  {%- endif %}
{%- endfor %}

vLLMコマンドを実行するときは、必ず--served-model-nameを指定してください。次に例を示します:

vllm serve "mistralai/Mistral-7B-Instruct-v0.3" --port <port> --max-model-len 17776 --served-model-name mistral --chat-template chat_template.jinja

GitLab UIでvLLMサーバーのURLを確認して、URLに/v1サフィックスが含まれていることを確認します。正しい形式は次のとおりです:
```
http(s)://<your-host>:<your-port>/v1
```

コード提案アクセスエラー

セットアップ後にコード提案へのアクセスで問題が発生する場合は、次の手順を試してください:

Railsコンソールで、ライセンスパラメータを確認および検証します:

sudo gitlab-rails console
user = User.find(id) # Replace id with the user provisioned with GitLab Duo Enterprise seat
Ability.allowed?(user, :access_code_suggestions) # Must return true

必要な機能が有効になっていて、使用可能であることを確認します:
```
::Ai::FeatureSetting.code_suggestions_self_hosted? # Should be true
```

GitLabのセットアップを検証する

GitLabセルフマネージドモデルのセットアップを検証するには、次のコマンドを実行します:

gitlab-rake gitlab:duo:verify_self_hosted_setup

AIゲートウェイサーバーでログが生成されていません

AI gateway server（AIゲートウェイサーバー）でログが生成されない場合は、次の手順に従ってトラブルシューティングを行います:

AIログが有効になっていることを確認します。
次のコマンドを実行して、エラーがないかGitLab Railsコンソールログを表示します:
```
sudo gitlab-ctl tail
sudo gitlab-ctl tail sidekiq
```
ログで「Error」や「Exception」などのキーワードを探して、根本的な問題を特定します。

AIゲートウェイコンテナでのSSL証明書エラーとキーの逆シリアライズの問題

AIゲートウェイコンテナ内でDuoチャットを開始しようとすると、SSL証明書エラーとキーのデシリアライズの問題が発生する可能性があります。

システムでPEMファイルの読み込む際に問題が発生し、次のようなエラーが発生する可能性があります:

JWKError: Could not deserialize key data. The data may be in an incorrect format, the provided password may be incorrect, or it may be encrypted with an unsupported algorithm.

SSL証明書エラーを解決するには:

次の環境変数を使用して、Dockerコンテナに適切な証明書バンドルパスを設定します:
- SSL_CERT_FILE=/path/to/ca-bundle.pem
- REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

エラー: モデルIDメタの呼び出しはサポートされていません

AIGWログでは、モデル識別子の形式が正しくない場合、次のエラーが表示されます:

Invocation of model ID meta.llama3-3-70b-instruct-v1:0 with on-demand throughput isn\u2019t supported. Retry your request with the ID or ARN of an inference profile that contains this model

model identifierの形式がbedrock/<region>.<model-id>であることを確認します。ここで:

<region>はAWSリージョンです（usなど）。
<model-id>は完全なモデル識別子です。

例: bedrock/us.meta.llama3-3-70b-instruct-v1:0。正しい形式を使用するようにモデル設定を更新します。

一般的なDuoチャットエラーのトラブルシューティング

エラーA1000

I'm sorry, I couldn't respond in time. Please try again. Error code: A1000というエラーが表示されることがあります。

このエラーは、処理中にタイムアウトが発生した場合に発生します。リクエストをもう一度試してください。

エラーA1001

I'm sorry, I can't generate a response. Please try again. Error code: A1001というエラーが表示されることがあります。

このエラーは、AIゲートウェイへの接続に問題があったことを意味します。ネットワーク設定を確認し、GitLabインスタンスからAIゲートウェイにアクセスできることを確認する必要がある場合があります。

セルフホストモデルのデバッグスクリプトを使用して、GitLabインスタンスからAIゲートウェイにアクセスできるかどうか、および予期どおりに動作するかどうかを検証します。

問題が解決しない場合は、GitLabサポートチームに問題をレポートしてください。

エラーA1002

I'm sorry, I couldn't respond in time. Please try again. Error code: A1002というエラーが表示されることがあります。

このエラーは、AIゲートウェイからイベントが返されないか、GitLabがイベントの解析中に失敗した場合に発生します。エラーがないか、AIゲートウェイログを確認してください。

エラーA1003

I'm sorry, I couldn't respond in time. Please try again. Error code: A1003というエラーが表示されることがあります。

このエラーは通常、モデルからAIゲートウェイへのストリーミングの問題が原因で発生します。この問題を解決するには、以下を実行します:

AIゲートウェイコンテナで、次のコマンドを実行します:

curl --request 'POST' \
'http://localhost:5052/v2/chat/agent' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-gitlab-enabled-instance-verbose-ai-logs: true' \
--data '{
  "messages": [
    {
      "role": "user",
      "content": "Hello",
      "context": null,
      "current_file": null,
      "additional_context": []
    }
  ],
  "model_metadata": {
    "provider": "custom_openai",
    "name": "mistral",
    "endpoint": "<change here>",
    "api_key": "<change here>",
    "identifier": "<change here>"
  },
  "unavailable_resources": [],
  "options": {
    "agent_scratchpad": {
      "agent_type": "react",
      "steps": []
    }
  }
}'

ストリーミングが機能している場合、チャンク化された応答が表示されます。そうでない場合は、空の応答が表示される可能性があります。

通常これはモデルのデプロイの問題であるため、具体的なエラーメッセージについては、AIゲートウェイのログを確認してください。
接続を検証するには、AIゲートウェイコンテナでAIGW_CUSTOM_MODELS__DISABLE_STREAMING環境変数を設定して、ストリーミングを無効にします:
```
docker run .... -e AIGW_CUSTOM_MODELS__DISABLE_STREAMING=true ...
```

エラーA9999

I'm sorry, I can't generate a response. Please try again. Error code: A9999というエラーが表示されることがあります。

このエラーは、ReActエージェントで不明なエラーが発生した場合に発生します。リクエストをもう一度試してください。問題が解決しない場合は、GitLabサポートチームにレポートしてください。

機能にアクセスできないか、機能ボタンが表示されない

機能が動作しない場合、または機能ボタン（たとえば、/troubleshoot）が表示されない場合は、以下のようにします:

機能のunit_primitiveが、gitlab-cloud-connector gemのセルフホストモデルのユニットプリミティブの一覧にリストされているかどうかを確認します。
このファイルに機能が見つからない場合、それがアクセスできない理由である可能性があります。
オプション。機能がリストされていない場合は、GitLabインスタンスで以下を設定することにより、これが問題の原因であることを検証できます:
```
CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1
```
次に、GitLabを再起動し、機能にアクセスできるようになるかどうかを確認します。
Important（重要）: トラブルシューティング後、このフラグを設定without（せずに）GitLabを再起動します。
CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1を本番環境で使用しないでください。開発環境は本番環境を厳密に反映する必要があり、隠れたフラグや内部専用の回避策はありません。
この問題を解決するには、以下を実行します:
- GitLabチームのメンバーである場合は、#g_custom_models Slackチャンネル経由で、カスタムモデルチームに連絡してください。
- お客様の場合は、GitLabサポートを通じて問題をレポートしてください。