本ページでは、Corpus2Skillを手元の環境で動かすまでの手順を、インストール、APIキー設定、コンパイル、サーブの順に解説します。掲載しているコマンドはGitHubリポジトリの公開情報に基づくものです。OSSは開発途上（WIP）の早期リリースであるため、最新の変更は必ず公式リポジトリで確認してください。
前提条件と全体の流れ
導入に必要なものは大きく3つです。第一にPython実行環境、第二にコンパイル時の要約・ラベル生成とサーブ時のナビゲーションに使うAnthropic APIキー、第三に変換対象の文書コーパス（.txt / .md / .json / .jsonl）です。埋め込みモデル（既定はQwen3-Embedding-0.6B）はsentence-transformers経由でローカル実行されるため、コンパイルをスムーズに進めたい場合はGPUがあると有利ですが、小規模なコーパスならCPUでも試行できます。
所要時間とコストの見積もりも、着手前に押さえておきたいポイントです。コンパイルの処理時間は、埋め込みとクラスタリングが文書数に、要約・ラベル生成が生成されるノード数に依存します。LLM呼び出しを伴うのは後者であるため、コンパイルのAPIコストは「文書数」ではなく「ツリーの規模」で決まる点に注意してください。初回は小さめのコーパスで一度コンパイルを通し、実測した時間とトークン消費を基準に本番規模を見積もる進め方が堅実です。
インストールとAPIキー設定
リポジトリをクローンし、編集可能モードでインストールします。開発途上のOSSであるため、PyPIのパッケージではなくリポジトリからの直接インストールが基本です。
# リポジトリの取得とインストール
git clone https://github.com/dukesun99/Corpus2Skill.git
cd Corpus2Skill
pip install -e .次に、プロジェクトルートの.envファイルにAnthropic APIキーを設定します。このキーは、コンパイル時のSummarize・Label段階と、サーブ時のエージェント実行の両方で使用されます。
# .env ファイル
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxCLIでコンパイルを実行する
コーパスのディレクトリを用意したら、CLIからコンパイルを実行します。公式に示されている実行例は次のとおりです。
python -m corpus2skill \
--input ./corpus_dir \
--output ./compiled_output \
--p 10 \
--max-top 8 \
--model claude-sonnet-4-6 \
--embed-model Qwen/Qwen3-Embedding-0.6B主要なオプションの意味を整理します。
| オプション | 意味 | 調整の考え方 |
|---|---|---|
--input |
コーパスのディレクトリ | .txt / .md / .json / .jsonl を配置 |
--output |
スキルツリーの出力先 | サーブ時に skills_dir として指定 |
--p |
分岐率 | 大きいほど浅く広い木、小さいほど深く狭い木 |
--max-top |
トップレベルスキルの最大数 | 鳥瞰ビューの読みやすさを左右（例：8） |
--model |
要約・ラベル生成に使うLLM | 例：claude-sonnet-4-6 |
--embed-model |
埋め込みモデル | 既定は Qwen/Qwen3-Embedding-0.6B |
--compact |
リーフインデックスの統合 | 小規模コーパスで探索段数を削減 |
サーブ：answer_queryで回答を得る
コンパイルが完了したら、Pythonコードからサーブ機能を呼び出します。corpus2skill.serveモジュールのanswer_query()関数に、質問文とServeConfig（スキルツリーのディレクトリ指定）を渡すだけです。
from corpus2skill.serve import answer_query, ServeConfig
config = ServeConfig(skills_dir="./compiled_output")
result = answer_query("返金はどの支払い方法に対応していますか？", config)
print(result)内部では、エージェントがトップレベルのスキル説明を読み、関連するブランチへドリルダウンし、リーフで文書IDを特定してget_documentツールで全文を取得し、根拠付きの回答を生成します。この一連の動作の詳細は「スキルツリー構造とナビゲーション」で解説しています。
業務システムへ組み込む場合は、answer_query()を薄いWeb APIでラップする構成が扱いやすいでしょう。スキルツリーは読み取り専用の静的ファイルであるため、APIサーバーを複数並べる水平スケールも、ツリーを同梱したコンテナイメージの配布だけで実現できます。再コンパイル後の切り替えは、新しいツリーのディレクトリを配置してServeConfigの参照先を切り替えるだけで済み、いわゆるブルーグリーン方式の安全なリリースと相性が良い構造です。
回答品質を定量評価したい場合は、QAペアを用意して評価モジュールを実行します。
# QAベンチマークによる評価
python -m corpus2skill.eval --qa benchmark.jsonlF1・BLEU・ROUGEといった自動指標に加え、LLM判定による事実性やコンテキスト再現率、トークン会計とUSDコスト計算まで内蔵されています。指標の読み方は「ベンチマークと評価指標」をご参照ください。
評価用QAセットの作り方
評価の質はQAセットの質で決まります。おすすめは、実際の問い合わせログから代表的な質問を30〜100件程度サンプリングし、正解となる回答と根拠文書を担当者が付与する方法です。よくある質問だけでなく、複数文書にまたがる質問や、コーパスに答えが存在しない質問も意図的に混ぜると、ナビゲーションの強み（横断探索）と誠実さ（回答差し控え）の両方を確認できます。QAセットは一度作れば、パラメータ調整や埋め込みモデル差し替えのたびに回帰テストとして再利用でき、投資対効果の高い資産になります。
運用のヒントと注意点
最初の試行では、いきなり全社ナレッジを投入するのではなく、1つのドメインに閉じた数百件規模のコーパスから始めることをおすすめします。ヘルプセンターの1カテゴリや特定製品のマニュアルなどが適しています。コンパイル後は、生成されたSKILL.mdとINDEX.mdを人間の目で確認し、要約とラベルが業務用語として自然かをチェックしてください。ツリーは静的ファイルなので、この検証が容易である点はCorpus2Skillの利点です。
つまずきやすいポイントも挙げておきます。コンパイルが想定より長時間かかる場合は、埋め込みモデルのダウンロードや実行環境（CPU/GPU）を確認してください。生成されたトップレベルスキルが多すぎて鳥瞰ビューが読みにくい場合は--max-topを絞り、逆にリーフまでの段数が深すぎる場合は--pを上げるか--compactを検討します。サーブ時の回答が的外れな場合は、まずSKILL.mdの要約品質を疑い、必要に応じて--modelをより上位のモデルに変更して再コンパイルすると改善することがあります。
注意点として、OSSはWIP（開発途上）の早期リリースであり、API・CLIの仕様が変わる可能性があります。また、コーパスを更新した場合は再コンパイルが必要です。更新頻度が高いナレッジでは、再コンパイルの所要時間とLLMコストを含めた運用サイクルを設計しておく必要があります。週次や月次の定期再コンパイルをバッチとして自動化し、生成されたツリーの検証と評価モジュールの実行までをひとつのパイプラインにまとめておくと、更新のたびの手作業を減らしつつ品質の退行も検知できます。コスト見積もりの考え方は「コスト構造とプロンプトキャッシュ最適化」で詳しく扱います。
- 導入は pip install -e . と .env へのAnthropic APIキー設定だけで始められます。
- コンパイルは python -m corpus2skill を実行し、--p や --max-top でツリー形状を調整します。
- サーブは answer_query() と ServeConfig のみ。評価モジュールで品質とコストを定量確認できます。