HumansXドキュメントセンター
公式サイトへ ↗
ドキュメントセンター › GX-MAT-09S

意味理解 LLM -- API インターフェース仕様

概要

LLM モジュールは REST API と WebSocket インターフェースを提供し、大規模言語モデルとの対話、Function Calling によるツール呼び出し、MCP サービスとの統合に対応しています。

REST API

基本情報

  • Base URL: http://localhost:8002
  • Content-Type: application/json
  • すべての API エンドポイントが CORS に対応しています

1. ヘルスチェック

GET /health

サーバーの稼働状態を確認します

GET /health

レスポンス:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z",
  "version": "1.0.0"
}

2. 設定情報の取得

GET /config

現在のシステム設定情報を取得します（機密情報はマスキング済み）

GET /config

レスポンス:

{
  "server": {
    "host": "0.0.0.0",
    "port": 8002,
    "debug": false
  },
  "llm": {
    "model": {
      "name": "doubao-seed-1-6-250615"
    },
    "parameters": {
      "temperature": 0.7,
      "top_p": 0.95,
      "max_tokens": 4096
    }
  },
  "function_calling": {
    "enabled": true
  },
  "mcp": {
    "enabled": true
  }
}

3. 非ストリーミング対話

POST /chat

メッセージを送信して対話します（非ストリーミングレスポンス）

POST /chat
Content-Type: application/json

{
    "message": "你好，请帮我计算 123 + 456",
    "session_id": "default",
    "stream": false
}

リクエストパラメータ:

  • message (string, 必須): ユーザーのメッセージ内容
  • session_id (string, 任意): セッション ID。デフォルトは ”default”
  • stream (boolean, 任意): ストリーミングレスポンスにするかどうか。デフォルトは false

レスポンス:

{
  "success": true,
  "message": "你好！我来帮你计算 123 + 456 = 579",
  "session_id": "default",
  "tool_calls": [
    {
      "name": "calculator",
      "arguments": {"expression": "123 + 456"},
      "result": "579"
    }
  ],
  "timestamp": "2024-01-01T12:00:00Z"
}

エラーレスポンス:

{
  "success": false,
  "error": "API密钥无效",
  "error_code": "INVALID_API_KEY",
  "timestamp": "2024-01-01T12:00:00Z"
}

4. ストリーミング対話

POST /chat

メッセージを送信してストリーミング対話を行います

POST /chat
Content-Type: application/json

{
    "message": "请详细解释机器学习的概念",
    "session_id": "default",
    "stream": true
}

レスポンス (Server-Sent Events):

data: {"type": "content", "text": "机器学习"}

data: {"type": "content", "text": "是人工智能的一个分支"}

data: {"type": "tool_calling", "name": "calculator", "status": "calling"}

data: {"type": "tool_result", "name": "calculator", "result": "42"}

data: {"type": "complete", "session_id": "default"}

5. 対話履歴の取得

GET /conversations/{session_id}

指定したセッションの対話履歴を取得します

GET /conversations/default

レスポンス:

{
  "session_id": "default",
  "history": [
    {
      "role": "user",
      "content": "你好",
      "timestamp": "2024-01-01T12:00:00Z"
    },
    {
      "role": "assistant",
      "content": "你好！我是AI助手，很高兴为您服务。",
      "timestamp": "2024-01-01T12:00:01Z"
    }
  ],
  "total_messages": 2
}

6. 対話履歴のクリア

DELETE /conversations/{session_id}

指定したセッションの対話履歴をクリアします

DELETE /conversations/default

レスポンス:

{
  "success": true,
  "message": "会话历史已清空",
  "session_id": "default"
}

7. 利用可能なツール一覧の取得

GET /tools

現在システムで利用可能なすべてのツールを取得します

GET /tools

レスポンス:

