人工智能

人工智能板块用于统一管理平台调用的大模型，并把模型能力提供给 AI 助手、智能问答、物模型生成、协议生成、TCP 分包脚本和快速接入等功能使用。

使用顺序建议如下：

先在人工智能 > 模型管理中配置可用模型。
测试模型调用是否成功。
将常用模型设为默认模型。
到具体业务页面使用 AI 能力，并在写入平台数据前人工确认生成结果。

使用前准备

已获取可用的大模型服务地址和认证信息，例如 API Key、Access Token 或私有化模型地址。
服务器可以访问对应的大模型服务；如果使用 Ollama，本地或内网 Ollama 服务需提前启动。
使用 AI 生成协议、快速接入等耗时功能时，建议保证后端服务和模型服务网络稳定。
使用设备控制、创建场景、创建告警等功能前，应先完成产品、设备、物模型和指令配置。

模型管理

进入人工智能 > 模型管理，点击新增创建模型配置。模型保存后不会立即改变业务数据，只是让平台具备调用该模型的能力。

基础配置

配置项	说明
模型标识	平台内部引用模型的唯一标识。建议使用清晰英文，例如`deepseek-chat`、`qwen-plus`、`local-llama`。只能使用字母、数字、点、下划线、冒号或短横线，长度 2-96 位。
模型名称	页面展示名称，例如`DeepSeek V3`、`通义千问 Plus`。
厂商类型	选择模型供应商。常用类型包括`DEEPSEEK`、`QWEN`、`BAILIAN`、`DOUBAO`、`SPARK`、`WENXIN`、`XIAOMI`、`OLLAMA`。
协议类型	云端 OpenAI 兼容接口通常选择`OPENAI_COMPATIBLE`；本地 Ollama 选择`OLLAMA`。
Base URL	模型接口地址。已内置默认地址的厂商可不填；私有化部署、代理地址或 Ollama 内网地址需要填写。
模型名	实际传给模型服务的模型名称，例如`deepseek-chat`、`qwen-plus`、`llama3.1`。
状态	启用后才能被业务功能选择或调用。

常见 Base URL 示例：

厂商类型	默认地址或示例
DEEPSEEK	`https://api.deepseek.com`
QWEN / BAILIAN	`https://dashscope.aliyuncs.com/compatible-mode/v1`
DOUBAO	`https://ark.cn-beijing.volces.com/api/v3`
OLLAMA	`http://localhost:11434` 或内网 Ollama 地址

认证配置

认证配置使用 JSON 格式填写。保存后平台会加密存储，不会在列表中明文展示。

常用写法：

{"apiKey":"sk-xxxx"}

也可以使用 Access Token：

{"accessToken":"xxxx"}

如果模型服务使用自定义请求头：

{"authHeader":"X-API-Key","authValue":"xxxx"}

修改模型时，如果不需要变更密钥，可以不重新填写认证配置；如需清除原认证信息，使用页面上的清除认证配置选项。

能力配置

模型能力用于告诉平台该模型可以处理哪些输入。配置不准确时，业务页面可能无法上传对应类型附件，或调用时提示模型不支持该能力。

能力	说明
`TEXT`	文本能力。所有问答、AI 助手、物模型生成、协议生成都建议配置。
`DOCUMENT`	原生文档理解能力。模型支持直接理解 PDF、DOCX 等文档时配置。
`IMAGE`	图片理解能力。需要上传图片资料时配置。
`AUDIO`	音频理解能力。仅模型接口支持音频输入时配置。
`VIDEO`	视频理解能力。仅模型接口支持视频输入时配置。
`REASONING`	推理能力。需要使用推理强度参数时配置。

能力字段可以按 JSON 数组理解，例如：

["TEXT","DOCUMENT","IMAGE"]

如果模型不支持原生文档能力，也可以只配置TEXT。平台会尽量从 PDF、Word、Excel、TXT、JSON、CSV、LOG、XML 等附件中提取文本，再发送给模型。

参数配置

配置项	建议
上下文长度	按模型实际上下文窗口填写。平台会根据该值裁剪过长历史消息。
最大输出长度	控制单次回答长度。协议生成、快速接入可适当调大。
Temperature	业务配置类场景建议使用较低值，例如`0.1`到`0.3`。
Top P / Top K	没有特殊要求可留空，使用模型默认值。
推理强度	模型支持推理参数时再填写，例如`low`、`medium`、`high`。
响应格式	需要模型返回 JSON 时可填写`json_object`，普通问答可留空。
停止序列	可填写 JSON 数组或逗号分隔文本。普通场景通常不需要。
超时时间	复杂生成建议设置为`120`秒或更长。
重试次数	网络偶发不稳定时可设置为`1`或`2`。
系统提示词	用于给该模型补充角色和风格要求。平台业务规则会自动追加，不建议写过多冲突规则。
扩展参数	高级参数，必须是合法 JSON，会合并到模型请求体中。

测试模型

保存并启用模型后，点击模型行中的测试，输入一个简单问题，例如“请回复一段简短中文”。如果模型支持附件，也可以上传测试文件。

测试成功后，列表会记录最近一次测试状态、返回内容和耗时。测试失败时，根据错误信息检查以下内容：

