メインコンテンツへ移動
AIチュートリアル

AI搭載WeChat学習ミニアプリの構築と実行

AIナレッジベース・スマート学習ミニアプリの設定と実行方法、FastAPIバックエンドとTaroフロントエンドの接続、サービスの動作確認、テストの実行、Dockerベースのバックエンドのデプロイ準備について解説します。

約12分で読了
AI搭載WeChat学習ミニアプリの構築と実行

構築するもの

AI Knowledge Base Smart Learning Mini Appは、WeChatエコシステム向けのインテリジェントな学習アプリケーションです。学習者はトピックを入力するか、非公開ドキュメントをアップロードできます。その後、AI支援ワークフローを使って問題を生成し、すぐに解説を受け、理解度、弱点、推奨される次のステップをまとめたレポートを確認できます。

このプロジェクトは、大規模言語モデル、ウェブ検索、検索拡張生成（RAG）を組み合わせています。Tavilyは最新のウェブコンテキストを提供し、ChromaはアップロードされたPDF、Word、Markdown、TXTファイルからの検索をサポートします。

主な機能

  • トピックベースの問題生成：ユーザーが指定したトピックから学習問題を生成します。
  • ウェブ検索による強化：Tavilyを使って最新のコンテキストを追加します。
  • 非公開ナレッジベース学習：PDF、Word、Markdown、TXTドキュメントをアップロードし、RAGで関連コンテンツを検索します。
  • 即時フィードバック：回答を確認し、各回答の後に解説を返します。
  • 学習レポート：理解度を分析し、弱点を特定して学習の提案を行います。
  • 問題用イラスト：補助画像を生成し、Tencent Cloud COSに保存します。
  • WeChatユーザー対応：ログイン、学習履歴、レポート確認を提供します。
  • コンテナデプロイ：Dockerを使ってバックエンドをWeChat Cloud Runまたは互換プラットフォームにデプロイします。

アーキテクチャを理解する

ミニアプリのフロントエンドは、Taro 4、React 18、TypeScript、Sassを使用します。バックエンドはPython 3.11上で、FastAPI、Pydantic v2、Uvicornを使用して動作します。LangChainとLangGraphがAI処理を調整し、DeepSeekとAlibaba Bailianがモデルおよび検索スタックに含まれています。

MySQLはアプリケーションデータを保存し、Tencent Cloud COSは生成されたイラストを保存します。Chromaはベクトルストアとして機能します。認証にはWeChatのjscode2sessionとJWTを使用します。バックエンドのテストにはpytestとpytest-asyncioを使用します。

リポジトリ構成

.
├── backend/        # FastAPIバックエンド
├── frontend/       # TaroベースのWeChatミニアプリフロントエンド
├── docs/           # ローカルで管理するプロジェクトドキュメント
├── openspec/       # ローカルで管理する仕様ファイル
└── prototypes/     # ローカルで管理するプロトタイプファイル

前提条件

開始する前に、Python 3.11、npmを含むNode.js、WeChat DevToolsをインストールしてください。また、backend/.env.exampleで想定されているサービス認証情報と設定値が必要です。Dockerが必要になるのは、バックエンドコンテナをビルドまたはデプロイする段階だけです。

実際のAPIキー、データベース認証情報、JWTシークレット、クラウドストレージ認証情報をバージョン管理に含めないでください。本番環境のシークレットは、デプロイプラットフォームを通じて注入してください。

ステップ1：バックエンドを設定する

ターミナルを開き、backendディレクトリに移動して、分離されたPython環境を作成します。READMEには、PowerShell向けの次のセットアップが記載されています。

cd backend
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env

新しく作成された.envファイルを開き、選択したモデル、Tavily連携、データベース、認証、ベクトル検索、Tencent Cloudストレージに必要な設定を入力します。想定される変数の正式な一覧としてbackend/.env.exampleを使用してください。

FastAPIサービスを起動する

python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

--reloadオプションは、バックエンドコードの変更時にUvicornが再起動するため、ローカル開発で役立ちます。0.0.0.0にバインドすると、開発サービスをマシンのネットワークインターフェース経由で利用できるようになります。

バックエンドを確認する

起動後、インタラクティブAPIドキュメントをhttp://localhost:8000/docsで開きます。サービスのヘルス状態はhttp://localhost:8000/api/v1/healthでも確認できます。

フロントエンドのトラブルシューティングを行う前に、ヘルスエンドポイントを確認してください。利用できない場合は、仮想環境が有効になっていること、依存関係のインストールが正常に完了していること、.envファイルが存在すること、ポート8000がすでに使用されていないことを確認します。

ステップ2：WeChatミニアプリのフロントエンドをビルドする

