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

セマンティック検索の管理

  • プラン: Premium、Ultimate
  • アドオン: GitLab Duo Core、Pro、またはEnterprise
  • 提供形態: GitLab Self-Managed
  • ステータス: ベータ版

ユーザードキュメントについては、セマンティック検索を参照してください。

セマンティック検索を使用すると、AIネイティブなGitLab Duo機能は、リポジトリ内の関連するコードスニペットを見つけることができます。

前提条件

ベクターストレージ

大規模なリポジトリにはElasticsearchまたはOpenSearchを使用してください。pgvector付きのPostgreSQLは、少数の小さなリポジトリがあるセットアップのみに使用してください。インデックス作成およびクエリのパフォーマンスは、pgvectorで制限される可能性があります。

詳細検索のクラスターに接続する

GitLabインスタンスがElasticsearchまたはOpenSearchを詳細検索に使用している場合、同じクラスターに接続することでセマンティック検索を有効にできます:

  1. 右上隅で、管理者を選択します。
  2. 左サイドバーで、設定 > 検索を選択します。
  3. セマンティック検索を展開します。
  4. ベクターストレージで、設定するを選択します。
  5. ベクターストレージページで、Advanced search clusterの下にある接続を選択します。

カスタムベクターストアを設定する

Elasticsearch、OpenSearch、またはPostgreSQL用のカスタムベクターストア接続を設定するには:

  • Railsコンソールで、adapter_classとoptionsを使用してAi::ActiveContext::Connectionを作成します。

Elasticsearch

connection = Ai::ActiveContext::Connection.create!(
  name: "elasticsearch",
  options: options,
  adapter_class: "ActiveContext::Databases::Elasticsearch::Adapter"
)
connection.activate!

接続オプション:

オプション型必須デフォルト説明
url文字列の配列はいなしElasticsearchクラスターのURLの配列（例: ["http://localhost:9200"]）。
client_adapter文字列いいえtyphoeus使用するHTTPアダプター。使用可能な値はtyphoeusとnet_httpです。
client_request_timeout整数いいえ30リクエストのタイムアウト（秒）。
retry_on_failure整数いいえ0失敗時の再試行回数。
debugブール値いいえfalseデバッグログを有効にします。

OpenSearch

connection = Ai::ActiveContext::Connection.create!(
  name: "opensearch",
  options: options,
  adapter_class: "ActiveContext::Databases::Opensearch::Adapter"
)
connection.activate!

接続オプション:

オプション型必須デフォルト説明
url文字列の配列はいなしOpenSearchクラスターのURLの配列（例: ["http://localhost:9200"]）。
client_adapter文字列いいえtyphoeus使用するHTTPアダプター。使用可能な値はtyphoeusとnet_httpです。
client_request_timeout整数いいえ30リクエストのタイムアウト（秒）。
retry_on_failure整数いいえ0失敗時の再試行回数。
debugブール値いいえfalseデバッグログを有効にします。
awsブール値いいえfalseAWS Signature Version 4署名を有効にします。
aws_region文字列いいえなしOpenSearchドメインのAWSリージョン。
aws_access_key文字列いいえなしAWSアクセスキーID。
aws_secret_access_key文字列いいえなしAWSシークレットアクセスキー。
aws_role_arn文字列いいえなしロールベースの認証用のAWS IAMロールARN。

pgvector機能付きPostgreSQL

PostgreSQLでは、pgvector拡張機能を使用します:

  1. PostgreSQLデータベースで、拡張機能を作成します:

    CREATE EXTENSION vector;

  2. Railsコンソールで、接続を作成します:

    connection = Ai::ActiveContext::Connection.create!(
  name: "postgres",
  options: options,
  adapter_class: "ActiveContext::Databases::Postgresql::Adapter"
)
connection.activate!

接続オプション:

オプション型必須デフォルト説明
host文字列はいなしPostgreSQLホスト。
port整数いいえなしPostgreSQLポート。
database文字列いいえなしデータベース名。
user文字列いいえなしPostgreSQLユーザー。
password文字列いいえなしPostgreSQLパスワード。
connect_timeout整数いいえ5接続タイムアウト（秒）。
pool_size整数いいえ5接続プールサイズ。

埋め込みモデルを設定する

