daveebbelaar/ai-cookbook

⭐ 20,000 🍴 0 Python📄 MIT License GitHubで見る →

主な特徴

  • **実践重視**: 理論よりも実際に動作するコードに焦点
  • **最小限の依存関係**: OpenAIとrequestsが主要な依存関係
  • **Building Blocks アプローチ**: 7つの基本要素を組み合わせてシステム構築
  • **本番対応**: エラーハンドリング、バリデーション、人間の承認フローを含む
  • **包括的なカバレッジ**: エージェント、RAG、メモリシステム、MCPなど幅広いトピック

リポジトリ解析: daveebbelaar/ai-cookbook

基本情報

  • リポジトリ名: daveebbelaar/ai-cookbook
  • 主要言語: Python
  • スター数: 20,000以上（推定）
  • フォーク数: 多数（推定）
  • 最終更新: アクティブに更新中
  • ライセンス: MIT License
  • トピックス: AI, LLM, agents, RAG, memory-systems, production-patterns

概要

一言で言うと

実践的なAIシステム構築のためのコピペ可能なコードスニペット集。複雑なフレームワークを避け、シンプルで堅牢な building blocks を組み合わせて本番環境で動作するAIアプリケーションを構築する方法を示す。

詳細説明

このクックブックは、Dave Ebbelaar（Datalumina創業者）によって作成された、AIシステム構築の実践的なリポジトリです。YouTube チャンネルでの教育活動と連動し、開発者が実際の本番環境で動作するAIシステムを構築するための具体的なコード例を提供しています。

重要な思想として「LLMにツールを与えてすべてを任せる」アプローチを否定し、代わりに決定論的なコードの中で戦略的にLLMを使用する方法を推奨しています。これは実際の本番環境での経験に基づいた、実用的なアプローチです。

主な特徴

  • 実践重視: 理論よりも実際に動作するコードに焦点
  • 最小限の依存関係: OpenAIとrequestsが主要な依存関係
  • Building Blocks アプローチ: 7つの基本要素を組み合わせてシステム構築
  • 本番対応: エラーハンドリング、バリデーション、人間の承認フローを含む
  • 包括的なカバレッジ: エージェント、RAG、メモリシステム、MCPなど幅広いトピック

使用方法

インストール

前提条件

  • Python 3.11以上
  • OpenAI APIキー（大部分の例で必要）
  • Git（リポジトリのクローン用）

インストール手順

# リポジトリのクローン
git clone https://github.com/daveebbelaar/ai-cookbook.git
cd ai-cookbook

# 仮想環境の作成（推奨）
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 必要なディレクトリに移動して依存関係をインストール
cd agents/building-blocks
pip install -r requirements.txt

# 環境変数の設定
export OPENAI_API_KEY="your-api-key-here"

基本的な使い方

Hello World相当の例

# 最も基本的なLLM呼び出し
from openai import OpenAI

def basic_intelligence(prompt: str) -> str:
    client = OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# 使用例
result = basic_intelligence("What is artificial intelligence?")
print(result)

実践的な使用例

# RAGシステムでの文書検索
import lancedb

# データベースに接続
uri = "data/lancedb"
db = lancedb.connect(uri)

# テーブルを開く
table = db.open_table("docling")

# ベクトル検索を実行
results = table.search(
    query="What is docling?", 
    query_type="vector"
).limit(3).to_pandas()

# 結果を表示
for idx, row in results.iterrows():
    print(f"Score: {row['_distance']}")
    print(f"Content: {row['text'][:200]}...")
    print("---")

高度な使い方

# メモリシステムを使った会話の文脈保持
from mem0 import Memory
from dotenv import load_dotenv

load_dotenv()
m = Memory()

# 会話履歴
messages = [
    {"role": "user", "content": "I love sci-fi movies."},
    {"role": "assistant", "content": "Great! I'll remember that."}
]

# メモリに追加
m.add(messages, user_id="user123", metadata={"category": "preferences"})

# 後の会話で文脈を活用
related_memories = m.search("What movies should I recommend?", user_id="user123")

