API 集成指南

介绍如何从外部系统直接调用 PlantPulse AI 的 MCP 及 API。

注意

2026-07 改版： MCP 与本体（Ontology）工具现由 PlantPulse 平台的 server-web 集成 MCP（/api/v5/mcp，api_key 认证）提供。原独立服务 MCP Server(:50000) 与 Ontology(:8888) 已归档，RAG 已由 LightRAG 服务器替代。

API 端点列表

服务	URL	协议	认证
集成 MCP（平台）	`<platform>/api/v5/mcp`	MCP (JSON-RPC 2.0)	api_key (`Authorization: Bearer`)
TimeSeries	`http://<server>:8970`	MCP (JSON-RPC 2.0) / REST	内网
RAG (LightRAG)	`http://<server>:7114`	REST + WebUI(`/webui`)	X-API-Key
LiteLLM (LLM)	`http://<server>:4000`	OpenAI 兼容	API Key

MCP 协议调用

集成 MCP 与 TimeSeries-Insight 遵循 MCP（Model Context Protocol） 标准。工厂数据与本体工具通过平台集成 MCP 端点（/api/v5/mcp）调用。

MCP 基本结构

MCP 是基于 JSON-RPC 2.0 的 HTTP POST 通信。集成 MCP 需要 api_key 认证（Authorization: Bearer <token>）。

POST /api/v5/mcp HTTP/1.1
Content-Type: application/json
Authorization: Bearer <mcp.api.token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool-name>",
    "arguments": {
      "<param1>": "<value1>",
      "<param2>": "<value2>"
    }
  }
}

查询工具列表

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

工具调用示例

查询站点列表

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_site_list",
      "arguments": {}
    }
  }'

设备检索

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_asset_search",
      "arguments": {
        "keyword": "DJ",
        "page": 1,
        "size": 10
      }
    }
  }'

查询传感器最新值

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_point_latest",
      "arguments": {
        "tag_id": "TAG_DJ_M_01_1_1093"
      }
    }
  }'

集成 MCP 认证

集成 MCP 必须使用 api_key 认证。令牌通过 AI Chat Web 的 web/config/application.properties（mcp.api.url/mcp.api.token）管理。

认证头

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{ ... }'

本体（知识图谱）调用

本体工具已并入集成 MCP。请通过集成 MCP 端点调用 ontology_* 工具。

查询图谱统计

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ontology_get_stats",
      "arguments": {}
    }
  }'

子图探索

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ontology_get_subgraph",
      "arguments": {
        "label": "Equipment",
        "id": "ASSET_DJ_M_01_1",
        "depth": 2
      }
    }
  }'

TimeSeries MCP 调用

设备异常检测

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "detect_asset_anomaly",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1",
        "lookback_minutes": 1440,
        "threshold": 0,
        "top_k": 5
      }
    }
  }'

设备传感器预测

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "forecast_asset",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1",
        "prediction_length": 96,
        "enable_bounds": true
      }
    }
  }'

设备健康评分

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_asset_health",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1"
      }
    }
  }'

RAG (LightRAG) 调用

RAG 引擎为 LightRAG 1.5.4 服务器。文档上传、列表、删除等管理操作在 WebUI（http://<server>:7114/webui）中执行，检索则通过 REST /query 调用（X-API-Key 认证）。

信息

AI Chat Web 内置代理无需单独调用，即可通过 rag_search 工具自动查询 LightRAG。以下为从外部直接调用的示例，详细 schema 以 LightRAG 官方文档为准。

文本检索

curl -X POST http://127.0.0.1:7114/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <rag.api.key>" \
  -d '{
    "query": "펌프 정비 절차",
    "mode": "hybrid"
  }'

检索模式支持 hybrid（默认）、naive、local、global。

LLM API 调用（OpenAI 兼容）

LiteLLM 代理提供 OpenAI 兼容 API，可直接沿用现有的 OpenAI SDK。

聊天补全

curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 설치-시-변경" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "주입기 베어링 교체 주기를 알려줘."}
    ],
    "temperature": 0.7
  }'

生成嵌入向量

curl http://127.0.0.1:4000/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 설치-시-변경" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "주입기 베어링 교체 절차"
  }'

查看模型列表

curl http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer 설치-시-변경"

可用模型

模型名称	用途	说明
`gpt-4o`	LLM（对话/分析）	AURA LLM 主模型
`gpt-4o-mini`	VLM（视觉）	AURA 视觉模型
`text-embedding-3-large`	嵌入	生成 2560 维向量
`rerank-multilingual-v3.0`	重排	对检索结果重新排序

信息

为兼容 OpenAI，模型名称设置为 gpt-4o 等，但实际使用的是本地部署的 AURA 模型（vLLM 服务）。

Python SDK 示例

使用 OpenAI SDK 调用 LLM

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:4000/v1",
    api_key="설치-시-변경"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "주입기 상태를 분석해줘."}
    ]
)

print(response.choices[0].message.content)

MCP 工具调用

import requests

def call_mcp_tool(url, tool_name, arguments=None, headers=None):
    response = requests.post(
        url,
        headers=headers or {},
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments or {}
            }
        }
    )
    return response.json()

# 사이트 목록 조회 (통합 MCP — api_key 필요)
result = call_mcp_tool(
    "<platform>/api/v5/mcp",
    "api_read_site_list",
    headers={"Authorization": "Bearer <mcp.api.token>"}
)
print(result)

# 설비 이상 탐지 (TimeSeries-Insight)
result = call_mcp_tool("http://127.0.0.1:8970/mcp", "detect_asset_anomaly", {
    "asset_id": "ASSET_DJ_M_01_1",
    "lookback_minutes": 1440,
    "threshold": 0
})
print(result)

响应格式

MCP 成功响应

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... 도구 실행 결과 JSON ... }"
      }
    ]
  }
}

MCP 错误响应

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": "상세 오류 메시지"
  }
}

分页

查询大量数据时使用分页。

{
  "name": "api_read_asset_search",
  "arguments": {
    "keyword": "DJ",
    "page": 1,
    "size": 10
  }
}

参数	说明	默认值	最大值
`page`	页码	1	-
`size`	每页条目数	10	50
`limit`	普通查询上限	10	100

时间格式

集成 MCP 的时间相关参数以 KST（韩国标准时间） 为准。

{
  "name": "api_read_point_range",
  "arguments": {
    "tag_id": "TAG_DJ_M_01_1_1093",
    "start_time": "2026-03-29T00:00:00",
    "end_time": "2026-03-29T23:59:59"
  }
}

响应中带有 _iso 后缀的字段为便于阅读的 KST 格式：

{
  "timestamp": 1711641600000,
  "timestamp_iso": "2026-03-29 09:00:00"
}

API 端点列表​

MCP 协议调用​

MCP 基本结构​

查询工具列表​

工具调用示例​

查询站点列表​

设备检索​

查询传感器最新值​

集成 MCP 认证​

认证头​

本体（知识图谱）调用​

查询图谱统计​

子图探索​

TimeSeries MCP 调用​

设备异常检测​

设备传感器预测​

设备健康评分​

RAG (LightRAG) 调用​

文本检索​

LLM API 调用（OpenAI 兼容）​

聊天补全​

生成嵌入向量​

查看模型列表​

可用模型​

Python SDK 示例​

使用 OpenAI SDK 调用 LLM​

MCP 工具调用​

响应格式​

MCP 成功响应​

MCP 错误响应​

分页​

时间格式​