diff --git a/docs/deployment.ja.md b/docs/deployment.ja.md new file mode 100644 index 0000000..1a5fb45 --- /dev/null +++ b/docs/deployment.ja.md @@ -0,0 +1,31 @@ +# デプロイメント手順 + +## Docker Hub + +Docker Hub に Docker イメージを公開するには、[アクセストークンを作成](https://app.docker.com/settings/personal-access-tokens/create)し、リポジトリ設定で以下のシークレットを設定する必要があります。 + +```shell +gh secret set DOCKERHUB_USERNAME --body $DOCKERHUB_USERNAME +gh secret set DOCKERHUB_TOKEN --body $DOCKERHUB_TOKEN +``` + +## Azure Static Web Apps + +```shell +RESOURCE_GROUP_NAME=your-resource-group-name +SWA_NAME=your-static-web-app-name + +# 静的アプリを作成する +az staticwebapp create --name $SWA_NAME --resource-group $RESOURCE_GROUP_NAME + +# APIキーを取得する +AZURE_STATIC_WEB_APPS_API_TOKEN=$(az staticwebapp secrets list --name $SWA_NAME --query "properties.apiKey" -o tsv) + +# APIキーをGitHubシークレットとして設定する +gh secret set AZURE_STATIC_WEB_APPS_API_TOKEN --body $AZURE_STATIC_WEB_APPS_API_TOKEN +``` + +詳細については、以下のリンクを参照してください： + +- [Azure Static Web App へのデプロイ](https://docs.github.com/en/actions/use-cases-and-examples/deploying/deploying-to-azure-static-web-app) +- [静的 Web アプリの作成: `az staticwebapp create`](https://learn.microsoft.com/en-us/cli/azure/staticwebapp?view=azure-cli-latest#az-staticwebapp-create) diff --git a/docs/development.ja.md b/docs/development.ja.md new file mode 100644 index 0000000..492d48c --- /dev/null +++ b/docs/development.ja.md @@ -0,0 +1,39 @@ +# 開発手順 + +## ローカル開発 + +Makefile を使用してプロジェクトをローカルで実行します。 + +```shell +# ヘルプを表示 +make + +# 開発用の依存関係をインストール +make install-deps-dev + +# テストを実行 +make test + +# CIテストを実行 +make ci-test +``` + +## テスト + +```shell +# AIエージェントのすべてのテストを実行 +bash scripts/test_all.sh +``` + +## Docker 開発 + +```shell +# Dockerイメージをビルド +make docker-build + +# Dockerコンテナを実行 +make docker-run + +# DockerコンテナでCIテストを実行 +make ci-test-docker +``` diff --git a/docs/faq.ja.md b/docs/faq.ja.md new file mode 100644 index 0000000..84c1070 --- /dev/null +++ b/docs/faq.ja.md @@ -0,0 +1,21 @@ +# よくある質問 + +## Docker Compose で Elasticsearch を起動できない + +**現象:** + +WSL2 上で `docker compose up elasticsearch` を実行した際に、以下のエラーが発生する + +`java.lang.IllegalStateException: failed to obtain node locks, tried [/usr/share/elasticsearch/data]; maybe these locations are not writable or multiple nodes were started on the same data path?` + +**原因:** + +Elasticsearch がデータディレクトリ（/usr/share/elasticsearch/data）にロックファイルを作成できないことを示しています。 + +**対処方法:** + +ディレクトリの権限を修正するために、以下のコマンドを実行してください。 + +```shell +sudo chown -R 1000:1000 ./assets/es_data +``` diff --git a/docs/index.ja.md b/docs/index.ja.md new file mode 100644 index 0000000..52ee0ff --- /dev/null +++ b/docs/index.ja.md @@ -0,0 +1,253 @@ +# LangGraph AI エージェント テンプレート + +[LangGraph](https://langchain-ai.github.io/langgraph/)を使用して AI エージェントを構築するための包括的なテンプレートプロジェクト。様々なエージェントパターン、ツール統合、実際のユースケースを実演します。 + +## LangGraph とは？ + +[LangGraph](https://langchain-ai.github.io/langgraph/)は[LangChain](https://python.langchain.com/)の上に構築されたフレームワークで、ステートフルなマルチエージェントワークフローを作成できます。単一のインタラクションを処理する従来のチャットボットとは異なり、LangGraph では以下のような複雑な AI システムを構築できます： + +- 複数のターンにわたって会話状態を維持 +- ツールと外部 API の使用 +- 複雑な推論パターンの実装 +- 複数の AI エージェントの協調 +- 循環ワークフローと条件ロジックの処理 + +このテンプレートは、トラブルシューティングシナリオ用の架空のシステム「KABUTO」を使用して、これらの機能を実際の例で示しています。 + +## プロジェクト概要 + +このプロジェクトは、シンプルなツール呼び出しエージェントから複雑なマルチエージェントシステムまで、異なる AI エージェントパターンとアーキテクチャを紹介しています。例では、エージェントが複数のデータソースから情報を取得し、構造化された回答を提供する方法を示すために、架空の技術サポートシナリオを使用しています。 + +### このテンプレートが存在する理由 + +多くの AI アプリケーションは以下のことが必要です： + +1. **外部情報へのアクセス** - LLM は特定のデータにアクセスできません +2. **ツールの使用** - テキスト生成以外のアクションを実行 +3. **コンテキストの維持** - 以前のインタラクションを記憶 +4. **複雑なワークフローの処理** - タスクを管理可能なステップに分解 + +このテンプレートは、LangGraph を使用してこれらすべてのパターンの動作例を提供しています。 + +## 前提条件 + +- [Python 3.10+](https://www.python.org/downloads/) +- [uv](https://docs.astral.sh/uv/getting-started/installation/) - モダンな Python パッケージマネージャー +- [GNU Make](https://www.gnu.org/software/make/) - 一般的なタスクの実行用 +- [Docker](https://www.docker.com/) - ベクターデータベースの実行用（オプション） + +## クイックスタート + +### 1. 環境設定 + +```shell +# リポジトリをクローン +git clone https://github.com/ks6088ts-labs/template-langgraph.git +cd template-langgraph + +# Python依存関係をインストール +uv sync --all-extras + +# 環境設定を作成 +cp .env.template .env +# .envを編集してAPIキー（Azure OpenAIなど）を設定 +``` + +### 2. サポートサービスの開始（オプション） + +完全な機能のために、ベクターデータベースを開始します： + +```shell +# DockerでQdrantとElasticsearchを開始 +docker compose up -d +``` + +### 3. データソースの初期化 + +**Qdrant ベクターデータベースの設定:** + +```shell +uv run python scripts/qdrant_operator.py add-documents \ + --collection-name qa_kabuto \ + --verbose +``` + +**Elasticsearch 検索インデックスの設定:** + +```shell +uv run python scripts/elasticsearch_operator.py create-index \ + --index-name docs_kabuto \ + --verbose +``` + +## プロジェクト構造 + +### コアコンポーネント + +- **`data/`** - 架空の KABUTO システム用のサンプルデータ（PDF、FAQ、トラブルシューティングガイド） +- **`template_langgraph/`** - すべてのエージェント実装を含むメイン Python パッケージ +- **`notebooks/`** - インタラクティブな例と説明付き Jupyter ノートブック +- **`scripts/`** - エージェント実行用コマンドラインツール + +### エージェントの例（`template_langgraph/agents/`） + +このプロジェクトには、それぞれ異なる LangGraph パターンを実演する複数のエージェント実装が含まれています： + +#### 1. `kabuto_helpdesk_agent/` - **ここから始めよう！** + +LangGraph の事前構築された`create_react_agent`関数を使用したシンプルなエージェント。基本を理解するのに最適な出発点です。 + +**主要概念:** ReAct パターン、ツール呼び出し、事前構築エージェント + +#### 2. `chat_with_tools_agent/` - **コア実装** + +ヘルプデスクエージェントと同じロジックの手動実装で、LangGraph ワークフローがゼロから構築される方法を示しています。 + +**主要概念:** グラフ構築、状態管理、ノード関数、エッジ + +#### 3. `issue_formatter_agent/` - **構造化出力** + +Pydantic モデルを使用して AI 応答から構造化データを取得する方法を実演しています。 + +**主要概念:** 構造化出力、データ検証、レスポンス形式設定 + +#### 4. `task_decomposer_agent/` - **計画と分解** + +複雑なタスクを小さく管理可能なステップに分解する方法を示しています。 + +**主要概念:** タスク計画、マルチステップ推論、条件付きワークフロー + +#### 5. `supervisor_agent/` - **マルチエージェント協調** + +1 つのエージェントが複数の専門エージェントを協調させるスーパーバイザーパターンを実装しています。 + +**主要概念:** マルチエージェントシステム、エージェント協調、スーパーバイザーパターン + +### サポートモジュール + +- **`template_langgraph/llms/`** - LLM API ラッパー（Azure OpenAI など） +- **`template_langgraph/tools/`** - 検索、データ取得用ツール実装 +- **`template_langgraph/utilities/`** - ドキュメント読み込みと処理用ヘルパー関数 + +## 例の実行 + +### オプション 1: LangGraph Studio（開発用推奨） + +[LangGraph Studio](https://langchain-ai.github.io/langgraph/concepts/langgraph_studio/)は、エージェントの開発とデバッグのためのビジュアルインターフェースを提供します： + +```shell +uv run langgraph dev +``` + +これにより、以下が可能な Web インターフェースが開きます： + +- エージェントワークフローの可視化 +- 実行のステップスルー +- 状態遷移のデバッグ +- 異なる入力のテスト + +![langgraph-studio.png](./images/langgraph-studio.png) + +### オプション 2: Jupyter ノートブック（学習に最適） + +説明と例付きのインタラクティブノートブック： + +```shell +uv run jupyter lab +# http://localhost:8888 に移動し、notebooks/*.ipynbを開く +``` + +![jupyterlab.png](./images/jupyterlab.png) + +### オプション 3: コマンドライン（本番環境的） + +ターミナルからエージェントを実行： + +```shell +uv run python scripts/agent_operator.py run \ + --name "chat_with_tools_agent" \ + --question "KABUTO startup issue: screen flashes purple and system freezes" \ + --verbose +``` + +エージェントの推論プロセスを示す出力例： + +```text +Event: {'chat_with_tools': {'messages': [AIMessage(content='', tool_calls=[ + {'name': 'search_elasticsearch', 'args': {'keywords': 'KABUTO startup purple flashing freeze'}}, + {'name': 'search_qdrant', 'args': {'keywords': 'KABUTO startup purple flashing freeze'}} +])]}} + +Event: {'tools': {'messages': [ToolMessage(content='Found documentation about startup protocol...')]}} + +Event: {'chat_with_tools': {'messages': [AIMessage(content=' +### 問題分析 +KABUTO起動時の紫画面点滅は「忍者プロトコル」初期化エラーを示しています... + +### 解決策 +1. **周辺機器の切断**: すべての接続デバイスを5秒以上取り外す +2. **外部クロックキャッシュのクリア**: クロック同期問題を解決 +3. **KABUTOの再起動**: 必要に応じて「ドラゴンボール」ボタンを5秒以上押す +')]}} +``` + +## 実演されている主要概念 + +### 1. **ReAct パターン**（推論 + 行動） + +現代の AI エージェントの基盤 - 何をすべきかを推論し、行動を取り、結果について推論する能力。 + +### 2. **ツール呼び出し** + +エージェントが外部関数を使用する方法： + +- データベース検索（Elasticsearch、Qdrant） +- API 呼び出し +- ファイル処理 +- 計算実行 + +### 3. **状態管理** + +LangGraph が複数のインタラクションステップにわたってコンテキストを維持し、複雑なマルチターン会話を可能にする方法。 + +### 4. **条件付きワークフロー** + +エージェントの決定や外部条件に基づく分岐ロジックを作成するためのグラフ構造の使用。 + +### 5. **マルチエージェントシステム** + +異なる専門知識を必要とする複雑なタスクを処理するための複数の専門エージェントの協調。 + +## データソースの説明 + +プロジェクトは実際のシナリオを実演するために「KABUTO」というシステムについての架空のデータを使用しています： + +- **`data/docs_kabuto.pdf`** - 技術文書（ユーザーマニュアルをシミュレート） +- **`data/qa_kabuto.csv`** - FAQ データベース（過去のサポートチケットをシミュレート） +- **`data/docs_kabuto.md`** - 追加文書 + +この架空のデータには目的があります：AI エージェントが LLM の訓練データにない情報で動作できることを証明し、検索拡張生成（RAG）の価値を実演しています。 + +## 次のステップ + +1. **基本から始める**: `kabuto_helpdesk_agent`の例を実行 +2. **実装を理解する**: `chat_with_tools_agent`と比較 +3. **高度なパターンを探索**: タスク分解器とスーパーバイザーエージェントを試す +4. **独自のものを構築**: このテンプレートをあなたのユースケースの出発点として使用 + +## 学習リソース + +- [LangGraph 文書](https://langchain-ai.github.io/langgraph/) +- [LangChain 文書](https://python.langchain.com/) + +## アーキテクチャの例 + +このテンプレートは複数の実証済みエージェントアーキテクチャを実演しています： + +1. **ツール付きシングルエージェント** - 基本的なツール呼び出しパターン +2. **ReAct エージェント** - ループでの推論と行動 +3. **構造化出力エージェント** - フォーマットされたデータの返却 +4. **計画エージェント** - 複雑なタスクの分解 +5. **スーパーバイザーエージェント** - 複数エージェントの協調 + +各パターンは、いつどのように使用するかを理解するのに役立つ明確な例と文書で実装されています。 diff --git a/docs/references.ja.md b/docs/references.ja.md new file mode 100644 index 0000000..5e7e371 --- /dev/null +++ b/docs/references.ja.md @@ -0,0 +1,21 @@ +# 参考資料 + +## LangGraph + +- [カスタムワークフローの構築](https://langchain-ai.github.io/langgraph/concepts/why-langgraph/) +- [LangGraph の(LLM なし)Human-in-the-loop を試してみた](https://qiita.com/te_yama/items/db38201af60dec76384d) +- [🤖 LangGraph Multi-Agent Supervisor](https://github.com/langchain-ai/langgraph-supervisor-py) +- [Software Design 誌「実践 LLM アプリケーション開発」第 24 回サンプルコード](https://github.com/mahm/softwaredesign-llm-application/tree/main/24) + +## サンプルコード + +- [「現場で活用するための AI エージェント実践入門」リポジトリ](https://github.com/masamasa59/genai-agent-advanced-book) + +## モデル + +- [AzureOpenAIEmbeddings](https://python.langchain.com/docs/integrations/text_embedding/azureopenai/) + +## ツール + +- [CSVLoader](https://python.langchain.com/docs/how_to/document_loader_csv/) +- [Qdrant](https://github.com/qdrant/qdrant) diff --git a/mkdocs.yml b/mkdocs.yml index 746f2e1..9af7199 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,3 +46,14 @@ extra: analytics: provider: google property: G-0ZTKFXVQ5K +plugins: + - i18n: + docs_structure: suffix + languages: + - locale: en + default: true + name: English + build: true + - locale: ja + name: 日本語 + build: true diff --git a/pyproject.toml b/pyproject.toml index 11cf874..95e325a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,6 +23,7 @@ dependencies = [ [dependency-groups] docs = [ "mkdocs-material>=9.6.14", + "mkdocs-static-i18n>=1.3.0", ] [tool.uv] diff --git a/uv.lock b/uv.lock index 646ba0f..07f6ac0 100644 --- a/uv.lock +++ b/uv.lock @@ -2039,6 +2039,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" }, ] +[[package]] +name = "mkdocs-static-i18n" +version = "1.3.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mkdocs" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/03/2b/59652a2550465fde25ae6a009cb6d74d0f7e724d272fc952685807b29ca1/mkdocs_static_i18n-1.3.0.tar.gz", hash = "sha256:65731e1e4ec6d719693e24fee9340f5516460b2b7244d2a89bed4ce3cfa6a173", size = 1370450, upload-time = "2025-01-24T09:03:24.389Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ca/f7/ef222a7a2f96ecf79c7c00bfc9dde3b22cd2cc1bd2b7472c7b204fc64225/mkdocs_static_i18n-1.3.0-py3-none-any.whl", hash = "sha256:7905d52fff71d2c108b6c344fd223e848ca7e39ddf319b70864dfa47dba85d6b", size = 21660, upload-time = "2025-01-24T09:03:22.461Z" }, +] + [[package]] name = "multidict" version = "6.6.3" @@ -3691,6 +3703,7 @@ dev = [ ] docs = [ { name = "mkdocs-material" }, + { name = "mkdocs-static-i18n" }, ] [package.metadata] @@ -3721,7 +3734,10 @@ dev = [ { name = "ruff", specifier = ">=0.11.7" }, { name = "ty", specifier = ">=0.0.1a6" }, ] -docs = [{ name = "mkdocs-material", specifier = ">=9.6.14" }] +docs = [ + { name = "mkdocs-material", specifier = ">=9.6.14" }, + { name = "mkdocs-static-i18n", specifier = ">=1.3.0" }, +] [[package]] name = "tenacity"