{
  "function_calling_tools": [
    {
      "name": "calculator",
      "description": "基本数学计算工具",
      "enabled": true,
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "要计算的数学表达式"
          }
        },
        "required": ["expression"]
      }
    },
    {
      "name": "music_play",
      "description": "播放音乐",
      "enabled": true,
      "parameters": {
        "type": "object",
        "properties": {
          "music_name": {
            "type": "string",
            "description": "要播放的音乐名称"
          }
        },
        "required": ["music_name"]
      }
    }
  ],
  "mcp_tools": [
    {
      "name": "amap_search",
      "description": "高德地图搜索",
      "server": "amap_maps",
      "enabled": false
    }
  ],
  "total_tools": 8
}

WebSocket API

リアルタイム対話

WebSocket /ws

WebSocket 接続を確立してリアルタイム対話を行います

接続:

const ws = new WebSocket('ws://localhost:8002/ws');

送信メッセージの形式:

{
    "message": "你好，请帮我播放音乐",
    "session_id": "default"
}

受信メッセージの種類:

1. コンテンツメッセージ

{
  "type": "content",
  "text": "你好！我来帮你播放音乐。",
  "session_id": "default"
}

2. ツール呼び出しのステータス

{
  "type": "tool_calling",
  "name": "music_play",
  "status": "calling",
  "arguments": {"music_name": "背景音乐"},
  "session_id": "default"
}

3. ツール呼び出しの結果

{
  "type": "tool_result",
  "name": "music_play",
  "result": "音乐开始播放",
  "success": true,
  "session_id": "default"
}

4. メッセージ完了

{
  "type": "complete",
  "session_id": "default",
  "total_tokens": 150,
  "timestamp": "2024-01-01T12:00:00Z"
}

5. エラーメッセージ

{
  "type": "error",
  "error": "工具调用失败",
  "error_code": "TOOL_CALL_ERROR",
  "session_id": "default"
}

6. システムステータス

{
  "type": "status",
  "status": "connected",
  "active_tools": ["calculator", "music_player"],
  "session_id": "default"
}

Function Calling ツール

1. 電卓ツール

calculator

基本的な数学計算

パラメータ:

  • expression (string): 数式

呼び出し例:

{
  "name": "calculator",
  "arguments": {
    "expression": "123 + 456 * 2"
  }
}

advanced_calculator

高度な数学計算

パラメータ:

  • operation (string): 演算の種類
  • value (number): 演算する値
  • base (number, 任意): 底（対数演算用）

呼び出し例:

{
  "name": "advanced_calculator",
  "arguments": {
    "operation": "sin",
    "value": 30
  }
}

2. 音楽プレーヤーツール

music_list

音楽リストを取得します

パラメータ: なし

呼び出し例:

{
  "name": "music_list",
  "arguments": {}
}

music_play

指定した音楽を再生します

パラメータ:

  • music_name (string): 曲名

呼び出し例:

{
  "name": "music_play",
  "arguments": {
    "music_name": "背景音乐"
  }
}

music_volume_set

音量を設定します

パラメータ:

  • volume (integer): 音量値（0-100）

呼び出し例:

{
  "name": "music_volume_set",
  "arguments": {
    "volume": 75
  }
}

3. ロボットアーム制御ツール

arm_grab_object

物体を把持します

パラメータ:

  • x (float): X 座標
  • y (float): Y 座標
  • z (float): Z 座標

呼び出し例:

{
  "name": "arm_grab_object",
  "arguments": {
    "x": 100.0,
    "y": 50.0,
    "z": 20.0
  }
}

arm_move_to_position

指定位置へ移動します

パラメータ:

  • x (float): X 座標
  • y (float): Y 座標
  • z (float): Z 座標

呼び出し例:

{
  "name": "arm_move_to_position",
  "arguments": {
    "x": 150.0,
    "y": 75.0,
    "z": 30.0
  }
}

4. 雲台制御ツール

gimbal_control

雲台の回転を制御します

パラメータ:

  • pan (float): 水平角度（-90～90）
  • tilt (float): 垂直角度（-90～90）

呼び出し例:

{
  "name": "gimbal_control",
  "arguments": {
    "pan": 45.0,
    "tilt": -30.0
  }
}

5. 画像認識ツール

vlm_analyze_image

画像の内容を解析します

