外部大模型对接

沃丰对接外部智能体Chat接口标准

接口详情

项目	说明
传输方式	HTTPS
请求地址
调用方式	同步调用，等待模型执行完成并返回最终结果
字符编码	UTF-8
接口请求格式	JSON
响应格式	JSON
接口请求类型	POST
开发语言	任意可发起 HTTPS 请求的开发语言

请求参数

Request fields

参数名称	参数说明	是否必须	数据类型
chatId	会话Id（对应会话id调用方生成）	true	number
im_robot_log_id	机器人消息id	true	number
messages	用户消息	true	array
messages[].content	对话内容	true	string
messages[].type	类型(text,image) 类型为image时为图片链接	true	string
businessData	业务数据	false	jsonObject
stream	是否流式（true流式, 默认仅支持流式）	true	boolean
userId	用户Id(对应customer_token)	true	number
sign	沃丰签名	true	string
timestamp	时间戳	true	long

请求示例

{
  "chatId": 714731010, 
  "im_robot_log_id": 4740181939,
  "messages": [
    {
      "content": "你好",
      "type": "TEXT"
    }
  ],
  "businessData": {
      "dialogueDesc":"P1234567", 
      "nickName":"金牌会员",
      "customerId":"abc123456",
      "sourcePlugin":"2437",
      "customer_token":"123456"
  },
  "stream": true,
  "userId": 4842328052,
  "sign": "1e18abb8c62ebcc80148026888d28585",
  "timestamp": 1732796173
}

响应参数

1. 流式输出

初始返回流式样式，最后一条结束消息的data对象可参考下方2.对象示例

参数名称	参数说明	类型
type	流式状态：成功/结束/错误	string
content_chunk	流式内容：支持markdown格式	string

流式状态说明

SUCCESS: 正常返回（流式输出）
END: 对话结束（choice参数参考同步接口返回）
SENSITIVENESS: 敏感信息（接收后请清除之前流式输出内容）
ERROR: 报警标签（接收后请清除之前流式输出内容）

响应示例（流式）

data:{"type":"SUCCESS", "content_chunk": "你好"}

data:{"type":"SUCCESS", "content_chunk": "！\n\n由于"}

...

data:{"type":"SUCCESS", "content_chunk": "告诉我"}

data:{"type":"ERROR", "content_chunk": "错误内容"}

data:{"type":"END", "content_chunk":"","data": "参考下方'2.对象示例'中的data字段","usage": {"execution_time": 500}}

2. 对象示例

参数名称	参数说明	类型
data	返回数据体	object
data.message	返回消息	object
data.message.content	返回内容，类型为image时为图片链接	string
data.message.type	消息类型	string
data.cardInfo	卡片信息	object
data.imageData	图片数据，url或base64	string
data.html	html标签	string
data.recommendedList	推荐列表	list
data.dialogueSlots	对话槽位	object
data.dialogueSlots.dialogueIntent	对话意图(CUSTOMER_SERVICE: 转人工，NULL_ANSWER：域外拒答)	string
data.faqId	FAQ唯一ID	string
data.usage	使用	object
data.usage.executionTime	总耗时(毫秒)	long
data.formId	表单id	string

对象示例json

{
    "message": {
        "content": "文本消息：文字(markdown格式)",
        "type": ""
    },
    "html": "<p>这是一段富文本<span>人工客服</span></p>",
    "recommendedList": [
        {
            "title": "测试商品一",
            "image": "商品图片链接",
            "price": "商品价格",
            "description": "商品描述"
        }
    ],
    "cardInfo": {},
    "imageData": "https://ali-pro-km.udeskcs.com/Data/0/oss-km-image/trjH6jpmFpMS8x5m3hnQ3yiRxN8BWaBf/12d50512-478a-4e36-b713-6221365fc717.jpg",
    "dialogueSlots": {
        "dialogueIntent": "CUSTOMER_SERVICE"
    },
    "usage": {
        "executionTime": 1000
    },
    "formId": "表单id"
}

验签方案

验签流程

验签流程图

签名生成方式

根据消息内容(content)、时间戳(timestamp) 和API 密钥 (apiKey) 生成一个 MD5 签名字符串

1. 准备参数

参数名	类型	必填	说明
content	String	是	用户输入的原始内容，可能包含换行符或双引号
timestamp	long	是	当前 Unix 时间戳（单位：秒），用于防止重放攻击
apiKey	String	是	预先分配的 API 密钥，用于签名计算，需保密。长度 128 以内

2. 预处理消息内容

先将所有\n替换为单个空格

content = content.replaceAll("\\n+"," ");

将双引号按照如下进行替换

content = content.replaceAll("\"", "&quot;");

3. 拼接签名字符串

按照以下格式拼接字符串（注意：apiKey 直接拼在末尾，前面无 & 或其他分隔符）：

<content>&timestamp=<timestamp><apiKey>

示例： 当前时间戳(timestamp)为：1721620571，content为："123456"，APIKEY为：TEST-aaabbbccc，最终拼接的字符串为：

content=123456&timestamp=1721620571TEST-aaabbbccc

4. 转为小写

将上一步的拼接的字符串转小写

例如:

String signString = "content=123456&timestamp=1721620571TEST-aaabbbccc".toLowerCase();

5. 计算 MD5 哈希

对小写后的字符串进行 MD5 摘要计算，并输出 32 位小写十六进制字符串。

APIKey 为调用客户大模型的 accessToken

sign=md5(content=123456&timestamp=1721620571TEST-aaabbbccc)

将md5里面内容转成小写字母再进行MD5加密

重要提示：

生成签名的内容（上文提到的拼装的参数，也就是 md5() 中的内容），必须为 UTF-8 编码格式
内容中换行会被替换成空格，而且多个换行也会替换为一个空格

验签流程图

UD前端

传入内容 content

UD后端

通过签名生成方式生成签名，返回签名 sign 和时间戳 timestamp

客户方面

API 请求体中需要增加的参数：

参数名称	参数说明	类型
timestamp	时间戳，用于校验签名的时效性	number
sign	签名	string

按照上述方式进行验签：

验签成功：返回真实数据
验签失败：返回标志字段表示"验签失败"
签名过期：时间戳过期（有效时间半个小时），返回标志字段表示"签名过期"

注意事项

暂不支持非流式调用,请求示例的stream参数,UD默认传true 请求参数
客户方提供的大模型调用地址需要使用 HTTPS 协议
客户方接口需要处理跨域问题
流式输出默认按照SSE技术实现解析
转人工需求,可参考对象示例中的data.dialogueSlots.dialogueIntent字段说明

支持的消息类型

消息类型	说明	处理方式
文字	支持富文本	直接支持
图片	支持（富文本）	直接支持
语音	IM转了文字，最终为富文本	转换为文字后处理
附件	富文本	转换为富文本后处理

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search