Spaces:
Running
Running
| <!--广场机器人 API 规范（草案）--> | |
| ## 概述 | |
| 机器人通过 HTTP 接口的形式来提供对话服务，比如： | |
| ``` | |
| https://www.my-bot.com/api/v1/chat | |
| ``` | |
| 机器人只需要实现以下任意一种接口方案，即可申请入驻广场。 | |
| ## [方案一] 标准接口 | |
| 这是平台向机器人（也就是提供服务的第三方）发起的请求。 | |
| 在这个请求里，平台会向机器人提供本次对话的唯一标识 qid（query id） 和唯一用户标识 uid（user id）。 | |
| 机器人需要自行储存或处理 qid 和 uid，以便支持以下需求： | |
| - qid：单个用户的多轮对话。 | |
| - uid：区别多个用户的对话。 | |
| **POST** `~/chat` （接口地址必须以 `chat` 结尾） | |
| 请求体（JSON）： | |
| ```json | |
| { "p": "天空为什么是蓝色的？" } | |
| ``` | |
| 请求体可能包含如下字段： | |
| 字段名 | 类型 | 必填 | 含义 | 示例 | 备注 | |
| ---|---|:---:|---|---|--- | |
| `p` | String | ✓ | 提问内容 |`'天空为什么是蓝色的？'`|`p` 表示 “prompt” | |
| `qid` | String | | 平台为当前提问分配的唯一标识 |`'bxqid-cManAtRMszw...'`|由平台生成并传递给机器人，以便机器人区分单个问题（写日志、追踪调试、异步回调等） | |
| `uid` | String | | 用户的唯一标识 | `'bxuid-Aj8Spso8Xsp...'` | 由平台生成并传递给机器人，以便机器人区分用户 | |
| 响应体（JSON）： | |
| ```js | |
| -{ | |
| "data": { | |
| "type": "text", // 也可以是 "markdown" | |
| "content": "因为..." | |
| } | |
| } | |
| ``` | |
| 字段名 | 类型 | 必填 | 含义 | 示例 | 备注 | |
| ---|---|:---:|---|---|--- | |
| `type` | String | ✓ | 返回类型 |`text`| 目前支持 text 和 markdown | |
| `content` | String | | 机器人所返回的内容 |`很高兴见到你，我是……`| | |
| ## [方案二] Hugging Face 风格接口 | |
| **POST** `https://*.hf.space/run/predict` | |
| > 为方便 Hugging Face 开发者快速接入，特提供本方案。 | |
| > | |
| > 当机器人提供的接口符合上述模式，平台会自动识别它是一个 Hugging Face 应用。 | |
| 请求体（JSON）： | |
| ```js | |
| -{ | |
| "data": [ // 注意：这里 `data` 是一个数组 | |
| "天空为什么是蓝色的？", // 相当于方案一的 `p` 字段 | |
| "bxqid-cManAtRMszw...", // 相当于方案一的 `qid` 字段 | |
| "bxuid-Aj8Spso8Xsp..." // 相当于方案一的 `uid` 字段 | |
| ] | |
| } | |
| ``` | |
| 响应体（JSON）： | |
| ```js | |
| -{ | |
| "data": [ // 注意：这里 `data` 是一个数组 | |
| "text", // 相当于方案一的 `type` 字段 | |
| "因为..." // 相当于方案一的 `content` 字段 | |
| ] | |
| } | |
| ``` | |
| 在 Hugging Face 里，你可以通过一下方式来完成： | |
| ``` | |
| def chat(p, qid, uid): | |
| #your process | |
| return ["text", response] | |
| iface = gr.Interface(fn=chat, | |
| inputs=["text", "text", "text"], | |
| outputs=["text", "text"], | |
| description="""这是我的机器人""") | |
| iface.launch() | |
| ``` | |
| 其中，gr.Interface 的 inputs 对应了 chat 的三个输入参数， outputs 对应了 chat 返回的两个变量。 | |