# 人間の承認を含むワークフロー
def intelligence_with_approval(prompt: str) -> str:
    client = OpenAI()
    
    # AIの応答を生成
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    draft = response.choices[0].message.content
    
    # 人間の承認を求める
    print(f"AI Draft: {draft}")
    if input("Approve? (y/n): ").lower().startswith('y'):
        return draft
    else:
        return "Response not approved"

ドキュメント・リソース

公式ドキュメント

  • README.md: プロジェクト概要とDave Ebbelaarの紹介
  • agents/building-blocks/README.md: 7つのBuilding Blocksの詳細説明
  • knowledge/docling/README.md: Doclingを使ったRAGパイプラインの構築方法
  • knowledge/mem0/README.md: Mem0メモリシステムの実装ガイド
  • mcp/crash-course/README.md: MCPの包括的なクラッシュコース

サンプル・デモ

  • agents/building-blocks/1-7: 各Building Blockの実装例
  • knowledge/docling/1-5: 文書処理からRAG検索までの完全なパイプライン
  • patterns/workflows/: 4つの主要なワークフローパターンの実装

チュートリアル・ガイド

  • YouTubeチャンネル: https://www.youtube.com/@daveebbelaar
  • Data Alchemyコミュニティ: 無料の学習リソースとサポート
  • GenAI Launchpad: 本番環境向けフレームワーク

技術的詳細

アーキテクチャ

全体構造

このリポジトリは「複雑なフレームワークより、シンプルなBuilding Blocks」という哲学に基づいて構築されています。各コンポーネントは独立して動作し、必要に応じて組み合わせることができます。

ディレクトリ構成

ai-cookbook/
├── agents/                    # AIエージェントの構築パターン
│   └── building-blocks/       # 7つの基本要素の実装
├── knowledge/                 # 知識管理とRAGシステム
│   ├── docling/              # 文書処理とRAGパイプライン
│   └── mem0/                 # 高度なメモリシステム
├── mcp/                      # Model Context Protocol
│   └── crash-course/         # MCPの包括的なガイド
├── models/                   # LLMの使用パターン
│   └── openai/              # OpenAI API の実践的な使い方
└── patterns/                 # 設計パターン
    └── workflows/            # 4つの主要なワークフロー

主要コンポーネント

  • Intelligence (agents/building-blocks/1): LLM呼び出しの基本

    • 場所: agents/building-blocks/1-intelligence.py
    • 依存: OpenAI API
    • インターフェース: basic_intelligence(prompt) -> str

  • Memory (agents/building-blocks/2): 文脈の永続化

    • 場所: agents/building-blocks/2-memory.py
    • 依存: 辞書ベースのストレージ
    • インターフェース: add_memory(), get_memory()

  • Tools (agents/building-blocks/3): 外部システム統合

    • 場所: agents/building-blocks/3-tools.py
    • 依存: requests, APIs
    • インターフェース: use_tool(tool_name, params)

  • Validation (agents/building-blocks/4): スキーマ検証

    • 場所: agents/building-blocks/4-validation.py
    • 依存: Pydantic
    • インターフェース: validate_output(response, schema)

技術スタック

コア技術

  • 言語: Python 3.11+ (型ヒント、async/await対応)
  • LLMプロバイダー: OpenAI (GPT-4oがデフォルト)
  • 主要ライブラリ:
    • openai: LLM API アクセス
    • pydantic: データバリデーション
    • requests: HTTPリクエスト
    • python-dotenv: 環境変数管理

開発・運用ツール

  • ベクトルDB: LanceDB (軽量で組み込み可能)
  • メモリシステム: Mem0 (高精度な文脈管理)
  • 文書処理: Docling (マルチフォーマット対応)
  • UI: Streamlit (デモ用インターフェース)

設計パターン・手法

  • Building Blocks パターン: 7つの独立したコンポーネントの組み合わせ
  • 決定論的制御フロー: LLMは必要な箇所のみで使用
  • バリデーションゲート: 各ステップでの品質保証
  • 人間参加型ループ: 重要な決定での承認プロセス
  • エラーリカバリー: 失敗時の自動リトライとフォールバック

