LLM Engineer's Handbook リポジトリを採用前に読む: ZenML パイプラインと AWS 前提の構成

このリポジトリが埋める穴: 書籍のコードを書籍の外に出す

Packt から出ている書籍の公式リポジトリであり、単体のライブラリではない。README は「The goal of this book is to create your own end-to-end LLM-based system using best practices」と述べ、データ収集と生成、LLM の学習パイプライン、RAG システム、AWS への本番デプロイ、監視、テストと評価という 6 領域を列挙している。つまり対象読者は、LLM アプリを試作したことはあるが、学習から配信までを一続きの工程として組み立てた経験がないエンジニアだ。

重要な但し書きが README の冒頭にある。「The code in this GitHub repository is actively maintained and may contain updates not reflected in the book. Always refer to this repository for the latest version of the code.」と明記されており、書籍とコードの内容がずれる前提で運用されている。紙面のコードをそのまま写すのではなく、リポジトリ側を正とする姿勢が求められる。学習教材として読む場合、この差分は自分で埋める必要がある。

もう一点、README は Issue セクションを案内し、インストールや実行で詰まったら同じ問題を解決した人がいるかもしれないと書いている。セットアップの摩擦が想定されている証拠であり、後述する依存の多さと整合する。

llm_engineering パッケージの層構造と依存の向き

中核は llm_engineering/ パッケージで、Domain-Driven Design に従って 4 つに分かれている。domain/ は業務エンティティ、application/ は業務ロジックとクローラおよび RAG 実装、model/ は LLM の学習と推論、infrastructure/ は AWS・Qdrant・MongoDB・FastAPI といった外部サービス連携を担当する。

README は依存の流れを明示している。「The code logic and imports flow as follows: infrastructure → model → application → domain」。ここは設計意図として素直に読めるが、実務では扱いにくい面もある。最も外側の infrastructure が最も内側の domain に依存する一方向の鎖なので、外部サービスを差し替えるには model と application を経由して変更が伝播する。ベクトル DB を Qdrant から別のものに替えるといった作業は、infrastructure/ の一ファイル修正では終わらない可能性がある。

一方で、この分割はテストの粒度を揃えやすい。domain/ に外部依存が入らないなら、業務ルールの検証はクラウド接続なしで書ける。README は tests/ について「Covers a few sample tests used as examples within the CI pipeline」と控えめに説明しており、テスト群が網羅的だとは主張していない。この表現は正直だが、そのまま受け取るなら、テストは自分で足す前提で見たほうがよい。

ZenML が引き受ける範囲: pipelines と steps の分業

ML ライフサイクルの実行は ZenML に委ねられている。pipelines/ は「the entry point for all the ML pipelines」と説明され、データ処理とモデル学習の段階を調整する。steps/ は再利用可能な ZenML ステップの集合で、データ読み込みや前処理といった個別タスクを担い、組み合わせてパイプラインを構成する。

実行の制御は configs/ 配下の YAML が握る。README は「ZenML YAML configuration files to control the execution of pipelines and steps」と述べており、パイプラインの挙動をコードではなく設定ファイル側で切り替える設計だ。これは再現性の面では利点になる。同じパイプライン定義に対して、設定だけを差し替えて別のデータセットや別のハイパーパラメータを試せる。

ただし、設定がコードから分離されているということは、実行時にどの YAML が効いているかを追わないと挙動が読めないということでもある。tools/run.py がパイプライン起動の入口とされているので、まずこのスクリプトがどの設定を読み込むのかを確認するのが、リポジトリを理解する最短経路になる。

成果物の置き場も ZenML が担う。README のクラウドサービス表では ZenML の用途が「Orchestrator and artifacts layer」と書かれており、中間生成物の管理まで含む。パイプラインを分割して再実行する運用では、この artifacts 層の存在が効いてくる。

セットアップ手順と固定されるバージョン

README の手順は明快で、まずリポジトリを取得する。

git clone https://github.com/PacktPublishing/LLM-Engineers-Handbook.git cd LLM-Engineers-Handbook

次に Python 環境を用意する。プロジェクトは Python 3.11 を要求し、README はグローバルインストールを使う方法と pyenv を使う方法の 2 つを並べている。バージョン確認は python --version で、3.11.x が表示されることを期待する。pyenv を使う場合は pyenv --version で導入済みかを確認する流れだ。

依存ツールのバージョンは表で固定されている。pyenv は 2.3.36 以上、Python は 3.11、Poetry は 1.8.3 以上かつ 2.0 未満、Docker は 27.1.1 以上、AWS CLI は 2.15.42 以上、Git は 2.44.0 以上。Poetry の上限が 2.0 未満と明示されている点は見落としやすい。Poetry 2 系が入っている環境では、そのままでは手順どおりに進まない可能性がある。

クラウド側は HuggingFace（モデルレジストリ）、Comet ML（実験トラッカー）、Opik（プロンプト監視）、ZenML（オーケストレーターと artifacts）、AWS（計算とストレージ）、MongoDB（NoSQL データベース）、Qdrant（ベクトル DB）、GitHub Actions（CI/CD）が挙げられている。README は「For now, you don't have to do anything」とし、設定は書籍の第 10 章と第 11 章で段階的に案内されるとしている。つまりリポジトリ単体ではセットアップが完結せず、書籍の該当章が実質的なインストールガイドになる。

学習済みモデルの入手経路と、そこで切れる範囲

README は最終的に学習されたモデルを Hugging Face で公開していると案内しており、mlabonne/TwinLlama-3.1-8B-DPO がその置き場とされている。自分で学習パイプラインを回さずに推論側だけを試したい場合、ここから始められる。