Base URL 是否正确。
API Key 或认证请求头是否正确。
模型名是否和厂商控制台中的模型名一致。
服务器是否能访问模型服务。
模型能力是否包含当前测试所需能力。

设置默认模型

模型测试成功后，建议点击设为默认。未在业务页面手动选择模型时，平台会使用默认模型。

注意：

只能将启用状态的模型设为默认模型。
默认模型被业务场景使用时，不能直接停用；需要先切换默认模型。
多个模型可同时启用，不同页面可按需要选择更适合的模型。

统一问答入口

如当前版本部署了统一问答入口，可通过该页面调用 AI 网关，处理普通问题、资料分析和平台相关问答。使用时选择功能类型、模型，输入问题，必要时上传附件后提交。

常用功能类型：

功能类型	适用场景
自定义问答	普通知识问答、资料总结、文本整理。
智能问数	查询和分析平台数据，只用于数据查询，不应让模型编造实时数据。
AI 智能助手	设备查询、指令下发、创建场景和告警。
物模型生成	根据描述或文档生成物模型属性。
写协议	根据协议资料生成解析代码。
TCP 脚本	根据协议资料生成分包脚本。

如果开启会话保存，平台会保留当前用户的问答会话。后续可以从会话列表继续查看或删除历史会话。

AI 助手

平台任意页面右下角会显示AI 悬浮球。点击后打开右侧抽屉，直接用自然语言描述要做的事。

AI 助手支持：

查询设备最新属性，例如“客厅温度多少”。
下发设备指令，例如“打开客厅水阀”。
修改设备属性，例如“把卧室空调温度设为 26 度”。
创建场景联动，例如“每天早上 8 点打开办公室空调”。
创建告警配置，例如“烟雾报警器报警时触发严重告警”。

涉及下发指令、创建场景、创建告警等会改变系统状态的操作时，AI 会先展示待确认卡片。只有点击确认执行后才会真正执行。

为了让 AI 助手识别更准确，建议按以下方式配置设备资料：

设备名称包含位置或用途，例如客厅空调、卧室温湿度计。
物模型属性填写清楚名称、标识符、单位、备注。
字典型属性填写完整字典配置，例如1=制冷、2=制热。
指令下发的备注写清参数含义，例如1=开 0=关、temp 整数 16-30 单位℃。
如需 AI 修改任意属性，在设备配置中绑定属性修改指令。

AI 生成物模型

进入产品详情或设备详情的物模型管理，点击AI 生成。在弹窗中描述需要的物模型，例如“生成一个空调物模型，包含开关、温度、模式、风速”。

生成后页面会展示预览结果，并标记新增、移除、保留的属性。可以手动切换处理方式：

方式	说明
追加	保留现有属性，只追加 AI 新识别出的属性。
移除	根据 AI 判断移除不需要的属性。
重写	用 AI 返回的属性列表替换当前列表。

点击应用到表格后，结果只会写入当前页面表格；仍需点击页面中的全部保存才会真正保存到数据库。

AI 生成协议解析代码

进入协议管理，新增或编辑 JAR 协议时，点击AI 生成解析代码。

操作步骤：

选择网络类型，例如MQTT_BROKER、TCP_SERVER、UDP_SERVER、HTTP_SERVER、MODBUS_TCP。
选择生成模型。
上传协议文档，或填写协议要点。建议同时提供完整上报报文、设备 SN 来源、字段含义、校验方式和下发指令示例。
点击开始生成，等待 AI 返回解析类代码、物模型和指令建议。
人工检查并修改生成代码。
点击编译校验，确认源码可以编译。
校验通过后点击编译并部署。

已生成过的 JAR 协议可以点击查看/编辑源码，修改后再点击保存并重新部署。重新部署会保持原协议 ID 不变。

注意：

AI 生成的代码必须人工检查后再部署。
物模型和指令建议只用于复制参考，不会自动写入产品或设备。
如果 AI 无法生成有效代码，通常是协议资料不完整，需要补充报文示例、字段说明和校验规则。

AI 生成 TCP 分包脚本

在网络组件中配置 TCP 相关分包脚本时，可点击脚本编辑器里的AI 生成。

操作步骤：

选择生成模型。
上传协议文档，或填写分包规则描述。
点击开始生成。
检查 AI 返回的脚本和备注。
确认无误后点击确定并覆盖。
保存网络组件配置。

分包脚本必须实现getMessageLength(buffer, length)方法，并返回一条完整消息的字节数；数据不足时返回-1。如果协议有固定帧头、帧尾、长度域或校验位，应在需求描述里明确说明。

快速接入

进入设备管理 > 快速接入，平台会根据设备资料生成完整接入方案。方案包括产品、网络组件、协议源码、物模型和指令配置。

快速接入分三步：

提交设备资料。
审阅 AI 方案。
确认创建配置。

提交资料时需要填写：

信息	说明
产品信息	产品名称、产品编码、设备类型。
连接方式	网络协议、协议名称、网络组件名称和对应连接参数。
生成依据	协议文档、设备对接描述、上报报文示例、下发指令示例。

点击生成接入方案后，平台只生成待审阅方案，不会创建业务数据。应重点检查以下内容：