AI 集成指南

概述

智航云 AI 中台提供统一的 AI 接口，支持多种大语言模型。AI 能力包括：

同步对话 -- 发送消息，获取完整回复
流式对话 -- SSE 流式返回，适合实时展示
工具调用 -- AI 自动选择并调用已注册的工具
数据分析 -- 提交数据和分析提示，获取 AI 分析结果

支持的模型

模型	标识符	特点
Claude Sonnet 4	`claude-sonnet-4-20250514`	默认模型，平衡性能和成本
Claude Opus 4	`claude-opus-4-20250514`	最强推理能力
Qwen3 235B	`qwen:qwen3-235b-a22b`	国产大模型，延迟低

不指定模型时默认使用 claude-sonnet-4-20250514。

同步对话

发送消息，等待 AI 处理完成后返回完整响应。

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/ai/chat \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "分析本月能耗数据，给出节能建议",
    "model": "claude-sonnet-4-20250514",
    "systemPrompt": "你是专业的能源管理顾问"
  }'

python

response = claw.ai.chat(
    "分析本月能耗数据，给出节能建议",
    model="claude-sonnet-4-20250514"
)
print(response.text)
print(f"模型: {response.model}")
print(f"Token: 输入 {response.usage['inputTokens']}, 输出 {response.usage['outputTokens']}")

javascript

const response = await claw.ai.chat('分析本月能耗数据，给出节能建议', {
  model: 'claude-sonnet-4-20250514'
})
console.log(response.response)
console.log(`Token: 输入 ${response.usage.inputTokens}, 输出 ${response.usage.outputTokens}`)

请求参数：

参数	类型	必填	说明
`message`	string	是	用户消息
`model`	string	否	模型标识符
`systemPrompt`	string	否	系统提示词，定义 AI 角色
`appContext`	string	否	应用上下文，限定 AI 使用的工具集
`tools`	array	否	额外的工具定义
`conversationId`	string	否	会话ID，用于多轮对话

流式对话 (SSE)

使用 Server-Sent Events 流式返回 AI 响应，适合需要实时显示的场景。

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/ai/chat/stream \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "详细解释什么是 RAG 技术",
    "model": "claude-sonnet-4-20250514"
  }'

python

for chunk in claw.ai.chat_stream("详细解释什么是 RAG 技术"):
    if chunk["type"] == "stream":
        print(chunk["text"], end="", flush=True)
    elif chunk["type"] == "done":
        print(f"\n\n完成 - Token: {chunk.get('usage')}")
    elif chunk["type"] == "error":
        print(f"\n错误: {chunk['message']}")

javascript

const stream = claw.ai.chatStream('详细解释什么是 RAG 技术')
for await (const chunk of stream) {
  if (chunk.type === 'stream') {
    process.stdout.write(chunk.text)
  } else if (chunk.type === 'done') {
    console.log('\n完成:', chunk.usage)
  }
}

SSE 事件格式：

data: {"type":"stream","text":"RAG"}
data: {"type":"stream","text":"（检索增强生成）"}
data: {"type":"stream","text":"是一种..."}
...
data: {"type":"done","usage":{"input_tokens":30,"output_tokens":500}}

浏览器端集成

javascript

async function streamChat(message) {
  const response = await fetch('https://api.invoratec.cn/v1/ai/chat/stream', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ message })
  })

  const reader = response.body.getReader()
  const decoder = new TextDecoder()
  let fullText = ''

  while (true) {
    const { done, value } = await reader.read()
    if (done) break

    const chunk = decoder.decode(value, { stream: true })
    const lines = chunk.split('\n').filter(l => l.startsWith('data: '))

    for (const line of lines) {
      const data = JSON.parse(line.slice(6))
      if (data.type === 'stream') {
        fullText += data.text
        document.getElementById('output').textContent = fullText
      }
    }
  }
}

直接调用工具

不经过 AI 推理，直接执行一个已注册的工具：

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/ai/tool-call \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "hr_get_dashboard",
    "input": {}
  }'

python

result = claw.ai.tool_call("hr_get_dashboard")
print(result)
# {"status": "success", "result": {"employees": 150, "departments": 12}}

javascript

const result = await claw.ai.toolCall('hr_get_dashboard')
console.log(result.result)

这在以下场景中有用：

定期抓取数据（不需要 AI 分析）
工作流中的工具调用步骤
测试工具是否正常工作

数据分析

提交结构化数据和分析提示，AI 返回分析结果：

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/ai/analyze \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "departments": [
        {"name": "技术部", "headcount": 50, "turnover_rate": 0.08},
        {"name": "市场部", "headcount": 30, "turnover_rate": 0.15},
        {"name": "人事部", "headcount": 10, "turnover_rate": 0.05}
      ]
    },
    "prompt": "分析各部门离职率，找出异常并给出建议",
    "outputFormat": "markdown"
  }'

python

analysis = claw.ai.analyze(
    data={
        "departments": [
            {"name": "技术部", "headcount": 50, "turnover_rate": 0.08},
            {"name": "市场部", "headcount": 30, "turnover_rate": 0.15},
            {"name": "人事部", "headcount": 10, "turnover_rate": 0.05}
        ]
    },
    prompt="分析各部门离职率，找出异常并给出建议",
    output_format="markdown"
)
print(analysis)

javascript

const analysis = await claw.ai.analyze({
  data: {
    departments: [
      { name: '技术部', headcount: 50, turnover_rate: 0.08 },
      { name: '市场部', headcount: 30, turnover_rate: 0.15 },
      { name: '人事部', headcount: 10, turnover_rate: 0.05 }
    ]
  },
  prompt: '分析各部门离职率，找出异常并给出建议',
  outputFormat: 'markdown'
})
console.log(analysis.analysis)

输出格式选项：

outputFormat	说明
`text`	纯文本（默认）
`markdown`	Markdown 格式，含表格
`json`	JSON 结构化输出

AI 能力等级

AI 中台定义了五个能力等级，帮助你规划 AI 集成深度：

级别	名称	说明	示例
L1	查询	AI 调用工具获取数据	"查询本月考勤"
L2	分析	AI 串联多个工具分析	"对比上月和本月能耗"
L3	建议	AI 给出可操作建议	"给出节能方案"
L4	审批执行	AI 执行操作，需确认	"帮我提交请假申请"
L5	自主执行	事件驱动自动化	"温度超标自动降温"

System Prompt 设计建议

好的 System Prompt 直接影响 AI 的回答质量：

json

{
  "systemPrompt": "你是太古里运维平台的AI助手。\n\n你的职责：\n1. 回答关于设备状态、能耗数据的查询\n2. 分析设备报警并给出处理建议\n3. 生成运维报告\n\n注意事项：\n- 温度数据单位为摄氏度\n- 能耗数据单位为 kWh\n- 设备编号格式为 XX-NNN\n- 如果数据不足，请明确说明而不是猜测"
}

下一步

事件与 Webhook -- AI 对话事件的订阅
工作流指南 -- 在工作流中集成 AI
API 参考: AI -- 完整 API 端点文档

AI 集成指南 ​

概述 ​

支持的模型 ​

同步对话 ​

流式对话 (SSE) ​

浏览器端集成 ​

直接调用工具 ​

数据分析 ​

AI 能力等级 ​

System Prompt 设计建议 ​

下一步 ​

AI 集成指南

概述

支持的模型

同步对话

流式对话 (SSE)

浏览器端集成

直接调用工具

数据分析

AI 能力等级

System Prompt 设计建议

下一步