専門家一覧
GitHubリポジトリをAIに読み込ませるためのソースコード専用コネクタの活用

GitHub RAG実装の落とし穴：AST解析でコードを「構造」としてAIに理解させる技術

この記事は急速に進化する技術について解説しています。最新情報は公式ドキュメントをご確認ください。

約13分で読めます
文字サイズ:
GitHub RAG実装の落とし穴：AST解析でコードを「構造」としてAIに理解させる技術
目次

この記事の要点

  • AST解析でコードの構造を正確にAIへ伝達
  • メタデータ付与によりコードの意味論的理解を促進
  • LangChainやLlamaIndexでのRAG実装精度を向上

なぜ「Ctrl+A, Ctrl+C」では通用しないのか：コードRAGの技術的課題

自社プロダクトのコードベースをLLM（大規模言語モデル）に学習させようとして、「コードをテキストとして読ませてもAIは構造を理解できない」という壁に直面したことはありませんか？

ドキュメントなら段落ごとのベクトル化で検索精度が出ますが、ビジネスの要件を形にしたソースコードは、ファイル間の依存関係、クラス継承、関数呼び出しといった「論理的なつながり」で成り立っています。これを文字数でぶつ切りにしてしまっては、せっかくの知的財産が無意味な文字列の羅列になってしまいます。

ファイル間の依存関係とインポート構造の欠落

例えば、main.pyの関数がutils.pyのヘルパー関数を呼ぶ場合、RAG（検索拡張生成）がmain.pyの断片だけを検索しても、LLMはutils.pyの中身が見えず本当の挙動を理解できません。

git cloneしたファイルをテキスト変換してVectorDB（ベクトルデータベース）に格納しただけのシステムは、実務の現場では通用しないケースが多く報告されています。「この関数はどう動く？」という質問に、AIは「Xをします」と表面的な回答しかできず、「内部でYライブラリのZメソッドを呼んでいるから」という深い洞察が得られません。

最新のGraphRAG（ナレッジグラフを活用したRAG）やエージェント型分析への移行も進んでいますが、まずは根本的な「依存関係の解決」をプロトタイプとして実装し、検証することが重要です。

トークン制限と意味の分断リスク

さらに深刻なのが「意味の分断」です。4000文字などで機械的にチャンキング（分割）すると、ひとつの関数定義が前半と後半で別々のチャンクに分かれることが頻繁に起きます。

  • チャンクA: 関数の定義と引数の部分
  • チャンクB: 処理ロジックとリターン文

これらが別々に検索されると、LLMは完全なロジックを再構築できません。また、Gemini 1.5 ProやGPT-4のようなモデルでコンテキストウィンドウが拡大しても、関連性の低いコードが大量に含まれると「Lost in the Middle（情報の埋没）」現象が発生し、重要なロジックが見落とされるリスクがあります。

「専用コネクタ」が果たす構造化の役割

そのため、GitHub上のコードを扱うにはテキストローダーではなく「ソースコード専用のコネクタ」が必要です。これらは単なるダウンロードではなく、以下のデータエンジニアリング処理を担います。

  1. 構文解析（AST解析）: コードの文法を理解し、関数やクラスの区切りを認識する。
  2. メタデータ抽出: ファイルパス、言語、依存関係をタグ付けする。
  3. ノイズ除去: ライセンス表記や自動生成コードなど、学習に不要な部分を削ぎ落とす。

本記事では、長年の開発現場で培った知見をベースに、LangChainやLlamaIndexを活用し、コードを「構造化データ」として扱う実践的なエンジニアリング手法を深掘りします。

特にLangChainでは、LangGraphによるエージェントワークフロー構築やセキュリティ脆弱性（CVE-2025-68664等）への対応が進み、Google Gen AI SDKへの移行（Vertex AI SDKの生成AIモジュール廃止に伴う対応）など最新API環境に追従する機能も提供されています。これらフレームワークの適切な選定・活用が、堅牢なRAGパイプライン構築の勘所です。

環境構築：GitHub APIとデータローダーの準備

まずは「実際にどう動くか」を重視し、ハンズオン形式で環境を整えましょう。GitHubリポジトリにアクセスし、データを効率よく抽出する準備として、Pythonを中心としたエコシステムを使用します。

必要なライブラリの選定（LangChain vs LlamaIndex）

コード解析において、LlamaIndexはデータローディングとインデックス構造化で強力な優位性を持ち、特にLlamaHubのローダー群は多様なデータソースへの対応力が魅力です。一方、LangChainはその後のチェーン構築やエージェント化、ツール呼び出しで高い柔軟性を誇ります。