データフロー・処理フロー

  1. 入力受付: ユーザーからのリクエストを構造化
  2. バリデーション: Pydanticでスキーマ検証
  3. ルーティング: 決定論的なロジックで処理方法を決定
  4. LLM呼び出し: 必要な場合のみ、適切なコンテキストで実行
  5. 後処理: 応答の検証と形式整形
  6. 人間の承認: 必要に応じて承認フローを挿入
  7. エラーハンドリング: 失敗時のリカバリー処理

API・インターフェース

公開API

Building Blocks インターフェース

  • 目的: AIシステムの基本要素を提供
  • 使用例:
# インテリジェンス層
response = basic_intelligence("Explain quantum computing")

# メモリ層
memory.add("user_preference", "likes technical topics")
context = memory.get("user_preference")

# ツール層
result = use_tool("web_search", query="latest AI news")

# バリデーション層
validated = validate_output(response, ResponseSchema)

設定・カスタマイズ

設定ファイル

# .env ファイル
OPENAI_API_KEY=your-api-key
MODEL_NAME=gpt-4o
MAX_RETRIES=3
TEMPERATURE=0.7

# Pythonでの読み込み
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

拡張・プラグイン開発

各Building Blockは独立しているため、新しい機能の追加が容易：

  • 新しいツールの追加: tools.pyに関数を追加
  • カスタムバリデーター: Pydanticモデルを定義
  • 新しいメモリバックエンド: メモリインターフェースを実装

パフォーマンス・スケーラビリティ

パフォーマンス特性

  • Mem0の精度: OpenAIメモリより26%高い精度
  • トークン節約: Mem0使用で90%のトークン削減
  • レスポンス時間: 基本的なLLM呼び出しは1-3秒
  • 並列処理: ワークフローパターンで複数LLM呼び出しを並列化

スケーラビリティ

  • 各コンポーネントが独立しているため水平スケーリングが容易
  • ステートレスな設計により複数インスタンスの実行が可能
  • ベクトルDBは必要に応じて外部サービスに切り替え可能

制限事項

  • OpenAI APIのレート制限に依存
  • メモリシステムは現状ローカルストレージベース
  • 大規模な文書処理にはGPUが推奨される（Docling）

評価・所感

技術的評価

強み

  • 実践的なアプローチ: 理論より実際に動作するコードを重視
  • 最小限の複雑性: 必要最小限の依存関係で高機能を実現
  • 明確な責任分離: 各Building Blockが単一の責任を持つ
  • 本番環境対応: エラーハンドリングと人間の承認フローを含む
  • 教育的価値: 各概念が独立した例として学習可能

改善の余地

  • より多くのLLMプロバイダーのサポート
  • 分散システム向けのメモリバックエンド
  • より詳細なパフォーマンスベンチマーク
  • エンタープライズ向けの認証・認可機能

向いている用途

  • AIアプリケーションのプロトタイピング
  • 本番環境でのAIシステム構築
  • AIシステムのベストプラクティス学習
  • カスタムAIワークフローの実装
  • 既存システムへのAI機能の統合

向いていない用途

  • 完全自律型のAIエージェント（人間の監督なし）
  • リアルタイムの高頻度取引システム
  • セキュリティクリティカルな自動化
  • 大規模な分散AIシステム（追加の基盤が必要）

総評

Dave Ebbelaarのai-cookbookは、AIシステム構築における実践的な知恵の結晶です。「複雑なフレームワークより、シンプルで理解可能なコンポーネント」という哲学は、多くの開発者が陥りがちな過度な抽象化の罠を避け、実際に動作し保守可能なシステムを構築するための優れたアプローチです。

特に印象的なのは、LLMを「魔法の箱」として扱うのではなく、システムの一部として適切に制御する姿勢です。7つのBuilding Blocksは、それぞれが明確な責任を持ち、必要に応じて組み合わせることで複雑な要求にも対応できます。

このリポジトリは、AIシステムを「作って終わり」ではなく、「本番環境で運用する」ことを前提としているため、エラーハンドリング、バリデーション、人間の承認フローなど、実務で必要となる要素が最初から組み込まれています。これは、多くのAIチュートリアルが見落としがちな重要な点です。

総じて、AIエンジニアリングの実践的な教科書として、また本番環境で使えるコードのリファレンスとして、非常に価値の高いリソースと言えるでしょう。