spacy-llm レビュー: spaCy パイプラインに LLM プロンプトを差し込む設計とその代償

spacy-llm が埋めるのは「教師データが無い」と「本番の信頼性」の間の溝

LLM にプロンプトを与えれば、固有表現抽出やテキスト分類は数例のデモだけで動く。だがそれを本番のパイプラインに組み込もうとすると、API 呼び出し、プロンプトの組み立て、返ってきた文字列のパース、失敗時のリトライといった配線をすべて自前で書くことになる。spacy-llm はこの配線を spaCy のコンポーネントとして提供する。README は、教師あり学習がプロトタイピングでは LLM プロンプトに劣る一方、明確な出力が定義できるタスクでは本番向きだと述べている。効率、信頼性、制御のいずれも教師あり学習が上で、精度も概して高いという立場だ。そのうえで、パイプラインの一部を LLM プロンプトで初期化し、進捗に応じて差し替えていく使い方を想定している。対象読者は、spaCy をすでに使っていて、ラベル付きデータを集める前にタスクの出力形式を検証したい人である。

llm コンポーネントとタスク、モデルの三層構造

中心にあるのは、シリアライズ可能な llm という単一のパイプラインコンポーネントだ。設定ファイルにこのコンポーネントを書き、どのタスク関数とどのモデル関数を使うかを指定する。タスクはプロンプトの組み立てと応答のパースを担い、モデルは API 呼び出しやローカル推論を担う。この2つが独立しているため、OpenAI から Anthropic へ、あるいは Hugging Face 上のオープンモデルへ切り替えるときに、タスク側の定義を書き直さずに済む。組み込みのタスクには NER、テキスト分類、レマ化、関係抽出、感情分析、スパン分類、要約、エンティティリンク、翻訳、そして生のプロンプト実行がある。プロンプトがモデルのコンテキスト長を超える場合は、map-reduce 方式で分割し、結果を統合する仕組みが用意されている。設定ファイルに書いた内容がそのままシリアライズされるので、パイプラインの構成をファイルとして差分管理できる点は、プロンプトをコードに埋め込む実装との実質的な違いになる。

インストールと、Python コードだけで試す最短経路

導入は spaCy を入れてある仮想環境で python -m pip install spacy-llm を実行する。README は、将来の spaCy バージョンでは自動的にインストールされると注記している。API キーは環境変数として設定する。0.5.0 以降は設定ファイルを書かずに Python コードから試せる。nlp = spacy.blank("en") で空のパイプラインを作り、nlp.add_pipe("llm_textcat") でコンポーネントを追加し、llm.add_label("INSULT") と llm.add_label("COMPLIMENT") でラベルを登録してから nlp("You look gorgeous!") を実行すると doc.cats にスコアが入る。README の例では {"COMPLIMENT": 1.0, "INSULT": 0.0} という出力が示されている。llm_textcat ファクトリを使うと、組み込み textcat タスクの最新版と OpenAI の既定モデルが使われる。ここで注意したいのは、この最短経路が既定モデルへの依存を暗黙に含む点だ。モデルを差し替える段階で設定ファイル方式に移ることになる。

設定ファイルとレジストリによる拡張の実際

パラメータを制御するには spaCy の設定システムを使う。コンポーネントのブロックにファクトリ名、タスク、モデルを書き、それぞれの引数を渡す。組み込みタスクで足りない場合は、spaCy のレジストリに関数を登録して自前のプロンプト生成、パース、モデル連携を差し込める。たとえば社内の独自スキーマで関係を抽出したい場合、プロンプトのテンプレートと、返答を spaCy の Doc 拡張に変換するパーサを1組にして登録する。この設計の代償は、テンプレートが Jinja で書かれることだ。v0.7.3 のリリースノートは、信頼できない設定ファイルからのコード実行を防ぐため Jinja をサンドボックス化したと述べている。つまり設定ファイルは実行可能な入力として扱われてきた経緯があり、外部から設定を受け取る運用ではバージョンとサンドボックス化の状況を確認する必要がある。