最新トレンドでは、ETL（抽出・変換・格納）部分にLlamaIndexのリーダー機能を使い、オーケストレーションにLangChainを利用するアプローチも一般的です。

まずは必要なパッケージをインストールします。LangChainのエコシステムはモジュール化が進んでいるため、langchain-communityなども含めておきます。

pip install llama-index langchain langchain-community langchain-openai tree-sitter pydantic

また、高度な構文解析のためにtree-sitterも導入します。これは非常に高速にAST（抽象構文木）を生成するパーサージェネレータです。

重要な注意点：
LangChainやLlamaIndexのエコシステムは進化が非常に速いです。

  • セキュリティ更新: LangChain Core等の基盤ライブラリでは、シリアライゼーション処理に関連する脆弱性対応が定期的に行われます。常に最新版の利用を推奨します。
  • SDKの変更: Google Vertex AIを利用する場合、旧SDKモジュールが非推奨となり、新しいgoogle-genaiパッケージへの移行が必須となるケースがあります。モデルプロバイダーの公式ドキュメントで最新の依存関係を確認してください。

GitHub Personal Access Tokenの発行と権限設定

パブリックリポジトリでも、認証なしのアクセスはAPIのレート制限（Rate Limit）にすぐ抵触します。業務利用ならプライベートリポジトリが対象になることがほとんどです。

GitHubのSettings > Developer settings > Personal access tokensからトークンを発行します。セキュリティの観点から、リポジトリ単位で権限を絞れる「Fine-grained tokens」の利用をお勧めします。必要なのは対象リポジトリへのRead-only権限のみです。

発行したトークンは環境変数にセットします。コード内への直接書き込みはセキュリティリスクとなるため避けてください。

import os

# 環境変数として設定（実際には.envファイルなどから読み込むことを推奨）
# LangChain等のライブラリは、この環境変数を自動的に読み込んで認証に使用します
os.environ["GITHUB_TOKEN"] = "your_github_pat_..."
os.environ["OPENAI_API_KEY"] = "your_openai_api_key_..."

開発環境のセットアップ

仮説を即座に形にして検証するため、試行錯誤にはJupyter Notebookなどが適しています。RAGの精度向上において、取得したコードの断片（チャンク）が意味のある単位で切れているかの目視確認は省略できません。

特にAST解析を用いる場合、パース結果が期待通りか確認しながら進める必要があります。最初から完璧なパイプラインを組むのではなく、「まず動くものを作る」プロトタイプ思考で、データを確認しながらアジャイルにイテレーションを回すアプローチが、ビジネスへの最短距離となります。

Part 1：専用コネクタによるリポジトリ情報の取得とフィルタリング

環境構築：GitHub APIとデータローダーの準備 - Section Image

実際にデータを取得します。ここで重要なのは「全部取らない」ことです。画像ファイル、設定ファイル、ロックファイルなどはLLMにとってノイズになります。

リポジトリローダーの基本実装コード

LlamaIndexのGithubRepositoryReaderを使用する例です。これはGitHub APIをラップし、ディレクトリ構造を再帰的に探索します。

from llama_index.readers.github import GithubRepositoryReader, GithubClient

github_client = GithubClient(github_token=os.environ["GITHUB_TOKEN"])
loader = GithubRepositoryReader(
    github_client=github_client,
    owner="langchain-ai",
    repo="langchain",
    use_parser=False,
    verbose=True,
    filter_file_extensions=([".py", ".md", ".ipynb"], GithubRepositoryReader.FilterType.INCLUDE)
)

# データの読み込み（これには時間がかかる場合があります）
docs = loader.load_data(branch="master")

print(f"Loaded {len(docs)} documents.")

ノイズ除去：不要なファイルとディレクトリの除外

上記コードでfilter_file_extensionsを指定していますが、これだけでは不十分なケースが多いです。例えばtests/やmigrations/ディレクトリは、プロダクト仕様の理解においてノイズになることがあります。

また、__init__.pyのような空に近いファイルも大量に含まれるため、プログラム側でフィルタリングします。

filtered_docs = []
for doc in docs:
    file_path = doc.metadata.get("file_path", "")
    file_name = doc.metadata.get("file_name", "")
    
    # 除外条件
    if "tests/" in file_path:
        continue
    if "migrations/" in file_path:
        continue
    if file_name == "__init__.py":
        continue
        
    filtered_docs.append(doc)

print(f"Filtered down to {len(filtered_docs)} documents.")

このように、「AIに何を読ませないか」を見極めるデータガバナンスの視点が、トークンコスト削減と回答精度向上に直結します。