バックエンドを起動したまま、2つ目のターミナルを開き、フロントエンドの依存関係をインストールします。

cd frontend
npm install
npm run dev:weapp

開発コマンドは、TaroアプリケーションをWeChat向けにコンパイルします。コンパイルが完了したら、WeChat DevToolsを起動し、生成されたfrontend/distディレクトリを開きます。

フロントエンドの変更を再ビルドできるよう、開発中はコンパイラのターミナルを開いたままにしてください。ミニアプリがバックエンド機能にアクセスできるよう、FastAPIサーバーも専用のターミナルで起動したままにします。

ステップ3：学習ワークフローを試す

フロントエンドとバックエンドが起動すると、このプロジェクトでは主に2つの学習パスを利用できます。

トピックから問題を生成する

  1. WeChatユーザーフローでログインします。
  2. 学習したい科目を入力します。
  3. そのトピックに基づいてAI支援問題を生成します。
  4. 回答を送信し、返された正解と解説を確認します。
  5. 学習セッションを完了し、理解度の分析、弱点、推奨事項を含むAIレポートを確認します。

非公開ドキュメントで学習する

  1. 対応しているPDF、Word、Markdown、またはTXTドキュメントを選択します。
  2. アプリケーションのナレッジベースワークフローにアップロードします。
  3. システムがRAGパイプラインを通じて、関連するドキュメントのコンテキストを取得できるようにします。
  4. 生成された質問に回答し、解説を確認します。
  5. 作成されたレポートを使って、教材のどの部分をさらに学習する必要があるか判断します。

トピックベースの学習では、Tavilyを使って最近のWebコンテキストを追加できます。一方、ドキュメントベースの学習では、アップロードした非公開資料を基盤として検索します。利用できる具体的な動作は、バックエンド環境で設定されているサービスと認証情報によって異なります。

ステップ4：テストスイートを実行する

backendディレクトリからバックエンドのテストを実行します。

cd backend
pytest

このプロジェクトではpytestとpytest-asyncioを使用しています。バックエンドを変更した後、デプロイ前にテストスイートを実行し、同期処理と非同期処理のリグレッションを検出します。

高度なヒント

開発中はAPIドキュメントを使用する

FastAPIのドキュメントページは、実行中のプロジェクトのバージョンで公開されているルートを確認するのに役立ちます。READMEに記載されていないリクエストフィールドやエンドポイントパスを想定せず、ドキュメントを正確な情報源として使用してください。

開発用と本番用のシークレットを分離する

ローカルの.envファイルは開発専用に使用します。本番環境では、WeChat Cloud Runまたは選択したコンテナプラットフォームを通じてシークレットを設定してください。値が入力された環境ファイルをリポジトリにコミットしないでください。

適切なナレッジソースを選択する

最新性が重要な場合は、Tavilyを使ったトピック生成を使用します。非公開または組織固有の資料に基づいて質問を生成する場合は、ドキュメントワークフローを使用します。アップロードに対応しているのはPDF、Word、Markdown、TXTファイルです。

サービスを段階的に検証する

  1. ヘルスエンドポイントが応答することを確認します。
  2. FastAPIのドキュメントを確認します。
  3. pytestを実行します。
  4. Taroフロントエンドをコンパイルします。
  5. WeChat DevToolsでfrontend/distを開きます。
  6. 設定済みの外部サービスを使って、ログイン、クイズ生成、フィードバック、履歴、レポート確認をテストします。

この順序で進めると、バックエンドの設定問題と、フロントエンドのコンパイルやWeChatツールに関する問題を切り分けやすくなります。

コンテナデプロイに備える

リポジトリにはbackend/Dockerfileとbackend/.dockerignoreが含まれています。これらのファイルにより、WeChat Cloud Runまたは別の互換プラットフォーム向けにバックエンドをDockerコンテナとしてパッケージ化できます。

デプロイ前にテストを実行し、必要な本番環境変数がプラットフォーム経由で利用できることを確認してください。また、イメージにシークレットを含めないでください。MySQL、Tencent Cloud COS、モデルプロバイダー、Tavily、WeChat認証などの外部依存サービスに、デプロイ環境から接続できることを確認します。

まとめ

このプロジェクトは、WeChat上でAI支援学習を実現するための完全な基盤を提供します。TaroとReactによるミニアプリ、FastAPIバックエンド、トピックおよびドキュメントベースのクイズ生成、即時解説、学習レポート、ユーザー履歴、コンテナ対応のデプロイが含まれています。まずバックエンドを検証し、WeChat DevToolsでフロントエンドをコンパイルしてから、選択した学習ワークフローに必要な外部サービスを設定してください。