パラメータ:

  • image_path (string): 画像ファイルのパス
  • query (string, 任意): 特定の質問内容

呼び出し例:

{
  "name": "vlm_analyze_image",
  "arguments": {
    "image_path": "/path/to/image.jpg",
    "query": "这张图片中有什么物体？"
  }
}

静的ファイルサービス

Web 画面

GET /

メインページにアクセスします

GET /

戻り値: HTML ページ

静的リソース

GET /static/

静的リソースファイルにアクセスします

GET /static/css/style.css
GET /static/js/app.js
GET /static/images/logo.png

エラー処理

HTTP ステータスコード

  • 200: 成功
  • 400: リクエストパラメータのエラー
  • 401: 未認証（API キーが無効）
  • 429: リクエスト頻度の制限
  • 500: サーバー内部エラー
  • 503: サービス利用不可

エラーレスポンスの形式

{
  "success": false,
  "error": "错误描述",
  "error_code": "ERROR_CODE",
  "details": {
    "field": "具体错误字段",
    "value": "错误值"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

主なエラーコード

  • INVALID_API_KEY: API キーが無効
  • INVALID_REQUEST: リクエスト形式のエラー
  • TOOL_CALL_ERROR: ツール呼び出しの失敗
  • SESSION_NOT_FOUND: セッションが存在しない
  • RATE_LIMIT_EXCEEDED: リクエスト頻度の上限超過
  • INTERNAL_ERROR: サーバー内部エラー

使用例

Python クライアントの例

非ストリーミング対話

import requests

# 发送对话请求
response = requests.post('http://localhost:8002/chat', json={
    'message': '帮我计算 100 * 25',
    'session_id': 'my_session',
    'stream': False
})

result = response.json()
print(result['message'])

ツール一覧の取得

import requests

# 获取可用工具
response = requests.get('http://localhost:8002/tools')
tools = response.json()

for tool in tools['function_calling_tools']:
    print(f"工具: {tool['name']} - {tool['description']}")

JavaScript WebSocket の例

// 建立WebSocket连接
const ws = new WebSocket('ws://localhost:8002/ws');

// 连接成功
ws.onopen = function() {
    console.log('WebSocket连接已建立');

    // 发送消息
    ws.send(JSON.stringify({
        message: '你好，请播放一首音乐',
        session_id: 'web_session'
    }));
};

// 接收消息
ws.onmessage = function(event) {
    const data = JSON.parse(event.data);

    switch(data.type) {
        case 'content':
            console.log('AI回复:', data.text);
            break;
        case 'tool_calling':
            console.log('调用工具:', data.name);
            break;
        case 'tool_result':
            console.log('工具结果:', data.result);
            break;
        case 'complete':
            console.log('消息完成');
            break;
        case 'error':
            console.error('错误:', data.error);
            break;
    }
};

// 连接关闭
ws.onclose = function() {
    console.log('WebSocket连接已断开');
};

cURL コマンドの例

ヘルスチェック

curl -X GET http://localhost:8002/health

対話の送信

curl -X POST http://localhost:8002/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "计算 2^10",
    "session_id": "curl_session",
    "stream": false
  }'

ツール一覧の取得

curl -X GET http://localhost:8002/tools

セッションのクリア

curl -X DELETE http://localhost:8002/conversations/curl_session

パフォーマンスに関する考慮事項

リクエスト頻度の制限

  • 1 IP あたり 1 分間に最大 100 リクエスト
  • WebSocket 接続数の制限：1 IP あたり最大 5 つの同時接続

応答時間

  • 簡単な計算ツール：< 100ms
  • 音楽再生の制御：< 200ms
  • LLM 対話の応答：1～5 秒（メッセージの複雑さによる）
  • ロボットアーム制御：200ms～2 秒（動作の複雑さによる）

データサイズの制限

  • 1 回のリクエストのメッセージ長：最大 10KB
  • セッション履歴：最大 20 件のメッセージを保存
  • WebSocket メッセージ：最大 1MB
← 前へMCP 機能 -- 天気と地図の検索次へ →意味理解 LLM -- Function_Calling ツールシステム