意味理解 LLM -- システムアーキテクチャ設計

概要

LLM モジュールは FastAPI ベースの大規模言語モデル対話サービスで、Function Calling と MCP 統合に対応したインテリジェント対話システムです。本システムはモジュール設計を採用しており、音楽再生、ロボットアーム制御、雲台制御、画像認識など、さまざまな外部ツールの統合に対応しています。

🏗️ システムアーキテクチャ

全体アーキテクチャ図

+-------------------+
|   Web浏览器前端    |
+-------------------+
         |
   HTTP/WebSocket
         |
+-------------------+
|   FastAPI服务器    |
+-------------------+
         |
   +-----+-----+
   |           |
   |  LLM核心  |<---> 配置管理
   |  服务模块 |
   +-----------+
         |
    +----+----+
    |         |
    | 对话管理 | Function Calling
    | 器      | 工具集成
    +----+----+
         |
   +-----+-----+
   |           |
   | MCP管理器 | 火山引擎API
   |          |
   +-----------+

🔧 コアコンポーネント

1. メインアプリケーション (main.py)

FastAPI アプリケーションのエントリーポイント: HTTP と WebSocket のインターフェースを提供します
ライフサイクル管理: アプリケーションリソースの初期化とクリーンアップ
ルーティング管理: 各種 API エンドポイントを処理します
WebSocket 接続管理: リアルタイム通信の接続を管理します
ミドルウェア設定: CORS、静的ファイルサービスなど

主な機能:

REST API エンドポイント：/chat, /health, /config, /tools
WebSocket エンドポイント：/ws（リアルタイム対話用）
静的ファイルサービス：Web 画面のリソース

2. LLM クライアント (app/llm_client.py)

火山引擎 API との統合: 火山引擎の LLM サービスを利用します
ストリーミング／非ストリーミング対話: 2 種類の対話モードに対応
パラメータ設定: temperature、top_p、max_tokens などのモデルパラメータ
エラー処理: 充実した例外処理とリトライ機構
思考モード: モデルの思考プロセスの制御に対応

API 設定:

エンドポイント：https://ark.cn-beijing.volces.com/api/v3/chat/completions
モデル：doubao-seed-1-6-250615
Function Calling とツール呼び出しに対応

3. 対話マネージャー (app/conversation_manager.py)

複数セッションの管理: 複数の独立した対話セッションに対応
履歴管理: 対話コンテキストを自動的に維持
永続化ストレージ: 履歴の保存を設定可能
コンテキスト制御: 対話の長さをスマートに制御

特長:

セッションの分離：session_id ごとに独立して管理
履歴の制限：最大履歴件数を設定可能
メモリ管理：期限切れのセッションを自動的にクリーンアップ

4. 設定管理 (config/)

YAML 設定ファイル: config/llm_config.yaml がメインの設定
環境変数への対応: .env ファイルとシステム環境変数
設定クラスの定義: 型安全な設定構造
設定の検証: 起動時に設定パラメータを検証
ホットリロード: 実行中の設定更新に対応

設定の階層（優先順位の高い順）:

システム環境変数
.env ファイル
YAML 設定ファイル
デフォルト値

5. Function Calling ツールの統合 (utils/function_call/)

5.1 関数レジストリ (function_registry.py)

統一された登録の仕組み: @FunctionRegistry.register_function デコレーター
非同期関数への対応: 同期／非同期関数を自動判別
動的な呼び出し: 統一された関数呼び出しインターフェース
ツールの検出: 登録済みツールを自動検出

5.2 電卓ツール (calculator.py)

基本演算: 四則演算、べき乗、剰余
高度な演算: 三角関数、対数、平方根、絶対値
安全な計算: 悪意のある式の実行を防止
数学定数: π、e などの数学定数に対応

5.3 音楽プレーヤー (music_functions.py, music_player.py)

再生制御: 再生、一時停止、停止、ランダム再生
音量制御: 音量調整、スマート音量設定
プレイリスト: 音楽ファイルリストの管理
状態の照会: 現在の再生状態と情報
対応ファイル: MP3、WAV、OGG などの形式

5.4 ロボットアーム制御 (arm_functions.py)

基本動作: 把持、配置、指定位置への移動
関節制御: 各関節の角度を精密に制御
プリセット動作: 初期化、リセットなどの標準動作
状態監視: ロボットアームの状態をリアルタイムで取得
安全制御: 可動範囲の制限と衝突検出

5.5 雲台制御 (gimbal_functions.py)

方向制御: 水平／垂直方向の回転
相対移動: 現在位置を基準とした相対移動
絶対位置決め: 正確な角度への位置決め
リセット機能: 初期位置への復帰
接続管理: シリアル接続と切断

5.6 画像認識 (vlm_functions.py)

画像解析: VLM による画像内容の認識
物体検出: 画像内の物体やシーンを識別
説明文の生成: 画像の内容を自然言語で説明
マルチモーダル統合: テキストと画像を組み合わせた理解能力

6. MCP マネージャー (utils/mcp/)

MCP プロトコルへの対応: Model Context Protocol の統合
外部サービスへの接続: 外部の MCP サーバーに接続
ツールの検出: MCP が提供するツールを自動検出
統一インターフェース: ローカルツールと MCP ツールを統一的に呼び出し

対応している MCP サービス:

高徳地図（Amap）サービス：位置情報とナビゲーション機能
拡張可能なサードパーティ MCP サービスの統合

7. ハードウェア制御モジュール (utils/servo_*)

