daveebbelaar/ai-cookbook

⭐ 2,227 🍴 826 Python📄 MIT License GitHubで見る →

主な特徴

**7つの基本ビルディングブロック**: AIエージェント構築の基礎要素
**実践的なコードスニペット**: コピー&ペーストですぐに使える実装例
**Model Context Protocol (MCP)クラッシュコース**: 最新のMCP技術の包括的チュートリアル
**OpenAI APIの詳細ガイド**: 構造化出力、Function Calling、Responses等
**知識管理システム**: Docling、Mem0を使用した実装例
**ワークフローパターン**: プロンプトチェーン、ルーティング、並列化等
**プロダクション指向**: フレームワークに依存しないカスタム実装アプローチ

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

基本情報

リポジトリ名: daveebbelaar/ai-cookbook
主要言語: Python
スター数: 2,227
フォーク数: 826
最終更新: アクティブに更新中
ライセンス: MIT License
トピックス: AI Systems, LLM Applications, AI Agents, MCP, Structured Output, OpenAI, Knowledge Management

概要

一言で言うと

実用的なAIシステム構築のためのコードスニペットとチュートリアル集。フレームワークに依存せず、本番環境で実際に使えるアプローチを重視したAIアプリケーション開発の実践ガイド。

詳細説明

このCookbookは、AIエンジニアでありDataluminaの創設者であるDave Ebbelaar氏が作成した、AIシステム構築のための実践的なガイドです。多くのAIフレームワークが本番環境で使われていない現実を踏まえ、実際に動作するAIシステムを構築するためのプラグマティックなアプローチを提供しています。特に、LLMを「魔法の箱」として扱うのではなく、適切な場所で適切に使用することを強調しています。

主な特徴

7つの基本ビルディングブロック: AIエージェント構築の基礎要素
実践的なコードスニペット: コピー&ペーストですぐに使える実装例
Model Context Protocol (MCP)クラッシュコース: 最新のMCP技術の包括的チュートリアル
OpenAI APIの詳細ガイド: 構造化出力、Function Calling、Responses等
知識管理システム: Docling、Mem0を使用した実装例
ワークフローパターン: プロンプトチェーン、ルーティング、並列化等
プロダクション指向: フレームワークに依存しないカスタム実装アプローチ

使用方法

インストール

前提条件

Python 3.8以上
Git
OpenAI APIキー（一部の例で必要）
その他のAPIキー（使用するサービスに応じて）

インストール手順

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

# 使用したいセクションに移動（例：AIエージェントのビルディングブロック）
cd agents/building-blocks

# 依存関係のインストール
# uvを使用（推奨）
uv pip install -r requirements.txt

# またはpipを使用
pip install -r requirements.txt

基本的な使い方

Hello World相当の例（Intelligenceビルディングブロック）

# 1-intelligence.py
from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# シンプルなLLM呼び出し
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, how are you?"}
    ]
)

print(response.choices[0].message.content)

実践的な使用例（Tool使用とValidation）

# 3-tools.py と 4-validation.py の組み合わせ
from pydantic import BaseModel
import json

# スキーマ定義
class TicketClassification(BaseModel):
    category: str
    priority: str
    summary: str

# Tool定義
tools = [
    {
        "type": "function",
        "function": {
            "name": "classify_ticket",
            "description": "Classify a support ticket",
            "parameters": TicketClassification.model_json_schema()
        }
    }
]

# LLMによる分類と検証
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=tools,
    tool_choice="required"
)

# 結果の検証
tool_call = response.choices[0].message.tool_calls[0]
arguments = json.loads(tool_call.function.arguments)
validated_data = TicketClassification(**arguments)  # Pydanticによる検証

高度な使い方（MCPサーバーとクライアント）

# MCPサーバーの実装
from mcp.server import Server, stdio_server
from mcp.types import Tool, TextContent

