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

GitLab Duo Self-Hostedサポートエンジニアプレイブック

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

サポートエンジニアプレイブックと一般的なイシュー

このセクションでは、サポートエンジニアがGitLab Duoセルフホストの問題をデバッグするための重要なコマンドとトラブルシューティング手順について説明します。

重要なデバッグコマンド

AIゲートウェイ環境変数の表示

すべてのAIゲートウェイ環境変数をチェックして、設定を検証します:

docker exec -it <ai-gateway-container> env | grep AIGW

確認すべきキーとなる変数:

  • AIGW_CUSTOM_MODELS__ENABLEDはtruetrueである必要があります。
  • AIGW_GITLAB_URL - GitLabインスタンスのURLと一致する必要があります
  • AIGW_GITLAB_API_URL - コンテナからアクセスできる必要があります
  • AIGW_AUTH__BYPASS_EXTERNAL - トラブルシューティング中にのみtrueである必要があります

ユーザー権限の検証

ユーザーがセルフホストモデルでコード提案の正しいユーザー権限を持っているかどうかを確認します:

# In GitLab Rails console
user = User.find_by_id("<user_id>")
user.allowed_to_use?(:code_suggestions, service_name: :self_hosted_models)

AIゲートウェイクライアントログの調査

AIゲートウェイのクライアントログを表示して、接続の問題を特定します:

docker logs <ai-gateway-container> | grep "Gitlab::Llm::AiGateway::Client"

AIゲートウェイリクエストのGitLabログの表示

AIゲートウェイへの実際のリクエストを確認するには、以下を使用します:

# View live logs
sudo gitlab-ctl tail | grep -E "(ai_gateway|llm\.log)"

# View specific log file with JSON formatting
sudo cat /var/log/gitlab/gitlab-rails/llm.log | jq '.'

# Filter for specific request types
 sudo cat /var/log/gitlab/gitlab-rails/llm.log | jq 'select(.message)'

 sudo cat /var/log/gitlab/gitlab-rails/llm.log | grep Llm::CompletionWorker | jq '.'

モデルリクエストのAIゲートウェイログの表示

モデルに送信された実際のリクエストを確認するには:

# View AI Gateway container logs
docker logs <ai-gateway-container> 2>&1 | grep -E "(model|litellm|custom_openai)"

# For structured logs, if available
docker logs <ai-gateway-container> 2>&1 | grep "model_endpoint"

一般的な設定の問題と解決策

モデルエンドポイントの/v1サフィックスの欠落

Symptom（現象）: vLLMまたはOpenAI互換モデルにリクエストを行う際の404エラー

How to spot in logs（ログでの確認方法）:

# Look for 404 errors in AI Gateway logs
docker logs <ai-gateway-container> | grep "404"

解決策: モデルエンドポイントに/v1サフィックスが含まれていることを確認します:

  • 誤った例: http://localhost:4000
  • 正しい例: http://localhost:4000/v1

証明書の検証の問題

Symptom（現象）: SSL証明書エラーまたは接続障害

How to spot in logs（ログでの確認方法）:

# Look for SSL/TLS errors
sudo cat /var/log/gitlab/gitlab-rails/llm.log | grep -i "ssl\|certificate\|tls"

Validation（検証）: 証明書のステータスを検証します - GitLabサーバーは、自己署名証明書がサポートされていないため、信頼できる証明書を使用する必要があります。

解決策:

  • GitLabインスタンスに信頼できる証明書を使用する
  • 自己署名証明書を使用している場合は、AIゲートウェイコンテナで適切な証明書パスを設定します

ネットワーク接続の問題

Symptom（現象）: タイムアウトまたは接続拒否エラー

How to spot in logs（ログでの確認方法）:

# Look for network-related errors
docker logs <ai-gateway-container> | grep -E "(timeout|connection|refused|unreachable)"

Validation commands（検証コマンド）:

# Test from AI Gateway container to GitLab
docker exec -it <ai-gateway-container> curl "$AIGW_GITLAB_API_URL/projects"

# Test from AI Gateway container to model endpoint
docker exec -it <ai-gateway-container> curl "<model_endpoint>/health"

認証と認可の問題

Symptom（現象）: 401 Unauthorizedまたは403 Forbiddenエラー

How to spot in logs（ログでの確認方法）:

# Look for authentication errors
sudo cat /var/log/gitlab/gitlab-rails/llm.log | jq 'select(.status == 401 or .status == 403)'

Common causes（一般的な原因）:

  • ユーザーにGitLab Duo Enterpriseのシートが割り当てられていません
  • ライセンスの問題
  • AIゲートウェイURLの設定が正しくありません

モデル設定の問題

Symptom（現象）: モデルが応答しないか、エラーを返しています

