Elfe commited on
Commit
1aa5abf
1 Parent(s): b8345f6

add api doc

Browse files
Files changed (1) hide show
  1. bot-api.md +79 -0
bot-api.md ADDED
@@ -0,0 +1,79 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <!--广场机器人 API 规范(草案)-->
2
+
3
+ ## 概述
4
+
5
+ 机器人通过 HTTP 接口的形式来提供对话服务,比如:
6
+
7
+ ```
8
+ https://www.my-bot.com/api/v1/chat
9
+ ```
10
+
11
+ 机器人只需要实现以下任意一种接口方案,即可申请入驻广场。
12
+
13
+
14
+
15
+
16
+ ## [方案一] 标准接口
17
+
18
+ **POST** `~/chat` (接口地址必须以 `chat` 结尾)
19
+
20
+ 请求体(JSON):
21
+
22
+ ```json
23
+ { "p": "天空为什么是蓝色的?" }
24
+ ```
25
+
26
+ 请求体可能包含如下字段:
27
+
28
+ 字段名 | 类型 | 必填 | 含义 | 示例 | 备注
29
+ ---|---|:---:|---|---|---
30
+ `p` | String | ✓ | 提问内容 |`'天空为什么是蓝色的?'`|`p` 表示 “prompt”
31
+ `qid` | String | | 平台为当前提问分配的唯一标识 |`'bxqid-cManAtRMszw...'`|由平台生成并传递给机器人,以便机器人区分单个问题(写日志、追踪调试、异步回调等)
32
+ `uid` | String | | 用户的唯一标识 | `'bxuid-Aj8Spso8Xsp...'` | 由平台生成并传递给机器人,以便机器人区分用户
33
+
34
+ 响应体(JSON):
35
+
36
+ ```js
37
+ -{
38
+ "data": {
39
+ "type": "text", // 也可以是 "markdown"
40
+ "content": "因为..."
41
+ }
42
+ }
43
+ ```
44
+
45
+
46
+
47
+ ## [方案二] Hugging Face 风格接口
48
+
49
+ **POST** `https://*.hf.space/run/predict`
50
+
51
+ > 为方便 Hugging Face 开发者快速接入,特提供本方案。
52
+ >
53
+ > 当机器人提供的接口符合上述模式,平台会自动识别它是一个 Hugging Face 应用。
54
+
55
+ 请求体(JSON):
56
+
57
+ ```js
58
+ -{
59
+ "data": [ // 注意:这里 `data` 是一个数组
60
+ "天空为什么是蓝色的?", // 相当于方案一的 `p` 字段
61
+ "bxqid-cManAtRMszw...", // 相当于方案一的 `qid` 字段
62
+ "bxuid-Aj8Spso8Xsp..." // 相当于方案一的 `uid` 字段
63
+ ]
64
+ }
65
+ ```
66
+
67
+ 响应体(JSON):
68
+
69
+ ```js
70
+ -{
71
+ "data": [ // 注意:这里 `data` 是一个数组
72
+ "text", // 相当于方案一的 `type` 字段
73
+ "因为..." // 相当于方案一的 `content` 字段
74
+ ]
75
+ }
76
+ ```
77
+
78
+
79
+