HumansXドキュメントセンター
公式サイトへ ↗
ドキュメントセンター › RAI-P4

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）

  • Volcano Engine API との統合：Volcano Engine の 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 ファイルとシステム環境変数
  • 設定クラスの定義：型安全な設定構造
  • 設定の検証：起動時に設定パラメータを検証します
  • ホットリロード：実行時の設定更新をサポートします

設定の階層（優先度の高い順）：

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

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 クライアントの実装
  • 機能デモ：デモボタンとサンプルを内蔵

データフロー

対話処理のフロー

  1. ユーザー入力：Web 画面または API からメッセージを送信します
  2. セッション管理：ConversationManager がセッションコンテキストを処理します
  3. LLM 呼び出し：LLMClient が Volcano Engine API を呼び出します
  4. ツールの特定：システムが呼び出すべきツールを自動的に特定します
  5. ツールの実行：FunctionRegistry を通じて該当するツールを実行します
  6. 結果の返却：ツールの結果を統合してユーザーに返します

Function Calling のプロセス

  1. ツールの登録：起動時にすべてのツールを自動登録します
  2. Schema の生成：ツール関数に基づいて OpenAI Function Schema を生成します
  3. LLM による識別：大規模モデルがユーザーの意図を識別し、ツールを選択します
  4. パラメータの解析：ツール呼び出しのパラメータを解析します
  5. ツールの実行：該当するツール関数を呼び出します
  6. 結果の統合：ツールの結果を対話に統合します

リアルタイム通信のプロセス

  1. WebSocket 接続：フロントエンドが WebSocket 接続を確立します
  2. メッセージの受信：サーバーがユーザーメッセージを受信します
  3. ストリーミング：LLM が応答内容をストリーミングします
  4. リアルタイムプッシュ：WebSocket を通じて内容をリアルタイムにプッシュします
  5. ツール呼び出し：ストリーミング処理中にツール呼び出しを処理します
  6. 接続管理：切断と再接続を自動的に処理します

️ 技術スタック

バックエンド技術

  • Web フレームワーク：FastAPI（高性能な非同期 Web フレームワーク）
  • LLM 統合：Volcano Engine 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 接続の自動クリーンアップ

​

← 前へLLM による意味理解：MCP 統合ガイド次へ →関数呼び出しによるパン・チルト制御システムのタスク計画