How to spot in logs（ログでの確認方法）:

# Look for model-specific errors
docker logs <ai-gateway-container> | grep -E "(model_name|model_endpoint|litellm)"

Validation（検証）:

# Test model directly from AI Gateway container
docker exec -it <ai-gateway-container> sh
curl --request POST "<model_endpoint>/v1/chat/completions" \
     --header 'Content-Type: application/json' \
     --data '{"model": "<model_name>", "messages": [{"role": "user", "content": "Hello"}]}'

ログ分析ワークフロー

ステップ1: 詳細ログの有効化

GitLab Railsコンソールで、Capture detailed information about AI-related activities and requestsインスタンス設定が有効になっているかどうかを確認します:

::Ai::Setting.instance.enabled_instance_verbose_ai_logs

falseが返された場合は、以下を使用してフラグを有効にします:

::Ai::Setting.instance.update!(enabled_instance_verbose_ai_logs: true)

ログを有効にするには、enabled_instance_verbose_ai_logsインスタンス設定を使用します。expanded_ai_logging機能フラグは使用しないでください。デバッグを目的として、GitLab.comでのみexpanded_ai_logging機能フラグを使用してください。GitLab Duoセルフホストを実行しているインスタンスを含む、GitLab Self-Managedインスタンスでは、この機能フラグを使用しないでください。

ステップ2: 問題の再現

ログをモニタリングしながら、ユーザーに問題を再現してもらいます:

# Terminal 1: Monitor GitLab logs
sudo gitlab-ctl tail | grep -E "(ai_gateway|llm\.log)"

# Terminal 2: Monitor AI Gateway logs
docker logs -f <ai-gateway-container>

ステップ3: リクエストフローの分析

  1. GitLab to AI Gateway（GitLabからAIゲートウェイへ）: リクエストがAIゲートウェイに到達するかどうかを確認します
  2. AI Gateway to Model（AIゲートウェイからモデルへ）: モデルエンドポイントが呼び出すされることを確認します
  3. Response Path（応答パス）: 応答が適切にフォーマットされ、返されることを確認します

ステップ4: 一般的なエラーパターン

エラーパターン場所考えられる原因
Connection refusedGitLabログAIゲートウェイにアクセスできません
404 Not FoundAIゲートウェイのログモデルエンドポイントに/v1がない
401 UnauthorizedGitLabログ認証・ライセンスの問題
Timeoutいずれかネットワークまたはモデルのパフォーマンスの問題
SSL certificate verify failedGitLabログ証明書の検証の問題

クイック診断コマンド

AI Gateway Instance Commands:（AIゲートウェイインスタンスコマンド）

1.AIゲートウェイのヘルスをテストします：

curl --silent --output /dev/null --write-out "%{http_code}" "<ai-gateway-url>/monitoring/healthz"

2.AIゲートウェイの環境変数を確認します：

docker exec <ai-gateway-container> env | grep AIGW

3.AIゲートウェイログでエラーを確認します：

docker logs <ai-gateway-container> 2>&1 | grep --ignore-case error | tail --lines=20

GitLab Self-Managed Instance Commands:（GitLab Self-Managedインスタンスコマンド）

4.ユーザーユーザー権限の確認（GitLab Railsコンソール）：

sudo gitlab-rails console

次に、コンソールで:

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

5.GitLab大規模言語モデルログでエラーを確認します：

sudo tail --lines=100 /var/log/gitlab/gitlab-rails/llm.log | grep --ignore-case error

6.機能フラグの確認：

sudo gitlab-rails console

次に:

Feature.enabled?(:expanded_ai_logging)

7.GitLabからAIゲートウェイへの接続をテストします：

curl --verbose "<ai-gateway-url>/monitoring/healthz"

緊急診断ワンライナー

迅速な問題特定のため:

# Check all critical components at once
docker exec <ai-gateway-container> env | grep AIGW_CUSTOM_MODELS__ENABLED && \
curl --silent "<ai-gateway-url>/monitoring/healthz" && \
sudo tail --lines=10 /var/log/gitlab/gitlab-rails/llm.log | jq '.level'

エスカレーション基準

以下の場合、カスタムモデルチームにエスカレーションします:

  1. All basic troubleshooting steps completed（基本的なトラブルシューティング手順がすべて完了している）が、解決しない場合
  2. 高度な技術知識を必要とするModel integration issues（モデルインテグレーションの問題）
  3. Feature not listed（セルフホストモデルユニットのプリミティブにリストされていない機能）
  4. 複数のユーザーに影響を与えるSuspected GitLab Duo platform bugs（疑わしいGitLab Duoプラットフォームのバグ）
  5. 特定なモデル設定でのPerformance issues（パフォーマンスの問題）

追加リソース