7.1 サーボ制御 (servo_control/)

シリアル通信: シリアルベースのサーボ制御プロトコル
角度制御: サーボ角度の精密な設定
速度制御: サーボの動作速度の調整
状態フィードバック: サーボの現在位置と状態

7.2 ロボットアームのハードウェア制御 (servo_arm_control/)

多関節の協調: 6 自由度ロボットアームの制御
運動計画: 軌道計画と滑らかな動作
逆運動学: 目標位置から関節角度を算出
安全監視: 可動範囲と速度の制限

8. フロントエンド画面 (static/)

HTML 画面: index.html メイン画面
JavaScript クライアント: app.js フロントエンドロジック
CSS スタイル: style.css 画面スタイル
リアルタイム通信: WebSocket クライアントの実装
機能デモ: デモ用ボタンとサンプルを内蔵

🔄 データフロー

対話処理の流れ

ユーザー入力: Web 画面または API からメッセージを送信
セッション管理: ConversationManager がセッションのコンテキストを処理
LLM 呼び出し: LLMClient が火山引擎 API を呼び出し
ツールの識別: 呼び出すべきツールをシステムが自動的に識別
ツールの実行: FunctionRegistry を通じて該当ツールを実行
結果の返却: ツールの結果を統合してユーザーに返却

Function Calling の流れ

ツールの登録: 起動時にすべてのツールを自動登録
Schema の生成: ツール関数から OpenAI Function Schema を生成
LLM による識別: 大規模モデルがユーザーの意図を識別してツールを選択
パラメータの解析: ツール呼び出しのパラメータを解析
ツールの実行: 該当するツール関数を呼び出し
結果の統合: ツールの結果を対話に統合

リアルタイム通信の流れ

WebSocket 接続: フロントエンドが WebSocket 接続を確立
メッセージの受信: サーバーがユーザーのメッセージを受信
ストリーミング処理: LLM が応答内容をストリーミング生成
リアルタイムプッシュ: WebSocket で内容をリアルタイムにプッシュ
ツール呼び出し: ストリーミング中にツール呼び出しを処理
接続管理: 切断と再接続を自動処理

🛠️ 技術スタック

バックエンド技術

Web フレームワーク: FastAPI - 高性能な非同期 Web フレームワーク
LLM 統合: 火山引擎 API - 豆包（Doubao）大規模モデルを利用
非同期処理: Python asyncio - 非同期プログラミングに対応
HTTP クライアント: httpx - 非同期 HTTP クライアント
設定管理: PyYAML、python-dotenv
ログ記録: Python logging モジュール

ハードウェア制御

シリアル通信: pyserial - シリアルデバイスとの通信
音声処理: pygame - 音声の再生と処理
GPIO 制御: Raspberry Pi などの組み込みデバイスに対応

フロントエンド技術

HTML5: 最新の Web 標準
JavaScript ES6+: ネイティブ JavaScript、追加フレームワークなし
WebSocket API: リアルタイムの双方向通信
CSS3: レスポンシブデザインとモダンなスタイル

🚀 デプロイアーキテクチャ

標準デプロイ

客户端浏览器
    ↓ HTTP/WebSocket
FastAPI应用服务器 (端口8002)
    ↓
火山引擎LLM API
    ↓
外部硬件设备 (串口/GPIO)

分散デプロイ

前端Web界面
    ↓
负载均衡器
    ↓
多个LLM应用实例
    ↓
共享配置存储
    ↓
外部服务集成

🔐 セキュリティ上の考慮事項

API のセキュリティ

API キーの管理: 機密情報は環境変数に保存
CORS 設定: クロスオリジンリクエストのセキュリティ制御
入力検証: 厳格なパラメータ検証とサニタイズ

ツールのセキュリティ

権限制御: ツール呼び出しの権限を制限
パラメータ検証: ツールパラメータの厳格な検証
リソース制限: リソースの乱用や上限超過を防止

ハードウェアの安全性

可動範囲の制限: ロボットアームと雲台の安全範囲
非常停止: ハードウェアデバイスの非常停止機構
状態監視: デバイス状態のリアルタイム監視

🔧 拡張性の設計

ツールの拡張

プラグイン方式の設計: 新しいツールはデコレーターで登録
Schema の自動生成: 関数シグネチャからツールの説明を自動生成
非同期への対応: 同期ツールと非同期ツールの両方に対応

モデルの拡張

複数モデルへの対応: 異なる LLM プロバイダーを設定可能
柔軟なパラメータ設定: さまざまなモデルパラメータの調整に対応
思考モード: 異なる推論モードに対応

ハードウェアの拡張

デバイスの抽象化: 統一されたハードウェア制御インターフェース
ドライバーのモジュール化: 着脱可能なハードウェアドライバー
プロトコルへの適応: 複数の通信プロトコルに対応

⚡ パフォーマンス最適化

非同期処理

ノンブロッキング I/O: ネットワークと I/O 操作を完全に非同期化
同時実行の制御: 同時接続数を適切に制限
リソースプール: コネクションプールとリソースの再利用

キャッシュ戦略

設定のキャッシュ: 設定情報をキャッシュして重複読み込みを回避
ツール Schema のキャッシュ: ツールの説明情報をキャッシュ
セッションのキャッシュ: 対話履歴のスマートなキャッシュ管理

メモリ管理

ガベージコレクション: 期限切れのセッションとキャッシュを自動クリーンアップ
リソース制限: メモリ使用量の監視と制限
接続管理: WebSocket 接続の自動クリーンアップ