本番で効く制約: 再現性、コスト、そして実験的であること

最大の制約は README 自身が認めている点で、このパッケージは experimental であり、マイナーバージョン更新でインターフェースが壊れうる。v0.7.4 では Pydantic v2 への移行と Python 3.14 対応が入っており、依存関係の更新が破壊的変更を運んでくる可能性がある。次に効くのが出力の性質だ。LLM の応答は確率的で、同じ入力でもスコアが揺れる。doc.cats に入る 1.0 や 0.0 は教師ありモデルの確率とは意味が違う。パースに失敗する応答も前提に入れる必要があり、タスク関数側のパース処理が事実上の防波堤になる。コストとレイテンシは入力トークン数に比例して増える。map-reduce は長文を扱えるようにするが、分割した分だけ呼び出し回数も増える。低レイテンシが要件のリアルタイム処理や、監査のために同一出力を再現する必要がある用途では、この仕組みは適さない。

spaCy ネイティブの教師ありモデルとの使い分け

比較対象は spaCy 本体の教師ありコンポーネントだ。数百から数千のラベル付き事例を用意できるなら、単一 GPU で動く transformer モデルを訓練するほうが、効率、信頼性、制御、そして多くの場合で精度の面でも有利だと README は明言している。アプローチの違いは学習の有無そのものにある。spacy-llm は重みを更新せず、プロンプトとパース規則で振る舞いを決める。したがって、ラベル体系がまだ流動的な段階では設定ファイルの書き換えだけで済むが、ラベル体系が固まった後は同じタスクを教師ありモデルに移したほうが運用は軽くなる。README が想定するのはこの移行であり、最初から最後まで LLM で通す構成ではない。要約のように複数文書をまたぐ生成が本質的に必要な箇所だけ LLM に残し、前段の絞り込みや後段の検査を spaCy の既存コンポーネントに任せる、という混成が現実的な落としどころになる。

ライセンスとメンテナンスの見取り図

ライセンスは MIT で、商用利用を含む利用と改変が許される。ただし spaCy 本体および各 LLM プロバイダの利用条件は別に適用される。特に Hugging Face 上のモデルはモデルごとにライセンスが異なるため、Falcon、Llama 2、Mistral などを選ぶ場合は重みのライセンスを個別に確認する必要がある。ここで法的な判断を代行はできない。メンテナンス面では、リポジトリはアーカイブされておらず、2026年3月時点で v0.7.4 が公開されている。リリースの間隔は一定ではなく、v0.7.2 から v0.7.3 まで約8か月、v0.7.3 から v0.7.4 まで約14か月空いている。プロバイダ側の API 仕様変更に追随する必要がある以上、依存を固定して四半期ごとに更新の有無を確認する程度の運用が妥当だ。

編集部の結論

採用を検討すべきなのは、ラベル付きデータがまだ無い状態で NER や textcat の出力形式を先に固めたいチーム、あるいは本番パイプラインの一部だけを LLM に任せ、残りを spaCy の既存コンポーネントで処理したいチームである。逆に、レイテンシとコストの見積もりが既に確定している本番系や、出力の完全な再現性が要求される用途には向かない。spaCy ネイティブの教師ありモデルで足りるなら、そちらを選ぶべきだ。導入前に確認すべきは、利用予定のタスクが組み込みで用意されているか、および spaCy のレジストリ経由で自前のプロンプト関数を書く必要があるかどうかの2点である。README が experimental と明記している以上、マイナーバージョンでインターフェースが壊れる前提でバージョンを固定し、設定ファイルをリポジトリにコミットしておくところから始めるのが現実的だ。

公式情報源

1. explosion/spacy-llm on GitHub
2. License: MIT
3. Project website
4. README
5. Releases