bot-api.md

概述

机器人通过 HTTP 接口的形式来提供对话服务，比如：

https://www.my-bot.com/api/v1/chat

机器人只需要实现以下任意一种接口方案，即可申请入驻广场。

[方案一] 标准接口

这是平台向机器人（也就是提供服务的第三方）发起的请求。 在这个请求里，平台会向机器人提供本次对话的唯一标识 qid（query id） 和唯一用户标识 uid（user id）。 机器人需要自行储存或处理 qid 和 uid，以便支持以下需求：

• qid：单个用户的多轮对话。
• uid：区别多个用户的对话。

POST ~/chat （接口地址必须以 chat 结尾）

请求体（JSON）：

{ "p": "天空为什么是蓝色的？" }

请求体可能包含如下字段：

字段名	类型	必填	含义	示例	备注
p	String	✓	提问内容	'天空为什么是蓝色的？'	p 表示 “prompt”
qid	String		平台为当前提问分配的唯一标识	'bxqid-cManAtRMszw...'	由平台生成并传递给机器人，以便机器人区分单个问题（写日志、追踪调试、异步回调等）
uid	String		用户的唯一标识	'bxuid-Aj8Spso8Xsp...'	由平台生成并传递给机器人，以便机器人区分用户

响应体（JSON）：

-{
    "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）：

-{
    "data": [	// 注意：这里 `data` 是一个数组
        "天空为什么是蓝色的？",	// 相当于方案一的 `p` 字段
        "bxqid-cManAtRMszw...",	// 相当于方案一的 `qid` 字段
        "bxuid-Aj8Spso8Xsp..."	// 相当于方案一的 `uid` 字段
    ]
}

响应体（JSON）：

-{
    "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 返回的两个变量。