Part 2：AST（抽象構文木）を意識した「意味の切れない」チャンキング

ここからが本記事の核心です。取得したソースコードの分割において、単純な文字数分割（Character Splitting）は避けるべきです。

文字数分割の限界と「関数・クラス分断」のリスク

例えば、Pythonコードを500文字で切り、クラスのメソッド定義の途中で分断されたとします。

# チャンク1の終わり
    def calculate_metrics(self, data):
        result = self.preprocessing(data)
        
# チャンク2の始まり
        return self.model.predict(result)

これでは、チャンク1には「何をするか」の一部、チャンク2には「何を返すか」しかなく、単独では意味を成しません。

言語別スプリッター（LanguageSplitter）の実装

これを解決するため、LangChainやLlamaIndexにはプログラミング言語の構文を理解するスプリッターが用意されています。これらはAST（抽象構文木）の概念を簡易的に取り入れ、クラスや関数のブロック単位でのテキスト分割を試みます。

LangChainのRecursiveCharacterTextSplitterでfrom_languageメソッドを使うのが最も手軽で効果的です。

from langchain.text_splitter import RecursiveCharacterTextSplitter, Language

# Python用の区切り文字（class, def, \n\n など）が自動設定される
python_splitter = RecursiveCharacterTextSplitter.from_language(
    language=Language.PYTHON,
    chunk_size=1000,
    chunk_overlap=200
)

# LangChain形式のDocumentオブジェクトに変換してから分割
# (LlamaIndexのdocsをLangChain形式に変換する処理が必要な場合があります)
texts = python_splitter.split_documents(langchain_docs)

このスプリッターは優先順位をつけて分割場所を探します。Pythonならトップレベルのクラスや関数定義で切れないか試し、無理ならメソッド定義、さらに長ければ改行という具合です。これにより論理的なまとまりが保持される確率が格段に上がります。

チャンクヘッダーへのメタデータ（ファイルパス、行番号）付与

さらに重要なテクニックがあります。コードの断片だけをLLMに見せても、「どのファイルのどの部分か」がわからないと文脈が失われます。

各チャンクの先頭に、メタデータをテキストとして注入する「Context Injection」をお勧めします。

def add_metadata_header(doc):
    metadata = doc.metadata
    file_path = metadata.get('file_path', 'unknown')
    
    # チャンクの先頭にファイルパスを埋め込む
    header = f"# File: {file_path}\n"
    doc.page_content = header + doc.page_content
    return doc

# 全チャンクに適用
processed_docs = [add_metadata_header(doc) for doc in texts]

これにより、AIがチャンクを読んだ際に「これはauth/login.pyのコードだ」と即座に理解できます。複数ファイルに同名関数（process_dataなど）がある場合、このパス情報は識別子として決定的な役割を果たします。

Part 3：ベクトルストアへの格納とコード文脈検索の実行

Part 2：AST（抽象構文木）を意識した「意味の切れない」チャンキング - Section Image

データが整形されたら、ベクトル化して検索できるようにします。単にデータを格納するだけでなく、コード特有の構造を維持したまま検索精度を高めるアプローチをとります。

コード検索に適したEmbeddingモデルの選択

ソースコードのベクトル化には、一般的な自然言語用モデルよりも、コードの論理構造や構文を理解できるモデル、あるいはコンテキストウィンドウが広いモデルが適しています。

OpenAIのtext-embedding-3シリーズ（smallまたはlarge）はコストパフォーマンスが良く、コードのセマンティクス（意味）も高精度に捉えます。以前のモデルに比べ多言語のコード理解力が向上しており、実用的な選択肢です。

専門的な要件がある場合はHugging Faceのmicrosoft/codebert-base系モデルも検討価値がありますが、インフラ管理コストと手軽さを考慮すると、まずは動くものを作るという観点から、OpenAIのモデルでベースラインを作成し、素早く検証することをお勧めします。

ローカルVectorDB（Chroma）へのインデックス作成

開発段階やPoC（概念実証）では、手軽に使えるChromaやFAISSが便利です。

ただし、ライブラリ選定ではセキュリティと互換性に注意が必要です。LangChain Coreの最新版（1.2.7以降）では、シリアライゼーション・インジェクションに関する重要な脆弱性（CVE-2025-68664）への対応が行われています。外部データを扱うRAGパイプラインでは、常に最新のセキュリティパッチが適用されたバージョンを使用してください。

以下は、Chromaを使用したインデックス作成の実装例です。

# 実際の環境に合わせて最新のパッケージを使用してください
# pip install langchain-chroma langchain-openai

from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings

# 最新のモデルを指定
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

