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

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

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

リクエスト頻度の制限

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

応答時間

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

データサイズの制限

  • 1 リクエストあたりのメッセージ長：最大 10KB
  • セッション履歴：最大 20 件のメッセージを保存
  • WebSocket メッセージ：最大 1MB
← 前へ関数呼び出しによるロボットアームの動作制御の実装次へ →LLM による意味理解：設定ガイド