ただし、モデルを取得できることと、推論サービスが動くことは別だ。tools/ml_service.py が REST API の推論サーバーを起動するスクリプトとされているが、README にはその起動コマンドも、必要な環境変数も、待ち受けポートも書かれていない。この部分は書籍本文に依存する。リポジトリだけを手がかりに推論まで到達しようとすると、ここで情報が途切れる。

同様に tools/rag.py は「Demonstrates usage of the RAG retrieval module」と説明されるが、実行例は README には載っていない。RAG の動作を確認したいだけなら、code_snippets/ の独立したサンプルのほうが入口として軽い。README は code_snippets/ を「Independent code examples that can be executed independently」と説明しており、全体を組み上げる前に個別機能を確かめる用途に向く。

この構成が向かない場面

第一に、単一の RAG ライブラリや推論ラッパーが欲しいだけの場合、このリポジトリは重すぎる。ZenML、MongoDB、Qdrant、AWS、Comet ML、Opik が前提に並んでおり、RAG の検索部分だけを抜き出して使うにも、infrastructure/ 層がこれら外部サービスをまとめて引き受けている構造をほどく作業が要る。

第二に、AWS を使わない構成を想定している場合。README は本番デプロイの到達点を AWS 上の「Production-ready AWS deployment」と明記しており、計算とストレージを AWS が担う前提でパイプラインが組まれている。オンプレミスや別クラウドに置き換える場合、infrastructure/ の広い範囲を書き換えることになり、書籍の手順もそのままは使えない。

第三に、バージョン固定を受け入れられない環境。Python 3.11 と Poetry 1.8.3 以上 2.0 未満という制約は、既存プロジェクトに組み込む際の摩擦になる。特に Poetry の上限は、他の依存と衝突しやすい。

第四に、書籍を持たずにリポジトリだけで完結させたい場合。セットアップの詳細、推論サーバーの起動方法、クラウド各サービスの接続設定は書籍の章に委ねられており、README には書かれていない。

代替となるアプローチとの違い

同じ「LLM アプリを本番まで持っていく」目的でも、LangChain や LlamaIndex のようなフレームワークを中心に据える構成とは性格が異なる。これらはアプリケーションコードの中に抽象化レイヤーを提供し、検索やチェーン呼び出しを数行で書けるようにする。対してこのリポジトリは、アプリケーションの抽象化よりもパイプラインの実行管理に重心がある。ZenML が学習とデータ処理の段階を調整し、設定は configs/ の YAML に外出しされ、成果物は artifacts 層に残る。モデルの再学習を含む工程を回すことを想定した作りであり、単発のチャットアプリを素早く組む用途とは力の入れどころが違う。

もう一つの比較軸は、フレームワークを自作するか既存に乗るかだ。このリポジトリは llm_engineering/ という自前のパッケージを持ち、DDD の層を自分で切っている。既存フレームワークの抽象化に従うのではなく、業務ロジックと外部連携の境界を自分で引きたい場合に意味が出る。逆に、その境界設計に関心がなく、動くものを最短で得たいなら、フレームワークに寄せたほうが記述量は減る。

どちらが優れているという話ではない。学習パイプラインの再現性と成果物の追跡を重視するなら ZenML 型が合い、アプリ側の記述量を削りたいならフレームワーク型が合う。このリポジトリは前者に振り切っている。

維持コストとライセンスの確認点

ライセンスは MIT と表示されている。コードの利用条件としては緩い部類だが、リポジトリが依存する外部サービスはそれぞれ別の契約と料金体系を持つ。AWS、MongoDB、Qdrant、Comet ML、Opik、HuggingFace、ZenML の利用条件は MIT ライセンスの対象外であり、コードが自由に使えることと、運用が無料であることは別問題だ。ここは法務判断ではなく、費用と契約の確認事項として扱うべき部分になる。

維持については README が「actively maintained」と述べており、取得時点の最終 push は 2026-04-22 だった。ただし releases は取得できておらず、バージョン付きのリリースで管理されているのか、main ブランチへの直接コミットで進んでいるのかは、この材料からは判断できない。追従するなら main の差分を自分で見る前提になる。

アップグレードの難所は依存の広さにある。Poetry の 2.0 未満という上限、Python 3.11 の固定、Docker と AWS CLI の下限。これらは書籍の手順と整合させるために置かれた制約に見えるが、他のプロジェクトと同居させる場合は衝突しやすい。また README が「may contain updates not reflected in the book」と断っている以上、書籍の記述とリポジトリのコードがずれた状態が常態になりうる。学習目的で追うなら、書籍の該当章と現在のコードを突き合わせる作業が継続的に発生する。

編集部の結論

書籍の章立てに沿って LLM システムを一通り組み立てたい読者、特に ZenML でパイプラインを管理し、AWS 上に推論サービスを置く構成を自分の手で再現したい人に向く。逆に、単一の RAG ライブラリだけが欲しい場合や、AWS を使わずローカル完結を求める場合、あるいは Python 3.11 と Poetry 1.x を固定できない環境では、このリポジトリの構成は過剰になる。採用を決める前に、README の依存表にある pyenv・Python 3.11・Poetry >=1.8.3,<2.0・Docker ≥27.1.1・AWS CLI ≥2.15.42 が自分の環境で揃うかを確認し、次に tools/run.py と configs/ 配下の YAML を開いて、実行したいパイプラインがどの設定ファイルを指しているのかを突き合わせてほしい。

公式情報源

1. Issues
2. License: MIT
3. PacktPublishing/LLM-Engineers-Handbook on GitHub
4. Project website
5. README