Poe的标准协议规范

Poe 是一个与基于 AI 的机器人交互的平台。Poe 不仅提供对如 OpenAI 的 GPT-3.5-Turbo 和 Anthropic 的 Claude 等流行聊天机器人的访问，而且还允许创建者通过实现以下协议来创建自己的机器人。

简介

本规范提供了一种从任何可通过网络访问的服务运行自定义机器人的方法，这些机器人可被 Poe 应用使用。Poe 用户将请求发送到 Poe 服务器，Poe 服务器随后将请求转发至机器人服务器。随着机器人服务器的响应，Poe 将显示响应给用户。请查看快速开始了解如何运行服务器机器人的高级介绍。

术语

• Poe 服务器： 由 Poe 运行的服务器，接收客户端请求，将其转换为对机器人服务器的请求，并将响应流式传输回 Poe 客户端。
• 机器人服务器： 由创建者运行的服务器，响应来自 Poe 服务器的请求。响应最终在用户的 Poe 客户端中显示。

概念

标识符

协议使用标识符为某些请求字段标记。这些标识符是全球唯一的。它们由 1 到 3 个小写 ASCII 字符的序列组成，后跟一个连字符，然后是 32 个小写字母数字 ASCII 字符或 = 字符（即，它们满足正则表达式 ^[a-z]{1,3}-[a-z0-9=]{32}$）。

认证

创建机器人时，创建者可以提供一个由 32 个 ASCII 字符组成的访问密钥。为了让机器人服务器确认请求来自 Poe，所有请求都将具有一个 Authorization HTTP 头部 Bearer <access_key>。

内容类型

消息可能使用以下内容类型：

• text/plain：纯文本，未进行进一步处理
• text/markdown：Markdown 文本。特别是，这支持 GitHub-Flavored Markdown (GFM，规定于 https://github.github.com/gfm/) 的所有功能。然而，Poe 可以出于安全或可用性原因修改渲染的 Markdown。

版本控制

预计将来会扩展 API 以支持额外的功能。协议版本字符串由两个数字组成（例如，1.0）。

限制

Poe 可能对机器人服务器实施限制，以确保产品的可靠性和可扩展性。具体来说：

• 对任何请求的初始响应必须在 5 秒内返回。
• 对任何请求的响应（包括 query 请求）必须在 600 秒内完成。
• 机器人响应的总长度（对 query 请求发送的所有 text 事件的文本长度之和）不得超过 100,000 个字符。
• 对 query 事件的响应中发送的事件总数不得超过 10,000 个。
• 如果用户与机器人的先前对话中的消息数超过 1000，Poe 可能会截断对话。

请求

Poe 服务器将向机器人服务器的 URL 发送一个 HTTP POST 请求，内容类型为 application/json。请求体是一个包含以下键的 JSON 字典：

• version (string)：服务器使用的 API 版本。
• type(string)：这是以下字符串之一：
  • query：当用户向机器人发起查询时调用（即，他们发送消息）。
  • settings：查询机器人希望的设置。
  • report_feedback：向机器人服务器报告某些事件发生时（例如，用户喜欢一条消息）。
  • report_error：向机器人服务器报告发生归因于机器人的错误时（例如，它不正确使用协议）。
  • 未来可能会添加额外的请求类型。机器人服务器应忽略它们不理解的任何请求类型，理想情况下通过发送 501 Not Implemented HTTP 响应。

query

query 请求类型除了所有查询有效的请求字段外，还接受以下参数：

• query：一个包含一个或多个字典的数组，这些字典代表与机器人的对话中的先前消息。这些字典包含以下键：
  • role (string)：可能是以下字符串之一：
    • system：告诉机器人应如何工作的消息。
    • user：用户的消息。
    • bot：机器人的回应。
  • content (string)：消息的文本。
  • content_type (string)：消息的内容类型。
  • timestamp (int)：消息发送的时间，为自 Unix 纪元以来的微秒数。
  • message_id (identifier with type m)：此消息的标识符。

响应

机器人服务器应以 HTTP 200 响应代码响应。如果返回任何其他响应代码，Poe 服务器将向用户显示错误消息。服务器必须以 WhatWG 规定的服务器发送事件流形式响应。

服务器发送事件包含一个类型和数据。Poe API 支持几种具有不同含义的事件类型。对于每种类型，数据是如下指定的 JSON 字符串。支持的事件类型包括：

• meta：表示有关如何处理机器人服务器响应的元数据。
• text：代表要发送给用户的文本片段。
• json：代表响应中发送的数据片段。
• replace_response：与 text 类似，但放弃所有先前的 text 事件。
• suggested_reply：代表用户可以发送的建议后续查询。
• error：表示机器人服务器中发生错误。如果接收到此事件类型，服务器将关闭连接并向用户指示与机器人服务器通信时出现错误。
• done：必须是流中的最后一个事件，表示机器人响应已完成。服务器在接收到此事件后将关闭连接。

机器人响应必须包含至少一个 text 或 error 事件；不发送任何响应是错误的。

如果 Poe 服务器接收到它不认识的事件类型，它将忽略该事件。