server = Server("my-knowledge-server")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="search",
            description="Search the knowledge base",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                },
                "required": ["query"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "search":
        # 検索ロジックの実装
        results = search_knowledge_base(arguments["query"])
        return [TextContent(type="text", text=json.dumps(results))]

# サーバーの起動
async def main():
    async with stdio_server() as streams:
        await server.run(
            streams[0], streams[1], 
            server.create_initialization_options()
        )

ドキュメント・リソース

公式ドキュメント

各セクションのREADME: 詳細な説明と実装方法
YouTubeチャンネル: https://www.youtube.com/@daveebbelaar
Dataluminaサイト: https://www.datalumina.com/
GenAI Launchpad: https://launchpad.datalumina.com/

サンプル・デモ

agents/building-blocks/: 7つの基本ビルディングブロックの実装例
knowledge/docling/: ドキュメント処理から検索システムまでの完全なパイプライン
knowledge/mem0/: メモリ管理システムの実装（クラウドとOSS両方）
mcp/crash-course/: MCPの基礎からOpenAI統合まで
models/openai/: 構造化出力、Assistants API、Responsesの使用例
patterns/workflows/: ワークフローパターンと設計パターン

チュートリアル・ガイド

AIエージェントの7つの基本ビルディングブロック
MCPクラッシュコース（Python開発者向け）
OpenAI APIの構造化出力チュートリアル
ワークフローパターンの実装ガイド

技術的詳細

アーキテクチャ

全体構造

このCookbookは、モジュラーなアプローチを採用しています。各セクションは独立して動作し、特定の問題解決にフォーカスしています。基本的な哲学は「LLMは魔法の箱ではなく、適切なツール」というもので、決定論的なコードで解決できない場合のみ使用することを推奨しています。

ディレクトリ構成

ai-cookbook/
├── agents/            # AIエージェント構築
│   └── building-blocks/  # 7つの基本ビルディングブロック
├── knowledge/         # 知識管理システム
│   ├── docling/         # ドキュメント処理パイプライン
│   └── mem0/            # メモリ管理システム
├── mcp/               # Model Context Protocol
│   └── crash-course/    # MCPクラッシュコース
├── models/            # LLMモデルの使用例
│   └── openai/          # OpenAI APIの詳細ガイド
└── patterns/          # 設計パターン
    └── workflows/       # ワークフローパターン

主要コンポーネント

7つの基本ビルディングブロック: AIエージェント構築の基礎要素
- 場所: agents/building-blocks/
- 依存: OpenAI SDK、Pydantic、その他の基本ライブラリ
- インターフェース: Intelligence、Memory、Tools、Validation、Control、Recovery、Feedback
MCPサーバー/クライアント: Model Context Protocolの実装
- 場所: mcp/crash-course/
- 依存: mcp、openai、asyncio
- インターフェース: Server、Client、Tool、Resource、Prompt
知識管理システム: ドキュメント処理と検索
- 場所: knowledge/docling/、knowledge/mem0/
- 依存: docling、mem0、sentence-transformers、chromadb
- インターフェース: 抽出、チャンキング、埋め込み、検索、チャット
ワークフローパターン: AIシステムの設計パターン
- 場所: patterns/workflows/
- 依存: 基本的なPythonライブラリ
- インターフェース: プロンプトチェーン、ルーティング、並列化、オーケストレーター

技術スタック

コア技術

言語: Python 3.8+（型ヒント、async/await、データクラス使用）
フレームワーク:
- フレームワークを避け、カスタム実装を推奨
- 必要に応じてPydantic、FastAPI等を活用
主要ライブラリ:
- openai: OpenAI APIクライアント
- pydantic: データ検証とスキーマ定義
- mcp: Model Context Protocol SDK
- docling: ドキュメント処理
- mem0: メモリ管理
- chromadb: ベクトルデータベース
- sentence-transformers: 文章埋め込み
- instructor: 構造化出力の強化

開発・運用ツール

パッケージ管理: pip、uv（推奨）
環境管理: Python仮想環境
コード品質: シンプルで読みやすいコードを重視
デプロイ: Dockerサポート（MCPセクション）

設計パターン・手法

ビルディングブロックパターン: 7つの基本要素を組み合わせてシステム構築
決定論的コード優先: LLM呼び出しを最小限に
コンテキストエンジニアリング: 適切なコンテキストの構築と管理
ワークフローパターン:
- プロンプトチェーン: 連続的なプロンプトの連鎖
- ルーティング: 意図に基づく処理の分岐
- 並列化: 複数タスクの同時実行
- オーケストレーション: 中央制御によるタスク管理

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

入力処理: ユーザー入力の受け取りと前処理
意図分類: Controlブロックでのルーティング
コンテキスト構築: Memoryブロックからの情報取得
LLM処理: Intelligenceブロックでの推論
ツール実行: Toolsブロックでの外部操作
検証: Validationブロックでの出力確認
エラーハンドリング: Recoveryブロックでの障害対応
承認: Feedbackブロックでの人間確認（必要時）
出力: 最終結果の返却

API・インターフェース

公開API

7つのビルディングブロックAPI

目的: AIエージェント構築の基礎コンポーネント
使用例:

# Intelligence: LLM呼び出し
response = await call_llm(prompt, model="gpt-4o-mini")

# Memory: コンテキスト管理
context = memory.get_context(user_id)
memory.add_message(user_id, message)

# Tools: 外部システム統合
result = await execute_tool("search", {"query": query})

# Validation: スキーマ検証
validated_data = validate_output(response, schema=MySchema)

# Control: フロー制御
route = determine_route(intent)

# Recovery: エラーハンドリング
result = with_retry(operation, max_attempts=3)

# Feedback: 承認フロー
if requires_approval(action):
    approved = await get_human_approval(action)

MCPサーバーAPI

目的: 外部システムとLLMの標準化された統合
使用例:

# MCPサーバーの定義
server = Server("my-server")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [Tool(...)]  # ツール定義

@server.list_resources()
async def list_resources() -> list[Resource]:
    return [Resource(...)]  # リソース定義

@server.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [Prompt(...)]  # プロンプト定義

設定・カスタマイズ

環境変数設定

# APIキー
export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"

# モデル設定
export DEFAULT_MODEL="gpt-4o-mini"
export DEFAULT_TEMPERATURE="0.7"

拡張・プラグイン開発

新しいビルディングブロックの追加
カスタムツールの実装
MCPサーバーのカスタマイズ
ワークフローパターンの拡張

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

パフォーマンス特性

LLM呼び出しの最小化: 決定論的コードで解決可能な部分はLLMを使わない
最適化手法:
- コンテキストの効率的な管理
- キャッシュの活用
- バッチ処理
- 並列化可能なタスクの同時実行

スケーラビリティ

水平スケーリング: 各ビルディングブロックの独立性による容易なスケールアウト
MCPを使用した分散処理: 複数のMCPサーバーの並列利用
メモリ管理: Mem0による効率的なコンテキスト管理
ベクトルデータベース: ChromaDBによる大規模検索

制限事項

LLM APIのレート制限
コスト（LLM API呼び出しは最も高価な操作）
確率的な出力による予測不可能性
コンテキスト長の制限

評価・所感

技術的評価

強み

実用的なアプローチ: 本番環境で実際に使える実装方法
明確な哲学: LLMの適切な使い方に関する明確なガイダンス
モジュラー設計: 各コンポーネントが独立して動作
包括的なカバレッジ: 基礎から高度な実装まで
最新技術のサポート: MCP、構造化出力、Responses等

改善の余地

テストコードの充実
CI/CDパイプラインの整備
より多くのLLMプロバイダーのサポート
パフォーマンスベンチマーク

向いている用途

本番環境でのAIシステム構築
バックグラウンド自動化システム
カスタムAIエージェントの開発
既存システムへのAI機能統合
プロトタイプ開発

向いていない用途

完全に自律的なAIエージェント（人間の監視が必要）
リアルタイムクリティカルシステム
初心者向けのノーコードソリューション

総評

ai-cookbookは、AIシステム開発の現実的な課題に対するプラグマティックなソリューションを提供する優れたリソースです。特に、「LLMは魔法の箱ではなく、適切なツール」という明確な哲学は、多くの開発者が陥りがちなフレームワーク依存の罠を避けるのに役立ちます。7つのビルディングブロックアプローチはシンプルながら強力で、複雑なビジネス問題を解決するための明確なフレームワークを提供しています。また、MCPのような最新技術も取り入れており、実用性と先進性のバランスが取れています。