埋め込みモデルを設定するには:

  1. 右上隅で、管理者を選択します。
  2. 左サイドバーで、設定 > 検索を選択します。
  3. セマンティック検索を展開します。
  4. Code embeddingsについては、モデルを設定を選択します。すでに埋め込みモデルを設定している場合は、代わりにモデルの変更が表示されます。
  5. Semantic search code embeddingsページで、埋め込みモデル、埋め込みディメンション、およびチャンキング戦略を選択します。
  6. 埋め込みを設定するを選択します。すでに埋め込みモデルを設定している場合は、代わりに埋め込みを更新し、バックフィル処理を開始しますが表示されます。

埋め込みモデルまたはディメンションを変更すると、コードベースのサイズによっては数時間かかるバックフィルが実行されます。この処理中もセマンティック検索は引き続き利用可能です。

埋め込みモデル

GitLab管理モデル

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。

GitLab管理モデルは、GitLab AIゲートウェイで提供されます。Gemini Enterprise Agent Platformによって提供されるtext-embedding-005モデルを選択します。

GitLab Duo Self-HostedセットアップでGitLab管理モデルを選択することもできます。詳細については、ハイブリッドAIゲートウェイとモデル設定を参照してください。

GitLabが選択したモデルを非推奨にした場合、ご自身で別のモデルに切り替える必要があります。

セルフホストモデル

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。

セルフホストモデルは、独自のインフラストラクチャでホストされる AIモデルです。

セルフホストモデルを選択するには:

  1. GitLab Duo Self-Hostedをセットアップします。
  2. モデルファミリーにEMBEDDINGを指定して、セルフホストモデルを追加します。

チャンク戦略

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。

チャンク戦略は、コードファイルを埋め込み用のより小さなスニペットに分割するために使用されるアルゴリズムです。次のいずれかの戦略を選択します:

  • コードバイト: コードの構造やセマンティクスを考慮せずに、コードを固定サイズのバイトチャンクに分割します。チャンクサイズは、チャンクあたりの最大バイト数を指します。次の場合にこの戦略を使用します:
    • より高速なインデックス作成と、より予測可能なチャンクサイズ。
    • 多様なファイルタイプと言語を持つリポジトリ。
  • コードpre-BERT: BERTベースの埋め込みモデル用に最適化されたセマンティック境界を使用してコードを分割します。チャンクサイズは、チャンクあたりの最大トークン数を指します。次の場合にこの戦略を使用します:
    • 検索品質の向上と、コード構造を尊重したより意味のあるチャンク。
    • 整然としたコードを持つリポジトリ。

チャンク戦略は、埋め込みモデルを初めて設定するときにのみ選択できます。インデックス作成が開始された後にチャンク戦略を変更するには、インスタンスを完全に再インデックス作成する必要があります。自動再インデックス作成のサポートは、イシュー600200およびイシュー602138で提案されています。

セマンティック検索ステータスの確認

セマンティック検索のステータス（インデックス作成ステータス、ベクターストア接続の詳細、リポジトリ統計、埋め込みキューサイズなど）を確認するには、このRakeタスクを実行します:

sudo gitlab-rake gitlab:semantic_search:code:info

ステータスを継続的に監視するには、監視間隔を秒単位で指定します:

sudo gitlab-rake "gitlab:semantic_search:code:info[5]"

このタスクは、指定された間隔で出力を更新します。タスクを停止するには、Control+Cを押します。

デッドキューの管理

前提条件:

  • admin_mode、ai_features、apiのスコープを持つパーソナルアクセストークン。

埋め込み生成が繰り返し失敗すると、手動介入のためにアイテムがデッドキューに移動されます。デッドキューのサイズは、ステータスRakeタスク出力のEmbedding Queuesセクションで確認できます。

デッドキューのクリア

デッドキューからすべてのアイテムを削除するには、このコマンドを実行します:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue"

デッドキューの再実行

デッドキューアイテムを別の試行のために処理キューに戻すには、queueパラメータを使用してターゲットを指定します。有効な値はretry_queue、code、code_backfillです。

デッドキューに再度失敗する前に、もう一度処理を試行するには、retry_queueを使用します:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "queue=retry_queue" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue/replay"

メインのコードキューにアイテムを追加するには、codeを使用します:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "queue=code" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue/replay"