# ベクトルストアの構築
# persist_directoryを指定することでローカルに永続化
db = Chroma.from_documents(
    documents=processed_docs,
    embedding=embeddings,
    persist_directory="./chroma_db"
)

print("Vector store created successfully.")

※ LangChainのエコシステムは頻繁に更新されています。Pydantic V2への移行も進んでいるため、依存関係の競合を避ける仮想環境での実行を推奨します。

RAGチェーンの構築と「この関数の使い方は？」への回答テスト

検索アルゴリズムの選択はRAGの回答品質を左右する重要な要素です。コード検索においては、MMR (Maximum Marginal Relevance)の使用を強く推奨します。

通常の類似度検索（Similarity Search）だけでは、似たコード（同関数のオーバーロード、コピペされたテストコード、わずかなバージョン違いなど）ばかりが上位に来て情報の多様性が失われがちです。MMRを使用することで「類似性は高いが情報の質が異なる」チャンクをバランスよく取得でき、AIに渡すコンテキストの網羅性が向上します。

# MMRを使用して多様性を確保
retriever = db.as_retriever(
    search_type="mmr",
    search_kwargs={
        "k": 5,        # 最終的に取得するドキュメント数
        "fetch_k": 20, # 多様性フィルタリングのために最初に取得する候補数
        "lambda_mult": 0.5 # 多様性の度合い（0に近いほど多様性重視）
    }
)

# 検索実行テスト
query = "How is the authentication token generated?"
retrieved_docs = retriever.invoke(query)

for i, doc in enumerate(retrieved_docs):
    print(f"--- Result {i+1} ---")
    # メタデータも含めて確認することで、どのファイルのどの部分か把握
    print(f"Source: {doc.metadata.get('source', 'Unknown')}")
    print(doc.page_content[:200]) # 先頭だけ表示
    print("\n")

実際に検索を実行してみましょう。Part 2で注入した# File: ...というヘッダー情報がいかに役立つか、実感していただけるはずです。検索結果を見ただけでどのファイルのコードがヒットしたか一目瞭然であり、LLMも「ファイルAの関数X」と「ファイルBの関数X」を明確に区別して回答できるようになります。いかがでしょうか？少しの工夫でAIの理解度が劇的に変わるのが面白いところです。

トラブルシューティングと大規模リポジトリへの対応

プロトタイプが動いたら、次は実運用に向けた課題が出てきます。

API Rate Limit Exceededへの対処法（遅延ロード）

GitHub APIは短時間に大量のリクエストを送るとブロックされます。数千ファイルあるリポジトリを一気に読み込もうとすると確実に止まります。

対策として、読み込み処理にtime.sleep()を入れるか、ローカルに一度git cloneしてからローカルファイルとして読み込む（DirectoryLoaderなどを使用）のが現実的です。API経由はメタデータ（コミット情報など）が欲しい場合に限定し、コード本文はローカルファイルから読むハイブリッド構成も有効です。

コンテキストウィンドウ溢れを防ぐ検索結果の再ランク付け（Re-ranking）

大規模リポジトリでは関連しそうなコードが大量に見つかり、プロンプトのトークン制限（コンテキストウィンドウ）を圧迫することがあります。また、ベクトル検索だけでは「本当に重要なコード」を見抜けないこともあります。

ここでCross-Encoder（Re-ranker）の出番です。ベクトル検索で広めに（例えば50件）取得した後、CohereなどのRe-rank APIを使って質問との関連度が高い順に並び替え、上位5件だけをLLMに渡す2段構えの構成にします。これにより精度が劇的に向上します。

まとめ：コードは「読む」ものではなく「解析」するもの

(LlamaIndexのdocsをLangChain形式に変換する処理が必要な場合があります) - Section Image 3

GitHubリポジトリをAIに活用させる鍵は、LLMの性能ではなく前処理（Data Engineering）の質にあります。

  1. フィルタリング: 不要なファイルを徹底的に排除する。
  2. 構造化チャンキング: ASTを意識して、関数やクラスの単位で分割する。
  3. メタデータ注入: ファイルパスや文脈情報を明示的に埋め込む。

これらを実装することで、AIは単なる「文字検索ボット」から、コードの構造を理解した「頼れるペアプログラマー」へと進化します。技術の本質を見抜き、まずは手を動かしてプロトタイプを作ってみてください。皆さんのAIプロジェクトが成功し、ビジネスの最短距離を駆け抜ける一助となれば幸いです。

GitHub RAG実装の落とし穴：AST解析でコードを「構造」としてAIに理解させる技術 - Conclusion Image

コメント

コメントは1週間で消えます
0 / 150
コメントを読み込み中...